Trigger
Custom JavaScript event system
Usage
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.
Set up handlers
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 way
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.
Vanilla way
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.
Triggering events
Plain execution
Use Trigger(trigger, ...args) to execute normal handlers set up for given trigger. This is similar to array.forEach
Polling results
Use Trigger.poll(trigger, ...args) to execute normal handlers set up for given trigger and collect execution results. This is similar to array.map
Value modifications
Use Trigger.modify(input, trigger, ...args) to execute modifier handlers set up for the trigger in a chain. This is similar to array.reduce.
Miscellaneous
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.
Quick example
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)
Quick reference (based on JSDoc)
Classes
- TriggerHandler
handler for an event, associated with a trigger
Constants
- 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)
Functions
- 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()
Typedefs
- HandlerCallback ⇒
any - TransformativeCallback ⇒
any - TriggerFunction :
function - PollFunction ⇒
any - ModifierFunction ⇒
any
TriggerHandler
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 |
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)
Kind: global object
| Param | Type | Description |
|---|---|---|
| trigger | any |
trigger key |
| ...args | any |
arguments provided to each handler after its own arguments |
Trigger.execute(trigger, ...args)
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 |
Trigger.poll(trigger, ...args) ⇒ any
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 |
Trigger.modify(input, trigger, ...args) ⇒ any
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
Trigger.clearTrigger(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 |
HandlerCallback ⇒ any
Kind: global typedef
Returns: any - - return value for .poll (optional)
| Param | Type | Description |
|---|---|---|
| ...args | any |
own arguments, passed before trigger's arguments |
TransformativeCallback ⇒ any
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 |
TriggerFunction : function
Kind: global typedef
| Param | Type | Description |
|---|---|---|
| ...args | any |
arguments, passed to handler after own arguments |
PollFunction ⇒ any
Kind: global typedef
Returns: any - - return values of handlers
| Param | Type | Description |
|---|---|---|
| ...args | any |
arguments, passed to handler after own arguments |
ModifierFunction ⇒ any
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 |
