Documentation / @cashconnect-js/core / primitives/event-emitter

EventMap

type EventMap = Record<string, unknown>;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:14

A record type that maps event names (strings) to their payload types. Used as a constraint for the EventEmitter's generic type parameter.

Example

interface MyEvents extends EventMap {
  'user-login': { userId: string; timestamp: number };
  'data-updated': { data: any[] };
  'error': { message: string; code: number };
}

---

OffCallback()

type OffCallback = () => void;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:52

A callback function returned by event registration methods that can be called to unregister the listener.

Returns

void

Example

const off = emitter.on('test', handler);
off(); // Unregisters the handler

---

EventEmitter

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:79

A type-safe event emitter that supports debouncing, one-time listeners, and async event waiting.

Example

interface AppEvents extends EventMap {
  'user-login': { userId: string };
  'data-change': { data: any[] };
  'error': { message: string };
}

const emitter = new EventEmitter<AppEvents>();

// Type-safe event registration
emitter.on('user-login', ({ userId }) => {
  console.log(`User ${userId} logged in`);
});

// Emit events with proper typing
emitter.emit('user-login', { userId: '123' });

Type Parameters

Type Parameter	Description
T extends EventMap	An EventMap that defines the available events and their payload types

Constructors

Constructor

new EventEmitter<T>(): EventEmitter<T>;

Returns

EventEmitter<T>

Methods

on()

on<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:102

Registers a listener for the specified event type.

Type Parameters

Type Parameter	Description
K extends string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to listen for
listener	Listener<T[K]>	The function to call when the event is emitted
debounceMilliseconds?	number	Optional debounce time in milliseconds

Returns

OffCallback

A callback function that can be used to unregister this listener

Example

const off = emitter.on('data-change', (data) => {
  console.log('Data updated:', data);
}, 300); // Debounce for 300ms

// Later, unregister the listener
off();

once()

once<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:145

Registers a one-time listener for the specified event type. The listener will be automatically removed after being called once.

Type Parameters

Type Parameter	Description
K extends string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to listen for
listener	Listener<T[K]>	The function to call when the event is emitted
debounceMilliseconds?	number	Optional debounce time in milliseconds

Returns

OffCallback

A callback function that can be used to unregister this listener before it fires

Example

emitter.once('user-login', ({ userId }) => {
  console.log(`Welcome ${userId}! This will only show once.`);
});

off()

off<K>(type, listener): void;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:191

Removes a specific listener for the given event type.

Type Parameters

Type Parameter	Description
K extends string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to remove the listener from
listener	Listener<T[K]>	The listener function to remove

Returns

void

Example

const handler = (data) => console.log(data);
emitter.on('test', handler);
emitter.off('test', handler); // Removes the listener

emit()

emit<K>(type, payload): boolean;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:226

Emits an event of the specified type with the given payload. All registered listeners for this event type will be called.

Type Parameters

Type Parameter	Description
K extends string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to emit
payload	T[K]	The data to pass to all listeners

Returns

boolean

true if there were listeners for this event, false otherwise

Example

const hasListeners = emitter.emit('user-login', {
  userId: '123',
  timestamp: Date.now()
});

if (!hasListeners) {
  console.log('No one was listening for user-login events');
}

removeAllListeners()

removeAllListeners(): void;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:247

Removes all listeners for all events. This effectively resets the EventEmitter to its initial state.

Returns

void

Example

emitter.removeAllListeners();
// All previously registered listeners are now gone

waitFor()

waitFor<K>(
   type, 
   predicate, 
   timeoutMs?): Promise<T[K]>;

Defined in: cashconnect-js/packages/core/src/primitives/event-emitter.ts:276

Returns a Promise that resolves when an event of the specified type is emitted and matches the given predicate.

Type Parameters

Type Parameter	Description
K extends string | number | symbol	The event type key

Parameters

Parameter	Type	Description
type	K	The event type to wait for
predicate	(payload) => boolean	A function that determines if the event payload matches what we're waiting for
timeoutMs?	number	Optional timeout in milliseconds. If specified, the promise will reject after this time

Returns

Promise<T[K]>

A Promise that resolves with the event payload when the condition is met

Throws

If the timeout is reached before a matching event occurs

Example

try {
  const loginData = await emitter.waitFor(
    'user-login',
    ({ userId }) => userId === 'admin',
    5000 // Wait up to 5 seconds
  );
  console.log('Admin logged in:', loginData);
} catch (error) {
  console.log('Timeout: Admin never logged in');
}