Options
All
  • Public
  • Public/Protected
  • All
Menu

Stateful version of StatelessEventBus.

remarks

Wraps an IAtom state container (i.e. Atom/Cursor/History) and provides additional pre-defined event handlers and side effects to manipulate wrapped state. Prefer this as the default implementation for most use cases.

Hierarchy

Implements

Index

Constructors

constructor

Properties

Protected currCtx

currCtx: undefined | InterceptorContext

Protected currQueue

currQueue: undefined | Event[]

Protected effects

effects: IObjectOf<SideEffect>

Protected eventQueue

eventQueue: Event[]

Protected handlers

handlers: IObjectOf<Interceptor[]>

Protected priorities

priorities: EffectPriority[]

Readonly state

state: IAtom<any>

Methods

addBuiltIns

  • addBuiltIns(): any
  • Adds same built-in event & side effect handlers as in StatelessEventBus.addBuiltIns() and the following additions:

    Handlers

    EV_SET_VALUE

    Resets state path to provided value. See setIn.

    Example event definition:

    [EV_SET_VALUE, ["path.to.value", val]]
    

    EV_UPDATE_VALUE

    Updates a state path's value with provided function and optional extra arguments. See updateIn.

    Example event definition:

    [EV_UPDATE_VALUE, ["path.to.value", (x, y) => x + y, 1]]
    

    EV_TOGGLE_VALUE

    Negates a boolean state value at given path.

    Example event definition:

    [EV_TOGGLE_VALUE, "path.to.value"]
    

    EV_UNDO

    Calls ctx[id].undo() and uses return value as new state. Assumes ctx[id] is a History instance, provided via e.g. processQueue({ history }). The event can be triggered with or without ID. By default "history" is used as default key to lookup the History instance. Furthermore, an additional event can be triggered based on if a previous state has been restored or not (basically, if the undo was successful). This is useful for resetting/re-initializing stateful resources after a successful undo action or to notify the user that no more undo's are possible. The new event will be processed in the same frame and has access to the (possibly) restored state. The event structure for these options is shown below:

    // using default ID
    bus.dispatch([EV_UNDO]);
    
    // using custom history ID
    bus.dispatch([EV_UNDO, ["custom"]]);
    
    // using custom ID and dispatch another event after undo
    bus.dispatch([EV_UNDO, ["custom", ["ev-undo-success"], ["ev-undo-fail"]]]);
    

    EV_REDO

    Similar to EV_UNDO, but for redo actions.

    Side effects

    FX_STATE

    Resets state atom to provided value (only a single update per processing frame).

    Returns any

addEffect

  • addEffect(id: string, fx: SideEffect, priority?: number): void

addEffects

  • addEffects(specs: IObjectOf<EffectDef>): void

addHandler

  • addHandler(id: string, spec: EventDef): void

addHandlers

  • addHandlers(specs: IObjectOf<EventDef>): void

context

deref

  • deref(): any

dispatch

  • dispatch(...e: Event[]): void

dispatchLater

  • dispatchLater(e: Event, delay?: number): void

dispatchNow

  • dispatchNow(...e: Event[]): void

instrumentWith

Protected interceptorsFromSpec

  • interceptorsFromSpec(spec: EventDef): any

Protected mergeEffects

  • Merges the new side effects returned from an interceptor into the internal effect accumulator.

    remarks

    Any events assigned to the FX_DISPATCH_NOW effect key are immediately added to the currently active event batch.

    If an interceptor wishes to cause multiple invocations of a single side effect type (e.g. dispatch multiple other events), it MUST return an array of these values. The only exceptions to this are the following effects, which for obvious reasons can only accept a single value.

    Note: the FX_STATE effect is not actually defined by this class here, but is supported to avoid code duplication in EventBus.

    • FX_CANCEL
    • FX_STATE

    Because of this support (multiple values), the value of a single side effect MUST NOT be a nested array itself, or rather its first item can't be an array.

    For example:

    // interceptor result map to dispatch a single event
    { [FX_DISPATCH]: ["foo", "bar"]}
    
    // result map format to dispatch multiple events
    { [FX_DISPATCH]: [ ["foo", "bar"], ["baz", "beep"] ]}
    

    Any null / undefined values directly assigned to a side effect are ignored and will not trigger the effect.

    Parameters

    Returns void

Protected processEffect

Protected processEffects

Protected processEvent

  • Processes a single event using its configured handler/interceptor chain. Logs warning message and skips processing if no handler is available for the event type.

    remarks

    The array of interceptors is processed in bi-directional order. First any pre interceptors are processed in forward order. Then post interceptors are processed in reverse.

    Each interceptor can return a result object of side effects, which are being merged and collected for StatelessEventBus.processEffects.

    Any interceptor can trigger zero or more known side effects, each (side effect) will be collected in an array to support multiple invocations of the same effect type per frame. If no side effects are requested, an interceptor can return undefined.

    Processing of the current event stops immediately, if an interceptor sets the FX_CANCEL side effect key to true. However, the results of any previous interceptors (incl. the one which cancelled) are kept and processed further as usual.

    Parameters

    Returns void

Protected processForward

processQueue

  • Triggers processing of current event queue and returns true if the any of the processed events caused a state change.

    If an event handler triggers the FX_DISPATCH_NOW side effect, the new event will be added to the currently processed batch and therefore executed in the same frame. Also see dispatchNow.

    If the optional ctx arg is provided it will be merged into the InterceptorContext object passed to each interceptor. Since the merged object is also used to collect triggered side effects, care must be taken that there're no key name clashes.

    In order to use the built-in EV_UNDO, EV_REDO events, users MUST provide a History (or compatible undo history instance) via the ctx arg, e.g.

    bus.processQueue({ history });
    

    Parameters

    Returns boolean

Protected processReverse

removeEffect

  • removeEffect(id: string): void

removeEffects

  • removeEffects(ids: string[]): void

removeHandler

  • removeHandler(id: string): void

removeHandlers

  • removeHandlers(ids: string[]): void

Generated using TypeDoc