@kikiutils/shared 18.0.0 → 18.1.0

package/dist/enum.js

@@ -2,24 +2,25 @@
 /**
 * Extracts only the numeric values from an enumeration-like object.
 *
-* @template T - The type of the enum object
+* @typeParam T - The type of the enum object.
 *
-* @param {T} enumObject - The enumeration-like object to extract numeric values from,
+* @param enumObject - The enumeration-like object to extract numeric values from,
 * the object can contain numeric values, string values, or both.
 *
-* @returns {Extract<T[keyof T], number>[]} An array of numeric values extracted from the enum object
+* @returns An array of numeric values extracted from the enum object.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { getEnumNumberValues } from '@kikiutils/shared/enum';
 *
 * enum RecordType {
-*   Receive = 0,
-*   Send = 1,
-*   Unknown = 'unknown'
+*     Receive = 0,
+*     Send = 1,
+*     Unknown = 'unknown',
 * }
 *
-* console.log(getEnumNumberValues(RecordType)); // [0, 1]
+* console.log(getEnumNumberValues(RecordType)); // => [0, 1]
 * ```
 */
 function getEnumNumberValues(enumObject) {
@@ -28,24 +29,25 @@ function getEnumNumberValues(enumObject) {
 /**
 * Extracts only the string values from an enumeration-like object.
 *
-* @template T - The type of the enum object
+* @typeParam T - The type of the enum object.
 *
-* @param {T} enumObject - The enumeration-like object to extract string values from,
+* @param enumObject - The enumeration-like object to extract string values from,
 * the object can contain numeric values, string values, or both.
 *
-* @returns {Extract<T[keyof T], string>[]} An array of string values extracted from the enum object
+* @returns An array of string values extracted from the enum object.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { getEnumStringValues } from '@kikiutils/shared/enum';
 *
 * enum RecordType {
-*   Receive = 0,
-*   Send = 1,
-*   Unknown = 'unknown'
+*     Receive = 0,
+*     Send = 1,
+*     Unknown = 'unknown',
 * }
 *
-* console.log(getEnumStringValues(RecordType)); // ['unknown']
+* console.log(getEnumStringValues(RecordType)); // => ['unknown']
 * ```
 */
 function getEnumStringValues(enumObject) {
@@ -54,47 +56,49 @@ function getEnumStringValues(enumObject) {
 /**
 * Extracts all values from an enumeration-like object.
 *
+* @remarks
 * This function handles TypeScript enums correctly by accounting for the reverse mapping
 * that occurs with numeric enums. It works with pure numeric enums, pure string enums,
 * and mixed enums.
 *
-* @template T - The type of the enum object
+* @typeParam T - The type of the enum object.
 *
-* @param {T} enumObject - The enumeration-like object to extract values from,
+* @param enumObject - The enumeration-like object to extract values from,
 * the object can contain numeric values, string values, or both.
 *
-* @returns {(T[keyof T])[]} An array containing all the values from the enum object
+* @returns An array containing all the values from the enum object.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { getEnumValues } from '@kikiutils/shared/enum';
 *
 * // Numeric enum
 * enum Status {
-*   Active = 0,
-*   Inactive = 1,
-*   Pending = 2
+*     Active = 0,
+*     Inactive = 1,
+*     Pending = 2,
 * }
 *
-* console.log(getEnumValues(Status)); // [0, 1, 2]
+* console.log(getEnumValues(Status)); // => [0, 1, 2]
 *
 * // String enum
 * enum Color {
-*   Red = 'RED',
-*   Green = 'GREEN',
-*   Blue = 'BLUE'
+*     Red = 'RED',
+*     Green = 'GREEN',
+*     Blue = 'BLUE',
 * }
 *
-* console.log(getEnumValues(Color)); // ['RED', 'GREEN', 'BLUE']
+* console.log(getEnumValues(Color)); // => ['RED', 'GREEN', 'BLUE']
 *
 * // Mixed enum
 * enum RecordType {
-*   Receive = 0,
-*   Send = 1,
-*   Unknown = 'unknown'
+*     Receive = 0,
+*     Send = 1,
+*     Unknown = 'unknown',
 * }
 *
-* console.log(getEnumValues(RecordType)); // [0, 1, 'unknown']
+* console.log(getEnumValues(RecordType)); // => [0, 1, 'unknown']
 * ```
 */
 function getEnumValues(enumObject) {

package/dist/enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"enum.js","names":[],"sources":["../src/enum.ts"],"sourcesContent":["/**\n * Extracts only the numeric values from an enumeration-like object.\n *\n * @template T - The type of the enum object\n *\n * @param {T} enumObject - The enumeration-like object to extract numeric values from,\n * the object can contain numeric values, string values, or both.\n *\n * @returns {Extract<T[keyof T], number>[]} An array of numeric values extracted from the enum object\n *\n * @example\n * ```typescript\n * import { getEnumNumberValues } from '@kikiutils/shared/enum';\n *\n * enum RecordType {\n *   Receive = 0,\n *   Send = 1,\n *   Unknown = 'unknown'\n * }\n *\n * console.log(getEnumNumberValues(RecordType)); // [0, 1]\n * ```\n */\nexport function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], number>[] {\n    return getEnumValues(enumObject).filter((value) => typeof value === 'number');\n}\n\n/**\n * Extracts only the string values from an enumeration-like object.\n *\n * @template T - The type of the enum object\n *\n * @param {T} enumObject - The enumeration-like object to extract string values from,\n * the object can contain numeric values, string values, or both.\n *\n * @returns {Extract<T[keyof T], string>[]} An array of string values extracted from the enum object\n *\n * @example\n * ```typescript\n * import { getEnumStringValues } from '@kikiutils/shared/enum';\n *\n * enum RecordType {\n *   Receive = 0,\n *   Send = 1,\n *   Unknown = 'unknown'\n * }\n *\n * console.log(getEnumStringValues(RecordType)); // ['unknown']\n * ```\n */\nexport function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], string>[] {\n    return getEnumValues(enumObject).filter((value) => typeof value === 'string');\n}\n\n/**\n * Extracts all values from an enumeration-like object.\n *\n * This function handles TypeScript enums correctly by accounting for the reverse mapping\n * that occurs with numeric enums. It works with pure numeric enums, pure string enums,\n * and mixed enums.\n *\n * @template T - The type of the enum object\n *\n * @param {T} enumObject - The enumeration-like object to extract values from,\n * the object can contain numeric values, string values, or both.\n *\n * @returns {(T[keyof T])[]} An array containing all the values from the enum object\n *\n * @example\n * ```typescript\n * import { getEnumValues } from '@kikiutils/shared/enum';\n *\n * // Numeric enum\n * enum Status {\n *   Active = 0,\n *   Inactive = 1,\n *   Pending = 2\n * }\n *\n * console.log(getEnumValues(Status)); // [0, 1, 2]\n *\n * // String enum\n * enum Color {\n *   Red = 'RED',\n *   Green = 'GREEN',\n *   Blue = 'BLUE'\n * }\n *\n * console.log(getEnumValues(Color)); // ['RED', 'GREEN', 'BLUE']\n *\n * // Mixed enum\n * enum RecordType {\n *   Receive = 0,\n *   Send = 1,\n *   Unknown = 'unknown'\n * }\n *\n * console.log(getEnumValues(RecordType)); // [0, 1, 'unknown']\n * ```\n */\nexport function getEnumValues<T extends Record<string, any>>(enumObject: T): (T[keyof T])[] {\n    const values = Object.values(enumObject);\n    const hasNumberValues = values.some((value) => typeof value === 'number');\n    if (!hasNumberValues) return values;\n    return Object.keys(enumObject).filter((key) => Number.isNaN(Number(key))).map((key) => enumObject[key]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,oBAAmD,YAA8C;CAC7G,OAAO,cAAc,UAAU,CAAC,CAAC,QAAQ,UAAU,OAAO,UAAU,QAAQ;AAChF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,oBAAmD,YAA8C;CAC7G,OAAO,cAAc,UAAU,CAAC,CAAC,QAAQ,UAAU,OAAO,UAAU,QAAQ;AAChF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,cAA6C,YAA+B;CACxF,MAAM,SAAS,OAAO,OAAO,UAAU;CAEvC,IAAI,CADoB,OAAO,MAAM,UAAU,OAAO,UAAU,QAC7C,GAAG,OAAO;CAC7B,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,QAAQ,QAAQ,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,WAAW,IAAI;AAC1G"}
+{"version":3,"file":"enum.js","names":[],"sources":["../src/enum.ts"],"sourcesContent":["/**\n * Extracts only the numeric values from an enumeration-like object.\n *\n * @typeParam T - The type of the enum object.\n *\n * @param enumObject - The enumeration-like object to extract numeric values from,\n * the object can contain numeric values, string values, or both.\n *\n * @returns An array of numeric values extracted from the enum object.\n *\n * @example\n *\n * ```ts\n * import { getEnumNumberValues } from '@kikiutils/shared/enum';\n *\n * enum RecordType {\n *     Receive = 0,\n *     Send = 1,\n *     Unknown = 'unknown',\n * }\n *\n * console.log(getEnumNumberValues(RecordType)); // => [0, 1]\n * ```\n */\nexport function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], number>[] {\n    return getEnumValues(enumObject).filter((value) => typeof value === 'number');\n}\n\n/**\n * Extracts only the string values from an enumeration-like object.\n *\n * @typeParam T - The type of the enum object.\n *\n * @param enumObject - The enumeration-like object to extract string values from,\n * the object can contain numeric values, string values, or both.\n *\n * @returns An array of string values extracted from the enum object.\n *\n * @example\n *\n * ```ts\n * import { getEnumStringValues } from '@kikiutils/shared/enum';\n *\n * enum RecordType {\n *     Receive = 0,\n *     Send = 1,\n *     Unknown = 'unknown',\n * }\n *\n * console.log(getEnumStringValues(RecordType)); // => ['unknown']\n * ```\n */\nexport function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], string>[] {\n    return getEnumValues(enumObject).filter((value) => typeof value === 'string');\n}\n\n/**\n * Extracts all values from an enumeration-like object.\n *\n * @remarks\n * This function handles TypeScript enums correctly by accounting for the reverse mapping\n * that occurs with numeric enums. It works with pure numeric enums, pure string enums,\n * and mixed enums.\n *\n * @typeParam T - The type of the enum object.\n *\n * @param enumObject - The enumeration-like object to extract values from,\n * the object can contain numeric values, string values, or both.\n *\n * @returns An array containing all the values from the enum object.\n *\n * @example\n *\n * ```ts\n * import { getEnumValues } from '@kikiutils/shared/enum';\n *\n * // Numeric enum\n * enum Status {\n *     Active = 0,\n *     Inactive = 1,\n *     Pending = 2,\n * }\n *\n * console.log(getEnumValues(Status)); // => [0, 1, 2]\n *\n * // String enum\n * enum Color {\n *     Red = 'RED',\n *     Green = 'GREEN',\n *     Blue = 'BLUE',\n * }\n *\n * console.log(getEnumValues(Color)); // => ['RED', 'GREEN', 'BLUE']\n *\n * // Mixed enum\n * enum RecordType {\n *     Receive = 0,\n *     Send = 1,\n *     Unknown = 'unknown',\n * }\n *\n * console.log(getEnumValues(RecordType)); // => [0, 1, 'unknown']\n * ```\n */\nexport function getEnumValues<T extends Record<string, any>>(enumObject: T): (T[keyof T])[] {\n    const values = Object.values(enumObject);\n    const hasNumberValues = values.some((value) => typeof value === 'number');\n    if (!hasNumberValues) return values;\n    return Object.keys(enumObject).filter((key) => Number.isNaN(Number(key))).map((key) => enumObject[key]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,oBAAmD,YAA8C;CAC7G,OAAO,cAAc,UAAU,CAAC,CAAC,QAAQ,UAAU,OAAO,UAAU,QAAQ;AAChF;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,oBAAmD,YAA8C;CAC7G,OAAO,cAAc,UAAU,CAAC,CAAC,QAAQ,UAAU,OAAO,UAAU,QAAQ;AAChF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,cAA6C,YAA+B;CACxF,MAAM,SAAS,OAAO,OAAO,UAAU;CAEvC,IAAI,CADoB,OAAO,MAAM,UAAU,OAAO,UAAU,QAC7C,GAAG,OAAO;CAC7B,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,QAAQ,QAAQ,OAAO,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,WAAW,IAAI;AAC1G"}

package/dist/env.d.ts

@@ -2,43 +2,50 @@
 /**
  * Custom error class for handling missing environment variables.
  *
+ * @remarks
  * Extends the built-in `Error` class and includes the missing key.
- *
- * @extends {Error}
  */
-declare class EnvironmentNotFoundError extends Error {
+export declare class EnvironmentNotFoundError extends Error {
   readonly key: string;
   /**
-   * Creates a new EnvironmentNotFoundError.
+   * Creates an error identifying a missing environment variable.
    *
-   * @param {string} key - The missing environment variable key
+   * @param key - The missing environment variable key.
    */
   constructor(key: string);
 }
 /**
  * Retrieves the value of an environment variable, or throws an error if it is not defined.
  *
- * Only checks for `process.env[key] === undefined`. An empty string (e.g. '') or any falsy string
+ * @remarks
+ * Only checks for `process.env[key] === undefined`. An empty string (for example `''`) or any falsy string
  * value like `'0'` or `'false'` is considered a valid (defined) value.
  *
- * @param {string} key - The environment variable key to retrieve
+ * @param key - The environment variable key to retrieve.
  *
- * @returns {string} The value of the environment variable
+ * @returns The value of the environment variable.
  *
- * @throws {EnvironmentNotFoundError} If the environment variable is not defined
+ * @throws EnvironmentNotFoundError if the environment variable is not defined.
  *
  * @example
- * ```typescript
- * import { checkAndGetEnvValue } from '@kikiutils/shared/env';
+ *
+ * ```ts
+ * import {
+ *     checkAndGetEnvValue,
+ *     EnvironmentNotFoundError,
+ * } from '@kikiutils/shared/env';
  *
  * process.env.API_KEY = '';
- * checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered "defined")
+ * checkAndGetEnvValue('API_KEY'); // => ''
  *
  * delete process.env.API_KEY;
- * checkAndGetEnvValue('API_KEY'); // ❌ Throws EnvironmentNotFoundError
+ * try {
+ *     checkAndGetEnvValue('API_KEY');
+ * } catch (error) {
+ *     console.log(error instanceof EnvironmentNotFoundError); // => true
+ * }
  * ```
  */
-declare function checkAndGetEnvValue(key: string): string;
+export declare function checkAndGetEnvValue(key: string): string;
 //#endregion
-export { EnvironmentNotFoundError, checkAndGetEnvValue };
 //# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","names":[],"sources":["../src/env.ts"],"mappings":";;;;;;;;cAOa,iCAAiC;WACjC;;;;;;EAOG,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BA,oBAAoB"}
+{"version":3,"file":"env.d.ts","names":[],"sources":["../src/env.ts"],"mappings":";;;;;;;qBAMa,iCAAiC;WACjC;;;;;;EAOG,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwCA,oBAAoB"}

package/dist/env.js

@@ -2,16 +2,15 @@
 /**
 * Custom error class for handling missing environment variables.
 *
+* @remarks
 * Extends the built-in `Error` class and includes the missing key.
-*
-* @extends {Error}
 */
 var EnvironmentNotFoundError = class extends Error {
 	key;
 	/**
-	* Creates a new EnvironmentNotFoundError.
+	* Creates an error identifying a missing environment variable.
 	*
-	* @param {string} key - The missing environment variable key
+	* @param key - The missing environment variable key.
 	*/
 	constructor(key) {
 		super(`Missing environment variable: ${key}`);
@@ -23,24 +22,33 @@ var EnvironmentNotFoundError = class extends Error {
 /**
 * Retrieves the value of an environment variable, or throws an error if it is not defined.
 *
-* Only checks for `process.env[key] === undefined`. An empty string (e.g. '') or any falsy string
+* @remarks
+* Only checks for `process.env[key] === undefined`. An empty string (for example `''`) or any falsy string
 * value like `'0'` or `'false'` is considered a valid (defined) value.
 *
-* @param {string} key - The environment variable key to retrieve
+* @param key - The environment variable key to retrieve.
 *
-* @returns {string} The value of the environment variable
+* @returns The value of the environment variable.
 *
-* @throws {EnvironmentNotFoundError} If the environment variable is not defined
+* @throws EnvironmentNotFoundError if the environment variable is not defined.
 *
 * @example
-* ```typescript
-* import { checkAndGetEnvValue } from '@kikiutils/shared/env';
+*
+* ```ts
+* import {
+*     checkAndGetEnvValue,
+*     EnvironmentNotFoundError,
+* } from '@kikiutils/shared/env';
 *
 * process.env.API_KEY = '';
-* checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered "defined")
+* checkAndGetEnvValue('API_KEY'); // => ''
 *
 * delete process.env.API_KEY;
-* checkAndGetEnvValue('API_KEY'); // ❌ Throws EnvironmentNotFoundError
+* try {
+*     checkAndGetEnvValue('API_KEY');
+* } catch (error) {
+*     console.log(error instanceof EnvironmentNotFoundError); // => true
+* }
 * ```
 */
 function checkAndGetEnvValue(key) {

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","names":[],"sources":["../src/env.ts"],"sourcesContent":["/**\n * Custom error class for handling missing environment variables.\n *\n * Extends the built-in `Error` class and includes the missing key.\n *\n * @extends {Error}\n */\nexport class EnvironmentNotFoundError extends Error {\n    readonly key: string;\n\n    /**\n     * Creates a new EnvironmentNotFoundError.\n     *\n     * @param {string} key - The missing environment variable key\n     */\n    constructor(key: string) {\n        super(`Missing environment variable: ${key}`);\n        this.key = key;\n        this.name = this.constructor.name;\n        Error.captureStackTrace?.(this, this.constructor);\n    }\n}\n\n/**\n * Retrieves the value of an environment variable, or throws an error if it is not defined.\n *\n * Only checks for `process.env[key] === undefined`. An empty string (e.g. '') or any falsy string\n * value like `'0'` or `'false'` is considered a valid (defined) value.\n *\n * @param {string} key - The environment variable key to retrieve\n *\n * @returns {string} The value of the environment variable\n *\n * @throws {EnvironmentNotFoundError} If the environment variable is not defined\n *\n * @example\n * ```typescript\n * import { checkAndGetEnvValue } from '@kikiutils/shared/env';\n *\n * process.env.API_KEY = '';\n * checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered \"defined\")\n *\n * delete process.env.API_KEY;\n * checkAndGetEnvValue('API_KEY'); // ❌ Throws EnvironmentNotFoundError\n * ```\n */\nexport function checkAndGetEnvValue(key: string) {\n    if (process.env[key] === undefined) throw new EnvironmentNotFoundError(key);\n    return process.env[key];\n}\n"],"mappings":";;;;;;;;AAOA,IAAa,2BAAb,cAA8C,MAAM;CAChD;;;;;;CAOA,YAAY,KAAa;EACrB,MAAM,iCAAiC,KAAK;EAC5C,KAAK,MAAM;EACX,KAAK,OAAO,KAAK,YAAY;EAC7B,MAAM,oBAAoB,MAAM,KAAK,WAAW;CACpD;AACJ;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,oBAAoB,KAAa;CAC7C,IAAI,QAAQ,IAAI,SAAS,KAAA,GAAW,MAAM,IAAI,yBAAyB,GAAG;CAC1E,OAAO,QAAQ,IAAI;AACvB"}
+{"version":3,"file":"env.js","names":[],"sources":["../src/env.ts"],"sourcesContent":["/**\n * Custom error class for handling missing environment variables.\n *\n * @remarks\n * Extends the built-in `Error` class and includes the missing key.\n */\nexport class EnvironmentNotFoundError extends Error {\n    readonly key: string;\n\n    /**\n     * Creates an error identifying a missing environment variable.\n     *\n     * @param key - The missing environment variable key.\n     */\n    constructor(key: string) {\n        super(`Missing environment variable: ${key}`);\n        this.key = key;\n        this.name = this.constructor.name;\n        Error.captureStackTrace?.(this, this.constructor);\n    }\n}\n\n/**\n * Retrieves the value of an environment variable, or throws an error if it is not defined.\n *\n * @remarks\n * Only checks for `process.env[key] === undefined`. An empty string (for example `''`) or any falsy string\n * value like `'0'` or `'false'` is considered a valid (defined) value.\n *\n * @param key - The environment variable key to retrieve.\n *\n * @returns The value of the environment variable.\n *\n * @throws EnvironmentNotFoundError if the environment variable is not defined.\n *\n * @example\n *\n * ```ts\n * import {\n *     checkAndGetEnvValue,\n *     EnvironmentNotFoundError,\n * } from '@kikiutils/shared/env';\n *\n * process.env.API_KEY = '';\n * checkAndGetEnvValue('API_KEY'); // => ''\n *\n * delete process.env.API_KEY;\n * try {\n *     checkAndGetEnvValue('API_KEY');\n * } catch (error) {\n *     console.log(error instanceof EnvironmentNotFoundError); // => true\n * }\n * ```\n */\nexport function checkAndGetEnvValue(key: string) {\n    if (process.env[key] === undefined) throw new EnvironmentNotFoundError(key);\n    return process.env[key];\n}\n"],"mappings":";;;;;;;AAMA,IAAa,2BAAb,cAA8C,MAAM;CAChD;;;;;;CAOA,YAAY,KAAa;EACrB,MAAM,iCAAiC,KAAK;EAC5C,KAAK,MAAM;EACX,KAAK,OAAO,KAAK,YAAY;EAC7B,MAAM,oBAAoB,MAAM,KAAK,WAAW;CACpD;AACJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,oBAAoB,KAAa;CAC7C,IAAI,QAAQ,IAAI,SAAS,KAAA,GAAW,MAAM,IAAI,yBAAyB,GAAG;CAC1E,OAAO,QAAQ,IAAI;AACvB"}

package/dist/event-awaiter.d.ts

@@ -1,84 +1,79 @@
 //#region src/event-awaiter.d.ts
 /**
- * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.
+ * An asynchronous keyed event rendezvous for one or more waiting consumers.
  *
- * 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 or an AbortSignal is triggered.
+ * @remarks
+ * Triggers resolve the currently registered waiters; values are not retained for future waits.
+ * Timeouts and subsequent abort events resolve affected waiters with `undefined`.
+ * Use `triggerAll` to resolve pending waits during cleanup. Timers and abort listeners are not proactively
+ * removed by triggers, so they may remain until their timeout or abort event occurs.
  *
- * Typical use cases include long-polling, request coordination,
- * or implementing event-driven primitives in applications or services.
- *
- * @template T - The type of value that will be resolved when the event is triggered
+ * @typeParam T - The value delivered to waiting consumers.
  */
-declare class EventAwaiter<T> {
+export declare class EventAwaiter<T> {
   #private;
   /**
-   * Triggers all pending promises waiting for the given key.
-   * Each promise will be resolved with the provided value.
+   * Resolves all currently pending waits for a key with the supplied value.
    *
-   * @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.
+   * @param key - The event identifier; a key without pending waits has no effect.
+   * @param value - The delivered value; `undefined` indicates no result.
    */
   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.
+   * Resolves all currently pending waits and clears their registrations.
    *
-   * @param {T | undefined} [value] - Optional value to resolve all waiters with.
-   * Defaults to `undefined`, which usually indicates cancellation or shutdown.
+   * @param value - The delivered value; omission resolves all pending waits with `undefined`.
    */
   triggerAll(value?: T | undefined): void;
   /**
-   * Waits for an event associated with the given key.
+   * Waits for a trigger associated with a 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`.
+   * @remarks
+   * By default, multiple waiters share a key and all receive the next trigger value.
+   * `strict` mode rejects duplicate waits; `override` mode resolves existing waits with `undefined` before
+   * registering the new wait. Timeout and abort remove only the affected waiter's registration.
+   * An already aborted signal is not checked; only an abort event emitted after registration ends the wait.
+   * Without a timeout or subsequent abort, the wait remains pending until a trigger arrives.
    *
-   * Behavior when multiple waiters exist for the same key:
-   *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.
-   *  - `strict` mode: throws an error if a waiter already exists for the given key.
-   *  - `override` mode: cancels all existing waiters (resolving them with `undefined`)
-   *    and only keeps the latest one.
+   * @param key - The event identifier to wait for.
+   * @param timeoutMs - The optional timeout in milliseconds, using native `setTimeout` timing rules.
+   * @param mode - The policy for existing waiters; omission allows multiple waiters.
+   * @param signal - A signal whose subsequent abort event ends this wait.
    *
-   * @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 {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
+   * @returns A promise resolving to the triggered value, or `undefined` after timeout, abort, or replacement.
    *
-   * @returns {Promise<T | undefined>} A promise that resolves with the triggered value,
-   * or `undefined` if timeout or abort occurs
+   * @throws Error through promise rejection if `strict` mode encounters an existing waiter.
    */
   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,
-   * this method will throw an error.
+   * Waits for a key while rejecting duplicate registrations.
+   *
+   * @param key - The event identifier to wait for.
+   * @param timeoutMs - The optional timeout in milliseconds.
+   * @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.
+   *
+   * @returns A promise resolving to the triggered value, or `undefined` on timeout or subsequent abort.
    *
-   * @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`
+   * @throws Error through promise rejection if the key already has a pending waiter.
+   *
+   * @see {@link EventAwaiter.wait}
    */
   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
-   * (resolved with `undefined`) and replaced by the new waiter.
+   * Replaces existing waiters for a key and waits for its next trigger.
+   *
+   * @remarks
+   * Existing waiters resolve with `undefined` before the new waiter is registered.
+   *
+   * @param key - The event identifier to wait for.
+   * @param timeoutMs - The optional timeout in milliseconds.
+   * @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.
+   *
+   * @returns A promise resolving to the triggered value, or `undefined` on timeout, subsequent abort, or replacement.
    *
-   * @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`
+   * @see {@link EventAwaiter.wait}
    */
   waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal): Promise<T | undefined>;
 }
 //#endregion
-export { EventAwaiter };
 //# sourceMappingURL=event-awaiter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"event-awaiter.d.ts","names":[],"sources":["../src/event-awaiter.ts"],"mappings":";;;;;;;;;;;;;cAYa,aAAa;;;;;;;;;;EAWtB,QAAQ,aAAa,OAAO;;;;;;;;;;EAiB5B,WAAW,QAAO;;;;;;;;;;;;;;;;;;;;;;;;EA4BlB,KAAK,aAAa,oBAAoB,8BAA8B,SAAS,cAAW,QAAA;;;;;;;;;;;EA2DxF,cAAc,aAAa,oBAAoB,SAAS,cAAW,QAAA;;;;;;;;;;;EAcnE,WAAW,aAAa,oBAAoB,SAAS,cAAW,QAAA"}
+{"version":3,"file":"event-awaiter.d.ts","names":[],"sources":["../src/event-awaiter.ts"],"mappings":";;;;;;;;;;;;qBAWa,aAAa;;;;;;;;EAYtB,QAAQ,aAAa,OAAO;;;;;;EAa5B,WAAW,QAAO;;;;;;;;;;;;;;;;;;;;EAwBlB,KAAK,aAAa,oBAAoB,8BAA8B,SAAS,cAAW,QAAA;;;;;;;;;;;;;;EA8DxF,cAAc,aAAa,oBAAoB,SAAS,cAAW,QAAA;;;;;;;;;;;;;;;EAkBnE,WAAW,aAAa,oBAAoB,SAAS,cAAW,QAAA"}

package/dist/event-awaiter.js

@@ -1,25 +1,22 @@
 //#region src/event-awaiter.ts
 /**
-* EventAwaiter provides a mechanism to wait for events (by key) asynchronously.
+* An asynchronous keyed event rendezvous for one or more waiting consumers.
 *
-* 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 or an AbortSignal is triggered.
+* @remarks
+* Triggers resolve the currently registered waiters; values are not retained for future waits.
+* Timeouts and subsequent abort events resolve affected waiters with `undefined`.
+* Use `triggerAll` to resolve pending waits during cleanup. Timers and abort listeners are not proactively
+* removed by triggers, so they may remain until their timeout or abort event occurs.
 *
-* Typical use cases include long-polling, request coordination,
-* or implementing event-driven primitives in applications or services.
-*
-* @template T - The type of value that will be resolved when the event is triggered
+* @typeParam T - The value delivered to waiting consumers.
 */
 var EventAwaiter = class {
 	#promiseResolvers = /* @__PURE__ */ new Map();
 	/**
-	* Triggers all pending promises waiting for the given key.
-	* Each promise will be resolved with the provided value.
+	* Resolves all currently pending waits for a key with the supplied value.
 	*
-	* @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.
+	* @param key - The event identifier; a key without pending waits has no effect.
+	* @param value - The delivered value; `undefined` indicates no result.
 	*/
 	trigger(key, value) {
 		const resolvers = this.#promiseResolvers.get(key);
@@ -29,40 +26,32 @@ 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.
+	* Resolves all currently pending waits and clears their registrations.
 	*
-	* @param {T | undefined} [value] - Optional value to resolve all waiters with.
-	* Defaults to `undefined`, which usually indicates cancellation or shutdown.
+	* @param value - The delivered value; omission resolves all pending waits with `undefined`.
 	*/
 	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.
+	* Waits for a trigger associated with a 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`.
+	* @remarks
+	* By default, multiple waiters share a key and all receive the next trigger value.
+	* `strict` mode rejects duplicate waits; `override` mode resolves existing waits with `undefined` before
+	* registering the new wait. Timeout and abort remove only the affected waiter's registration.
+	* An already aborted signal is not checked; only an abort event emitted after registration ends the wait.
+	* Without a timeout or subsequent abort, the wait remains pending until a trigger arrives.
 	*
-	* Behavior when multiple waiters exist for the same key:
-	*  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.
-	*  - `strict` mode: throws an error if a waiter already exists for the given key.
-	*  - `override` mode: cancels all existing waiters (resolving them with `undefined`)
-	*    and only keeps the latest one.
+	* @param key - The event identifier to wait for.
+	* @param timeoutMs - The optional timeout in milliseconds, using native `setTimeout` timing rules.
+	* @param mode - The policy for existing waiters; omission allows multiple waiters.
+	* @param signal - A signal whose subsequent abort event ends this wait.
 	*
-	* @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 {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`
+	* @returns A promise resolving to the triggered value, or `undefined` after timeout, abort, or replacement.
 	*
-	* @returns {Promise<T | undefined>} A promise that resolves with the triggered value,
-	* or `undefined` if timeout or abort occurs
+	* @throws Error through promise rejection if `strict` mode encounters an existing waiter.
 	*/
 	wait(key, timeoutMs, mode, signal) {
 		return new Promise((resolve) => {
@@ -97,27 +86,34 @@ var EventAwaiter = class {
 		});
 	}
 	/**
-	* Waits for an event in strict mode.
-	* Only one waiter is allowed per key. If another waiter already exists,
-	* this method will throw an error.
+	* Waits for a key while rejecting duplicate registrations.
+	*
+	* @param key - The event identifier to wait for.
+	* @param timeoutMs - The optional timeout in milliseconds.
+	* @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.
+	*
+	* @returns A promise resolving to the triggered value, or `undefined` on timeout or subsequent abort.
 	*
-	* @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`
+	* @throws Error through promise rejection if the key already has a pending waiter.
+	*
+	* @see {@link EventAwaiter.wait}
 	*/
 	waitExclusive(key, timeoutMs, signal) {
 		return this.wait(key, timeoutMs, "strict", signal);
 	}
 	/**
-	* Waits for an event in override mode.
-	* If another waiter already exists for the given key, it will be canceled
-	* (resolved with `undefined`) and replaced by the new waiter.
+	* Replaces existing waiters for a key and waits for its next trigger.
+	*
+	* @remarks
+	* Existing waiters resolve with `undefined` before the new waiter is registered.
+	*
+	* @param key - The event identifier to wait for.
+	* @param timeoutMs - The optional timeout in milliseconds.
+	* @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.
+	*
+	* @returns A promise resolving to the triggered value, or `undefined` on timeout, subsequent abort, or replacement.
 	*
-	* @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`
+	* @see {@link EventAwaiter.wait}
 	*/
 	waitLatest(key, timeoutMs, signal) {
 		return this.wait(key, timeoutMs, "override", signal);