@kikiutils/shared 15.0.0 → 15.0.2

package/dist/storages/redis/msgpack.js

@@ -1,6 +1,26 @@
 import { decode, encode, isNativeAccelerationEnabled } from "msgpackr";
 //#region src/storages/redis/msgpack.ts
 if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled for msgpackr, verify that install finished properly");
+/**
+* Creates a Redis-like storage using msgpack serialization.
+*
+* @param {RedisLikeAdapter} adapter - The Redis-like adapter to use for raw buffer operations
+*
+* @returns {Readonly<RedisLikeStorage>} A readonly storage instance
+*   with getItem, setItem, hasItem, removeItem, getItemTtl, setItemWithTtl
+*
+* @example
+* ```typescript
+* import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';
+* import { createClient } from 'redis';
+*
+* const client = createClient();
+* await client.connect();
+* const storage = createRedisMsgpackStorage(client as unknown as RedisLikeAdapter);
+* await storage.setItem('key', { foo: 'bar' });
+* const value = await storage.getItem('key'); // { foo: 'bar' }
+* ```
+*/
 function createRedisMsgpackStorage(adapter) {
 	return Object.freeze({
 		async getItem(key) {

package/dist/storages/redis/msgpack.js.map

@@ -1 +1 @@
-{"version":3,"file":"msgpack.js","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"sourcesContent":["import {\n    decode,\n    encode,\n    isNativeAccelerationEnabled,\n} from 'msgpackr';\n\nimport type {\n    RedisLikeAdapter,\n    RedisLikeStorage,\n} from './types';\n\nif (!isNativeAccelerationEnabled) {\n    console.warn('Native acceleration not enabled for msgpackr, verify that install finished properly');\n}\n\nexport function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {\n    return Object.freeze({\n        async getItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBuffer(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        getItemTtl: (key: string) => adapter.ttl(key),\n        hasItem: (key: string) => adapter.has(key),\n        removeItem: async (key: string) => await adapter.delete(key) === 1,\n        setItem: async (key: string, value: any) => await adapter.setBuffer(key, encode(value)) === 'OK',\n        async setItemWithTtl(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n    });\n}\n"],"mappings":";;AAWA,IAAI,CAAC,4BACD,SAAQ,KAAK,sFAAsF;AAGvG,SAAgB,0BAA0B,SAAuD;AAC7F,QAAO,OAAO,OAAO;EACjB,MAAM,QAAqB,KAAa;GACpC,MAAM,WAAW,MAAM,QAAQ,UAAU,IAAI;AAC7C,UAAO,WAAW,OAAO,SAAS,GAAQ;;EAE9C,aAAa,QAAgB,QAAQ,IAAI,IAAI;EAC7C,UAAU,QAAgB,QAAQ,IAAI,IAAI;EAC1C,YAAY,OAAO,QAAgB,MAAM,QAAQ,OAAO,IAAI,KAAK;EACjE,SAAS,OAAO,KAAa,UAAe,MAAM,QAAQ,UAAU,KAAK,OAAO,MAAM,CAAC,KAAK;EAC5F,MAAM,eAAe,KAAa,YAAoB,OAAY;AAC9D,UAAO,MAAM,QAAQ,YAAY,KAAK,YAAY,OAAO,MAAM,CAAC,KAAK;;EAE5E,CAAC"}
+{"version":3,"file":"msgpack.js","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"sourcesContent":["import {\n    decode,\n    encode,\n    isNativeAccelerationEnabled,\n} from 'msgpackr';\n\nimport type {\n    RedisLikeAdapter,\n    RedisLikeStorage,\n} from './types';\n\nif (!isNativeAccelerationEnabled) {\n    console.warn('Native acceleration not enabled for msgpackr, verify that install finished properly');\n}\n\n/**\n * Creates a Redis-like storage using msgpack serialization.\n *\n * @param {RedisLikeAdapter} adapter - The Redis-like adapter to use for raw buffer operations\n *\n * @returns {Readonly<RedisLikeStorage>} A readonly storage instance\n *   with getItem, setItem, hasItem, removeItem, getItemTtl, setItemWithTtl\n *\n * @example\n * ```typescript\n * import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';\n * import { createClient } from 'redis';\n *\n * const client = createClient();\n * await client.connect();\n * const storage = createRedisMsgpackStorage(client as unknown as RedisLikeAdapter);\n * await storage.setItem('key', { foo: 'bar' });\n * const value = await storage.getItem('key'); // { foo: 'bar' }\n * ```\n */\nexport function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {\n    return Object.freeze({\n        async getItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBuffer(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        getItemTtl: (key: string) => adapter.ttl(key),\n        hasItem: (key: string) => adapter.has(key),\n        removeItem: async (key: string) => await adapter.delete(key) === 1,\n        setItem: async (key: string, value: any) => await adapter.setBuffer(key, encode(value)) === 'OK',\n        async setItemWithTtl(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n    });\n}\n"],"mappings":";;AAWA,IAAI,CAAC,4BACD,SAAQ,KAAK,sFAAsF;;;;;;;;;;;;;;;;;;;;;AAuBvG,SAAgB,0BAA0B,SAAuD;AAC7F,QAAO,OAAO,OAAO;EACjB,MAAM,QAAqB,KAAa;GACpC,MAAM,WAAW,MAAM,QAAQ,UAAU,IAAI;AAC7C,UAAO,WAAW,OAAO,SAAS,GAAQ;;EAE9C,aAAa,QAAgB,QAAQ,IAAI,IAAI;EAC7C,UAAU,QAAgB,QAAQ,IAAI,IAAI;EAC1C,YAAY,OAAO,QAAgB,MAAM,QAAQ,OAAO,IAAI,KAAK;EACjE,SAAS,OAAO,KAAa,UAAe,MAAM,QAAQ,UAAU,KAAK,OAAO,MAAM,CAAC,KAAK;EAC5F,MAAM,eAAe,KAAa,YAAoB,OAAY;AAC9D,UAAO,MAAM,QAAQ,YAAY,KAAK,YAAY,OAAO,MAAM,CAAC,KAAK;;EAE5E,CAAC"}

package/dist/storages/redis/types.d.ts

@@ -1,20 +1,62 @@
 import { Nullable } from "../../types/index.js";
 
 //#region src/storages/redis/types.d.ts
+/**
+ * Low-level Redis-like adapter interface for raw buffer operations.
+ */
 interface RedisLikeAdapter {
+  /**
+   * Deletes a key and returns the number of keys deleted.
+   */
   delete: (key: string) => Promise<number>;
+  /**
+   * Gets the raw buffer value for a key.
+   */
   getBuffer: (key: string) => Promise<Nullable<Uint8Array>>;
+  /**
+   * Checks if a key exists.
+   */
   has: (key: string) => Promise<boolean>;
+  /**
+   * Sets a raw buffer value for a key.
+   */
   setBuffer: (key: string, value: Uint8Array) => Promise<'OK' | void>;
+  /**
+   * Sets a raw buffer value for a key with a TTL.
+   */
   setBufferEx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | void>;
+  /**
+   * Gets the TTL of a key in seconds.
+   */
   ttl: (key: string) => Promise<number>;
 }
+/**
+ * High-level Redis-like storage interface with typed get/set operations.
+ */
 interface RedisLikeStorage {
+  /**
+   * Gets a deserialized value by key.
+   */
   getItem: <T = unknown>(key: string) => Promise<Nullable<T>>;
+  /**
+   * Gets the TTL of a key in seconds.
+   */
   getItemTtl: (key: string) => Promise<number>;
+  /**
+   * Checks if a key exists.
+   */
   hasItem: (key: string) => Promise<boolean>;
+  /**
+   * Removes a key.
+   */
   removeItem: (key: string) => Promise<boolean>;
+  /**
+   * Sets a value for a key.
+   */
   setItem: (key: string, value: any) => Promise<boolean>;
+  /**
+   * Sets a value for a key with a TTL.
+   */
   setItemWithTtl: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
 }
 //#endregion

package/dist/storages/redis/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/storages/redis/types.ts"],"mappings":";;;UAEiB,gBAAA;EACb,MAAA,GAAS,GAAA,aAAgB,OAAA;EACzB,SAAA,GAAY,GAAA,aAAgB,OAAA,CAAQ,QAAA,CAAS,UAAA;EAC7C,GAAA,GAAM,GAAA,aAAgB,OAAA;EACtB,SAAA,GAAY,GAAA,UAAa,KAAA,EAAO,UAAA,KAAe,OAAA;EAC/C,WAAA,GAAc,GAAA,UAAa,UAAA,UAAoB,KAAA,EAAO,UAAA,KAAe,OAAA;EACrE,GAAA,GAAM,GAAA,aAAgB,OAAA;AAAA;AAAA,UAGT,gBAAA;EACb,OAAA,gBAAuB,GAAA,aAAgB,OAAA,CAAQ,QAAA,CAAS,CAAA;EACxD,UAAA,GAAa,GAAA,aAAgB,OAAA;EAC7B,OAAA,GAAU,GAAA,aAAgB,OAAA;EAC1B,UAAA,GAAa,GAAA,aAAgB,OAAA;EAC7B,OAAA,GAAU,GAAA,UAAa,KAAA,UAAe,OAAA;EACtC,cAAA,GAAiB,GAAA,UAAa,UAAA,UAAoB,KAAA,UAAe,OAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/storages/redis/types.ts"],"mappings":";;;;;AAKA;UAAiB,gBAAA;;;;EAIb,MAAA,GAAS,GAAA,aAAgB,OAAA;EAKG;;;EAA5B,SAAA,GAAY,GAAA,aAAgB,OAAA,CAAQ,QAAA,CAAS,UAAA;EAeS;;;EAVtD,GAAA,GAAM,GAAA,aAAgB,OAAA;EAeO;;;EAV7B,SAAA,GAAY,GAAA,UAAa,KAAA,EAAO,UAAA,KAAe,OAAA;EAV/C;;;EAeA,WAAA,GAAc,GAAA,UAAa,UAAA,UAAoB,KAAA,EAAO,UAAA,KAAe,OAAA;EAfxB;;;EAoB7C,GAAA,GAAM,GAAA,aAAgB,OAAA;AAAA;;;;UAMT,gBAAA;EAXb;;;EAeA,OAAA,gBAAuB,GAAA,aAAgB,OAAA,CAAQ,QAAA,CAAS,CAAA;EAfT;;;EAoB/C,UAAA,GAAa,GAAA,aAAgB,OAAA;EAfP;;;EAoBtB,OAAA,GAAU,GAAA,aAAgB,OAAA;EAdG;;;EAmB7B,UAAA,GAAa,GAAA,aAAgB,OAAA;EAfU;;;EAoBvC,OAAA,GAAU,GAAA,UAAa,KAAA,UAAe,OAAA;EAAA;;;EAKtC,cAAA,GAAiB,GAAA,UAAa,UAAA,UAAoB,KAAA,UAAe,OAAA;AAAA"}

package/dist/string.js

@@ -34,7 +34,7 @@ function randomString(length, mode = "alphabetic") {
 	if (!Number.isInteger(length) || length <= 0) throw new Error(`Invalid length: ${length}. Must be a positive integer`);
 	const charset = CHARSETS[mode];
 	if (!charset) throw new Error(`Unsupported mode: ${mode}`);
-	return Array.from({ length }).fill(charset[Math.floor(Math.random() * charset.length)]).join("");
+	return Array.from({ length }, () => charset[Math.floor(Math.random() * charset.length)]).join("");
 }
 //#endregion
 export { randomString };

package/dist/string.js.map

@@ -1 +1 @@
-{"version":3,"file":"string.js","names":[],"sources":["../src/string.ts"],"sourcesContent":["export type RandomStringMode =\n  | 'alphabetic'\n  | 'alphanumeric'\n  | 'lowercase'\n  | 'lowercase-numeric'\n  | 'numeric'\n  | 'uppercase'\n  | 'uppercase-numeric';\n\nconst DIGITS = '0123456789';\nconst LOWERCASE = 'abcdefghijklmnopqrstuvwxyz';\nconst UPPERCASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';\nconst CHARSETS: Record<RandomStringMode, string> = {\n    'alphabetic': LOWERCASE + UPPERCASE,\n    'alphanumeric': DIGITS + LOWERCASE + UPPERCASE,\n    'lowercase': LOWERCASE,\n    'lowercase-numeric': DIGITS + LOWERCASE,\n    'numeric': DIGITS,\n    'uppercase': UPPERCASE,\n    'uppercase-numeric': DIGITS + UPPERCASE,\n};\n\n/**\n * Generates a random string of a given length using a specified character set.\n *\n * @param {number} length - The length of the string to generate. Must be a positive integer\n * @param {RandomStringMode} [mode] - The character set to use\n *\n * @returns {string} The generated random string\n *\n * @throws {Error} If the length is not a positive integer or the mode is unsupported\n *\n * @example\n * ```typescript\n * import { randomString } from '@kikiutils/shared/string';\n *\n * console.log(randomString(8)); // e.g. 'aZbXwTyQ' (alphabetic)\n * console.log(randomString(6, 'numeric')); // e.g. '402398'\n * console.log(randomString(10, 'alphanumeric')); // e.g. 'a9Z4pQ8xY2'\n * ```\n */\nexport function randomString(length: number, mode: RandomStringMode = 'alphabetic') {\n    if (!Number.isInteger(length) || length <= 0) {\n        throw new Error(`Invalid length: ${length}. Must be a positive integer`);\n    }\n\n    const charset = CHARSETS[mode];\n    if (!charset) throw new Error(`Unsupported mode: ${mode}`);\n    return Array.from({ length }).fill(charset[Math.floor(Math.random() * charset.length)]).join('');\n}\n"],"mappings":";AASA,MAAM,SAAS;AACf,MAAM,YAAY;AAClB,MAAM,YAAY;AAClB,MAAM,WAA6C;CAC/C,cAAc,YAAY;CAC1B,gBAAgB,SAAS,YAAY;CACrC,aAAa;CACb,qBAAqB,SAAS;CAC9B,WAAW;CACX,aAAa;CACb,qBAAqB,SAAS;CACjC;;;;;;;;;;;;;;;;;;;;AAqBD,SAAgB,aAAa,QAAgB,OAAyB,cAAc;AAChF,KAAI,CAAC,OAAO,UAAU,OAAO,IAAI,UAAU,EACvC,OAAM,IAAI,MAAM,mBAAmB,OAAO,8BAA8B;CAG5E,MAAM,UAAU,SAAS;AACzB,KAAI,CAAC,QAAS,OAAM,IAAI,MAAM,qBAAqB,OAAO;AAC1D,QAAO,MAAM,KAAK,EAAE,QAAQ,CAAC,CAAC,KAAK,QAAQ,KAAK,MAAM,KAAK,QAAQ,GAAG,QAAQ,OAAO,EAAE,CAAC,KAAK,GAAG"}
+{"version":3,"file":"string.js","names":[],"sources":["../src/string.ts"],"sourcesContent":["export type RandomStringMode =\n  | 'alphabetic'\n  | 'alphanumeric'\n  | 'lowercase'\n  | 'lowercase-numeric'\n  | 'numeric'\n  | 'uppercase'\n  | 'uppercase-numeric';\n\nconst DIGITS = '0123456789';\nconst LOWERCASE = 'abcdefghijklmnopqrstuvwxyz';\nconst UPPERCASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';\nconst CHARSETS: Record<RandomStringMode, string> = {\n    'alphabetic': LOWERCASE + UPPERCASE,\n    'alphanumeric': DIGITS + LOWERCASE + UPPERCASE,\n    'lowercase': LOWERCASE,\n    'lowercase-numeric': DIGITS + LOWERCASE,\n    'numeric': DIGITS,\n    'uppercase': UPPERCASE,\n    'uppercase-numeric': DIGITS + UPPERCASE,\n};\n\n/**\n * Generates a random string of a given length using a specified character set.\n *\n * @param {number} length - The length of the string to generate. Must be a positive integer\n * @param {RandomStringMode} [mode] - The character set to use\n *\n * @returns {string} The generated random string\n *\n * @throws {Error} If the length is not a positive integer or the mode is unsupported\n *\n * @example\n * ```typescript\n * import { randomString } from '@kikiutils/shared/string';\n *\n * console.log(randomString(8)); // e.g. 'aZbXwTyQ' (alphabetic)\n * console.log(randomString(6, 'numeric')); // e.g. '402398'\n * console.log(randomString(10, 'alphanumeric')); // e.g. 'a9Z4pQ8xY2'\n * ```\n */\nexport function randomString(length: number, mode: RandomStringMode = 'alphabetic') {\n    if (!Number.isInteger(length) || length <= 0) {\n        throw new Error(`Invalid length: ${length}. Must be a positive integer`);\n    }\n\n    const charset = CHARSETS[mode];\n    if (!charset) throw new Error(`Unsupported mode: ${mode}`);\n    return Array.from({ length }, () => charset[Math.floor(Math.random() * charset.length)]).join('');\n}\n"],"mappings":";AASA,MAAM,SAAS;AACf,MAAM,YAAY;AAClB,MAAM,YAAY;AAClB,MAAM,WAA6C;CAC/C,cAAc,YAAY;CAC1B,gBAAgB,SAAS,YAAY;CACrC,aAAa;CACb,qBAAqB,SAAS;CAC9B,WAAW;CACX,aAAa;CACb,qBAAqB,SAAS;CACjC;;;;;;;;;;;;;;;;;;;;AAqBD,SAAgB,aAAa,QAAgB,OAAyB,cAAc;AAChF,KAAI,CAAC,OAAO,UAAU,OAAO,IAAI,UAAU,EACvC,OAAM,IAAI,MAAM,mBAAmB,OAAO,8BAA8B;CAG5E,MAAM,UAAU,SAAS;AACzB,KAAI,CAAC,QAAS,OAAM,IAAI,MAAM,qBAAqB,OAAO;AAC1D,QAAO,MAAM,KAAK,EAAE,QAAQ,QAAQ,QAAQ,KAAK,MAAM,KAAK,QAAQ,GAAG,QAAQ,OAAO,EAAE,CAAC,KAAK,GAAG"}

package/dist/time.d.ts

@@ -1,4 +1,21 @@
 //#region src/time.d.ts
+/**
+ * Creates a delay that can be aborted via AbortSignal.
+ *
+ * @param {number} ms - Delay duration in milliseconds
+ * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the delay
+ *
+ * @returns {Promise<undefined>} A promise that resolves after ms or resolves immediately on abort
+ *
+ * @example
+ * ```typescript
+ * import { abortableDelay } from '@kikiutils/shared/time';
+ *
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 1000);
+ * await abortableDelay(5000, controller.signal); // resolves after ~1s when aborted
+ * ```
+ */
 declare function abortableDelay(ms: number, signal?: AbortSignal): Promise<unknown>;
 //#endregion
 export { abortableDelay };

package/dist/time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time.d.ts","names":[],"sources":["../src/time.ts"],"mappings":";iBAAgB,cAAA,CAAe,EAAA,UAAY,MAAA,GAAS,WAAA,GAAW,OAAA"}
+{"version":3,"file":"time.d.ts","names":[],"sources":["../src/time.ts"],"mappings":";;AAiBA;;;;;;;;;;;;;;;;iBAAgB,cAAA,CAAe,EAAA,UAAY,MAAA,GAAS,WAAA,GAAW,OAAA"}

package/dist/time.js

@@ -1,4 +1,21 @@
 //#region src/time.ts
+/**
+* Creates a delay that can be aborted via AbortSignal.
+*
+* @param {number} ms - Delay duration in milliseconds
+* @param {AbortSignal} [signal] - Optional AbortSignal to cancel the delay
+*
+* @returns {Promise<undefined>} A promise that resolves after ms or resolves immediately on abort
+*
+* @example
+* ```typescript
+* import { abortableDelay } from '@kikiutils/shared/time';
+*
+* const controller = new AbortController();
+* setTimeout(() => controller.abort(), 1000);
+* await abortableDelay(5000, controller.signal); // resolves after ~1s when aborted
+* ```
+*/
 function abortableDelay(ms, signal) {
 	return new Promise((resolve) => {
 		const timeout = setTimeout(resolve, ms);

package/dist/time.js.map

@@ -1 +1 @@
-{"version":3,"file":"time.js","names":[],"sources":["../src/time.ts"],"sourcesContent":["export function abortableDelay(ms: number, signal?: AbortSignal) {\n    return new Promise((resolve) => {\n        const timeout = setTimeout(resolve, ms);\n        if (signal) {\n            signal.addEventListener(\n                'abort',\n                () => {\n                    clearTimeout(timeout);\n                    resolve(undefined);\n                },\n            );\n        }\n    });\n}\n"],"mappings":";AAAA,SAAgB,eAAe,IAAY,QAAsB;AAC7D,QAAO,IAAI,SAAS,YAAY;EAC5B,MAAM,UAAU,WAAW,SAAS,GAAG;AACvC,MAAI,OACA,QAAO,iBACH,eACM;AACF,gBAAa,QAAQ;AACrB,WAAQ,KAAA,EAAU;IAEzB;GAEP"}
+{"version":3,"file":"time.js","names":[],"sources":["../src/time.ts"],"sourcesContent":["/**\n * Creates a delay that can be aborted via AbortSignal.\n *\n * @param {number} ms - Delay duration in milliseconds\n * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the delay\n *\n * @returns {Promise<undefined>} A promise that resolves after ms or resolves immediately on abort\n *\n * @example\n * ```typescript\n * import { abortableDelay } from '@kikiutils/shared/time';\n *\n * const controller = new AbortController();\n * setTimeout(() => controller.abort(), 1000);\n * await abortableDelay(5000, controller.signal); // resolves after ~1s when aborted\n * ```\n */\nexport function abortableDelay(ms: number, signal?: AbortSignal) {\n    return new Promise((resolve) => {\n        const timeout = setTimeout(resolve, ms);\n        if (signal) {\n            signal.addEventListener(\n                'abort',\n                () => {\n                    clearTimeout(timeout);\n                    resolve(undefined);\n                },\n            );\n        }\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,SAAgB,eAAe,IAAY,QAAsB;AAC7D,QAAO,IAAI,SAAS,YAAY;EAC5B,MAAM,UAAU,WAAW,SAAS,GAAG;AACvC,MAAI,OACA,QAAO,iBACH,eACM;AACF,gBAAa,QAAQ;AACrB,WAAQ,KAAA,EAAU;IAEzB;GAEP"}

package/dist/url.d.ts

@@ -6,8 +6,11 @@
  *
  * @param {string} url - The target URL to modify
  * @param {string} redirectPath - The path to use as the redirect destination
+ * (must be an absolute path starting with '/')
  *
  * @returns {string} A new URL string with the `redirect` query parameter
+ *
+ * @throws {Error} If redirectPath is not a valid relative path (must start with '/')
  */
 declare function appendRedirectParamToUrl(url: string, redirectPath: string): string;
 //#endregion

package/dist/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","names":[],"sources":["../src/url.ts"],"mappings":";;AAUA;;;;;;;;;iBAAgB,wBAAA,CAAyB,GAAA,UAAa,YAAA"}
+{"version":3,"file":"url.d.ts","names":[],"sources":["../src/url.ts"],"mappings":";;AAaA;;;;;;;;;;;;iBAAgB,wBAAA,CAAyB,GAAA,UAAa,YAAA"}

package/dist/url.js

@@ -6,14 +6,20 @@
 *
 * @param {string} url - The target URL to modify
 * @param {string} redirectPath - The path to use as the redirect destination
+* (must be an absolute path starting with '/')
 *
 * @returns {string} A new URL string with the `redirect` query parameter
+*
+* @throws {Error} If redirectPath is not a valid relative path (must start with '/')
 */
 function appendRedirectParamToUrl(url, redirectPath) {
-	const [base, rawQuery = ""] = url.split("?");
+	if (!redirectPath.startsWith("/")) throw new Error(`Invalid redirect path: "${redirectPath}". Redirect paths must be absolute paths starting with '/'.`);
+	const [baseAndHash, rawQuery = ""] = url.split("?");
+	const [base, hash] = (baseAndHash || "").split("#");
 	const searchParams = new URLSearchParams(rawQuery);
 	searchParams.set("redirect", redirectPath);
-	return `${base}?${searchParams.toString()}`;
+	const queryString = searchParams.toString();
+	return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;
 }
 //#endregion
 export { appendRedirectParamToUrl };

package/dist/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param {string} url - The target URL to modify\n * @param {string} redirectPath - The path to use as the redirect destination\n *\n * @returns {string} A new URL string with the `redirect` query parameter\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    const [base, rawQuery = ''] = url.split('?');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    return `${base}?${searchParams.toString()}`;\n}\n"],"mappings":";;;;;;;;;;;AAUA,SAAgB,yBAAyB,KAAa,cAAsB;CACxE,MAAM,CAAC,MAAM,WAAW,MAAM,IAAI,MAAM,IAAI;CAC5C,MAAM,eAAe,IAAI,gBAAgB,SAAS;AAClD,cAAa,IAAI,YAAY,aAAa;AAC1C,QAAO,GAAG,KAAK,GAAG,aAAa,UAAU"}
+{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param {string} url - The target URL to modify\n * @param {string} redirectPath - The path to use as the redirect destination\n * (must be an absolute path starting with '/')\n *\n * @returns {string} A new URL string with the `redirect` query parameter\n *\n * @throws {Error} If redirectPath is not a valid relative path (must start with '/')\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    if (!redirectPath.startsWith('/')) {\n        throw new Error(\n            `Invalid redirect path: \"${redirectPath}\". Redirect paths must be absolute paths starting with '/'.`,\n        );\n    }\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;AACxE,KAAI,CAAC,aAAa,WAAW,IAAI,CAC7B,OAAM,IAAI,MACN,2BAA2B,aAAa,6DAC3C;CAGL,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,IAAI;CACnD,MAAM,CAAC,MAAM,SAAS,eAAe,IAAI,MAAM,IAAI;CACnD,MAAM,eAAe,IAAI,gBAAgB,SAAS;AAClD,cAAa,IAAI,YAAY,aAAa;CAC1C,MAAM,cAAc,aAAa,UAAU;AAC3C,QAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG"}

package/dist/vue.d.ts

@@ -26,6 +26,12 @@ declare function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setT
  * A Vue composition function that remembers and restores scroll position
  * of a scrollable container across route changes and keep-alive activation.
  *
+ * Designed for use with `<KeepAlive>` components. Scroll state is saved on
+ * route leave and restored when the component is activated again.
+ *
+ * Note: Without `<KeepAlive>`, the component state is destroyed on unmount,
+ * so scroll position will not be preserved.
+ *
  * @template T - The type of the scrollable element (defaults to HTMLElement)
  *
  * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element

package/dist/vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vue.d.ts","names":[],"sources":["../src/vue.ts"],"mappings":";;;;;;AAiBA;;;;;iBAAgB,wCAAA,CAAyC,GAAA;;;;;;iBASzC,gBAAA,CAAiB,WAAA,EAAa,GAAA,CAAI,QAAA,CAAS,UAAA,QAAkB,WAAA;;;;;;iBAU7D,eAAA,CAAgB,UAAA,EAAY,GAAA,CAAI,QAAA,CAAS,UAAA,QAAkB,UAAA;;;;AAA3E;;;;;iBAagB,iBAAA,WAA4B,OAAA,GAAU,WAAA,CAAA,CAAa,YAAA,EAAc,GAAA,CAAI,QAAA,CAAS,CAAA"}
+{"version":3,"file":"vue.d.ts","names":[],"sources":["../src/vue.ts"],"mappings":";;;;;;AAiBA;;;;;iBAAgB,wCAAA,CAAyC,GAAA;;;;;;iBASzC,gBAAA,CAAiB,WAAA,EAAa,GAAA,CAAI,QAAA,CAAS,UAAA,QAAkB,WAAA;;;;;;iBAU7D,eAAA,CAAgB,UAAA,EAAY,GAAA,CAAI,QAAA,CAAS,UAAA,QAAkB,UAAA;;;;AAA3E;;;;;;;;;;;iBAmBgB,iBAAA,WAA4B,OAAA,GAAU,WAAA,CAAA,CAAa,YAAA,EAAc,GAAA,CAAI,QAAA,CAAS,CAAA"}

package/dist/vue.js

@@ -34,6 +34,12 @@ function clearTimeoutRef(timeoutRef) {
 * A Vue composition function that remembers and restores scroll position
 * of a scrollable container across route changes and keep-alive activation.
 *
+* Designed for use with `<KeepAlive>` components. Scroll state is saved on
+* route leave and restored when the component is activated again.
+*
+* Note: Without `<KeepAlive>`, the component state is destroyed on unmount,
+* so scroll position will not be preserved.
+*
 * @template T - The type of the scrollable element (defaults to HTMLElement)
 *
 * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element

package/dist/vue.js.map

@@ -1 +1 @@
-{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport type { Nullable } from './types';\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setInterval>>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearIntervalRef(intervalRef: Ref<Nullable<ReturnType<typeof setInterval>>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setTimeout>>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setTimeout>>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement)\n *\n * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<Nullable<T>>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAgB,yCAAyC,KAAa;AAClE,QAAO,yBAAyB,KAAK,UAAU,CAAC,SAAS;;;;;;;AAQ7D,SAAgB,iBAAiB,aAA4D;AACzF,KAAI,YAAY,MAAO,eAAc,YAAY,MAAM;AACvD,aAAY,QAAQ;;;;;;;AAQxB,SAAgB,gBAAgB,YAA0D;AACtF,KAAI,WAAW,MAAO,cAAa,WAAW,MAAM;AACpD,YAAW,QAAQ;;;;;;;;;;AAWvB,SAAgB,kBAAmD,cAAgC;CAC/F,IAAI,aAAa;CACjB,IAAI,YAAY;AAChB,mBAAkB;AACd,MAAI,CAAC,aAAa,MAAO;AACzB,eAAa,MAAM,aAAa;AAChC,eAAa,MAAM,YAAY;GACjC;AAEF,0BAAyB;AACrB,eAAa,aAAa,OAAO,cAAc;AAC/C,cAAY,aAAa,OAAO,aAAa;GAC/C"}
+{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport type { Nullable } from './types';\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setInterval>>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearIntervalRef(intervalRef: Ref<Nullable<ReturnType<typeof setInterval>>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setTimeout>>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setTimeout>>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * Designed for use with `<KeepAlive>` components. Scroll state is saved on\n * route leave and restored when the component is activated again.\n *\n * Note: Without `<KeepAlive>`, the component state is destroyed on unmount,\n * so scroll position will not be preserved.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement)\n *\n * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<Nullable<T>>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAgB,yCAAyC,KAAa;AAClE,QAAO,yBAAyB,KAAK,UAAU,CAAC,SAAS;;;;;;;AAQ7D,SAAgB,iBAAiB,aAA4D;AACzF,KAAI,YAAY,MAAO,eAAc,YAAY,MAAM;AACvD,aAAY,QAAQ;;;;;;;AAQxB,SAAgB,gBAAgB,YAA0D;AACtF,KAAI,WAAW,MAAO,cAAa,WAAW,MAAM;AACpD,YAAW,QAAQ;;;;;;;;;;;;;;;;AAiBvB,SAAgB,kBAAmD,cAAgC;CAC/F,IAAI,aAAa;CACjB,IAAI,YAAY;AAChB,mBAAkB;AACd,MAAI,CAAC,aAAa,MAAO;AACzB,eAAa,MAAM,aAAa;AAChC,eAAa,MAAM,YAAY;GACjC;AAEF,0BAAyB;AACrB,eAAa,aAAa,OAAO,cAAc;AAC/C,cAAY,aAAa,OAAO,aAAa;GAC/C"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "15.0.0",
+  "version": "15.0.2",
   "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",
@@ -67,21 +67,21 @@
     "typecheck": "tsc -b --noEmit"
   },
   "peerDependencies": {
-    "@noble/hashes": "^2.0.1",
+    "@noble/hashes": "^2.2.0",
     "@types/ssh2": "^1.15.5",
     "async-validator": "^4.2.5",
     "bson": "^7.2.0",
     "consola": "^3.4.2",
     "date-fns": "^4.1.0",
     "decimal.js": "^10.6.0",
-    "element-plus": "^2.13.5",
-    "lru-cache": "^11.2.6",
+    "element-plus": "^2.13.7",
+    "lru-cache": "^11.3.5",
     "millify": "^6.1.0",
-    "msgpackr": "^1.11.8",
+    "msgpackr": "^1.11.9",
     "node-ssh": "^13.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "vue": "^3.5.30",
+    "vue": "^3.5.32",
     "vue-router": ">= 4.6.4"
   },
   "peerDependenciesMeta": {
@@ -135,13 +135,13 @@
     }
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^7.7.0",
-    "@kikiutils/eslint-config": "^7.0.2",
-    "@kikiutils/tsconfigs": "^5.1.0",
-    "@noble/hashes": "^2.0.1",
-    "@types/node": "^25.4.0",
+    "@antfu/eslint-config": "^8.2.0",
+    "@kikiutils/eslint-config": "^9.0.1",
+    "@kikiutils/tsconfigs": "^6.0.0",
+    "@noble/hashes": "^2.2.0",
+    "@types/node": "^25.6.0",
     "@types/ssh2": "^1.15.5",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.4",
     "async-validator": "^4.2.5",
     "bson": "^7.2.0",
     "changelogen": "^0.6.2",
@@ -149,22 +149,22 @@
     "cross-env": "^10.1.0",
     "date-fns": "^4.1.0",
     "decimal.js": "^10.6.0",
-    "element-plus": "^2.13.5",
-    "jsdom": "^28.1.0",
-    "knip": "^5.86.0",
-    "lru-cache": "^11.2.6",
+    "element-plus": "^2.13.7",
+    "jsdom": "^29.0.2",
+    "knip": "^6.5.0",
+    "lru-cache": "^11.3.5",
     "millify": "^6.1.0",
-    "msgpackr": "^1.11.8",
+    "msgpackr": "^1.11.10",
     "node-ssh": "^13.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "publint": "^0.3.18",
-    "tsdown": "^0.21.1",
-    "typescript": "^5.9.3",
+    "tsdown": "^0.21.9",
+    "typescript": "^6.0.3",
     "unplugin-unused": "^0.5.7",
-    "vitest": "^4.0.18",
-    "vue": "^3.5.30",
-    "vue-router": "^5.0.3"
+    "vitest": "^4.1.4",
+    "vue": "^3.5.32",
+    "vue-router": "^5.0.4"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/crypto-hash.ts

@@ -1,61 +1,190 @@
+import { createHash } from 'node:crypto';
+import type {
+    BinaryLike,
+    BinaryToTextEncoding,
+} from 'node:crypto';
+
 /**
- * This file provides a set of functions for creating hash digests using different algorithms and bit lengths.
- * It includes functions for generating SHA-3 hash digests with bit lengths of 224, 256, 384, and 512,
- * as well as a function for generating MD5 hash digests.
+ * Computes the MD5 hash of the given data.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ * @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
  *
- * These functions use the Node.js crypto module to generate the hashes.
- * Can only be used in Node.js/Deno/Bun runtimes.
+ * @returns {string | Buffer} The hash digest in the specified encoding
  *
  * @example
  * ```typescript
- * import { cryptoSha3256 } from '@kikiutils/shared/crypto-hash';
+ * import { cryptoMd5 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * console.log(cryptoMd5('test')); // 33ed9a05a10b21f0...
  * ```
  */
-
-import { createHash } from 'node:crypto';
-import type {
-    BinaryLike,
-    BinaryToTextEncoding,
-} from 'node:crypto';
-
 export function cryptoMd5(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
     return createHash('md5').update(data).digest(outputEncoding);
 }
 
+/**
+ * Computes the MD5 hash of the given data and returns the raw buffer.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ *
+ * @returns {Buffer} The raw hash digest as a Buffer
+ *
+ * @example
+ * ```typescript
+ * import { cryptoMd5ToBuffer } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoMd5ToBuffer('test')); // <Buffer 33 ed 9a ...>
+ * ```
+ */
 export function cryptoMd5ToBuffer(data: BinaryLike) {
     return createHash('md5').update(data).digest();
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 224-bit digest.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ * @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
+ *
+ * @returns {string | Buffer} The hash digest in the specified encoding
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3224 } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YX...
+ * ```
+ */
 export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
     return createHash('sha3-224').update(data).digest(outputEncoding);
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 224-bit digest and returns the raw buffer.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ *
+ * @returns {Buffer} The raw hash digest as a Buffer
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3224ToBuffer } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3224ToBuffer('test')); // <Buffer 0q W8 Fo ...>
+ * ```
+ */
 export function cryptoSha3224ToBuffer(data: BinaryLike) {
     return createHash('sha3-224').update(data).digest();
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 256-bit digest.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ * @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
+ *
+ * @returns {string | Buffer} The hash digest in the specified encoding
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3256 } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * ```
+ */
 export function cryptoSha3256(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
     return createHash('sha3-256').update(data).digest(outputEncoding);
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 256-bit digest and returns the raw buffer.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ *
+ * @returns {Buffer} The raw hash digest as a Buffer
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3256ToBuffer } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3256ToBuffer('test')); // <Buffer 36 f0 28 ...>
+ * ```
+ */
 export function cryptoSha3256ToBuffer(data: BinaryLike) {
     return createHash('sha3-256').update(data).digest();
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 384-bit digest.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ * @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
+ *
+ * @returns {string | Buffer} The hash digest in the specified encoding
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3384 } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
+ * ```
+ */
 export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
     return createHash('sha3-384').update(data).digest(outputEncoding);
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 384-bit digest and returns the raw buffer.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ *
+ * @returns {Buffer} The raw hash digest as a Buffer
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3384ToBuffer } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3384ToBuffer('test')); // <Buffer 1Q 2w QZ ...>
+ * ```
+ */
 export function cryptoSha3384ToBuffer(data: BinaryLike) {
     return createHash('sha3-384').update(data).digest();
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 512-bit digest.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ * @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
+ *
+ * @returns {string | Buffer} The hash digest in the specified encoding
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3512 } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3512('test')); // b_NQJ8FJBY9dIjm1q7...
+ * ```
+ */
 export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
     return createHash('sha3-512').update(data).digest(outputEncoding);
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 512-bit digest and returns the raw buffer.
+ *
+ * @param {BinaryLike} data - The input data to hash
+ *
+ * @returns {Buffer} The raw hash digest as a Buffer
+ *
+ * @example
+ * ```typescript
+ * import { cryptoSha3512ToBuffer } from '@kikiutils/shared/crypto-hash';
+ *
+ * console.log(cryptoSha3512ToBuffer('test')); // <Buffer b_ NQ ...>
+ * ```
+ */
 export function cryptoSha3512ToBuffer(data: BinaryLike) {
     return createHash('sha3-512').update(data).digest();
 }

package/src/datetime.ts

@@ -42,8 +42,6 @@ export type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek'
  * // Format a date string
  * console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10
  * ```
- *
- * @see https://date-fns.org/docs/format
  */
 export function formatDate(date: DateArg<Date> & {}, format: string = 'yyyy-MM-dd HH:mm:ss', options?: FormatOptions) {
     return dateFnsFormat(date, format, options);

package/src/env.ts

@@ -35,6 +35,8 @@ export class EnvironmentNotFoundError extends Error {
  *
  * @example
  * ```typescript
+ * import { checkAndGetEnvValue } from '@kikiutils/shared/env';
+ *
  * process.env.API_KEY = '';
  * checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered "defined")
  *

package/src/event-awaiter.ts

@@ -82,7 +82,7 @@ export class EventAwaiter<T> {
 
             resolvers.push(resolve);
             this.#promiseResolvers.set(key, resolvers);
-            if (timeoutMs) {
+            if (timeoutMs != null) {
                 setTimeout(
                     () => {
                         const resolvers = this.#promiseResolvers.get(key);