@kikiutils/shared 18.0.0 → 18.1.0

package/dist/object.js

@@ -2,6 +2,7 @@
 /**
 * Serializes a nested object into a deterministic, flat string format.
 *
+* @remarks
 * This function recursively traverses the input object (including nested objects and arrays),
 * flattens it into key paths using dot notation (e.g. "a.b.0.c"), sorts all keys,
 * and joins each key-value pair into a string with customizable separators.
@@ -12,18 +13,30 @@
 * Note: Empty objects and arrays produce an empty string, which is useful for
 * generating deterministic signature payloads.
 *
-* @param {Record<string, any>} input - The object to serialize. Can contain nested objects and arrays
-* @param {string} kvSeparator - The string used to separate each key from its value (default: '=')
-* @param {string} pairSeparator - The string used to separate each key-value pair (default: '&')
-* @returns {string} A deterministic string representation of the input object
+* @param input - The object to serialize. Can contain nested objects and arrays.
+* @param kvSeparator - The string used to separate each key from its value (default: '=').
+* @param pairSeparator - The string used to separate each key-value pair (default: '&').
+*
+* @returns A deterministic string representation of the input object.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { stringifyObjectDeterministically } from '@kikiutils/shared/object';
 *
-* console.log(stringifyObjectDeterministically({ b: 2, a: { x: 1, y: [3, 4] } })); // a.x=1&a.y.0=3&a.y.1=4&b=2
-* console.log(stringifyObjectDeterministically({ foo: 'bar' }, ':', '|')); // foo:bar
-* console.log(stringifyObjectDeterministically({})); // ''
+* console.log(stringifyObjectDeterministically({
+*     b: 2,
+*     a: {
+*         x: 1,
+*         y: [
+*             3,
+*             4,
+*         ],
+*     },
+* })); // => a.x=1&a.y.0=3&a.y.1=4&b=2
+*
+* console.log(stringifyObjectDeterministically({ foo: 'bar' }, ':', '|')); // => foo:bar
+* console.log(stringifyObjectDeterministically({})); // => ''
 * ```
 */
 function stringifyObjectDeterministically(input, kvSeparator = "=", pairSeparator = "&") {

package/dist/object.js.map

@@ -1 +1 @@
-{"version":3,"file":"object.js","names":[],"sources":["../src/object.ts"],"sourcesContent":["/**\n * Serializes a nested object into a deterministic, flat string format.\n *\n * This function recursively traverses the input object (including nested objects and arrays),\n * flattens it into key paths using dot notation (e.g. \"a.b.0.c\"), sorts all keys,\n * and joins each key-value pair into a string with customizable separators.\n *\n * It is designed for use cases such as signature generation, cache key construction,\n * or any context requiring consistent and predictable object serialization.\n *\n * Note: Empty objects and arrays produce an empty string, which is useful for\n * generating deterministic signature payloads.\n *\n * @param {Record<string, any>} input - The object to serialize. Can contain nested objects and arrays\n * @param {string} kvSeparator - The string used to separate each key from its value (default: '=')\n * @param {string} pairSeparator - The string used to separate each key-value pair (default: '&')\n * @returns {string} A deterministic string representation of the input object\n *\n * @example\n * ```typescript\n * import { stringifyObjectDeterministically } from '@kikiutils/shared/object';\n *\n * console.log(stringifyObjectDeterministically({ b: 2, a: { x: 1, y: [3, 4] } })); // a.x=1&a.y.0=3&a.y.1=4&b=2\n * console.log(stringifyObjectDeterministically({ foo: 'bar' }, ':', '|')); // foo:bar\n * console.log(stringifyObjectDeterministically({})); // ''\n * ```\n */\nexport function stringifyObjectDeterministically(\n    input: Record<string, any>,\n    kvSeparator: string = '=',\n    pairSeparator: string = '&',\n) {\n    const entries: string[] = [];\n\n    function walk(object: any, path: string[] = []) {\n        if (Array.isArray(object)) {\n            object.forEach((value, i) => {\n                walk(\n                    value,\n                    [\n                        ...path,\n                        i.toString(),\n                    ],\n                );\n            });\n        } else if (\n            object !== null\n            && typeof object === 'object'\n            && Object.prototype.toString.call(object) === '[object Object]'\n        ) {\n            Object.keys(object).sort().forEach((key) => {\n                walk(\n                    object[key],\n                    [\n                        ...path,\n                        key,\n                    ],\n                );\n            });\n        } else entries.push(`${path.join('.')}${kvSeparator}${String(object)}`);\n    }\n\n    walk(input);\n    return entries.sort().join(pairSeparator);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,iCACZ,OACA,cAAsB,KACtB,gBAAwB,KAC1B;CACE,MAAM,UAAoB,CAAC;CAE3B,SAAS,KAAK,QAAa,OAAiB,CAAC,GAAG;EAC5C,IAAI,MAAM,QAAQ,MAAM,GACpB,OAAO,SAAS,OAAO,MAAM;GACzB,KACI,OACA,CACI,GAAG,MACH,EAAE,SAAS,CACf,CACJ;EACJ,CAAC;OACE,IACH,WAAW,QACR,OAAO,WAAW,YAClB,OAAO,UAAU,SAAS,KAAK,MAAM,MAAM,mBAE9C,OAAO,KAAK,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ;GACxC,KACI,OAAO,MACP,CACI,GAAG,MACH,GACJ,CACJ;EACJ,CAAC;OACE,QAAQ,KAAK,GAAG,KAAK,KAAK,GAAG,IAAI,cAAc,OAAO,MAAM,GAAG;CAC1E;CAEA,KAAK,KAAK;CACV,OAAO,QAAQ,KAAK,CAAC,CAAC,KAAK,aAAa;AAC5C"}
+{"version":3,"file":"object.js","names":[],"sources":["../src/object.ts"],"sourcesContent":["/**\n * Serializes a nested object into a deterministic, flat string format.\n *\n * @remarks\n * This function recursively traverses the input object (including nested objects and arrays),\n * flattens it into key paths using dot notation (e.g. \"a.b.0.c\"), sorts all keys,\n * and joins each key-value pair into a string with customizable separators.\n *\n * It is designed for use cases such as signature generation, cache key construction,\n * or any context requiring consistent and predictable object serialization.\n *\n * Note: Empty objects and arrays produce an empty string, which is useful for\n * generating deterministic signature payloads.\n *\n * @param input - The object to serialize. Can contain nested objects and arrays.\n * @param kvSeparator - The string used to separate each key from its value (default: '=').\n * @param pairSeparator - The string used to separate each key-value pair (default: '&').\n *\n * @returns A deterministic string representation of the input object.\n *\n * @example\n *\n * ```ts\n * import { stringifyObjectDeterministically } from '@kikiutils/shared/object';\n *\n * console.log(stringifyObjectDeterministically({\n *     b: 2,\n *     a: {\n *         x: 1,\n *         y: [\n *             3,\n *             4,\n *         ],\n *     },\n * })); // => a.x=1&a.y.0=3&a.y.1=4&b=2\n *\n * console.log(stringifyObjectDeterministically({ foo: 'bar' }, ':', '|')); // => foo:bar\n * console.log(stringifyObjectDeterministically({})); // => ''\n * ```\n */\nexport function stringifyObjectDeterministically(\n    input: Record<string, any>,\n    kvSeparator: string = '=',\n    pairSeparator: string = '&',\n) {\n    const entries: string[] = [];\n\n    function walk(object: any, path: string[] = []) {\n        if (Array.isArray(object)) {\n            object.forEach((value, i) => {\n                walk(\n                    value,\n                    [\n                        ...path,\n                        i.toString(),\n                    ],\n                );\n            });\n        } else if (\n            object !== null\n            && typeof object === 'object'\n            && Object.prototype.toString.call(object) === '[object Object]'\n        ) {\n            Object.keys(object).sort().forEach((key) => {\n                walk(\n                    object[key],\n                    [\n                        ...path,\n                        key,\n                    ],\n                );\n            });\n        } else entries.push(`${path.join('.')}${kvSeparator}${String(object)}`);\n    }\n\n    walk(input);\n    return entries.sort().join(pairSeparator);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,iCACZ,OACA,cAAsB,KACtB,gBAAwB,KAC1B;CACE,MAAM,UAAoB,CAAC;CAE3B,SAAS,KAAK,QAAa,OAAiB,CAAC,GAAG;EAC5C,IAAI,MAAM,QAAQ,MAAM,GACpB,OAAO,SAAS,OAAO,MAAM;GACzB,KACI,OACA,CACI,GAAG,MACH,EAAE,SAAS,CACf,CACJ;EACJ,CAAC;OACE,IACH,WAAW,QACR,OAAO,WAAW,YAClB,OAAO,UAAU,SAAS,KAAK,MAAM,MAAM,mBAE9C,OAAO,KAAK,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ;GACxC,KACI,OAAO,MACP,CACI,GAAG,MACH,GACJ,CACJ;EACJ,CAAC;OACE,QAAQ,KAAK,GAAG,KAAK,KAAK,GAAG,IAAI,cAAc,OAAO,MAAM,GAAG;CAC1E;CAEA,KAAK,KAAK;CACV,OAAO,QAAQ,KAAK,CAAC,CAAC,KAAK,aAAa;AAC5C"}

package/dist/pino.d.ts

@@ -1,27 +1,24 @@
 //#region src/pino.d.ts
 /**
- * A pino logger instance with the configured stream.
+ * A pino logger with environment-controlled verbosity.
  *
- * The logger's level is determined based on the `PINO_LOGGER_LEVEL` and `NODE_ENV` environment variables.
- * If `PINO_LOGGER_LEVEL` is set, it will be used; otherwise, if `NODE_ENV` is `production`,
- * the level will be set to `error`.
- *
- * To manually change the level, assign the desired level to `logger.level`.
- *
- * See available levels [here](https://getpino.io/#/docs/api?id=level-string).
+ * @remarks
+ * `PINO_LOGGER_LEVEL` sets the log level when nonempty at module initialization;
+ * otherwise, `NODE_ENV=production` selects `error`, and other environments retain the logger's default level.
+ * Assign `logger.level` to change verbosity after initialization.
  *
  * @example
- * ```typescript
- * import { logger } from '@kikiutils/shared/pino';
  *
- * logger.info('test'); // [2024-07-11 12:12:30.085] INFO: test
+ * ```ts
+ * import { logger } from '@kikiutils/shared/pino';
  *
- * // Manually change the level
  * logger.level = 'info';
+ * logger.info('Application started');
  * ```
+ *
+ * @see {@link https://getpino.io/#/docs/api?id=level-string | Pino log levels}
  */
-declare const pinoLogger: import("pino").Logger<never, boolean>;
-declare const logger: import("pino").Logger<never, boolean>;
+export declare const pinoLogger: import("pino").Logger<never, boolean>;
+export declare const logger: import("pino").Logger<never, boolean>;
 //#endregion
-export { logger, pinoLogger };
 //# sourceMappingURL=pino.d.ts.map

package/dist/pino.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pino.d.ts","names":[],"sources":["../src/pino.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;cAiCa,2BAAU;cACV,uBAAM"}
+{"version":3,"file":"pino.d.ts","names":[],"sources":["../src/pino.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;qBA6Ba,2BAAU;qBACV,uBAAM"}

package/dist/pino.js

@@ -1,34 +1,29 @@
 import { pino } from "pino";
 import { PinoPretty } from "pino-pretty";
 //#region src/pino.ts
-/**
-* Configure pinoPretty to enhance the log output.
-*/
 const stream = PinoPretty({
 	colorize: true,
 	ignore: "hostname,pid",
 	translateTime: "SYS:yyyy-mm-dd HH:MM:ss.l"
 });
 /**
-* A pino logger instance with the configured stream.
-*
-* The logger's level is determined based on the `PINO_LOGGER_LEVEL` and `NODE_ENV` environment variables.
-* If `PINO_LOGGER_LEVEL` is set, it will be used; otherwise, if `NODE_ENV` is `production`,
-* the level will be set to `error`.
-*
-* To manually change the level, assign the desired level to `logger.level`.
+* A pino logger with environment-controlled verbosity.
 *
-* See available levels [here](https://getpino.io/#/docs/api?id=level-string).
+* @remarks
+* `PINO_LOGGER_LEVEL` sets the log level when nonempty at module initialization;
+* otherwise, `NODE_ENV=production` selects `error`, and other environments retain the logger's default level.
+* Assign `logger.level` to change verbosity after initialization.
 *
 * @example
-* ```typescript
-* import { logger } from '@kikiutils/shared/pino';
 *
-* logger.info('test'); // [2024-07-11 12:12:30.085] INFO: test
+* ```ts
+* import { logger } from '@kikiutils/shared/pino';
 *
-* // Manually change the level
 * logger.level = 'info';
+* logger.info('Application started');
 * ```
+*
+* @see {@link https://getpino.io/#/docs/api?id=level-string | Pino log levels}
 */
 const pinoLogger = pino({}, stream);
 const logger = pinoLogger;

package/dist/pino.js.map

@@ -1 +1 @@
-{"version":3,"file":"pino.js","names":[],"sources":["../src/pino.ts"],"sourcesContent":["import { pino } from 'pino';\nimport { PinoPretty } from 'pino-pretty';\n\n/**\n * Configure pinoPretty to enhance the log output.\n */\nconst stream = PinoPretty({\n    colorize: true, // Enable colored output for better readability\n    ignore: 'hostname,pid', // Exclude 'hostname' and 'pid' fields from the logs\n    translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l', // Format the timestamp in 'yyyy-mm-dd HH:MM:ss.l' format\n});\n\n/**\n * A pino logger instance with the configured stream.\n *\n * The logger's level is determined based on the `PINO_LOGGER_LEVEL` and `NODE_ENV` environment variables.\n * If `PINO_LOGGER_LEVEL` is set, it will be used; otherwise, if `NODE_ENV` is `production`,\n * the level will be set to `error`.\n *\n * To manually change the level, assign the desired level to `logger.level`.\n *\n * See available levels [here](https://getpino.io/#/docs/api?id=level-string).\n *\n * @example\n * ```typescript\n * import { logger } from '@kikiutils/shared/pino';\n *\n * logger.info('test'); // [2024-07-11 12:12:30.085] INFO: test\n *\n * // Manually change the level\n * logger.level = 'info';\n * ```\n */\nexport const pinoLogger = pino({}, stream);\nexport const logger = pinoLogger;\n// eslint-disable-next-line style/max-len\npinoLogger.level = process.env.PINO_LOGGER_LEVEL || (process.env.NODE_ENV === 'production' ? 'error' : pinoLogger.level);\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,WAAW;CACtB,UAAU;CACV,QAAQ;CACR,eAAe;AACnB,CAAC;;;;;;;;;;;;;;;;;;;;;;AAuBD,MAAa,aAAa,KAAK,CAAC,GAAG,MAAM;AACzC,MAAa,SAAS;AAEtB,WAAW,QAAQ,QAAQ,IAAI,sBAAsB,QAAQ,IAAI,aAAa,eAAe,UAAU,WAAW"}
+{"version":3,"file":"pino.js","names":[],"sources":["../src/pino.ts"],"sourcesContent":["import { pino } from 'pino';\nimport { PinoPretty } from 'pino-pretty';\n\n// Configure pretty-printed log output.\nconst stream = PinoPretty({\n    colorize: true, // Enable colored output for better readability\n    ignore: 'hostname,pid', // Exclude 'hostname' and 'pid' fields from the logs\n    translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l', // Format the timestamp in 'yyyy-mm-dd HH:MM:ss.l' format\n});\n\n/**\n * A pino logger with environment-controlled verbosity.\n *\n * @remarks\n * `PINO_LOGGER_LEVEL` sets the log level when nonempty at module initialization;\n * otherwise, `NODE_ENV=production` selects `error`, and other environments retain the logger's default level.\n * Assign `logger.level` to change verbosity after initialization.\n *\n * @example\n *\n * ```ts\n * import { logger } from '@kikiutils/shared/pino';\n *\n * logger.level = 'info';\n * logger.info('Application started');\n * ```\n *\n * @see {@link https://getpino.io/#/docs/api?id=level-string | Pino log levels}\n */\nexport const pinoLogger = pino({}, stream);\nexport const logger = pinoLogger;\n// eslint-disable-next-line style/max-len\npinoLogger.level = process.env.PINO_LOGGER_LEVEL || (process.env.NODE_ENV === 'production' ? 'error' : pinoLogger.level);\n"],"mappings":";;;AAIA,MAAM,SAAS,WAAW;CACtB,UAAU;CACV,QAAQ;CACR,eAAe;AACnB,CAAC;;;;;;;;;;;;;;;;;;;;AAqBD,MAAa,aAAa,KAAK,CAAC,GAAG,MAAM;AACzC,MAAa,SAAS;AAEtB,WAAW,QAAQ,QAAQ,IAAI,sBAAsB,QAAQ,IAAI,aAAa,eAAe,UAAU,WAAW"}

package/dist/random.d.ts

@@ -1,25 +1,27 @@
 //#region src/random.d.ts
 /**
- * Generates a value using a provided generator function, where the input length
- * is determined by two levels of nested random ranges:
+ * Calls a generator once with a length sampled from two nested random ranges.
  *
- * 1. First, a random number (`innerMin`) is chosen between `minMin` and `minMax`.
- * 2. Then, a final length is chosen between `Math.max(innerMin, maxMin)` and `maxMax`.
- * 3. The generator is called with the final length and its result is returned.
+ * @remarks
+ * Integer bounds are inclusive. First, a lower bound is sampled between `minMin` and `minMax`;
+ * the final length is sampled between the larger of that value and `maxMin`, and `maxMax`.
+ * Inputs must be finite integers and `minMax` must not exceed `maxMax` for valid nested ranges;
+ * these requirements are not checked beyond the two individual bound-order checks.
+ * The callback is called synchronously once after sampling. Its return value, including a promise,
+ * is returned unchanged, and any synchronous exception propagates.
  *
- * This function supports any return type by using a generic type parameter.
+ * @typeParam T - The generator's return value, preserved without awaiting or copying.
  *
- * @template T - The return type of the generator function
+ * @param generator - The callback that receives the sampled length.
+ * @param minMin - The inclusive lower bound for the first sample.
+ * @param minMax - The inclusive upper bound for the first sample.
+ * @param maxMin - The minimum inclusive lower bound for the final sample.
+ * @param maxMax - The inclusive upper bound for the final sample.
  *
- * @param {(length: number) => T} generator - A function that accepts a length and returns a value of type T
- * @param {number} minMin - Lower bound of the first random range
- * @param {number} minMax - Upper bound of the first random range
- * @param {number} maxMin - Lower bound of the second random range
- * @param {number} maxMax - Upper bound of the second random range
+ * @returns The generator's result for the sampled length.
  *
- * @returns {T} The result of the generator function using the computed final length
+ * @throws Error if `minMin` exceeds `minMax` or `maxMin` exceeds `maxMax`.
  */
-declare function generateWithNestedRandomLength<T = string>(generator: (length: number) => T, minMin: number, minMax: number, maxMin: number, maxMax: number): T;
+export declare function generateWithNestedRandomLength<T = string>(generator: (length: number) => T, minMin: number, minMax: number, maxMin: number, maxMax: number): T;
 //#endregion
-export { generateWithNestedRandomLength };
 //# sourceMappingURL=random.d.ts.map

package/dist/random.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random.d.ts","names":[],"sources":["../src/random.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;iBAoBgB,+BAA+B,YAC3C,YAAY,mBAAmB,GAC/B,gBACA,gBACA,gBACA,iBAAc"}
+{"version":3,"file":"random.d.ts","names":[],"sources":["../src/random.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;wBAuBgB,+BAA+B,YAC3C,YAAY,mBAAmB,GAC/B,gBACA,gBACA,gBACA,iBAAc"}

package/dist/random.js

@@ -1,23 +1,26 @@
 //#region src/random.ts
 /**
-* Generates a value using a provided generator function, where the input length
-* is determined by two levels of nested random ranges:
+* Calls a generator once with a length sampled from two nested random ranges.
 *
-* 1. First, a random number (`innerMin`) is chosen between `minMin` and `minMax`.
-* 2. Then, a final length is chosen between `Math.max(innerMin, maxMin)` and `maxMax`.
-* 3. The generator is called with the final length and its result is returned.
+* @remarks
+* Integer bounds are inclusive. First, a lower bound is sampled between `minMin` and `minMax`;
+* the final length is sampled between the larger of that value and `maxMin`, and `maxMax`.
+* Inputs must be finite integers and `minMax` must not exceed `maxMax` for valid nested ranges;
+* these requirements are not checked beyond the two individual bound-order checks.
+* The callback is called synchronously once after sampling. Its return value, including a promise,
+* is returned unchanged, and any synchronous exception propagates.
 *
-* This function supports any return type by using a generic type parameter.
+* @typeParam T - The generator's return value, preserved without awaiting or copying.
 *
-* @template T - The return type of the generator function
+* @param generator - The callback that receives the sampled length.
+* @param minMin - The inclusive lower bound for the first sample.
+* @param minMax - The inclusive upper bound for the first sample.
+* @param maxMin - The minimum inclusive lower bound for the final sample.
+* @param maxMax - The inclusive upper bound for the final sample.
 *
-* @param {(length: number) => T} generator - A function that accepts a length and returns a value of type T
-* @param {number} minMin - Lower bound of the first random range
-* @param {number} minMax - Upper bound of the first random range
-* @param {number} maxMin - Lower bound of the second random range
-* @param {number} maxMax - Upper bound of the second random range
+* @returns The generator's result for the sampled length.
 *
-* @returns {T} The result of the generator function using the computed final length
+* @throws Error if `minMin` exceeds `minMax` or `maxMin` exceeds `maxMax`.
 */
 function generateWithNestedRandomLength(generator, minMin, minMax, maxMin, maxMax) {
 	if (minMin > minMax) throw new Error(`Invalid range: minMin (${minMin}) cannot be greater than minMax (${minMax})`);

package/dist/random.js.map

@@ -1 +1 @@
-{"version":3,"file":"random.js","names":[],"sources":["../src/random.ts"],"sourcesContent":["/**\n * Generates a value using a provided generator function, where the input length\n * is determined by two levels of nested random ranges:\n *\n * 1. First, a random number (`innerMin`) is chosen between `minMin` and `minMax`.\n * 2. Then, a final length is chosen between `Math.max(innerMin, maxMin)` and `maxMax`.\n * 3. The generator is called with the final length and its result is returned.\n *\n * This function supports any return type by using a generic type parameter.\n *\n * @template T - The return type of the generator function\n *\n * @param {(length: number) => T} generator - A function that accepts a length and returns a value of type T\n * @param {number} minMin - Lower bound of the first random range\n * @param {number} minMax - Upper bound of the first random range\n * @param {number} maxMin - Lower bound of the second random range\n * @param {number} maxMax - Upper bound of the second random range\n *\n * @returns {T} The result of the generator function using the computed final length\n */\nexport function generateWithNestedRandomLength<T = string>(\n    generator: (length: number) => T,\n    minMin: number,\n    minMax: number,\n    maxMin: number,\n    maxMax: number,\n) {\n    if (minMin > minMax) throw new Error(`Invalid range: minMin (${minMin}) cannot be greater than minMax (${minMax})`);\n    if (maxMin > maxMax) throw new Error(`Invalid range: maxMin (${maxMin}) cannot be greater than maxMax (${maxMax})`);\n\n    const random = (min: number, max: number) => Math.floor(Math.random() * (max - min + 1)) + min;\n    const innerMin = random(minMin, minMax);\n    const finalLength = random(Math.max(innerMin, maxMin), maxMax);\n    return generator(finalLength);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,+BACZ,WACA,QACA,QACA,QACA,QACF;CACE,IAAI,SAAS,QAAQ,MAAM,IAAI,MAAM,0BAA0B,OAAO,mCAAmC,OAAO,EAAE;CAClH,IAAI,SAAS,QAAQ,MAAM,IAAI,MAAM,0BAA0B,OAAO,mCAAmC,OAAO,EAAE;CAElH,MAAM,UAAU,KAAa,QAAgB,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE,IAAI;CAC3F,MAAM,WAAW,OAAO,QAAQ,MAAM;CAEtC,OAAO,UADa,OAAO,KAAK,IAAI,UAAU,MAAM,GAAG,MAC5B,CAAC;AAChC"}
+{"version":3,"file":"random.js","names":[],"sources":["../src/random.ts"],"sourcesContent":["/**\n * Calls a generator once with a length sampled from two nested random ranges.\n *\n * @remarks\n * Integer bounds are inclusive. First, a lower bound is sampled between `minMin` and `minMax`;\n * the final length is sampled between the larger of that value and `maxMin`, and `maxMax`.\n * Inputs must be finite integers and `minMax` must not exceed `maxMax` for valid nested ranges;\n * these requirements are not checked beyond the two individual bound-order checks.\n * The callback is called synchronously once after sampling. Its return value, including a promise,\n * is returned unchanged, and any synchronous exception propagates.\n *\n * @typeParam T - The generator's return value, preserved without awaiting or copying.\n *\n * @param generator - The callback that receives the sampled length.\n * @param minMin - The inclusive lower bound for the first sample.\n * @param minMax - The inclusive upper bound for the first sample.\n * @param maxMin - The minimum inclusive lower bound for the final sample.\n * @param maxMax - The inclusive upper bound for the final sample.\n *\n * @returns The generator's result for the sampled length.\n *\n * @throws Error if `minMin` exceeds `minMax` or `maxMin` exceeds `maxMax`.\n */\nexport function generateWithNestedRandomLength<T = string>(\n    generator: (length: number) => T,\n    minMin: number,\n    minMax: number,\n    maxMin: number,\n    maxMax: number,\n) {\n    if (minMin > minMax) throw new Error(`Invalid range: minMin (${minMin}) cannot be greater than minMax (${minMax})`);\n    if (maxMin > maxMax) throw new Error(`Invalid range: maxMin (${maxMin}) cannot be greater than maxMax (${maxMax})`);\n\n    const random = (min: number, max: number) => Math.floor(Math.random() * (max - min + 1)) + min;\n    const innerMin = random(minMin, minMax);\n    const finalLength = random(Math.max(innerMin, maxMin), maxMax);\n    return generator(finalLength);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,+BACZ,WACA,QACA,QACA,QACA,QACF;CACE,IAAI,SAAS,QAAQ,MAAM,IAAI,MAAM,0BAA0B,OAAO,mCAAmC,OAAO,EAAE;CAClH,IAAI,SAAS,QAAQ,MAAM,IAAI,MAAM,0BAA0B,OAAO,mCAAmC,OAAO,EAAE;CAElH,MAAM,UAAU,KAAa,QAAgB,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE,IAAI;CAC3F,MAAM,WAAW,OAAO,QAAQ,MAAM;CAEtC,OAAO,UADa,OAAO,KAAK,IAAI,UAAU,MAAM,GAAG,MAC5B,CAAC;AAChC"}

package/dist/redis/script-runner.d.ts

@@ -0,0 +1,57 @@
+//#region src/redis/script-runner.d.ts
+/**
+ * An asynchronous Lua script runner with caller-declared results.
+ *
+ * @remarks
+ * Input arrays are unchanged, and numeric arguments are converted to strings before execution.
+ * Results are not cached or validated against the declared type.
+ *
+ * @typeParam T - The expected Lua result type, without runtime validation.
+ *
+ * @param keys - The script's Redis keys, in `KEYS` order.
+ * @param args - The script's arguments, in `ARGV` order.
+ *
+ * @returns A promise resolving to the Redis script result after execution completes.
+ */
+export type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: readonly (number | string)[]) => Promise<T>;
+/**
+ * A caller-owned Redis client exposing raw command execution.
+ *
+ * @remarks
+ * The client manages connections and command routing. `SCRIPT LOAD` and `EVALSHA` must target the same server
+ * for script-cache recovery to succeed. Missing-script rejections must be `Error` instances whose messages
+ * begin with the Redis error code `NOSCRIPT`, followed by whitespace or the end of the message.
+ */
+export interface RedisLikeScriptClient {
+  /**
+   * Sends a raw Redis command and resolves to its reply, or rejects on failure.
+   *
+   * @param command - The Redis command name.
+   * @param args - The command arguments in protocol order.
+   */
+  send: (command: string, args: string[]) => Promise<unknown>;
+}
+/**
+ * Creates a Lua script runner that reloads missing cached scripts before retrying execution.
+ *
+ * @remarks
+ * Calls use `EVALSHA` with the SHA-1 digest of the source. A `NOSCRIPT` rejection loads the script with
+ * `SCRIPT LOAD` before another execution attempt, provided the attempt limit has not been reached.
+ * Concurrent cache misses on the same runner share an in-flight load; reuse the runner to share that load.
+ * Load failures and errors other than `NOSCRIPT` propagate without retries. The final execution error is
+ * preserved when the attempt limit is reached. The runner does not cache results or close the client.
+ *
+ * @typeParam T - The expected Lua result type, without runtime validation.
+ *
+ * @param client - The caller-owned client used for raw Redis commands.
+ * @param source - The Lua source loaded when the script is absent from the server's cache.
+ * @param maxAttempts - The maximum `EVALSHA` attempts per invocation, including the initial attempt.
+ * Must be a positive safe integer. Defaults to `3`; `1` disables script loading and retries.
+ *
+ * @returns A reusable runner sharing the client and any in-flight script load.
+ *
+ * @throws RangeError if `maxAttempts` is not a positive safe integer.
+ */
+export declare function createRedisScriptRunner<T = unknown>(client: RedisLikeScriptClient, source: string, maxAttempts?: number): RedisScriptRunner<T>;
+//#endregion
+//# sourceMappingURL=script-runner.d.ts.map

package/dist/redis/script-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-runner.d.ts","names":[],"sources":["../../src/redis/script-runner.ts"],"mappings":";;;;;;;;;;;;;;;YAgBY,kBAAkB,gBAAgB,yBAAyB,uCAAuC,QAC1G;;;;;;;;;iBAWa;;;;;;;EAOb,OAAO,iBAAiB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;wBAwB/B,wBAAwB,aACpC,QAAQ,uBACR,gBACA,uBACD,kBAAkB"}

package/dist/redis/script-runner.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+//#region src/redis/script-runner.ts
+/**
+* Creates a Lua script runner that reloads missing cached scripts before retrying execution.
+*
+* @remarks
+* Calls use `EVALSHA` with the SHA-1 digest of the source. A `NOSCRIPT` rejection loads the script with
+* `SCRIPT LOAD` before another execution attempt, provided the attempt limit has not been reached.
+* Concurrent cache misses on the same runner share an in-flight load; reuse the runner to share that load.
+* Load failures and errors other than `NOSCRIPT` propagate without retries. The final execution error is
+* preserved when the attempt limit is reached. The runner does not cache results or close the client.
+*
+* @typeParam T - The expected Lua result type, without runtime validation.
+*
+* @param client - The caller-owned client used for raw Redis commands.
+* @param source - The Lua source loaded when the script is absent from the server's cache.
+* @param maxAttempts - The maximum `EVALSHA` attempts per invocation, including the initial attempt.
+* Must be a positive safe integer. Defaults to `3`; `1` disables script loading and retries.
+*
+* @returns A reusable runner sharing the client and any in-flight script load.
+*
+* @throws RangeError if `maxAttempts` is not a positive safe integer.
+*/
+function createRedisScriptRunner(client, source, maxAttempts = 3) {
+	if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) throw new RangeError("maxAttempts must be a positive safe integer");
+	const digest = createHash("sha1").update(source).digest("hex");
+	let loadingPromise;
+	return async (keys, args) => {
+		for (let attempt = 1;; attempt += 1) try {
+			return await client.send("EVALSHA", [
+				digest,
+				String(keys.length),
+				...keys,
+				...args.map(String)
+			]);
+		} catch (error) {
+			if (!(error instanceof Error) || !/^NOSCRIPT(?:\s|$)/.test(error.message) || attempt >= maxAttempts) throw error;
+			if (loadingPromise === void 0) loadingPromise = client.send("SCRIPT", ["LOAD", source]).finally(() => loadingPromise = void 0);
+			await loadingPromise;
+		}
+	};
+}
+//#endregion
+export { createRedisScriptRunner };
+
+//# sourceMappingURL=script-runner.js.map

package/dist/redis/script-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-runner.js","names":[],"sources":["../../src/redis/script-runner.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\n/**\n * An asynchronous Lua script runner with caller-declared results.\n *\n * @remarks\n * Input arrays are unchanged, and numeric arguments are converted to strings before execution.\n * Results are not cached or validated against the declared type.\n *\n * @typeParam T - The expected Lua result type, without runtime validation.\n *\n * @param keys - The script's Redis keys, in `KEYS` order.\n * @param args - The script's arguments, in `ARGV` order.\n *\n * @returns A promise resolving to the Redis script result after execution completes.\n */\nexport type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: readonly (number | string)[]) => Promise<\n    T\n>;\n\n/**\n * A caller-owned Redis client exposing raw command execution.\n *\n * @remarks\n * The client manages connections and command routing. `SCRIPT LOAD` and `EVALSHA` must target the same server\n * for script-cache recovery to succeed. Missing-script rejections must be `Error` instances whose messages\n * begin with the Redis error code `NOSCRIPT`, followed by whitespace or the end of the message.\n */\nexport interface RedisLikeScriptClient {\n    /**\n     * Sends a raw Redis command and resolves to its reply, or rejects on failure.\n     *\n     * @param command - The Redis command name.\n     * @param args - The command arguments in protocol order.\n     */\n    send: (command: string, args: string[]) => Promise<unknown>;\n}\n\n/**\n * Creates a Lua script runner that reloads missing cached scripts before retrying execution.\n *\n * @remarks\n * Calls use `EVALSHA` with the SHA-1 digest of the source. A `NOSCRIPT` rejection loads the script with\n * `SCRIPT LOAD` before another execution attempt, provided the attempt limit has not been reached.\n * Concurrent cache misses on the same runner share an in-flight load; reuse the runner to share that load.\n * Load failures and errors other than `NOSCRIPT` propagate without retries. The final execution error is\n * preserved when the attempt limit is reached. The runner does not cache results or close the client.\n *\n * @typeParam T - The expected Lua result type, without runtime validation.\n *\n * @param client - The caller-owned client used for raw Redis commands.\n * @param source - The Lua source loaded when the script is absent from the server's cache.\n * @param maxAttempts - The maximum `EVALSHA` attempts per invocation, including the initial attempt.\n * Must be a positive safe integer. Defaults to `3`; `1` disables script loading and retries.\n *\n * @returns A reusable runner sharing the client and any in-flight script load.\n *\n * @throws RangeError if `maxAttempts` is not a positive safe integer.\n */\nexport function createRedisScriptRunner<T = unknown>(\n    client: RedisLikeScriptClient,\n    source: string,\n    maxAttempts: number = 3,\n): RedisScriptRunner<T> {\n    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {\n        throw new RangeError('maxAttempts must be a positive safe integer');\n    }\n\n    const digest = createHash('sha1').update(source).digest('hex');\n    let loadingPromise: Promise<unknown> | undefined;\n\n    return async (keys, args) => {\n        for (let attempt = 1; ; attempt += 1) {\n            try {\n                return await client.send(\n                    'EVALSHA',\n                    [\n                        digest,\n                        String(keys.length),\n                        ...keys,\n                        ...args.map(String),\n                    ],\n                ) as T;\n            } catch (error) {\n                if (\n                    !(error instanceof Error)\n                    || !/^NOSCRIPT(?:\\s|$)/.test(error.message)\n                    || attempt >= maxAttempts\n                ) throw error;\n\n                if (loadingPromise === undefined) {\n                    loadingPromise = client\n                        .send(\n                            'SCRIPT',\n                            [\n                                'LOAD',\n                                source,\n                            ],\n                        )\n                        .finally(() => loadingPromise = undefined);\n                }\n\n                await loadingPromise;\n            }\n        }\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA2DA,SAAgB,wBACZ,QACA,QACA,cAAsB,GACF;CACpB,IAAI,CAAC,OAAO,cAAc,WAAW,KAAK,cAAc,GACpD,MAAM,IAAI,WAAW,6CAA6C;CAGtE,MAAM,SAAS,WAAW,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO,KAAK;CAC7D,IAAI;CAEJ,OAAO,OAAO,MAAM,SAAS;EACzB,KAAK,IAAI,UAAU,IAAK,WAAW,GAC/B,IAAI;GACA,OAAO,MAAM,OAAO,KAChB,WACA;IACI;IACA,OAAO,KAAK,MAAM;IAClB,GAAG;IACH,GAAG,KAAK,IAAI,MAAM;GACtB,CACJ;EACJ,SAAS,OAAO;GACZ,IACI,EAAE,iBAAiB,UAChB,CAAC,oBAAoB,KAAK,MAAM,OAAO,KACvC,WAAW,aAChB,MAAM;GAER,IAAI,mBAAmB,KAAA,GACnB,iBAAiB,OACZ,KACG,UACA,CACI,QACA,MACJ,CACJ,CAAC,CACA,cAAc,iBAAiB,KAAA,CAAS;GAGjD,MAAM;EACV;CAER;AACJ"}

package/dist/storages/lru/keyed-store.d.ts

@@ -1,32 +1,37 @@
 import { LRUCache } from "lru-cache";
 //#region src/storages/lru/keyed-store.d.ts
 /**
- * Creates a keyed store wrapper around an LRU cache instance.
+ * Creates a keyed cache factory sharing a caller-owned LRU cache.
  *
- * @template D - The data type stored in the keyed store
+ * @remarks
+ * The key resolver is called synchronously once per operation, and its exceptions propagate.
+ * Reads return the cached value without copying it, or `null` for missing or nullish values.
+ * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+ * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
  *
- * @param {LRUCache<any, any, any>} lruInstance - The underlying lru-cache instance
+ * @typeParam D - The stored value type used by reads and writes.
  *
- * @returns {(keyFn: (...args: P) => string) => Readonly<{
- *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem
- * }>} A factory that accepts a key resolver and returns a frozen keyed cache facade
+ * @param lruInstance - The shared LRU cache instance.
+ *
+ * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';
  * import { LRUCache } from 'lru-cache';
  *
- * const lru = new LRUCache({ max: 100 });
- * const keyedStore = createLruKeyedStore(lru)((userId: string) => `user:${userId}`);
+ * const cache = new LRUCache<string, { name: string }>({ max: 100 });
+ * const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);
  * keyedStore.setItem({ name: 'Alice' }, 'user-123');
- * const user = keyedStore.getItem('user-123'); // { name: 'Alice' }
+ * console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }
  * ```
  */
-declare function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>): <P extends any[]>(keyFn: (...args: P) => string) => Readonly<{
+export declare function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>): <P extends any[]>(keyFn: (...args: P) => string) => Readonly<{
   /**
-   * Return a value from the cache. Will update the recency of the cache entry found.
+   * Returns the cached value and applies the underlying cache's read-recency policy.
    *
-   * If the key is not found, returns `null`.
+   * @returns The cached value without copying it, or `null` when absent or nullish.
    */
   getItem(...args: P): NonNullable<D> | null;
   getItemTtl: (...args: P) => number;
@@ -39,5 +44,4 @@ declare function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any
   setItem: (value: D, ...args: P) => LRUCache<any, any, any>;
 }>;
 //#endregion
-export { createLruKeyedStore };
 //# sourceMappingURL=keyed-store.d.ts.map

package/dist/storages/lru/keyed-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;iBAwBgB,oBAAoB,aAAa,aAAa,2BAClD,iBAAiB,WAAW,MAAM,iBAAY;;;;;;EAMjC,WAAA,MAAA,IAAC,YAAA;EAII,gBAAA,MAAA;EACH,aAAA,MAAA;EACG,gBAAA,MAAA;;;;EAIA,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC"}
+{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA6BgB,oBAAoB,aAAa,aAAa,2BAClD,iBAAiB,WAAW,MAAM,iBAAY;;;;;;EAMjC,WAAA,MAAA,IAAC,YAAA;EAII,gBAAA,MAAA;EACH,aAAA,MAAA;EACG,gBAAA,MAAA;;;;EAIA,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC"}

package/dist/storages/lru/keyed-store.js

@@ -1,32 +1,37 @@
 //#region src/storages/lru/keyed-store.ts
 /**
-* Creates a keyed store wrapper around an LRU cache instance.
+* Creates a keyed cache factory sharing a caller-owned LRU cache.
 *
-* @template D - The data type stored in the keyed store
+* @remarks
+* The key resolver is called synchronously once per operation, and its exceptions propagate.
+* Reads return the cached value without copying it, or `null` for missing or nullish values.
+* `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+* The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
 *
-* @param {LRUCache<any, any, any>} lruInstance - The underlying lru-cache instance
+* @typeParam D - The stored value type used by reads and writes.
 *
-* @returns {(keyFn: (...args: P) => string) => Readonly<{
-*   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem
-* }>} A factory that accepts a key resolver and returns a frozen keyed cache facade
+* @param lruInstance - The shared LRU cache instance.
+*
+* @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';
 * import { LRUCache } from 'lru-cache';
 *
-* const lru = new LRUCache({ max: 100 });
-* const keyedStore = createLruKeyedStore(lru)((userId: string) => `user:${userId}`);
+* const cache = new LRUCache<string, { name: string }>({ max: 100 });
+* const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);
 * keyedStore.setItem({ name: 'Alice' }, 'user-123');
-* const user = keyedStore.getItem('user-123'); // { name: 'Alice' }
+* console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }
 * ```
 */
 function createLruKeyedStore(lruInstance) {
 	return (keyFn) => Object.freeze({
 		/**
-		* Return a value from the cache. Will update the recency of the cache entry found.
+		* Returns the cached value and applies the underlying cache's read-recency policy.
 		*
-		* If the key is not found, returns `null`.
+		* @returns The cached value without copying it, or `null` when absent or nullish.
 		*/
 		getItem(...args) {
 			return lruInstance.get(keyFn(...args)) ?? null;

package/dist/storages/lru/keyed-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a keyed store wrapper around an LRU cache instance.\n *\n * @template D - The data type stored in the keyed store\n *\n * @param {LRUCache<any, any, any>} lruInstance - The underlying lru-cache instance\n *\n * @returns {(keyFn: (...args: P) => string) => Readonly<{\n *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem\n * }>} A factory that accepts a key resolver and returns a frozen keyed cache facade\n *\n * @example\n * ```typescript\n * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';\n * import { LRUCache } from 'lru-cache';\n *\n * const lru = new LRUCache({ max: 100 });\n * const keyedStore = createLruKeyedStore(lru)((userId: string) => `user:${userId}`);\n * keyedStore.setItem({ name: 'Alice' }, 'user-123');\n * const user = keyedStore.getItem('user-123'); // { name: 'Alice' }\n * ```\n */\nexport function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        /**\n         * Return a value from the cache. Will update the recency of the cache entry found.\n         *\n         * If the key is not found, returns `null`.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(keyFn(...args));\n            return rawValue as D ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(keyFn(...args)),\n        hasItem: (...args: P) => lruInstance.has(keyFn(...args)),\n        removeItem: (...args: P) => lruInstance.delete(keyFn(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,oBAAiC,aAAsC;CACnF,QAAyB,UAAkC,OAAO,OAAO;;;;;;EAMrE,QAAQ,GAAG,MAAS;GAEhB,OADiB,YAAY,IAAI,MAAM,GAAG,IAAI,CAChC,KAAU;EAC5B;EACA,aAAa,GAAG,SAAY,YAAY,gBAAgB,MAAM,GAAG,IAAI,CAAC;EACtE,UAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,YAAY,OAAO,MAAM,GAAG,IAAI,CAAC;;;;EAI7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,KAAK;CAC5E,CAAC;AACL"}
+{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a keyed cache factory sharing a caller-owned LRU cache.\n *\n * @remarks\n * The key resolver is called synchronously once per operation, and its exceptions propagate.\n * Reads return the cached value without copying it, or `null` for missing or nullish values.\n * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.\n * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param lruInstance - The shared LRU cache instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.\n *\n * @example\n *\n * ```ts\n * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';\n * import { LRUCache } from 'lru-cache';\n *\n * const cache = new LRUCache<string, { name: string }>({ max: 100 });\n * const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);\n * keyedStore.setItem({ name: 'Alice' }, 'user-123');\n * console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }\n * ```\n */\nexport function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        /**\n         * Returns the cached value and applies the underlying cache's read-recency policy.\n         *\n         * @returns The cached value without copying it, or `null` when absent or nullish.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(keyFn(...args));\n            return rawValue as D ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(keyFn(...args)),\n        hasItem: (...args: P) => lruInstance.has(keyFn(...args)),\n        removeItem: (...args: P) => lruInstance.delete(keyFn(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,oBAAiC,aAAsC;CACnF,QAAyB,UAAkC,OAAO,OAAO;;;;;;EAMrE,QAAQ,GAAG,MAAS;GAEhB,OADiB,YAAY,IAAI,MAAM,GAAG,IAAI,CAChC,KAAU;EAC5B;EACA,aAAa,GAAG,SAAY,YAAY,gBAAgB,MAAM,GAAG,IAAI,CAAC;EACtE,UAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,YAAY,OAAO,MAAM,GAAG,IAAI,CAAC;;;;EAI7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,KAAK;CAC5E,CAAC;AACL"}

package/dist/storages/redis/keyed-store.d.ts

@@ -2,31 +2,22 @@ import { MaybeReadonly } from "../../types/index.js";
 import { RedisLikeStorage } from "./types.js";
 //#region src/storages/redis/keyed-store.d.ts
 /**
- * Creates a keyed store wrapper around a Redis-like storage.
+ * Creates a keyed store factory sharing a caller-owned Redis-like storage facade.
  *
- * @template D - The data type stored in the keyed store
+ * @remarks
+ * The key resolver is called synchronously once per operation with the operation's key arguments.
+ * Resolver exceptions propagate synchronously; asynchronous storage failures retain the underlying rejection.
+ * `setItemWithTtl` accepts its TTL in seconds before the value and key arguments.
+ * The factory does not open or close the underlying connection; cleanup remains the caller's responsibility.
  *
- * @param {MaybeReadonly<RedisLikeStorage>} storage - The underlying Redis-like storage instance
+ * @typeParam D - The stored value type used by reads and writes.
  *
- * @returns {(keyFn: (...args: P) => string) => Readonly<{
- *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem, setItemWithTtl
- * }>} A factory that accepts a key resolver and returns a frozen Redis keyed-store facade
+ * @param storage - The shared Redis-like storage instance.
  *
- * @example
- * ```typescript
- * import { createRedisKeyedStore } from '@kikiutils/shared/storages/redis/keyed-store';
- * 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);
- * const keyedStore = createRedisKeyedStore(storage)((userId: string) => `user:${userId}`);
- * await keyedStore.setItem({ name: 'Alice' }, 'user-123');
- * const user = await keyedStore.getItem('user-123'); // { name: 'Alice' }
- * ```
+ * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the storage.
+ * Reads, writes, removals, and TTL results retain the underlying storage contract.
  */
-declare function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>): <P extends any[]>(keyFn: (...args: P) => string) => Readonly<{
+export declare function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>): <P extends any[]>(keyFn: (...args: P) => string) => Readonly<{
   getItem: (...args: P) => Promise<D | null>;
   getItemTtl: (...args: P) => Promise<number>;
   hasItem: (...args: P) => Promise<boolean>;
@@ -36,5 +27,4 @@ declare function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<Redis
   setItemWithTtl(ttlSeconds: number, value: D, ...args: P): Promise<boolean>;
 }>;
 //#endregion
-export { createRedisKeyedStore };
 //# sourceMappingURL=keyed-store.d.ts.map

package/dist/storages/redis/keyed-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/redis/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BgB,sBAAsB,aAAa,SAAS,cAAc,qBAC9D,iBAAiB,WAAW,MAAM,iBAAY;EAC/B,aAAA,MAAA,MAAC,QAAA;EACE,gBAAA,MAAA,MAAC;EACJ,aAAA,MAAA,MAAC;EACE,gBAAA,MAAA,MAAC;EACD,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC;EACH,eAAA,oBAAM,OAAS,MAAC,MAAW,IAAC"}
+{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/redis/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;wBAoBgB,sBAAsB,aAAa,SAAS,cAAc,qBAC9D,iBAAiB,WAAW,MAAM,iBAAY;EAC/B,aAAA,MAAA,MAAC,QAAA;EACE,gBAAA,MAAA,MAAC;EACJ,aAAA,MAAA,MAAC;EACE,gBAAA,MAAA,MAAC;EACD,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC;EACH,eAAA,oBAAM,OAAS,MAAC,MAAW,IAAC"}