Harvmaster/xo-cash-utils
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'event-emitter' into sse-and-backoff

Browse Source
This commit is contained in:
Harvmaster
2026-08-07 05:47:18 +00:00
parent 011b0391a5 e981bf8095
commit 70d7be1be3
4 changed files with 131 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cspell.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"version": "0.1",
"import": ["@generalprotocols/cspell-dictionary/cspell.json"],
"words": ["nonfungible", "lockscript"],
"words": ["nonfungible", "lockscript", "bivariance"],
"ignorePaths": ["source/template/xo-template.schema.json"]
}
package-lock.json
Generated
+32 -32
View File
@@ -1105,9 +1105,9 @@
"license": "MIT"
},
"node_modules/@eslint/config-array/node_modules/brace-expansion": {
"version": "1.1.16",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
"integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -1186,9 +1186,9 @@
"license": "MIT"
},
"node_modules/@eslint/eslintrc/node_modules/brace-expansion": {
"version": "1.1.16",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
"integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -3503,16 +3503,16 @@
}
},
"node_modules/brace-expansion": {
"version": "5.0.7",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz",
"integrity": "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==",
"version": "5.0.9",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
"integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
"dev": true,
"license": "MIT",
"dependencies": {
"balanced-match": "^4.0.2"
},
"engines": {
"node": "18 || 20 || >=22"
"node": "20 || >=22"
}
},
"node_modules/brotli-size": {
@@ -5292,9 +5292,9 @@
"peer": true
},
"node_modules/eslint-plugin-import/node_modules/brace-expansion": {
"version": "1.1.16",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
"integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"dev": true,
"license": "MIT",
"peer": true,
@@ -5379,9 +5379,9 @@
"peer": true
},
"node_modules/eslint-plugin-jsx-a11y/node_modules/brace-expansion": {
"version": "1.1.16",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
"integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"dev": true,
"license": "MIT",
"peer": true,
@@ -5468,9 +5468,9 @@
"peer": true
},
"node_modules/eslint-plugin-react/node_modules/brace-expansion": {
"version": "1.1.16",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
"integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"dev": true,
"license": "MIT",
"peer": true,
@@ -5542,9 +5542,9 @@
"license": "MIT"
},
"node_modules/eslint/node_modules/brace-expansion": {
"version": "1.1.16",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",
"integrity": "sha512-IDw48K2/2kRkg9LdJxurvq3lV3aBgq0REY89duEqFRthjlPdXHKMj7EnQOXVckxzgisinf3nHfrcE2FufFLXMw==",
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"dev": true,
"license": "MIT",
"dependencies": {
@@ -7129,9 +7129,9 @@
"license": "MIT"
},
"node_modules/js-yaml": {
"version": "4.3.0",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
"integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
"version": "4.3.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
"integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
"dev": true,
"funding": [
{
@@ -7810,9 +7810,9 @@
"license": "MIT"
},
"node_modules/nanoid": {
"version": "3.3.12",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
"integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
"version": "3.3.17",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.17.tgz",
"integrity": "sha512-xQLf0A3HOMlgHq0n247/LRuAOYmB7dXJ/DvAxGvsSBij45XtBSmQycu+F8ODbHwns/XyFZagyL1+J0Offw1E0g==",
"dev": true,
"funding": [
{
@@ -8288,9 +8288,9 @@
}
},
"node_modules/postcss": {
"version": "8.5.15",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
"integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
"version": "8.5.26",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
"integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
"dev": true,
"funding": [
{
@@ -8308,7 +8308,7 @@
],
"license": "MIT",
"dependencies": {
"nanoid": "^3.3.12",
"nanoid": "^3.3.17",
"picocolors": "^1.1.1",
"source-map-js": "^1.2.1"
},
source/event-emitter.ts
+61 -25
View File
@@ -1,18 +1,29 @@
export type EventMap = Record<string, unknown>;
type Listener<T> = (detail: T) => void;
type Listener<T> = (detail: Readonly<T>) => void;
/**
* Internally permits listeners for individual event payloads to be stored
* in a collection typed with the union of all event payloads.
*/
type StoredListener<T> = {
bivarianceHack(detail: Readonly<T>): void;
}['bivarianceHack'];
/**
* A listener entry.
* @template T - The event type.
* @template T - The event payload type.
*/
interface ListenerEntry<T> {
listener: Listener<T>;
wrappedListener: Listener<T>;
listener: StoredListener<T>;
wrappedListener: StoredListener<T>;
debounceTime?: number;
once?: boolean;
}
/**
* Callback returned by {@link on} and {@link once} for removing a listener.
*/
export type OffCallback = () => void;
/**
@@ -24,7 +35,7 @@ export class EventEmitter<T extends EventMap> {
* The listeners map.
* @private
*/
private listeners: Map<keyof T, Set<ListenerEntry<T[keyof T]>>> = new Map();
#listeners: Map<keyof T, Set<ListenerEntry<T[keyof T]>>> = new Map();
/**
* Add a listener for an event.
@@ -38,19 +49,23 @@ export class EventEmitter<T extends EventMap> {
const wrappedListener = debounceMilliseconds && debounceMilliseconds > 0 ? this.debounce(listener, debounceMilliseconds) : listener;
// If the listeners map does not have the event type, create a new set.
if (!this.listeners.has(type)) {
this.listeners.set(type, new Set());
if (!this.#listeners.has(type)) {
this.#listeners.set(type, new Set());
}
// Create a listener entry.
const listenerEntry: ListenerEntry<T[K]> = {
listener,
wrappedListener,
...(debounceMilliseconds !== undefined ? { debounceTime: debounceMilliseconds } : {}),
};
// Set the debounce time if specified.
if (debounceMilliseconds && debounceMilliseconds > 0) {
listenerEntry.debounceTime = debounceMilliseconds;
}
// Add the listener entry to the listeners map.
this.listeners.get(type)?.add(listenerEntry as ListenerEntry<T[keyof T]>);
this.#listeners.get(type)?.add(listenerEntry);
// Return an "off" callback that can be called to stop listening for events.
return () => this.off(type, listener);
@@ -64,7 +79,7 @@ export class EventEmitter<T extends EventMap> {
* @returns An off callback that can be called to stop listening for events.
*/
once<K extends keyof T>(type: K, listener: Listener<T[K]>, debounceMilliseconds?: number): OffCallback {
const wrappedListener: Listener<T[K]> = (detail: T[K]) => {
const wrappedListener: Listener<T[K]> = (detail: Readonly<T[K]>) => {
this.off(type, listener);
listener(detail);
};
@@ -74,8 +89,8 @@ export class EventEmitter<T extends EventMap> {
debounceMilliseconds && debounceMilliseconds > 0 ? this.debounce(wrappedListener, debounceMilliseconds) : wrappedListener;
// If the listeners map does not have the event type, create a new set.
if (!this.listeners.has(type)) {
this.listeners.set(type, new Set());
if (!this.#listeners.has(type)) {
this.#listeners.set(type, new Set());
}
// Create a listener entry.
@@ -83,11 +98,15 @@ export class EventEmitter<T extends EventMap> {
listener,
wrappedListener: debouncedListener,
once: true,
...(debounceMilliseconds !== undefined ? { debounceTime: debounceMilliseconds } : {}),
};
// Set the debounce time if specified.
if (debounceMilliseconds && debounceMilliseconds > 0) {
listenerEntry.debounceTime = debounceMilliseconds;
}
// Add the listener entry to the listeners map.
this.listeners.get(type)?.add(listenerEntry as ListenerEntry<T[keyof T]>);
this.#listeners.get(type)?.add(listenerEntry);
// Return an "off" callback that can be called to stop listening for events.
return () => this.off(type, listener);
@@ -98,11 +117,18 @@ export class EventEmitter<T extends EventMap> {
* @param type - The event type.
* @param listener - The listener function.
*/
off<K extends keyof T>(type: K, listener: Listener<T[K]>): void {
off<K extends keyof T>(type: K, listener?: Listener<T[K]>): void {
// Get the listeners for the event type.
const listeners = this.listeners.get(type);
const listeners = this.#listeners.get(type);
if (!listeners) return;
// If no listener is provided, remove all listeners for the event type.
if (!listener) {
this.#listeners.delete(type);
return;
}
// Find the listener entry.
const listenerEntry = Array.from(listeners).find((entry) => entry.listener === listener || entry.wrappedListener === listener);
@@ -120,12 +146,15 @@ export class EventEmitter<T extends EventMap> {
*/
emit<K extends keyof T>(type: K, payload: T[K]): boolean {
// Get the listeners for the event type.
const listeners = this.listeners.get(type);
const listeners = this.#listeners.get(type);
if (!listeners) return false;
// Freeze the payload to make it readonly.
const readonlyPayload = Object.freeze(payload);
// Emit the event to all listeners.
listeners.forEach((entry) => {
entry.wrappedListener(payload);
entry.wrappedListener(readonlyPayload);
});
// Return true if there are listeners for the event, false otherwise.
@@ -136,24 +165,29 @@ export class EventEmitter<T extends EventMap> {
* Remove all listeners.
*/
removeAllListeners(): void {
this.listeners.clear();
this.#listeners.clear();
}
/**
* Wait for an event to be emitted.
* Wait for an event to be emitted that matches the provided predicate function's criteria.
* @param type - The event type.
* @param predicate - The predicate function.
* @param predicate - Predicate function to filter for whether the event payload matches the criteria.
* @param timeoutMs - The timeout in milliseconds.
* @returns The event payload.
*/
async waitFor<K extends keyof T>(type: K, predicate: (payload: T[K]) => boolean, timeoutMs?: number): Promise<T[K]> {
async waitFor<K extends keyof T>(type: K, predicate: (payload: Readonly<T[K]>) => boolean, timeoutMs?: number): Promise<Readonly<T[K]>> {
// Create a promise to wait for the event to be emitted.
return new Promise((resolve, reject) => {
let timeoutId: ReturnType<typeof setTimeout> | undefined;
// Create a listener function.
const listener = (payload: T[K]): void => {
if (predicate(payload)) {
const listener = (payload: Readonly<T[K]>): void => {
try {
// If the event payload does not match the predicate condition, return.
if (!predicate(payload)) {
return;
}
// Clean up
this.off(type, listener);
if (timeoutId !== undefined) {
@@ -161,6 +195,8 @@ export class EventEmitter<T extends EventMap> {
}
resolve(payload);
} catch (error) {
reject(error);
}
};
@@ -187,7 +223,7 @@ export class EventEmitter<T extends EventMap> {
// Create a timeout variable.
let timeout: ReturnType<typeof setTimeout>;
return (detail: T[K]) => {
return (detail: Readonly<T[K]>) => {
// If a debounce timer is already pending, clear it before scheduling the next one.
if (timeout !== undefined) {
clearTimeout(timeout);
test/event-emitter.test.ts
+37
View File
@@ -124,6 +124,21 @@ const testEventEmitterOffRemovesListenerByReference = (): void => {
expect(listener).not.toHaveBeenCalled();
};
/**
* Tests that off() removes all listeners for an event type when no listener is provided.
*/
const testEventEmitterOffRemovesAllListenersForEventType = (): void => {
const emitter = new EventEmitter<TestEvents>();
const listener = vi.fn();
emitter.on('message', listener);
emitter.off('message');
expect(listener).not.toHaveBeenCalled();
expect(emitter.emit('message', 'hello')).toBe(false);
expect(emitter.emit('count', 42)).toBe(false);
};
/**
* Tests that off() does nothing when given an unknown listener reference.
*/
@@ -476,6 +491,23 @@ const testEventEmitterDebouncedOnceListener = async (): Promise<void> => {
}
};
/**
* Tests that the `waitFor` method rejects if the predicate function throws
*/
const testEventEmitterWaitForRejectsOnPredicateError = async (): Promise<void> => {
const emitter = new EventEmitter<TestEvents>();
const listener = vi.fn();
const waitPromise = emitter.waitFor('message', () => {
throw new Error('predicate error');
});
emitter.emit('message', 'hello');
await expect(waitPromise).rejects.toThrow('predicate error');
expect(listener).not.toHaveBeenCalled();
};
const runTests = async (): Promise<void> => {
test('EventEmitter: calls listeners when an event is emitted', testEventEmitterCallsListeners);
test('EventEmitter: calls multiple listeners for the same event', testEventEmitterCallsMultipleListeners);
@@ -484,6 +516,10 @@ const runTests = async (): Promise<void> => {
test('EventEmitter: returns true when emitting with listeners', testEventEmitterEmitReturnsTrueWithListeners);
test('EventEmitter: stops calling a listener after its off callback is invoked', testEventEmitterOffCallbackRemovesListener);
test('EventEmitter: removes a listener when off is called with the same reference', testEventEmitterOffRemovesListenerByReference);
test(
'EventEmitter: removes all listeners for an event type when off is called with no listener',
testEventEmitterOffRemovesAllListenersForEventType,
);
test('EventEmitter: ignores off when the listener reference is unknown', testEventEmitterOffIgnoresUnknownListener);
test('EventEmitter: ignores off for an event type with no listeners', testEventEmitterOffIgnoresUnregisteredEventType);
test('EventEmitter: calls a once listener only one time', testEventEmitterOnceListenerFiresOnce);
@@ -500,6 +536,7 @@ const runTests = async (): Promise<void> => {
test('EventEmitter: resets the debounce timer on repeated emits', testEventEmitterDebouncedTimerResetsOnRepeatedEmits);
test('EventEmitter: does not debounce when debounceMilliseconds is zero', testEventEmitterZeroDebounceDoesNotDebounce);
test('EventEmitter: debounces once listeners and invokes them only once', testEventEmitterDebouncedOnceListener);
test('EventEmitter: rejects waitFor when the predicate function throws', testEventEmitterWaitForRejectsOnPredicateError);
};
await runTests();