@kikiutils/shared 13.0.0 → 13.1.0

package/README.md

@@ -28,7 +28,7 @@ A lightweight and modular utility library for modern JavaScript and TypeScript
 
 ## Requirements
 
-- **Node.js** `>= 22.0.0`
+- **Node.js** `>=22.12.0`
 
 ## Installation
 

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 * 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): 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,AAAS;;;;;;CAOT,YAAY,KAAa;AACrB,QAAM,iCAAiC,MAAM;AAC7C,OAAK,MAAM;AACX,OAAK,OAAO,KAAK,YAAY;AAC7B,QAAM,oBAAoB,MAAM,KAAK,YAAY;;;;;;;;;;;;;;;;;;;;;;;;AAyBzD,SAAgB,oBAAoB,KAAqB;AACrD,KAAI,QAAQ,IAAI,SAAS,OAAW,OAAM,IAAI,yBAAyB,IAAI;AAC3E,QAAO,QAAQ,IAAI"}
+{"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 * 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,AAAS;;;;;;CAOT,YAAY,KAAa;AACrB,QAAM,iCAAiC,MAAM;AAC7C,OAAK,MAAM;AACX,OAAK,OAAO,KAAK,YAAY;AAC7B,QAAM,oBAAoB,MAAM,KAAK,YAAY;;;;;;;;;;;;;;;;;;;;;;;;AAyBzD,SAAgB,oBAAoB,KAAa;AAC7C,KAAI,QAAQ,IAAI,SAAS,OAAW,OAAM,IAAI,yBAAyB,IAAI;AAC3E,QAAO,QAAQ,IAAI"}

package/dist/event-awaiter.d.ts

@@ -0,0 +1,44 @@
+//#region src/event-awaiter.d.ts
+/**
+ * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.
+ *
+ * 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.
+ *
+ * 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
+ */
+declare class EventAwaiter<T> {
+  #private;
+  /**
+   * 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 {T} [value] - Optional value to resolve the awaiting promises with
+   */
+  trigger(key: string, value?: T): 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`.
+   *
+   * Multiple consumers can wait on the same key; all of them will be notified when triggered.
+   *
+   * @param {string} [key] - Identifier for the awaited event
+   * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
+   * If reached, the promise resolves with `undefined`
+   *
+   * @returns {Promise<T | undefined>} A promise that resolves with the triggered value
+   * or `undefined` if timeout occurs
+   */
+  wait(key: string, timeoutMs?: number): Promise<T | undefined>;
+}
+//#endregion
+export { EventAwaiter };
+//# sourceMappingURL=event-awaiter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-awaiter.d.ts","names":[],"sources":["../src/event-awaiter.ts"],"sourcesContent":[],"mappings":";;AAYA;;;;;;;;;;;cAAa;;;;;;;;;+BAUoB;;;;;;;;;;;;;;;;;yCAwBO,QAAA"}

package/dist/event-awaiter.js

@@ -0,0 +1,66 @@
+//#region src/event-awaiter.ts
+/**
+* EventAwaiter provides a mechanism to wait for events (by key) asynchronously.
+*
+* 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.
+*
+* 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
+*/
+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.
+	*
+	* @param {string} [key] - Identifier for the awaited event
+	* @param {T} [value] - Optional value to resolve the awaiting promises with
+	*/
+	trigger(key, value) {
+		const resolvers = this.#promiseResolvers.get(key);
+		if (resolvers) {
+			this.#promiseResolvers.delete(key);
+			resolvers?.forEach((resolve) => resolve(value));
+		}
+	}
+	/**
+	* 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`.
+	*
+	* Multiple consumers can wait on the same key; all of them will be notified when triggered.
+	*
+	* @param {string} [key] - Identifier for the awaited event
+	* @param {number} [timeoutMs] - Optional timeout (in milliseconds).
+	* If reached, the promise resolves with `undefined`
+	*
+	* @returns {Promise<T | undefined>} A promise that resolves with the triggered value
+	* or `undefined` if timeout occurs
+	*/
+	wait(key, timeoutMs) {
+		return new Promise((resolve) => {
+			const resolvers = this.#promiseResolvers.get(key) || [];
+			resolvers.push(resolve);
+			this.#promiseResolvers.set(key, resolvers);
+			if (timeoutMs) setTimeout(() => {
+				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);
+				}
+			}, timeoutMs);
+		});
+	}
+};
+
+//#endregion
+export { EventAwaiter };
+//# sourceMappingURL=event-awaiter.js.map

package/dist/event-awaiter.js.map

