@kikiutils/shared 13.2.0 → 13.4.0

package/dist/event-awaiter.d.ts

@@ -4,7 +4,7 @@
  *
  * This class allows multiple consumers to `wait` for a specific key
  * and be resolved when `trigger` is called for that key, or automatically
- * resolved with `undefined` if a timeout occurs.
+ * resolved with `undefined` if a timeout occurs or an AbortSignal is triggered.
  *
  * Typical use cases include long-polling, request coordination,
  * or implementing event-driven primitives in applications or services.
@@ -17,17 +17,28 @@ declare class EventAwaiter<T> {
    * Triggers all pending promises waiting for the given key.
    * Each promise will be resolved with the provided value.
    *
-   * @param {string} [key] - Identifier for the awaited event
+   * @param {string} key - Identifier for the awaited event
    * @param {T | undefined} value - The value to resolve the awaiting promises with.
    * May be `undefined` to indicate no result or a timeout-like behavior.
    */
   trigger(key: string, value: T | undefined): void;
+  /**
+   * Triggers and resolves all pending promises across all keys.
+   *
+   * This is typically used during shutdown or cleanup to ensure that
+   * no consumer is left waiting indefinitely.
+   *
+   * @param {T | undefined} [value] - Optional value to resolve all waiters with.
+   * Defaults to `undefined`, which usually indicates cancellation or shutdown.
+   */
+  triggerAll(value?: T | undefined): void;
   /**
    * Waits for an event associated with the given key.
    *
    * The returned promise will resolve when:
    *  - `trigger(key)` is called, in which case it resolves with the provided value.
    *  - The optional timeout is reached, in which case it resolves with `undefined`.
+   *  - The optional `AbortSignal` is aborted, in which case it resolves with `undefined`.
    *
    * Behavior when multiple waiters exist for the same key:
    *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.
@@ -38,12 +49,13 @@ declare class EventAwaiter<T> {
    * @param {string} key - Identifier for the awaited event
    * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
    * If reached, the promise resolves with `undefined`.
-   * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters.
+   * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters
+   * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
    *
-   * @returns {Promise<T | undefined>} A promise that resolves with the triggered value
-   * or `undefined` if timeout occurs
+   * @returns {Promise<T | undefined>} A promise that resolves with the triggered value,
+   * or `undefined` if timeout or abort occurs
    */
-  wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict'): Promise<T | undefined>;
+  wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict', signal?: AbortSignal): Promise<T | undefined>;
   /**
    * Waits for an event in strict mode.
    * Only one waiter is allowed per key. If another waiter already exists,
@@ -52,8 +64,9 @@ declare class EventAwaiter<T> {
    * @param {string} key - Identifier for the awaited event
    * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
    * If reached, the promise resolves with `undefined`.
+   * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
    */
-  waitExclusive(key: string, timeoutMs?: number): Promise<T | undefined>;
+  waitExclusive(key: string, timeoutMs?: number, signal?: AbortSignal): Promise<T | undefined>;
   /**
    * Waits for an event in override mode.
    * If another waiter already exists for the given key, it will be canceled
@@ -62,8 +75,9 @@ declare class EventAwaiter<T> {
    * @param {string} key - Identifier for the awaited event
    * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
    * If reached, the promise resolves with `undefined`.
+   * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
    */
-  waitLatest(key: string, timeoutMs?: number): Promise<T | undefined>;
+  waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal): Promise<T | undefined>;
 }
 //#endregion
 export { EventAwaiter };

package/dist/event-awaiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-awaiter.d.ts","names":[],"sources":["../src/event-awaiter.ts"],"sourcesContent":[],"mappings":";;AAYA;;;;;;;;;;;cAAa;;;;;;;;;;8BAWmB;;;;;;;;;;;;;;;;;;;;;;uEA6BsC,QAAA;;;;;;;;;;kDA0CrB,QAAA;;;;;;;;;;+CAaH,QAAA"}
+{"version":3,"file":"event-awaiter.d.ts","names":[],"sources":["../src/event-awaiter.ts"],"sourcesContent":[],"mappings":";;AAYA;;;;;;;;;;;AAiIoE,cAjIvD,YAiIuD,CAAA,CAAA,CAAA,CAAA;UAAA;EAAA;;;;;;;;8BAtHpC;;;;;;;;;;qBAiBV;;;;;;;;;;;;;;;;;;;;;;;;+EA4B2D,cAAW,QAAA;;;;;;;;;;;0DA2DhC,cAAW,QAAA;;;;;;;;;;;uDAcd,cAAW,QAAA"}

