@kikiutils/shared 18.0.1 → 18.2.0

package/src/storages/redis/types.ts

@@ -1,69 +1,87 @@
 /**
- * Low-level Redis-like adapter interface for raw buffer operations.
+ * A caller-owned asynchronous adapter for Redis-like binary operations.
+ *
+ * @remarks
+ * Each callback performs one operation and rejects its promise on backend failure.
+ * TTL results use Redis conventions: `-1` means no expiry, and `-2` means the key is missing.
  */
 export interface RedisLikeAdapter {
     /**
-     * Deletes a key and returns the number of keys deleted.
+     * Deletes a key and resolves to the number of keys deleted.
      */
     delete: (key: string) => Promise<number>;
 
     /**
-     * Gets the raw buffer value for a key.
+     * Reads a key and resolves to its raw bytes, or `null` when the key is missing.
      */
     getBuffer: (key: string) => Promise<null | Uint8Array>;
 
     /**
-     * Checks if a key exists.
+     * Checks a key and resolves to whether it exists.
      */
     has: (key: string) => Promise<boolean>;
 
     /**
-     * Sets a raw buffer value for a key.
+     * Writes raw bytes and resolves to the backend acknowledgment, or no value.
      */
     setBuffer: (key: string, value: Uint8Array) => Promise<'OK' | void>;
 
     /**
-     * Sets a raw buffer value for a key with a TTL.
+     * Writes raw bytes with an expiry and resolves to the backend acknowledgment, or no value.
+     *
+     * @param key - The storage key.
+     * @param ttlSeconds - The expiry duration in seconds.
+     * @param value - The raw bytes to store.
      */
     setBufferEx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | void>;
 
     /**
-     * Gets the TTL of a key in seconds.
+     * Reads a key's remaining TTL in seconds, or `-1` for no expiry and `-2` for a missing key.
      */
     ttl: (key: string) => Promise<number>;
 }
 
 /**
- * High-level Redis-like storage interface with typed get/set operations.
+ * An asynchronous Redis-like storage contract with typed reads and serialized writes.
+ *
+ * @remarks
+ * Operations reject on backend or serialization failure. TTL values are in seconds;
+ * `-1` means no expiry, and `-2` means the key is missing. Connection cleanup remains caller-owned.
  */
 export interface RedisLikeStorage {
     /**
-     * Gets a deserialized value by key.
+     * Reads a deserialized value and resolves to `null` when the key is missing.
+     *
+     * @typeParam T - The expected value type; deserialization does not validate this type.
      */
     getItem: <T = unknown>(key: string) => Promise<null | T>;
 
     /**
-     * Gets the TTL of a key in seconds.
+     * Reads a key's remaining TTL in seconds, or `-1` for no expiry and `-2` for a missing key.
      */
     getItemTtl: (key: string) => Promise<number>;
 
     /**
-     * Checks if a key exists.
+     * Checks a key and resolves to whether it exists.
      */
     hasItem: (key: string) => Promise<boolean>;
 
     /**
-     * Removes a key.
+     * Removes a key and resolves to whether a key was deleted.
      */
     removeItem: (key: string) => Promise<boolean>;
 
     /**
-     * Sets a value for a key.
+     * Stores a value and resolves to whether the backend acknowledges the write.
      */
     setItem: (key: string, value: any) => Promise<boolean>;
 
     /**
-     * Sets a value for a key with a TTL.
+     * Stores a value with an expiry and resolves to whether the backend acknowledges the write.
+     *
+     * @param key - The storage key.
+     * @param ttlSeconds - The expiry duration in seconds.
+     * @param value - The value to serialize and store.
      */
     setItemWithTtl: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
 }

package/src/string.ts

