@kikiutils/shared 15.0.0 → 15.0.2

package/src/hash.ts

@@ -1,17 +1,3 @@
-/**
- * This file provides a set of functions for creating SHA-3 hash digests
- * using different bit lengths (224, 256, 384, 512).
- * These functions use the [@noble/hashes](https://github.com/paulmillr/noble-hashes) library to generate the hashes.
- * Can be used in the browser, mainly for Nuxt/Vue and other frameworks compiled and executed in the browser.
- *
- * @example
- * ```typescript
- * import { sha3256 } from '@kikiutils/shared/hash';
- *
- * console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
- * ```
- */
-
 import {
     sha3_224,
     sha3_256,
@@ -23,18 +9,74 @@ import {
     utf8ToBytes,
 } from '@noble/hashes/utils.js';
 
+/**
+ * Computes the SHA-3 hash of the given data using the 224-bit digest.
+ *
+ * @param {string | Uint8Array} data - The input data to hash
+ *
+ * @returns {string} The hexadecimal hash digest
+ *
+ * @example
+ * ```typescript
+ * import { sha3224 } from '@kikiutils/shared/hash';
+ *
+ * console.log(sha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YXVb3pWnLYgA4JqyprhqZ5H...
+ * ```
+ */
 export function sha3224(data: string | Uint8Array) {
     return bytesToHex(sha3_224(typeof data === 'string' ? utf8ToBytes(data) : data));
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 256-bit digest.
+ *
+ * @param {string | Uint8Array} data - The input data to hash
+ *
+ * @returns {string} The hexadecimal hash digest
+ *
+ * @example
+ * ```typescript
+ * import { sha3256 } from '@kikiutils/shared/hash';
+ *
+ * console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * ```
+ */
 export function sha3256(data: string | Uint8Array) {
     return bytesToHex(sha3_256(typeof data === 'string' ? utf8ToBytes(data) : data));
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 384-bit digest.
+ *
+ * @param {string | Uint8Array} data - The input data to hash
+ *
+ * @returns {string} The hexadecimal hash digest
+ *
+ * @example
+ * ```typescript
+ * import { sha3384 } from '@kikiutils/shared/hash';
+ *
+ * console.log(sha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
+ * ```
+ */
 export function sha3384(data: string | Uint8Array) {
     return bytesToHex(sha3_384(typeof data === 'string' ? utf8ToBytes(data) : data));
 }
 
+/**
+ * Computes the SHA-3 hash of the given data using the 512-bit digest.
+ *
+ * @param {string | Uint8Array} data - The input data to hash
+ *
+ * @returns {string} The hexadecimal hash digest
+ *
+ * @example
+ * ```typescript
+ * import { sha3512 } from '@kikiutils/shared/hash';
+ *
+ * console.log(sha3512('test')); // b_NQJ8FJBY9dIjm1q7...
+ * ```
+ */
 export function sha3512(data: string | Uint8Array) {
     return bytesToHex(sha3_512(typeof data === 'string' ? utf8ToBytes(data) : data));
 }

package/src/math.ts

@@ -51,7 +51,8 @@ export function toPercentageString(
     const molecularDecimal = new Decimal(molecular.toString());
     const denominatorDecimal = new Decimal(denominator.toString());
     const calculationResult = molecularDecimal.div(denominatorDecimal);
-    const result = calculationResult.isNaN()
+
+    const result = calculationResult.isNaN() || !calculationResult.isFinite()
         ? '0.00'
         : calculationResult.times(100).toFixed(options?.decimalPlaces ?? 2);
 

package/src/object.ts

@@ -8,6 +8,9 @@
  * It is designed for use cases such as signature generation, cache key construction,
  * or any context requiring consistent and predictable object serialization.
  *
+ * 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: '&')
@@ -19,6 +22,7 @@
  *
  * 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/random.ts

@@ -25,6 +25,9 @@ export function generateWithNestedRandomLength<T = string>(
     maxMin: number,
     maxMax: number,
 ) {
+    if (minMin > minMax) throw new Error(`Invalid range: minMin (${minMin}) cannot be greater than minMax (${minMax})`);
+    if (maxMin > maxMax) throw new Error(`Invalid range: maxMin (${maxMin}) cannot be greater than maxMax (${maxMax})`);
+
     const random = (min: number, max: number) => Math.floor(Math.random() * (max - min + 1)) + min;
     const innerMin = random(minMin, minMax);
     const finalLength = random(Math.max(innerMin, maxMin), maxMax);

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

@@ -1,5 +1,27 @@
 import type { LRUCache } from 'lru-cache';
 
+/**
+ * Creates a keyed store wrapper around an LRU cache instance.
+ *
+ * @template D - The data type stored in the keyed store
+ *
+ * @param {LRUCache<any, any, any>} lruInstance - The underlying lru-cache instance
+ *
+ * @returns {(keyFn: (...args: P) => string) => Readonly<{
+ *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem
+ * }>} A keyed store factory that takes a key resolution function
+ *
+ * @example
+ * ```typescript
+ * 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}`);
+ * await keyedStore.setItem({ name: 'Alice' }, 'user-123');
+ * const user = await 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({
         /**

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

@@ -2,6 +2,31 @@ import type { MaybeReadonly } from '../../types';
 
 import type { RedisLikeStorage } from './types';
 
+/**
+ * Creates a keyed store wrapper around a Redis-like storage.
+ *
+ * @template D - The data type stored in the keyed store
+ *
+ * @param {MaybeReadonly<RedisLikeStorage>} storage - The underlying Redis-like storage instance
+ *
+ * @returns {(keyFn: (...args: P) => string) => Readonly<{
+ *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem, setItemWithTtl
+ * }>} A keyed store factory that takes a key resolution function
+ *
+ * @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' }
+ * ```
+ */
 export function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>) {
     return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({
         getItem: (...args: P) => storage.getItem<D>(keyFn(...args)),

package/src/storages/redis/msgpack.ts

@@ -13,6 +13,26 @@ 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' }
+ * ```
+ */
 export function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {
     return Object.freeze({
         async getItem<T = unknown>(key: string) {

package/src/storages/redis/types.ts

@@ -1,19 +1,71 @@
 import type { Nullable } from '../../types';
 
+/**
+ * Low-level Redis-like adapter interface for raw buffer operations.
+ */
 export 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.
+ */
 export 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>;
 }

package/src/string.ts

@@ -46,5 +46,5 @@ export function randomString(length: number, mode: RandomStringMode = 'alphabeti
 
     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('');
 }

package/src/time.ts

@@ -1,3 +1,20 @@
+/**
+ * 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
+ * ```
+ */
 export function abortableDelay(ms: number, signal?: AbortSignal) {
     return new Promise((resolve) => {
         const timeout = setTimeout(resolve, ms);

package/src/url.ts

@@ -5,12 +5,23 @@
  *
  * @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 '/')
  */
 export function appendRedirectParamToUrl(url: string, redirectPath: string) {
-    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}`;
 }

package/src/vue.ts

@@ -43,6 +43,12 @@ export function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setTi
  * 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