package/dist/event-awaiter.js

@@ -4,7 +4,7 @@
 *
 * This class allows multiple consumers to `wait` for a specific key
 * and be resolved when `trigger` is called for that key, or automatically
-* resolved with `undefined` if a timeout occurs.
+* resolved with `undefined` if a timeout occurs or an AbortSignal is triggered.
 *
 * Typical use cases include long-polling, request coordination,
 * or implementing event-driven primitives in applications or services.
@@ -17,7 +17,7 @@ var EventAwaiter = class {
 	* Triggers all pending promises waiting for the given key.
 	* Each promise will be resolved with the provided value.
 	*
-	* @param {string} [key] - Identifier for the awaited event
+	* @param {string} key - Identifier for the awaited event
 	* @param {T | undefined} value - The value to resolve the awaiting promises with.
 	* May be `undefined` to indicate no result or a timeout-like behavior.
 	*/
@@ -29,11 +29,25 @@ var EventAwaiter = class {
 		}
 	}
 	/**
+	* Triggers and resolves all pending promises across all keys.
+	*
+	* This is typically used during shutdown or cleanup to ensure that
+	* no consumer is left waiting indefinitely.
+	*
+	* @param {T | undefined} [value] - Optional value to resolve all waiters with.
+	* Defaults to `undefined`, which usually indicates cancellation or shutdown.
+	*/
+	triggerAll(value = void 0) {
+		for (const [_, resolvers] of this.#promiseResolvers.entries()) resolvers.forEach((resolve) => resolve(value));
+		this.#promiseResolvers.clear();
+	}
+	/**
 	* Waits for an event associated with the given key.
 	*
 	* The returned promise will resolve when:
 	*  - `trigger(key)` is called, in which case it resolves with the provided value.
 	*  - The optional timeout is reached, in which case it resolves with `undefined`.
+	*  - The optional `AbortSignal` is aborted, in which case it resolves with `undefined`.
 	*
 	* Behavior when multiple waiters exist for the same key:
 	*  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.
@@ -44,12 +58,13 @@ var EventAwaiter = class {
 	* @param {string} key - Identifier for the awaited event
 	* @param {number} [timeoutMs] - Optional timeout (in milliseconds).
 	* If reached, the promise resolves with `undefined`.
-	* @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters.
+	* @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters
+	* @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
 	*
-	* @returns {Promise<T | undefined>} A promise that resolves with the triggered value
-	* or `undefined` if timeout occurs
+	* @returns {Promise<T | undefined>} A promise that resolves with the triggered value,
+	* or `undefined` if timeout or abort occurs
 	*/
-	wait(key, timeoutMs, mode) {
+	wait(key, timeoutMs, mode, signal) {
 		return new Promise((resolve) => {
 			const resolvers = this.#promiseResolvers.get(key) || [];
 			if (resolvers.length) switch (mode) {
@@ -70,6 +85,15 @@ var EventAwaiter = class {
 					else this.#promiseResolvers.delete(key);
 				}
 			}, timeoutMs);
+			if (signal) signal.addEventListener("abort", () => {
+				const resolvers$1 = this.#promiseResolvers.get(key);
+				if (resolvers$1?.includes(resolve)) {
+					resolve(void 0);
+					const newResolvers = resolvers$1.filter((r) => r !== resolve);
+					if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);
+					else this.#promiseResolvers.delete(key);
+				}
+			}, { once: true });
 		});
 	}
 	/**
@@ -80,9 +104,10 @@ var EventAwaiter = class {
 	* @param {string} key - Identifier for the awaited event
 	* @param {number} [timeoutMs] - Optional timeout (in milliseconds).
 	* If reached, the promise resolves with `undefined`.
+	* @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
 	*/
-	waitExclusive(key, timeoutMs) {
-		return this.wait(key, timeoutMs, "strict");
+	waitExclusive(key, timeoutMs, signal) {
+		return this.wait(key, timeoutMs, "strict", signal);
 	}
 	/**
 	* Waits for an event in override mode.
@@ -92,9 +117,10 @@ var EventAwaiter = class {
 	* @param {string} key - Identifier for the awaited event
 	* @param {number} [timeoutMs] - Optional timeout (in milliseconds).
 	* If reached, the promise resolves with `undefined`.
+	* @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
 	*/
-	waitLatest(key, timeoutMs) {
-		return this.wait(key, timeoutMs, "override");
+	waitLatest(key, timeoutMs, signal) {
+		return this.wait(key, timeoutMs, "override", signal);
 	}
 };
 

package/dist/event-awaiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-awaiter.js","names":["#promiseResolvers","resolvers"],"sources":["../src/event-awaiter.ts"],"sourcesContent":["/**\n * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.\n *\n * This class allows multiple consumers to `wait` for a specific key\n * and be resolved when `trigger` is called for that key, or automatically\n * resolved with `undefined` if a timeout occurs.\n *\n * Typical use cases include long-polling, request coordination,\n * or implementing event-driven primitives in applications or services.\n *\n * @template T - The type of value that will be resolved when the event is triggered\n */\nexport class EventAwaiter<T> {\n    #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();\n\n    /**\n     * Triggers all pending promises waiting for the given key.\n     * Each promise will be resolved with the provided value.\n     *\n     * @param {string} [key] - Identifier for the awaited event\n     * @param {T | undefined} value - The value to resolve the awaiting promises with.\n     * May be `undefined` to indicate no result or a timeout-like behavior.\n     */\n    trigger(key: string, value: T | undefined) {\n        const resolvers = this.#promiseResolvers.get(key);\n        if (resolvers) {\n            this.#promiseResolvers.delete(key);\n            resolvers?.forEach((resolve) => resolve(value));\n        }\n    }\n\n    /**\n     * Waits for an event associated with the given key.\n     *\n     * The returned promise will resolve when:\n     *  - `trigger(key)` is called, in which case it resolves with the provided value.\n     *  - The optional timeout is reached, in which case it resolves with `undefined`.\n     *\n     * Behavior when multiple waiters exist for the same key:\n     *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.\n     *  - `strict` mode: throws an error if a waiter already exists for the given key.\n     *  - `override` mode: cancels all existing waiters (resolving them with `undefined`)\n     *    and only keeps the latest one.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters.\n     *\n     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value\n     * or `undefined` if timeout occurs\n     */\n    wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict') {\n        return new Promise<T | undefined>((resolve) => {\n            const resolvers = this.#promiseResolvers.get(key) || [];\n            if (resolvers.length) {\n                switch (mode) {\n                    case 'override':\n                        resolvers.forEach((r) => r(undefined));\n                        resolvers.length = 0;\n                        break;\n                    case 'strict':\n                        throw new Error(`Duplicate wait detected for key: ${key}`);\n                }\n            }\n\n            resolvers.push(resolve);\n            this.#promiseResolvers.set(key, resolvers);\n            if (timeoutMs) {\n                setTimeout(\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    timeoutMs,\n                );\n            }\n        });\n    }\n\n    /**\n     * Waits for an event in strict mode.\n     * Only one waiter is allowed per key. If another waiter already exists,\n     * this method will throw an error.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     */\n    waitExclusive(key: string, timeoutMs?: number) {\n        return this.wait(key, timeoutMs, 'strict');\n    }\n\n    /**\n     * Waits for an event in override mode.\n     * If another waiter already exists for the given key, it will be canceled\n     * (resolved with `undefined`) and replaced by the new waiter.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     */\n    waitLatest(key: string, timeoutMs?: number) {\n        return this.wait(key, timeoutMs, 'override');\n    }\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,IAAa,eAAb,MAA6B;CACzB,oCAAoB,IAAI,KAA8E;;;;;;;;;CAUtG,QAAQ,KAAa,OAAsB;EACvC,MAAM,YAAY,MAAKA,iBAAkB,IAAI,IAAI;AACjD,MAAI,WAAW;AACX,SAAKA,iBAAkB,OAAO,IAAI;AAClC,cAAW,SAAS,YAAY,QAAQ,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;CAyBvD,KAAK,KAAa,WAAoB,MAA8B;AAChE,SAAO,IAAI,SAAwB,YAAY;GAC3C,MAAM,YAAY,MAAKA,iBAAkB,IAAI,IAAI,IAAI,EAAE;AACvD,OAAI,UAAU,OACV,SAAQ,MAAR;IACI,KAAK;AACD,eAAU,SAAS,MAAM,EAAE,OAAU,CAAC;AACtC,eAAU,SAAS;AACnB;IACJ,KAAK,SACD,OAAM,IAAI,MAAM,oCAAoC,MAAM;;AAItE,aAAU,KAAK,QAAQ;AACvB,SAAKA,iBAAkB,IAAI,KAAK,UAAU;AAC1C,OAAI,UACA,kBACU;IACF,MAAMC,cAAY,MAAKD,iBAAkB,IAAI,IAAI;AACjD,QAAIC,aAAW,SAAS,QAAQ,EAAE;AAC9B,aAAQ,OAAU;KAClB,MAAM,eAAeA,YAAU,QAAQ,MAAM,MAAM,QAAQ;AAC3D,SAAI,aAAa,OAAQ,OAAKD,iBAAkB,IAAI,KAAK,aAAa;SACjE,OAAKA,iBAAkB,OAAO,IAAI;;MAG/C,UACH;IAEP;;;;;;;;;;;CAYN,cAAc,KAAa,WAAoB;AAC3C,SAAO,KAAK,KAAK,KAAK,WAAW,SAAS;;;;;;;;;;;CAY9C,WAAW,KAAa,WAAoB;AACxC,SAAO,KAAK,KAAK,KAAK,WAAW,WAAW"}
+{"version":3,"file":"event-awaiter.js","names":["#promiseResolvers","resolvers"],"sources":["../src/event-awaiter.ts"],"sourcesContent":["/**\n * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.\n *\n * This class allows multiple consumers to `wait` for a specific key\n * and be resolved when `trigger` is called for that key, or automatically\n * resolved with `undefined` if a timeout occurs or an AbortSignal is triggered.\n *\n * Typical use cases include long-polling, request coordination,\n * or implementing event-driven primitives in applications or services.\n *\n * @template T - The type of value that will be resolved when the event is triggered\n */\nexport class EventAwaiter<T> {\n    #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();\n\n    /**\n     * Triggers all pending promises waiting for the given key.\n     * Each promise will be resolved with the provided value.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {T | undefined} value - The value to resolve the awaiting promises with.\n     * May be `undefined` to indicate no result or a timeout-like behavior.\n     */\n    trigger(key: string, value: T | undefined) {\n        const resolvers = this.#promiseResolvers.get(key);\n        if (resolvers) {\n            this.#promiseResolvers.delete(key);\n            resolvers?.forEach((resolve) => resolve(value));\n        }\n    }\n\n    /**\n     * Triggers and resolves all pending promises across all keys.\n     *\n     * This is typically used during shutdown or cleanup to ensure that\n     * no consumer is left waiting indefinitely.\n     *\n     * @param {T | undefined} [value] - Optional value to resolve all waiters with.\n     * Defaults to `undefined`, which usually indicates cancellation or shutdown.\n     */\n    triggerAll(value: T | undefined = undefined) {\n        for (const [_, resolvers] of this.#promiseResolvers.entries()) resolvers.forEach((resolve) => resolve(value));\n        this.#promiseResolvers.clear();\n    }\n\n    /**\n     * Waits for an event associated with the given key.\n     *\n     * The returned promise will resolve when:\n     *  - `trigger(key)` is called, in which case it resolves with the provided value.\n     *  - The optional timeout is reached, in which case it resolves with `undefined`.\n     *  - The optional `AbortSignal` is aborted, in which case it resolves with `undefined`.\n     *\n     * Behavior when multiple waiters exist for the same key:\n     *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.\n     *  - `strict` mode: throws an error if a waiter already exists for the given key.\n     *  - `override` mode: cancels all existing waiters (resolving them with `undefined`)\n     *    and only keeps the latest one.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters\n     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`\n     *\n     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value,\n     * or `undefined` if timeout or abort occurs\n     */\n    wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict', signal?: AbortSignal) {\n        return new Promise<T | undefined>((resolve) => {\n            const resolvers = this.#promiseResolvers.get(key) || [];\n            if (resolvers.length) {\n                switch (mode) {\n                    case 'override':\n                        resolvers.forEach((r) => r(undefined));\n                        resolvers.length = 0;\n                        break;\n                    case 'strict':\n                        throw new Error(`Duplicate wait detected for key: ${key}`);\n                }\n            }\n\n            resolvers.push(resolve);\n            this.#promiseResolvers.set(key, resolvers);\n            if (timeoutMs) {\n                setTimeout(\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    timeoutMs,\n                );\n            }\n\n            if (signal) {\n                signal.addEventListener(\n                    'abort',\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    { once: true },\n                );\n            }\n        });\n    }\n\n    /**\n     * Waits for an event in strict mode.\n     * Only one waiter is allowed per key. If another waiter already exists,\n     * this method will throw an error.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`\n     */\n    waitExclusive(key: string, timeoutMs?: number, signal?: AbortSignal) {\n        return this.wait(key, timeoutMs, 'strict', signal);\n    }\n\n    /**\n     * Waits for an event in override mode.\n     * If another waiter already exists for the given key, it will be canceled\n     * (resolved with `undefined`) and replaced by the new waiter.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`\n     */\n    waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal) {\n        return this.wait(key, timeoutMs, 'override', signal);\n    }\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,IAAa,eAAb,MAA6B;CACzB,oCAAoB,IAAI,KAA8E;;;;;;;;;CAUtG,QAAQ,KAAa,OAAsB;EACvC,MAAM,YAAY,MAAKA,iBAAkB,IAAI,IAAI;AACjD,MAAI,WAAW;AACX,SAAKA,iBAAkB,OAAO,IAAI;AAClC,cAAW,SAAS,YAAY,QAAQ,MAAM,CAAC;;;;;;;;;;;;CAavD,WAAW,QAAuB,QAAW;AACzC,OAAK,MAAM,CAAC,GAAG,cAAc,MAAKA,iBAAkB,SAAS,CAAE,WAAU,SAAS,YAAY,QAAQ,MAAM,CAAC;AAC7G,QAAKA,iBAAkB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;CA0BlC,KAAK,KAAa,WAAoB,MAA8B,QAAsB;AACtF,SAAO,IAAI,SAAwB,YAAY;GAC3C,MAAM,YAAY,MAAKA,iBAAkB,IAAI,IAAI,IAAI,EAAE;AACvD,OAAI,UAAU,OACV,SAAQ,MAAR;IACI,KAAK;AACD,eAAU,SAAS,MAAM,EAAE,OAAU,CAAC;AACtC,eAAU,SAAS;AACnB;IACJ,KAAK,SACD,OAAM,IAAI,MAAM,oCAAoC,MAAM;;AAItE,aAAU,KAAK,QAAQ;AACvB,SAAKA,iBAAkB,IAAI,KAAK,UAAU;AAC1C,OAAI,UACA,kBACU;IACF,MAAMC,cAAY,MAAKD,iBAAkB,IAAI,IAAI;AACjD,QAAIC,aAAW,SAAS,QAAQ,EAAE;AAC9B,aAAQ,OAAU;KAClB,MAAM,eAAeA,YAAU,QAAQ,MAAM,MAAM,QAAQ;AAC3D,SAAI,aAAa,OAAQ,OAAKD,iBAAkB,IAAI,KAAK,aAAa;SACjE,OAAKA,iBAAkB,OAAO,IAAI;;MAG/C,UACH;AAGL,OAAI,OACA,QAAO,iBACH,eACM;IACF,MAAMC,cAAY,MAAKD,iBAAkB,IAAI,IAAI;AACjD,QAAIC,aAAW,SAAS,QAAQ,EAAE;AAC9B,aAAQ,OAAU;KAClB,MAAM,eAAeA,YAAU,QAAQ,MAAM,MAAM,QAAQ;AAC3D,SAAI,aAAa,OAAQ,OAAKD,iBAAkB,IAAI,KAAK,aAAa;SACjE,OAAKA,iBAAkB,OAAO,IAAI;;MAG/C,EAAE,MAAM,MAAM,CACjB;IAEP;;;;;;;;;;;;CAaN,cAAc,KAAa,WAAoB,QAAsB;AACjE,SAAO,KAAK,KAAK,KAAK,WAAW,UAAU,OAAO;;;;;;;;;;;;CAatD,WAAW,KAAa,WAAoB,QAAsB;AAC9D,SAAO,KAAK,KAAK,KAAK,WAAW,YAAY,OAAO"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "13.2.0",
+  "version": "13.4.0",
   "description": "A lightweight and modular utility library for modern JavaScript and TypeScript — includes secure hashing, flexible logging, datetime tools, Vue/web helpers, storage abstraction, and more.",
   "author": "kiki-kanri",
   "license": "MIT",

package/src/event-awaiter.ts

@@ -3,7 +3,7 @@
  *
  * This class allows multiple consumers to `wait` for a specific key
  * and be resolved when `trigger` is called for that key, or automatically
- * resolved with `undefined` if a timeout occurs.
+ * resolved with `undefined` if a timeout occurs or an AbortSignal is triggered.
  *
  * Typical use cases include long-polling, request coordination,
  * or implementing event-driven primitives in applications or services.
@@ -17,7 +17,7 @@ export class EventAwaiter<T> {
      * Triggers all pending promises waiting for the given key.
      * Each promise will be resolved with the provided value.
      *
-     * @param {string} [key] - Identifier for the awaited event
+     * @param {string} key - Identifier for the awaited event
      * @param {T | undefined} value - The value to resolve the awaiting promises with.
      * May be `undefined` to indicate no result or a timeout-like behavior.
      */
@@ -29,12 +29,27 @@ export class EventAwaiter<T> {
         }
     }
 
+    /**
+     * Triggers and resolves all pending promises across all keys.
+     *
+     * This is typically used during shutdown or cleanup to ensure that
+     * no consumer is left waiting indefinitely.
+     *
+     * @param {T | undefined} [value] - Optional value to resolve all waiters with.
+     * Defaults to `undefined`, which usually indicates cancellation or shutdown.
+     */
+    triggerAll(value: T | undefined = undefined) {
+        for (const [_, resolvers] of this.#promiseResolvers.entries()) resolvers.forEach((resolve) => resolve(value));
+        this.#promiseResolvers.clear();
+    }
+
     /**
      * Waits for an event associated with the given key.
      *
      * The returned promise will resolve when:
      *  - `trigger(key)` is called, in which case it resolves with the provided value.
      *  - The optional timeout is reached, in which case it resolves with `undefined`.
+     *  - The optional `AbortSignal` is aborted, in which case it resolves with `undefined`.
      *
      * Behavior when multiple waiters exist for the same key:
      *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.
@@ -45,12 +60,13 @@ export class EventAwaiter<T> {
      * @param {string} key - Identifier for the awaited event
      * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
      * If reached, the promise resolves with `undefined`.
-     * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters.
+     * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters
+     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
      *
-     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value
-     * or `undefined` if timeout occurs
+     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value,
+     * or `undefined` if timeout or abort occurs
      */
-    wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict') {
+    wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict', signal?: AbortSignal) {
         return new Promise<T | undefined>((resolve) => {
             const resolvers = this.#promiseResolvers.get(key) || [];
             if (resolvers.length) {
@@ -80,6 +96,22 @@ export class EventAwaiter<T> {
                     timeoutMs,
                 );
             }
+
+            if (signal) {
+                signal.addEventListener(
+                    'abort',
+                    () => {
+                        const resolvers = this.#promiseResolvers.get(key);
+                        if (resolvers?.includes(resolve)) {
+                            resolve(undefined);
+                            const newResolvers = resolvers.filter((r) => r !== resolve);
+                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);
+                            else this.#promiseResolvers.delete(key);
+                        }
+                    },
+                    { once: true },
+                );
+            }
         });
     }
 
@@ -91,9 +123,10 @@ export class EventAwaiter<T> {
      * @param {string} key - Identifier for the awaited event
      * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
      * If reached, the promise resolves with `undefined`.
+     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
      */
-    waitExclusive(key: string, timeoutMs?: number) {
-        return this.wait(key, timeoutMs, 'strict');
+    waitExclusive(key: string, timeoutMs?: number, signal?: AbortSignal) {
+        return this.wait(key, timeoutMs, 'strict', signal);
     }
 
     /**
@@ -104,8 +137,9 @@ export class EventAwaiter<T> {
      * @param {string} key - Identifier for the awaited event
      * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
      * If reached, the promise resolves with `undefined`.
+     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
      */
-    waitLatest(key: string, timeoutMs?: number) {
-        return this.wait(key, timeoutMs, 'override');
+    waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal) {
+        return this.wait(key, timeoutMs, 'override', signal);
     }
 }