@kikiutils/shared 18.0.1 → 18.2.0

package/src/hash.ts

@@ -12,15 +12,16 @@ import {
 /**
  * Computes the SHA-3 hash of the given data using the 224-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3224 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
+ * console.log(sha3224('test')); // => 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
  * ```
  */
 export function sha3224(data: string | Uint8Array) {
@@ -30,15 +31,16 @@ export function sha3224(data: string | Uint8Array) {
 /**
  * Computes the SHA-3 hash of the given data using the 256-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3256 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * console.log(sha3256('test')); // => 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
  * ```
  */
 export function sha3256(data: string | Uint8Array) {
@@ -48,15 +50,16 @@ export function sha3256(data: string | Uint8Array) {
 /**
  * Computes the SHA-3 hash of the given data using the 384-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3384 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
+ * console.log(sha3384('test')); // => e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
  * ```
  */
 export function sha3384(data: string | Uint8Array) {
@@ -66,15 +69,16 @@ export function sha3384(data: string | Uint8Array) {
 /**
  * Computes the SHA-3 hash of the given data using the 512-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3512 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
+ * console.log(sha3512('test')); // => 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
  * ```
  */
 export function sha3512(data: string | Uint8Array) {

package/src/math.ts

@@ -7,40 +7,42 @@ type CalculableValue = Decimal.Value | { toString: () => string };
  */
 export interface ToPercentageStringOptions {
     /**
-     * Number of decimal places to include in the result.
+     * The number of decimal places to include in the result.
      *
-     * @default 2
+     * @defaultValue 2
      */
     decimalPlaces?: number;
 
     /**
-     * Whether to include the '%' symbol in the result.
+     * Whether to include the `%` symbol in the result.
      *
-     * @default true
+     * @defaultValue true
      */
     withSymbol?: boolean;
 }
 
 /**
- * Converts a fraction (numerator / denominator) into a percentage string.
+ * Converts a numerator and denominator into a formatted percentage.
  *
- * - Uses `decimal.js` for precise decimal calculations.
- * - Supports custom decimal places and optional percentage symbol.
- * - Returns `'0.00%'` if result is `NaN` or division is invalid.
+ * @remarks
+ * A `NaN` or infinite quotient produces `0.00`, regardless of the configured decimal places;
+ * the percent symbol is appended according to `options.withSymbol`.
+ * Invalid decimal input and formatting options propagate decimal.js exceptions.
  *
- * @param {CalculableValue} molecular - The numerator of the fraction
- * @param {CalculableValue} denominator - The denominator of the fraction
- * @param {ToPercentageStringOptions} [options] - Optional output settings
+ * @param molecular - The numerator of the fraction.
+ * @param denominator - The denominator of the fraction.
+ * @param options - Output precision and percent-symbol settings.
  *
- * @returns {string} Formatted percentage string
+ * @returns The formatted percentage string.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { toPercentageString } from '@kikiutils/shared/math';
  *
- * console.log(toPercentageString(50, 200)); // 25.00%
- * console.log(toPercentageString(50, 200, { withSymbol: false })); // 25.00
- * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // 25.0%
+ * console.log(toPercentageString(50, 200)); // => '25.00%'
+ * console.log(toPercentageString(50, 200, { withSymbol: false })); // => '25.00'
+ * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // => '25.0%'
  * ```
  */
 export function toPercentageString(

package/src/number.ts

@@ -3,19 +3,21 @@ import { millify } from 'millify';
 /**
  * Converts a large number into a compact, human-readable string using `millify`.
  *
- * Applies lowercase units (e.g. 'k', 'm') and default precision of 2, unless overridden.
+ * @remarks
+ * Uses lowercase units, for example `k` and `m`, and a precision of `2` unless overridden.
  *
- * @param {number} value - The number to format
- * @param {Parameters<typeof millify>[1]} [options] - Optional configuration passed to `millify`
+ * @param value - The number to format.
+ * @param options - Optional configuration passed to `millify`.
  *
- * @returns {string} The compact number string
+ * @returns The compact number string.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { toCompactNumberString } from '@kikiutils/shared/number';
  *
- * console.log(toCompactNumberString(1234567)); // 1.23m
- * console.log(toCompactNumberString(1234567, { precision: 3 })); // 1.235m
+ * console.log(toCompactNumberString(1234567)); // => 1.23m
+ * console.log(toCompactNumberString(1234567, { precision: 3 })); // => 1.235m
  * ```
  */
 export function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]) {

package/src/object.ts

@@ -1,6 +1,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.
@@ -11,18 +12,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({})); // => ''
  * ```
  */
 export function stringifyObjectDeterministically(

package/src/pino.ts

@@ -1,9 +1,7 @@
 import { pino } from 'pino';
 import { PinoPretty } from 'pino-pretty';
 
-/**
- * Configure pinoPretty to enhance the log output.
- */
+// Configure pretty-printed log output.
 const stream = PinoPretty({
     colorize: true, // Enable colored output for better readability
     ignore: 'hostname,pid', // Exclude 'hostname' and 'pid' fields from the logs
@@ -11,25 +9,23 @@ const stream = PinoPretty({
 });
 
 /**
- * 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}
  */
 export const pinoLogger = pino({}, stream);
 export const logger = pinoLogger;

package/src/random.ts

@@ -1,22 +1,25 @@
 /**
- * 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`.
  */
 export function generateWithNestedRandomLength<T = string>(
     generator: (length: number) => T,

package/src/redis/script-runner.ts

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * 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 function createRedisScriptRunner<T = unknown>(
+    client: RedisLikeScriptClient,
+    source: string,
+    maxAttempts: number = 3,
+): RedisScriptRunner<T> {
+    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: Promise<unknown> | undefined;
+
+    return async (keys, args) => {
+        for (let attempt = 1; ; attempt += 1) {
+            try {
+                return await client.send(
+                    'EVALSHA',
+                    [
+                        digest,
+                        String(keys.length),
+                        ...keys,
+                        ...args.map(String),
+                    ],
+                ) as T;
+            } catch (error) {
+                if (
+                    !(error instanceof Error)
+                    || !/^NOSCRIPT(?:\s|$)/.test(error.message)
+                    || attempt >= maxAttempts
+                ) throw error;
+
+                if (loadingPromise === undefined) {
+                    loadingPromise = client
+                        .send(
+                            'SCRIPT',
+                            [
+                                'LOAD',
+                                source,
+                            ],
+                        )
+                        .finally(() => loadingPromise = undefined);
+                }
+
+                await loadingPromise;
+            }
+        }
+    };
+}

package/src/storages/lru/keyed-store.ts

@@ -1,33 +1,38 @@
 import type { LRUCache } from 'lru-cache';
 
 /**
- * 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' }
  * ```
  */
 export function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {
     return <P extends any[]>(keyFn: (...args: P) => string) => 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: P) {
             const rawValue = lruInstance.get(keyFn(...args));

package/src/storages/redis/keyed-store.ts

@@ -3,29 +3,20 @@ import type { MaybeReadonly } from '../../types';
 import type { RedisLikeStorage } from './types';
 
 /**
- * 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.
  */
 export function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>) {
     return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({

package/src/storages/redis/msgpack.ts

@@ -14,23 +14,44 @@ if (!isNativeAccelerationEnabled) {
 }
 
 /**
- * Creates a Redis-like storage using msgpack serialization.
+ * Creates a frozen Redis-like storage facade using MessagePack serialization.
  *
- * @param {RedisLikeAdapter} adapter - The Redis-like adapter to use for raw buffer operations
+ * @remarks
+ * Adapter rejections and MessagePack serialization errors propagate to the caller.
+ * Reads resolve to `null` when no raw value exists. Writes resolve to `true` only when the adapter returns `OK`;
+ * removal resolves to `true` only when exactly one key is deleted.
+ * The adapter remains caller-owned; creating the facade does not open or close a connection.
  *
- * @returns {Readonly<RedisLikeStorage>} A readonly storage instance
- *   with getItem, setItem, hasItem, removeItem, getItemTtl, setItemWithTtl
+ * @param adapter - The caller-owned adapter for raw binary operations.
+ *
+ * @returns A new frozen facade sharing the supplied adapter.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';
- * import { createClient } from 'redis';
+ * import type { RedisLikeAdapter } from '@kikiutils/shared/storages/redis/types';
+ *
+ * // This in-memory adapter demonstrates non-expiring operations without an external service.
+ * const values = new Map<string, Uint8Array>();
+ * const adapter: RedisLikeAdapter = {
+ *     delete: async (key) => values.delete(key) ? 1 : 0,
+ *     getBuffer: async (key) => values.get(key) ?? null,
+ *     has: async (key) => values.has(key),
+ *     setBuffer: async (key, value) => {
+ *         values.set(key, value);
+ *         return 'OK';
+ *     },
+ *     setBufferEx: async () => {
+ *         throw new Error('TTL writes are not supported by this example adapter');
+ *     },
+ *     ttl: async (key) => values.has(key) ? -1 : -2,
+ * };
  *
- * 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' }
+ * const storage = createRedisMsgpackStorage(adapter);
+ * await storage.setItem('profile', { name: 'Alice' });
+ * const profile = await storage.getItem<{ name: string }>('profile');
+ * console.log(profile); // => { name: 'Alice' }
  * ```
  */
 export function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {