@kikiutils/shared 15.0.1 → 15.0.2

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/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