@@ -26,23 +26,25 @@ const CHARSETS: Record<RandomStringMode, string> = {
 /**
  * Generates a random string of a given length using a predefined character set.
  *
+ * @remarks
  * Uses `Math.random`, so this helper is suitable for display tokens, placeholders,
  * and test data, but not for passwords, API keys, or other cryptographic secrets.
  *
- * @param {number} length - The positive integer length of the string to generate
- * @param {RandomStringMode} [mode] - The character set to use (default: `'alphabetic'`)
+ * @param length - The positive integer length of the string to generate.
+ * @param mode - The character set to use (default: `'alphabetic'`).
  *
- * @returns {string} The generated random string
+ * @returns The generated random string.
  *
- * @throws {Error} If the length is not a positive integer or the mode is unsupported
+ * @throws Error if the length is not a positive integer or the mode is unsupported.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { randomString } from '@kikiutils/shared/string';
  *
- * randomString(8); // e.g. 'aZbXwTyQ'
- * randomString(6, 'numeric'); // e.g. '402398'
- * randomString(10, 'alphanumeric'); // e.g. 'a9Z4pQ8xY2'
+ * randomString(8); // For example, 'aZbXwTyQ'.
+ * randomString(6, 'numeric'); // For example, '402398'.
+ * randomString(10, 'alphanumeric'); // For example, 'a9Z4pQ8xY2'.
  * ```
  */
 export function randomString(length: number, mode: RandomStringMode = 'alphabetic') {

package/src/time.ts

@@ -1,20 +1,21 @@
 /**
- * Delays execution until the specified duration elapses or the signal is aborted.
+ * Waits until a duration elapses or cancellation occurs without rejecting on cancellation.
  *
- * Aborting the signal resolves the promise normally without throwing.
+ * @remarks
+ * The promise resolves without a value when the timer completes or the signal aborts.
+ * An already aborted signal resolves immediately; completion removes the abort listener and clears the timer.
  *
- * @param {number} ms - Delay duration in milliseconds
- * @param {AbortSignal} [signal] - Optional signal used to end the delay early
- *
- * @returns {Promise<void>} Resolves when the delay completes or the signal is aborted
+ * @param ms - The delay duration in milliseconds, using native `setTimeout` timing rules.
+ * @param signal - The signal that ends the wait early.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { delay } from '@kikiutils/shared/time';
  *
  * const controller = new AbortController();
- * setTimeout(() => controller.abort(), 1000);
- * await delay(5000, controller.signal); // resolves after ~1s
+ * controller.abort();
+ * await delay(5000, controller.signal);
  * ```
  */
 export function delay(ms: number, signal?: AbortSignal): Promise<void> {
@@ -37,22 +38,27 @@ export function delay(ms: number, signal?: AbortSignal): Promise<void> {
 }
 
 /**
- * Delays execution until the specified duration elapses or the signal is aborted.
+ * Waits until a duration elapses and rejects on cancellation.
  *
- * Aborting the signal rejects the promise with the signal's abort reason.
+ * @remarks
+ * The promise resolves without a value when the timer completes and rejects with `signal.reason` if aborted.
+ * An already aborted signal rejects immediately. Aborting clears the timer; timer completion removes the listener.
  *
- * @param {number} ms - Delay duration in milliseconds
- * @param {AbortSignal} [signal] - Optional signal used to abort the delay
- *
- * @returns {Promise<void>} Resolves when the delay completes or rejects when the signal is aborted
+ * @param ms - The delay duration in milliseconds, using native `setTimeout` timing rules.
+ * @param signal - The signal that cancels the wait.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { delayOrThrow } from '@kikiutils/shared/time';
  *
  * const controller = new AbortController();
- * setTimeout(() => controller.abort(), 1000);
- * await delayOrThrow(5000, controller.signal); // rejects after ~1s
+ * controller.abort(new Error('Canceled'));
+ * try {
+ *     await delayOrThrow(5000, controller.signal);
+ * } catch (error) {
+ *     console.error(error);
+ * }
  * ```
  */
 export function delayOrThrow(ms: number, signal?: AbortSignal): Promise<void> {

package/src/types/filtered-key-path.ts

@@ -1,14 +1,8 @@
 import type { ObjectId } from 'bson';
 
-/**
- * The following types are based on or inspired by types from the Element Plus project.
- * Source: https://github.com/element-plus/element-plus
- * License: MIT (https://opensource.org/licenses/MIT)
- *
- * Original types might have been modified to suit this project’s needs.
- */
+// Types adapted from Element Plus: https://github.com/element-plus/element-plus.
+// Original license: MIT (https://opensource.org/licenses/MIT).
 
-/***/
 type ConditionalPath<K extends number | string, V, U> = V extends U ? `${K}` : DefaultPath<K, V, U, never>;
 type DefaultPath<
     K extends number | string,
@@ -17,16 +11,17 @@ type DefaultPath<
     RK = `${K}`,
 > = V extends TerminalType ? RK : `${K}.${FilteredKeyPath<V, U>}`;
 
+/* eslint-disable style/max-len -- The existing conditional type is kept on one source line. */
+
 /**
- * A utility type that generates a union of key paths from a given object type `T`,
- * filtered by a specific type `U`. If `U` is
- * not provided, it defaults to including all key paths.
+ * A union of nested object key paths optionally filtered by the matching value type.
  *
- * @template T - The object type to traverse.
- * @template U - The type used to filter key paths. Defaults to `never`, meaning no filtering.
+ * @typeParam T - The object type to traverse.
+ * @typeParam U - The value type to select; `never` disables filtering.
  */
-// eslint-disable-next-line style/max-len
 export type FilteredKeyPath<T, U = never> = T extends ReadonlyArray<infer V> ? (IsTuple<T> extends true ? { [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K], U> }[TupleKey<T>] : PathImpl<number, V, U>) : { [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K], U> }[keyof T];
+/* eslint-enable style/max-len */
+
 type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
 type PathImpl<K extends number | string, V, U> = [U] extends [never] ? DefaultPath<K, V> : ConditionalPath<K, V, U>;
 type TerminalType =

package/src/types/vue.ts

@@ -1,14 +1,15 @@
 import type { GlobalComponents } from 'vue';
 
 /**
- * A type that represents a reference to a Vue component instance.
- * The reference can be either an instance of the specified component or null.
+ * A nullable reference to an instance of a globally registered Vue component.
  *
- * @template K - The key of the component in the GlobalComponents.
+ * @typeParam K - The component name in Vue's `GlobalComponents` registry.
  *
  * @example
- * ```typescript
- * import type { ComponentRef } from '@kikiutils/types/vue';
+ *
+ * ```ts
+ * import type { ComponentRef } from '@kikiutils/shared/types/vue';
+ * import { ref } from 'vue';
  *
  * const keepAliveRef = ref<ComponentRef<'KeepAlive'>>(null);
  * ```

package/src/url.ts

@@ -1,15 +1,15 @@
 /**
  * Appends or updates the `redirect` query parameter on a given URL.
  *
+ * @remarks
  * Typically used to preserve the user's current path for post-login navigation.
  *
- * @param {string} url - The target URL to modify
- * @param {string} redirectPath - The path to use as the redirect destination
- * (must be a safe same-origin application path starting with `/`)
+ * @param url - The target URL to modify.
+ * @param redirectPath - The safe same-origin application path starting with `/` to use as the redirect destination.
  *
- * @returns {string} A new URL string with the `redirect` query parameter
+ * @returns A new URL string with the `redirect` query parameter.
  *
- * @throws {Error} If redirectPath is not a safe same-origin application path
+ * @throws Error if `redirectPath` is not a safe same-origin application path.
  */
 export function appendRedirectParamToUrl(url: string, redirectPath: string) {
     // eslint-disable-next-line style/max-len
@@ -26,13 +26,14 @@ export function appendRedirectParamToUrl(url: string, redirectPath: string) {
 /**
  * Returns whether a value is a safe same-origin redirect path.
  *
+ * @remarks
  * Safe redirect paths are absolute application paths such as `/dashboard`.
  * Protocol-relative URLs (`//example.com`), absolute URLs, backslash paths,
  * and non-string values are rejected.
  *
- * @param {unknown} value - The value to check
+ * @param value - The value to check.
  *
- * @returns {boolean} Whether the value is safe to use as an application redirect path
+ * @returns Whether the value is safe to use as an application redirect path.
  */
 export function isSafeRedirectPath(value: unknown): value is string {
     if (typeof value !== 'string') return false;
@@ -45,13 +46,14 @@ export function isSafeRedirectPath(value: unknown): value is string {
 /**
  * Normalizes a redirect value into a safe same-origin application path.
  *
+ * @remarks
  * If an array is provided, the first value is checked. Unsafe values fall back
  * to the provided fallback path.
  *
- * @param {unknown} value - The redirect value to normalize
- * @param {string} fallback - The safe fallback path
+ * @param value - The redirect value to normalize.
+ * @param fallback - The caller-supplied safe fallback path; it is returned unchanged and is not validated.
  *
- * @returns {string} A safe redirect path
+ * @returns The validated input path, or the unvalidated fallback path.
  */
 export function normalizeRedirectPath(value: unknown, fallback = '/') {
     const redirectPath = Array.isArray(value) ? value[0] : value;

package/src/vue.ts

@@ -8,20 +8,20 @@ import {
 import { appendRedirectParamToUrl } from './url';
 
 /**
- * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.
+ * Appends the current Vue Router route's `fullPath` as the `redirect` query parameter to the given URL.
  *
- * @param {string} url - The base URL to modify
+ * @param url - The base URL to modify.
  *
- * @returns {string} A new URL with the current route fullPath as the `redirect` parameter
+ * @returns A new URL with the current route `fullPath` as the `redirect` parameter.
  */
 export function appendRedirectParamFromCurrentRouteToUrl(url: string) {
     return appendRedirectParamToUrl(url, useRoute().fullPath);
 }
 
 /**
- * Clears an interval referenced by a Vue ref and sets it to null.
+ * Clears an interval referenced by a Vue ref and sets it to `null`.
  *
- * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null
+ * @param intervalRef - A Vue ref holding a timer handle or `null`.
  */
 export function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {
     if (intervalRef.value) clearInterval(intervalRef.value);
@@ -29,9 +29,9 @@ export function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setIn
 }
 
 /**
- * Clears a timeout referenced by a Vue ref and sets it to null.
+ * Clears a timeout referenced by a Vue ref and sets it to `null`.
  *
- * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null
+ * @param timeoutRef - A Vue ref holding a timer handle or `null`.
  */
 export function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {
     if (timeoutRef.value) clearTimeout(timeoutRef.value);
@@ -39,18 +39,17 @@ export function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTime
 }
 
 /**
- * A Vue composition function that remembers and restores scroll position
- * of a scrollable container across route changes and keep-alive activation.
+ * Registers hooks that save and restore a container's scroll position across kept-alive route changes.
  *
- * Designed for use with `<KeepAlive>` components. Scroll state is saved on
- * route leave and restored when the component is activated again.
+ * @remarks
+ * Call within Vue component setup with Vue Router and `KeepAlive`.
+ * Route leave saves the current offsets, and each activation restores them to the currently referenced element.
+ * A missing element saves zero offsets and skips restoration. Without `KeepAlive`, unmounting discards the state.
+ * The hooks follow the component lifecycle; there is no separate cleanup handle.
  *
- * Note: Without `<KeepAlive>`, the component state is destroyed on unmount,
- * so scroll position will not be preserved.
+ * @typeParam T - The scrollable element type.
  *
- * @template T - The type of the scrollable element (defaults to HTMLElement)
- *
- * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element
+ * @param containerRef - The reference to the scrollable element, or `null` while it is unavailable.
  */
 export function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {
     let scrollLeft = 0;

package/src/web.ts

@@ -3,9 +3,9 @@ import { appendRedirectParamToUrl } from './url';
 /**
  * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
  *
- * @param {string} url - The base URL to modify
+ * @param url - The base URL to modify.
  *
- * @returns {string} A new URL with the current location as the `redirect` parameter
+ * @returns A new URL with the current location as the `redirect` parameter.
  */
 export function appendRedirectParamFromCurrentLocationToUrl(url: string) {
     const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;
@@ -13,14 +13,18 @@ export function appendRedirectParamFromCurrentLocationToUrl(url: string) {
 }
 
 /**
- * Navigates to the given URL, appending the current browser location
- * (path, query, and hash) as the `redirect` query parameter.
+ * Navigates to a URL with the current browser path, query, and hash as its redirect parameter.
  *
- * Useful for redirecting to login or other gateways while preserving
- * the current location for post-auth navigation.
+ * @remarks
+ * Omitting `delayMs` navigates immediately. Providing a delay, including `0`, schedules navigation;
+ * the current location is read when the timer fires, not when the timer is created.
+ * Requires a browser environment. Redirect-path validation errors propagate from the URL helper.
  *
- * @param {string} url - The destination URL to navigate to
- * @param {number} [delayMs] - Optional delay in milliseconds before navigation
+ * @param url - The destination URL.
+ * @param delayMs - The navigation delay in milliseconds, using native `setTimeout` timing rules.
+ *
+ * @returns A timer handle when delayed, which the caller can cancel with `clearTimeout`, or `undefined`
+ * when navigation is immediate.
  */
 export function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number) {
     if (delayMs === undefined) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));