@@ -0,0 +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} [value] - Optional value to resolve the awaiting promises with\n     */\n    trigger(key: string, value?: T) {\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     * Multiple consumers can wait on the same key; all of them will be notified when triggered.\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     * @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) {\n        return new Promise<T | undefined>((resolve) => {\n            const resolvers = this.#promiseResolvers.get(key) || [];\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"],"mappings":";;;;;;;;;;;;;AAYA,IAAa,eAAb,MAA6B;CACzB,oCAAoB,IAAI,KAA8E;;;;;;;;CAStG,QAAQ,KAAa,OAAW;EAC5B,MAAM,YAAY,MAAKA,iBAAkB,IAAI,IAAI;AACjD,MAAI,WAAW;AACX,SAAKA,iBAAkB,OAAO,IAAI;AAClC,cAAW,SAAS,YAAY,QAAQ,MAAM,CAAC;;;;;;;;;;;;;;;;;;;CAoBvD,KAAK,KAAa,WAAoB;AAClC,SAAO,IAAI,SAAwB,YAAY;GAC3C,MAAM,YAAY,MAAKA,iBAAkB,IAAI,IAAI,IAAI,EAAE;AACvD,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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "13.0.0",
+  "version": "13.1.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",
@@ -41,6 +41,7 @@
     "./element-plus": "./dist/element-plus.js",
     "./enum": "./dist/enum.js",
     "./env": "./dist/env.js",
+    "./event-awaiter": "./dist/event-awaiter.js",
     "./general": "./dist/general.js",
     "./hash": "./dist/hash.js",
     "./math": "./dist/math.js",
@@ -66,7 +67,7 @@
     "./src"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "build": "tsdown",
@@ -78,7 +79,7 @@
     "release": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && changelogen --hideAuthorEmail --push --release && npm publish",
     "test": "cross-env TZ=UTC vitest run --coverage",
     "test:watch": "cross-env TZ=UTC vitest watch --coverage",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -b --noEmit",
     "unused-exports": "ts-unused-exports ./tsconfig.json"
   },
   "peerDependencies": {
@@ -143,10 +144,10 @@
   },
   "devDependencies": {
     "@kikiutils/changelogen": "^0.9.0",
-    "@kikiutils/eslint-config": "^2.1.1",
-    "@kikiutils/tsconfigs": "^5.0.4",
+    "@kikiutils/eslint-config": "^3.0.1",
+    "@kikiutils/tsconfigs": "^5.0.5",
     "@noble/hashes": "^2.0.0",
-    "@types/node": "^24.3.3",
+    "@types/node": "^24.5.0",
     "@vitest/coverage-v8": "^3.2.4",
     "async-validator": "^4.2.5",
     "consola": "^3.4.2",

package/src/env.ts

@@ -42,7 +42,7 @@ export class EnvironmentNotFoundError extends Error {
  * checkAndGetEnvValue('API_KEY'); // ❌ Throws EnvironmentNotFoundError
  * ```
  */
-export function checkAndGetEnvValue(key: string): string {
+export function checkAndGetEnvValue(key: string) {
     if (process.env[key] === undefined) throw new EnvironmentNotFoundError(key);
     return process.env[key];
 }

package/src/event-awaiter.ts

@@ -0,0 +1,68 @@
+/**
+ * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.
+ *
+ * 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.
+ *
+ * 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
+ */
+export class EventAwaiter<T> {
+    #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();
+
+    /**
+     * 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 {T} [value] - Optional value to resolve the awaiting promises with
+     */
+    trigger(key: string, value?: T) {
+        const resolvers = this.#promiseResolvers.get(key);
+        if (resolvers) {
+            this.#promiseResolvers.delete(key);
+            resolvers?.forEach((resolve) => resolve(value));
+        }
+    }
+
+    /**
+     * 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`.
+     *
+     * Multiple consumers can wait on the same key; all of them will be notified when triggered.
+     *
+     * @param {string} [key] - Identifier for the awaited event
+     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).
+     * If reached, the promise resolves with `undefined`
+     *
+     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value
+     * or `undefined` if timeout occurs
+     */
+    wait(key: string, timeoutMs?: number) {
+        return new Promise<T | undefined>((resolve) => {
+            const resolvers = this.#promiseResolvers.get(key) || [];
+            resolvers.push(resolve);
+            this.#promiseResolvers.set(key, resolvers);
+            if (timeoutMs) {
+                setTimeout(
+                    () => {
+                        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);
+                        }
+                    },
+                    timeoutMs,
+                );
+            }
+        });
+    }
+}