Custom JavaScript event system
You set up handlers for arbitrary triggers and then can trigger them. Both handlers and trigger activations can have any number of arguments. Handler arguments are passed to callback before trigger arguments.
Any valid Map key can be a trigger. There are several ways to set up a handler.
There are two types of handlers:
- Normal - executes with given arguments and might return a value. Called with
handler(...handlerArguments, ...triggerArguments)
- Modifier - executed with input value in addition to arguments and returns modified value. Called with
handler(input, ...handlerArguments, ...triggerArguments)
Svelte-specific Trigger functions set up a trigger that will only exist during component's life cycle, from onMount
to onDestroy
.
Normal handlers are set up with Trigger.handles(trigger, handler, ...args)
or Trigger.on(trigger, handler, ...args)
Modifying handlers are set up with Trigger.modifies(trigger, handler, ...args)
These should be placed in top level of component, NOT within onMount. Both methods return a handler object chat can be cancelled or have its priority changed with .setPriority(X) where handlers with lower X would be executed earlier.
Unlike svelte-specific triggers, these can be set up anywhere, but need to be canceled manually.
Normal handlers are set up with Trigger.createHandler(trigger, handler, ...args)
Modifying handlers are set up with Trigger.createModifier(trigger, handler, ...args)
You can cancel either with .cancel()
method of returned value.
Use Trigger(trigger, ...args)
to execute normal handlers set up for given trigger. This is similar to array.forEach
Use Trigger.poll(trigger, ...args)
to execute normal handlers set up for given trigger and collect execution results. This is similar to array.map
Use Trigger.modify(input, trigger, ...args)
to execute modifier handlers set up for the trigger in a chain. This is similar to array.reduce
.
Trigger.createTrigger()
returns function that executes triggers with itself as a key. Trigger.createPoll()
and Trigger.createModification()
create similar functions for polling and modification.
Trigger.clearTrigger(trigger)
removes all handlers associated with event and removes entry for it from storage.
Component:
//top level
Trigger.on("tick", (value) => console.log("Tick", value))
Anywhere else:
setInterval(() => Trigger("tick", Math.random()), 1000)
Will output "Tick" with a random number to console while component is alive (trigger is created onMount and removed onDestroy)
- TriggerHandler
handler for an event, associated with a trigger
- Trigger :
function
Event handling system
Can be used as shorthand for Trigger.execute(trigger, ...args) executes all non-transformative handlers associated with trigger (like array.forEach)
- execute(trigger, ...args)
executes all non-transformative handlers associated with trigger (like array.forEach)
- poll(trigger, ...args) ⇒
any
collects return values of all non-transformative handlers associated with trigger (like array.map)
- modify(input, trigger, ...args) ⇒
any
applies all transformative handlers associated with trigger in a chain (like array.reduce)
- handles(trigger, callback, ...args) ⇒
Promise.<TriggerHandler>
creates non-transformative handler that exists for component's lifetime
- modifies(trigger, callback, ...args) ⇒
Promise.<TriggerHandler>
creates transformative handler that exists for component's lifetime
- createHandler(trigger, callback, ...args) ⇒
TriggerHandler
creates non-transformative handler
- createModifier(trigger, callback, ...args) ⇒
TriggerHandler
creates transformative handler
- createTrigger() ⇒
TriggerFunction
creates function that triggers using itself as a key
- createPoll() ⇒
PollFunction
creates function that triggers using itself as a key
- createModification() ⇒
ModifierFunction
creates function that triggers using itself as a key
- clearTrigger(trigger)
cancels all handlers for a trigger and removes it from lists
- on(trigger, callback, ...args) ⇒
Promise.<TriggerHandler>
creates non-transformative handler that exists for component's lifetime
shorthand to Trigger.handles()
- once(trigger, callback, ...args) ⇒
Promise.<TriggerHandler>
creates non-transformative handler that exists for component's lifetime or until first execution
shorthand to Trigger.handles().setOnce()
- HandlerCallback ⇒
any
- TransformativeCallback ⇒
any
- TriggerFunction :
function
- PollFunction ⇒
any
- ModifierFunction ⇒
any
handler for an event, associated with a trigger
Kind: global class
triggerHandler.cancel() ⇒ TriggerHandler
cancels a handler so it never executes anymore and queues it for removal
Kind: instance method of TriggerHandler
Returns: TriggerHandler
- itself
triggerHandler.setPriority(value) ⇒ TriggerHandler
sets priority (higher = executed later)
Kind: instance method of TriggerHandler
Returns: TriggerHandler
- itself
Param | Type | Default | Description |
---|---|---|---|
value | number |
0 |
new value (default is 0) |
triggerHandler.setOnce(value) ⇒ TriggerHandler
sets flag for cancellation after next execution
Kind: instance method of TriggerHandler
Returns: TriggerHandler
- itself
Param | Type | Default | Description |
---|---|---|---|
value | boolean |
true |
new value |
Event handling system
Can be used as shorthand for Trigger.execute(trigger, ...args) executes all non-transformative handlers associated with trigger (like array.forEach)
Kind: global object
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
...args | any |
arguments provided to each handler after its own arguments |
executes all non-transformative handlers associated with trigger (like array.forEach)
Kind: static method of Trigger
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
...args | any |
arguments provided to each handler after its own arguments |
collects return values of all non-transformative handlers associated with trigger (like array.map)
Kind: static method of Trigger
Returns: any
- - array of values returned by handlers
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
...args | any |
arguments provided to each handler after its own arguments |
applies all transformative handlers associated with trigger in a chain (like array.reduce)
Kind: static method of Trigger
Returns: any
- - value returned by last handler
Param | Type | Description |
---|---|---|
input | any |
initial value |
trigger | any |
trigger key |
...args | any |
arguments provided to each handler after its own arguments |
Trigger.handles(trigger, callback, ...args) ⇒ Promise.<TriggerHandler>
creates non-transformative handler that exists for component's lifetime
Kind: static method of Trigger
Returns: Promise.<TriggerHandler>
- Promise that would resolve to handler
and can forward .setPriority, .setOnce and .cancel to it
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
callback | HandlerCallback |
function |
...args | any |
arguments passed to handler before trigger arguments |
Trigger.modifies(trigger, callback, ...args) ⇒ Promise.<TriggerHandler>
creates transformative handler that exists for component's lifetime
Kind: static method of Trigger
Returns: Promise.<TriggerHandler>
- Promise that would resolve to handler
and can forward .setPriority, .setOnce and .cancel to it
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
callback | TransformativeCallback |
function that transforms input |
...args | any |
arguments passed to handler before trigger arguments |
Trigger.createHandler(trigger, callback, ...args) ⇒ TriggerHandler
creates non-transformative handler
Kind: static method of Trigger
Returns: TriggerHandler
- handler
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
callback | HandlerCallback |
function |
...args | any |
arguments passed to handler before trigger arguments |
Trigger.createModifier(trigger, callback, ...args) ⇒ TriggerHandler
creates transformative handler
Kind: static method of Trigger
Returns: TriggerHandler
- handler
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
callback | TransformativeCallback |
function that transforms input |
...args | any |
arguments passed to handler before trigger arguments |
Trigger.createTrigger() ⇒ TriggerFunction
creates function that triggers using itself as a key
Kind: static method of Trigger
Trigger.createPoll() ⇒ PollFunction
creates function that triggers using itself as a key
Kind: static method of Trigger
Trigger.createModification() ⇒ ModifierFunction
creates function that triggers using itself as a key
Kind: static method of Trigger
cancels all handlers for a trigger and removes it from lists
Kind: static method of Trigger
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
Trigger.on(trigger, callback, ...args) ⇒ Promise.<TriggerHandler>
creates non-transformative handler that exists for component's lifetime
shorthand to Trigger.handles()
Kind: static method of Trigger
Returns: Promise.<TriggerHandler>
- Promise that would resolve to handler
and can forward .setPriority, .setOnce and .cancel to it
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
callback | HandlerCallback |
function |
...args | any |
arguments passed to handler before trigger arguments |
Trigger.once(trigger, callback, ...args) ⇒ Promise.<TriggerHandler>
creates non-transformative handler that exists for component's lifetime or until first execution
shorthand to Trigger.handles().setOnce()
Kind: static method of Trigger
Returns: Promise.<TriggerHandler>
- Promise that would resolve to handler
and can forward .setPriority, .setOnce and .cancel to it
Param | Type | Description |
---|---|---|
trigger | any |
trigger key |
callback | HandlerCallback |
function |
...args | any |
arguments passed to handler before trigger arguments |
Kind: global typedef
Returns: any
- - return value for .poll (optional)
Param | Type | Description |
---|---|---|
...args | any |
own arguments, passed before trigger's arguments |
Kind: global typedef
Returns: any
- - modified value
Param | Type | Description |
---|---|---|
input | any |
initial value of return value of previous TransformativeHandler |
...args | any |
own arguments, passed before trigger's arguments |
Kind: global typedef
Param | Type | Description |
---|---|---|
...args | any |
arguments, passed to handler after own arguments |
Kind: global typedef
Returns: any
- - return values of handlers
Param | Type | Description |
---|---|---|
...args | any |
arguments, passed to handler after own arguments |
Kind: global typedef
Returns: any
- - initial value or return value of last handler
Param | Type | Description |
---|---|---|
input | any |
initial value |
...args | any |
arguments, passed to handler after own arguments |