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

Constants

Functions

Typedefs

TriggerHandler

handler for an event, associated with a trigger

Kind: global class

• TriggerHandler
  • .cancel() ⇒ TriggerHandler
  • .setPriority(value) ⇒ TriggerHandler
  • .setOnce(value) ⇒ TriggerHandler

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 |