Class ObserverEngine<Shape>

constructor

• new ObserverEngine<Shape extends Record<string, any> = Record<string, any>>(
      options?: ObserverEngine.Options<Shape>,
  ): ObserverEngine<Shape>

  Type Parameters

  • Shape extends Record<string, any> = Record<string, any>

  Parameters

  • Optionaloptions: ObserverEngine.Options<Shape>

  Returns ObserverEngine<Shape>

name

$facts

• $facts(): {
      hasSpy: boolean;
      listenerCounts: Record<string, number>;
      listeners: (keyof Shape)[];
      rgxListeners: string[];
  }

  Returns facts about the the internal state of the observable instance.

  Returns {
      hasSpy: boolean;
      listenerCounts: Record<string, number>;
      listeners: (keyof Shape)[];
      rgxListeners: string[];
  }

$has

• $has(event: keyof Shape): boolean

  Returns if the observable instance has the given event

  Parameters

  • event: keyof Shape

  Returns boolean

• $has(event: RegExp): boolean

  Returns if the observable instance has a regex event

  Parameters

  • event: RegExp

  Returns boolean

• $has(event: string): boolean

  Returns if the observable instance has the given event

  Parameters

  • event: string

  Returns boolean

$internals

• $internals(): {
      internalListener: EventTarget;
      listenerMap: Map<keyof Shape, Set<Func>>;
      name: string;
      rgxListenerMap: Map<string, Set<Func>>;
      spy: ObserverEngine.Spy<Shape> | undefined;
  }

  The internals of the observable instance. *

  • NOTE: Do not use this to try to meddle with the
  • internals of the observable instance. This is for
  • debugging purposes only.

  Returns {
      internalListener: EventTarget;
      listenerMap: Map<keyof Shape, Set<Func>>;
      name: string;
      rgxListenerMap: Map<string, Set<Func>>;
      spy: ObserverEngine.Spy<Shape> | undefined;
  }

clear

• clear(): void

  Returns void

debug

• debug(on?: boolean): void

  Enables or disables debugging for the observable instance. Works in conjunction with your spy function. Provides a stack trace of events that are triggered, listened to, and cleaned up.

  Parameters

  • on: boolean = true

    Whether to enable or disable debugging

  Returns void

emit

• emit<E extends string | number | symbol | RegExp>(
      event: E,
      data?: E extends keyof Shape
          ? Shape[E]
          : E extends string ? Record<E, any>[E] : unknown,
  ): void

  Emits an event

  Type Parameters

  • E extends string | number | symbol | RegExp

  Parameters

  • event: E
  • Optionaldata: E extends keyof Shape
        ? Shape[E]
        : E extends string ? Record<E, any>[E] : unknown

  Returns void

observe

• observe<C>(
      component: C,
      options?: ObserverEngine.ObserveOptions,
  ): ObserverEngine.Child<C, Shape>

  Observes given component as an extension of this observable instance.

  Type Parameters

  • C

  Parameters

  • component: C

    Component to wrap events around

  • Optionaloptions: ObserverEngine.ObserveOptions

    Optional configuration including signal for cleanup

  Returns ObserverEngine.Child<C, Shape>

  Example

  const obs = new ObserverEngine();
  
  const modal = {};
  
  obs.observe(modal);
  
  modal.on('modal-open', () => {});
  
  obs.trigger('modal-open'); // opens modal
  modal.trigger('modal-open'); // opens modal
  
  modal.cleanup(); // clears all event listeners
  Copy

off

• off(event: string | RegExp | keyof Shape, listener?: Function): void

  Stop listening for an event

  Parameters

  • event: string | RegExp | keyof Shape
  • Optionallistener: Function

  Returns void

on

• on<E extends string | number | symbol>(
      event: E,
      options?: ObserverEngine.ListenerOptions,
  ): EventGenerator<Shape, E>

  Returns an event generator that will listen for the specified event

  Type Parameters

  • E extends string | number | symbol

  Parameters

  • event: E
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns EventGenerator<Shape, E>

  Example

  const obs = new ObserverEngine();
  
  const something = obs.on('something');
  const data = await something.next(); // waits for next event
  something.emit('special'); // emits data to listeners
  
  something.cleanup(); // stops listening for events
  Copy

• on<E extends string>(
      event: E,
      options?: ObserverEngine.ListenerOptions,
  ): EventGenerator<Record<E, any>>

  Returns an event generator that will listen for the specified event

  Type Parameters

  • E extends string

  Parameters

  • event: E
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns EventGenerator<Record<E, any>>

  Example

  const obs = new ObserverEngine();
  
  const something = obs.on('something');
  const data = await something.next(); // waits for next event
  something.emit('special'); // emits data to listeners
  
  something.cleanup(); // stops listening for events
  Copy

• on<E extends string | number | symbol>(
      event: E,
      listener: ObserverEngine.EventCallback<Shape[E]>,
      options?: ObserverEngine.ListenerOptions,
  ): ObserverEngine.Cleanup

  Listens for the specified event and executes the given callback

  Type Parameters

  • E extends string | number | symbol

  Parameters

  • event: E
  • listener: ObserverEngine.EventCallback<Shape[E]>
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns ObserverEngine.Cleanup

  Example

  const obs = new ObserverEngine();
  
  obs.on('something', (data) => {
     console.log(data);
  });
  Copy

• on<E extends string>(
      event: E,
      listener: ObserverEngine.EventCallback<Record<E, any>>,
      options?: ObserverEngine.ListenerOptions,
  ): ObserverEngine.Cleanup

  Returns an event generator that will listen for the specified event

  Type Parameters

  • E extends string

  Parameters

  • event: E
  • listener: ObserverEngine.EventCallback<Record<E, any>>
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns ObserverEngine.Cleanup

  Example

  const obs = new ObserverEngine();
  
  const something = obs.on('something');
  const data = await something.next(); // waits for next event
  something.emit('special'); // emits data to listeners
  
  something.cleanup(); // stops listening for events
  Copy

• on(
      event: RegExp,
      options?: ObserverEngine.ListenerOptions,
  ): EventGenerator<Shape, RegExp>

  Returns an event generator that will listen for all events matching the regex

  Parameters

  • event: RegExp
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns EventGenerator<Shape, RegExp>

  Example

  const obs = new ObserverEngine();
  
  const onEvent = obs.on(/some/);
  const { event, data } = await onEvent.next(); // waits for next event
  onEvent.emit('something'); // emits data to listeners
  
  onEvent.cleanup(); // stops listening for events
  Copy

• on(
      event: RegExp,
      listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>,
      options?: ObserverEngine.ListenerOptions,
  ): ObserverEngine.Cleanup

  Listens for all events matching the regex and executes the given callback

  Parameters

  • event: RegExp
  • listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns ObserverEngine.Cleanup

  Example

  const obs = new ObserverEngine();
  
  obs.on(/some/, ({ event, data }) => {
      console.log(event, data);
  });
  Copy

once

• once<E extends string | number | symbol>(
      event: E,
      options?: ObserverEngine.ListenerOptions,
  ): EventPromise<Shape[E]>

  Returns an event promise that resolves when the specified event is emitted

  Type Parameters

  • E extends string | number | symbol

  Parameters

  • event: E
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns EventPromise<Shape[E]>

• once<E extends string>(
      event: E,
      options?: ObserverEngine.ListenerOptions,
  ): EventPromise<Record<E, any>>

  Returns an event promise that resolves when the specified event is emitted. This overload is untyped and can be used to listen for any event that is emitted.

  Type Parameters

  • E extends string

  Parameters

  • event: E
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns EventPromise<Record<E, any>>

• once<E extends string | number | symbol>(
      event: E,
      listener: ObserverEngine.EventCallback<Shape[E]>,
      options?: ObserverEngine.ListenerOptions,
  ): ObserverEngine.Cleanup

  Executes a callback once when the specified event is emitted

  Type Parameters

  • E extends string | number | symbol

  Parameters

  • event: E
  • listener: ObserverEngine.EventCallback<Shape[E]>
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns ObserverEngine.Cleanup

• once<E extends string>(
      event: E,
      listener: ObserverEngine.EventCallback<Record<E, any>>,
      options?: ObserverEngine.ListenerOptions,
  ): ObserverEngine.Cleanup

  Executes a callback once when the specified event is emitted. This overload is untyped and can be used to listen for any event that is emitted.

  Type Parameters

  • E extends string

  Parameters

  • event: E
  • listener: ObserverEngine.EventCallback<Record<E, any>>
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns ObserverEngine.Cleanup

• once(
      event: RegExp,
      options?: ObserverEngine.ListenerOptions,
  ): EventPromise<ObserverEngine.RgxEmitData<Shape>>

  Returns an event promise that resolves when any events matching the regex are emitted

  Parameters

  • event: RegExp
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns EventPromise<ObserverEngine.RgxEmitData<Shape>>

• once(
      event: RegExp,
      listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>,
      options?: ObserverEngine.ListenerOptions,
  ): ObserverEngine.Cleanup

  Executes a callback once when any events matching the regex are emitted

  Parameters

  • event: RegExp
  • listener: ObserverEngine.EventCallback<ObserverEngine.RgxEmitData<Shape>>
  • Optionaloptions: ObserverEngine.ListenerOptions

  Returns ObserverEngine.Cleanup

queue

• queue<E extends string | number | symbol | RegExp>(
      event: E,
      process: (data: EventData<Shape, E>) => any,
      options: QueueOpts,
  ): EventQueue<Shape, E>

  Type Parameters

  • E extends string | number | symbol | RegExp

  Parameters

  • event: E
  • process: (data: EventData<Shape, E>) => any
  • options: QueueOpts

  Returns EventQueue<Shape, E>

spy

• spy(spy: ObserverEngine.Spy<Shape>, force?: boolean): void

  Sets the spy function for the observable instance.

  Parameters

  • spy: ObserverEngine.Spy<Shape>

    The spy function to set

  • force: boolean = false

    Whether to force the spy function to be set even if one is already set

  Returns void

Staticcopy

• copy<Shape extends Record<string, any>>(
      source: ObserverEngine<Shape>,
      target: ObserverEngine<Shape>,
      options?: ObserverEngine.TransferOptions<Shape>,
  ): void

  Copies all matching listeners from source to target without removing them from the source. Target's existing listeners are preserved.

  Useful when forking an engine so both instances react to the same events independently.

  Type Parameters

  • Shape extends Record<string, any>

  Parameters

  • source: ObserverEngine<Shape>
  • target: ObserverEngine<Shape>
  • Optionaloptions: ObserverEngine.TransferOptions<Shape>

  Returns void

  Example

  const primary = new ObserverEngine();
      const mirror = new ObserverEngine();
  
      primary.on('update', handler);
  
      ObserverEngine.copy(primary, mirror);
      // Both engines now have the 'update' listener
  Copy

  Example

  // Copy everything except internal events
      ObserverEngine.copy(primary, mirror, {
          exclude: [/^__/]
      });
  Copy

Statictransfer

• transfer<Shape extends Record<string, any>>(
      source: ObserverEngine<Shape>,
      target: ObserverEngine<Shape>,
      options?: ObserverEngine.TransferOptions<Shape>,
  ): void

  Transfers all matching listeners from source to target, removing them from the source. Target's existing listeners are preserved.

  Useful when cloning an engine (e.g. FetchEngine) and carrying over observability listeners to the new instance.

  Type Parameters

  • Shape extends Record<string, any>

  Parameters

  • source: ObserverEngine<Shape>
  • target: ObserverEngine<Shape>
  • Optionaloptions: ObserverEngine.TransferOptions<Shape>

  Returns void

  Example

  const old = new ObserverEngine();
      const next = new ObserverEngine();
  
      old.on('ready', handler);
  
      ObserverEngine.transfer(old, next);
      // `next` now owns the 'ready' listener; `old` has none
  Copy

  Example

  // Transfer only specific events
      ObserverEngine.transfer(old, next, {
          filter: ['ready', /^user\./]
      });
  Copy