@kikiutils/shared 18.0.0 → 18.1.0

package/dist/types/index.d.ts

@@ -4,39 +4,39 @@ import { Blob as Blob$1, Buffer, File as File$1 } from "node:buffer";
 /**
  * A generic string-keyed object for utility APIs that intentionally accept any value shape.
  */
-type AnyRecord = Record<string, any>;
+export type AnyRecord = Record<string, any>;
 /**
  * Binary-like inputs accepted by `toBuffer` across browser and Node.js runtimes.
  */
-type BinaryInput = ArrayBuffer | Blob | Buffer | File | Blob$1 | File$1 | Uint8Array;
+export type BinaryInput = ArrayBuffer | Blob | Buffer | File | Blob$1 | File$1 | Uint8Array;
 /**
  * Boolean values represented either as booleans or common string literals.
  */
-type Booleanish = 'false' | 'true' | boolean;
+export type Booleanish = 'false' | 'true' | boolean;
 /**
  * Accepts either a full object or a partial patch of that object.
  */
-type MaybePartial<T> = Partial<T> | T;
+export type MaybePartial<T> = Partial<T> | T;
 /**
  * Accepts either a mutable value or a readonly view of that value.
  */
-type MaybeReadonly<T> = Readonly<T> | T;
+export type MaybeReadonly<T> = Readonly<T> | T;
 /**
  * Number-like value represented as a number or a numeric string.
  */
-type Numberish = number | string;
+export type Numberish = number | string;
 /**
  * A `Record` where every key is optional.
  */
-type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>;
+export type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>;
 /**
  * A readonly `PartialRecord`.
  */
-type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialRecord<K, T>>;
+export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialRecord<K, T>>;
 /**
  * A readonly `Record`.
  */
-type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;
+export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;
 //#endregion
-export { AnyRecord, BinaryInput, Booleanish, type FilteredKeyPath, MaybePartial, MaybeReadonly, Numberish, PartialRecord, ReadonlyPartialRecord, ReadonlyRecord };
+export type { FilteredKeyPath };
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types/index.ts"],"mappings":";;;;;;KAWY,YAAY;;;;KAKZ,cAAc,cAAc,OAAO,SAAS,OAAO,SAAW,SAAW;;;;KAKzE;;;;KAKA,aAAa,KAAK,QAAQ,KAAK;;;;KAK/B,cAAc,KAAK,SAAS,KAAK;;;;KAKjC;;;;KAKA,cAAc,qBAAqB,KAAK,QAAQ,OAAO,GAAG;;;;KAK1D,sBAAsB,qBAAqB,KAAK,SAAS,cAAc,GAAG;;;;KAK1E,eAAe,qBAAqB,KAAK,SAAS,OAAO,GAAG"}
+{"version":3,"file":"index.d.ts","names":["NodeBlob","NodeFile"],"sources":["../../src/types/index.ts"],"mappings":";;;;;;YAWY,YAAY;;;;YAKZ,cAAc,cAAc,OAAO,SAAS,OAAOA,SAAWC,SAAW;;;;YAKzE;;;;YAKA,aAAa,KAAK,QAAQ,KAAK;;;;YAK/B,cAAc,KAAK,SAAS,KAAK;;;;YAKjC;;;;YAKA,cAAc,qBAAqB,KAAK,QAAQ,OAAO,GAAG;;;;YAK1D,sBAAsB,qBAAqB,KAAK,SAAS,cAAc,GAAG;;;;YAK1E,eAAe,qBAAqB,KAAK,SAAS,OAAO,GAAG"}

package/dist/types/vue.d.ts

@@ -1,19 +1,19 @@
 import { GlobalComponents } from "vue";
 //#region src/types/vue.d.ts
 /**
- * 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);
  * ```
  */
-type ComponentRef<K extends keyof GlobalComponents> = InstanceType<GlobalComponents[K]> | null;
+export type ComponentRef<K extends keyof GlobalComponents> = InstanceType<GlobalComponents[K]> | null;
 //#endregion
-export { ComponentRef };
 //# sourceMappingURL=vue.d.ts.map

package/dist/types/vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vue.d.ts","names":[],"sources":["../../src/types/vue.ts"],"mappings":";;;;;;;;;;;;;;;KAeY,aAAa,gBAAgB,oBAAoB,aAAa,iBAAiB"}
+{"version":3,"file":"vue.d.ts","names":[],"sources":["../../src/types/vue.ts"],"mappings":";;;;;;;;;;;;;;;;YAgBY,aAAa,gBAAgB,oBAAoB,aAAa,iBAAiB"}

package/dist/url.d.ts

@@ -2,41 +2,42 @@
 /**
  * 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.
  */
-declare function appendRedirectParamToUrl(url: string, redirectPath: string): string;
+export declare function appendRedirectParamToUrl(url: string, redirectPath: string): 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.
  */
-declare function isSafeRedirectPath(value: unknown): value is string;
+export declare 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.
  */
-declare function normalizeRedirectPath(value: unknown, fallback?: string): string;
+export declare function normalizeRedirectPath(value: unknown, fallback?: string): string;
 //#endregion
-export { appendRedirectParamToUrl, isSafeRedirectPath, normalizeRedirectPath };
 //# sourceMappingURL=url.d.ts.map

package/dist/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","names":[],"sources":["../src/url.ts"],"mappings":";;;;;;;;;;;;;;iBAagB,yBAAyB,aAAa;;;;;;;;;;;;iBAuBtC,mBAAmB,iBAAiB;;;;;;;;;;;;iBAmBpC,sBAAsB,gBAAgB"}
+{"version":3,"file":"url.d.ts","names":[],"sources":["../src/url.ts"],"mappings":";;;;;;;;;;;;;;wBAagB,yBAAyB,aAAa;;;;;;;;;;;;;wBAwBtC,mBAAmB,iBAAiB;;;;;;;;;;;;;wBAoBpC,sBAAsB,gBAAgB"}

package/dist/url.js

@@ -2,15 +2,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.
 */
 function appendRedirectParamToUrl(url, redirectPath) {
 	if (!isSafeRedirectPath(redirectPath)) throw new Error(`Invalid redirect path: "${redirectPath}". Redirect paths must be safe same-origin paths starting with '/'.`);
@@ -24,13 +24,14 @@ function appendRedirectParamToUrl(url, redirectPath) {
 /**
 * 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.
 */
 function isSafeRedirectPath(value) {
 	if (typeof value !== "string") return false;
@@ -42,13 +43,14 @@ function isSafeRedirectPath(value) {
 /**
 * 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.
 */
 function normalizeRedirectPath(value, fallback = "/") {
 	const redirectPath = Array.isArray(value) ? value[0] : value;

package/dist/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param {string} url - The target URL to modify\n * @param {string} redirectPath - The path to use as the redirect destination\n * (must be a safe same-origin application path starting with `/`)\n *\n * @returns {string} A new URL string with the `redirect` query parameter\n *\n * @throws {Error} If redirectPath is not a safe same-origin application path\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    // eslint-disable-next-line style/max-len\n    if (!isSafeRedirectPath(redirectPath)) throw new Error(`Invalid redirect path: \"${redirectPath}\". Redirect paths must be safe same-origin paths starting with '/'.`);\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n\n/**\n * Returns whether a value is a safe same-origin redirect path.\n *\n * Safe redirect paths are absolute application paths such as `/dashboard`.\n * Protocol-relative URLs (`//example.com`), absolute URLs, backslash paths,\n * and non-string values are rejected.\n *\n * @param {unknown} value - The value to check\n *\n * @returns {boolean} Whether the value is safe to use as an application redirect path\n */\nexport function isSafeRedirectPath(value: unknown): value is string {\n    if (typeof value !== 'string') return false;\n    if (!value.startsWith('/')) return false;\n    if (value.startsWith('//')) return false;\n    if (value.includes('\\\\')) return false;\n    return true;\n}\n\n/**\n * Normalizes a redirect value into a safe same-origin application path.\n *\n * If an array is provided, the first value is checked. Unsafe values fall back\n * to the provided fallback path.\n *\n * @param {unknown} value - The redirect value to normalize\n * @param {string} fallback - The safe fallback path\n *\n * @returns {string} A safe redirect path\n */\nexport function normalizeRedirectPath(value: unknown, fallback = '/') {\n    const redirectPath = Array.isArray(value) ? value[0] : value;\n    return isSafeRedirectPath(redirectPath) ? redirectPath : fallback;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;CAExE,IAAI,CAAC,mBAAmB,YAAY,GAAG,MAAM,IAAI,MAAM,2BAA2B,aAAa,oEAAoE;CAEnK,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,GAAG;CAClD,MAAM,CAAC,MAAM,SAAS,eAAe,GAAA,CAAI,MAAM,GAAG;CAClD,MAAM,eAAe,IAAI,gBAAgB,QAAQ;CACjD,aAAa,IAAI,YAAY,YAAY;CACzC,MAAM,cAAc,aAAa,SAAS;CAC1C,OAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG;AAChE;;;;;;;;;;;;AAaA,SAAgB,mBAAmB,OAAiC;CAChE,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,CAAC,MAAM,WAAW,GAAG,GAAG,OAAO;CACnC,IAAI,MAAM,WAAW,IAAI,GAAG,OAAO;CACnC,IAAI,MAAM,SAAS,IAAI,GAAG,OAAO;CACjC,OAAO;AACX;;;;;;;;;;;;AAaA,SAAgB,sBAAsB,OAAgB,WAAW,KAAK;CAClE,MAAM,eAAe,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;CACvD,OAAO,mBAAmB,YAAY,IAAI,eAAe;AAC7D"}
+{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * @remarks\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param url - The target URL to modify.\n * @param redirectPath - The safe same-origin application path starting with `/` to use as the redirect destination.\n *\n * @returns A new URL string with the `redirect` query parameter.\n *\n * @throws Error if `redirectPath` is not a safe same-origin application path.\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    // eslint-disable-next-line style/max-len\n    if (!isSafeRedirectPath(redirectPath)) throw new Error(`Invalid redirect path: \"${redirectPath}\". Redirect paths must be safe same-origin paths starting with '/'.`);\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n\n/**\n * Returns whether a value is a safe same-origin redirect path.\n *\n * @remarks\n * Safe redirect paths are absolute application paths such as `/dashboard`.\n * Protocol-relative URLs (`//example.com`), absolute URLs, backslash paths,\n * and non-string values are rejected.\n *\n * @param value - The value to check.\n *\n * @returns Whether the value is safe to use as an application redirect path.\n */\nexport function isSafeRedirectPath(value: unknown): value is string {\n    if (typeof value !== 'string') return false;\n    if (!value.startsWith('/')) return false;\n    if (value.startsWith('//')) return false;\n    if (value.includes('\\\\')) return false;\n    return true;\n}\n\n/**\n * Normalizes a redirect value into a safe same-origin application path.\n *\n * @remarks\n * If an array is provided, the first value is checked. Unsafe values fall back\n * to the provided fallback path.\n *\n * @param value - The redirect value to normalize.\n * @param fallback - The caller-supplied safe fallback path; it is returned unchanged and is not validated.\n *\n * @returns The validated input path, or the unvalidated fallback path.\n */\nexport function normalizeRedirectPath(value: unknown, fallback = '/') {\n    const redirectPath = Array.isArray(value) ? value[0] : value;\n    return isSafeRedirectPath(redirectPath) ? redirectPath : fallback;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;CAExE,IAAI,CAAC,mBAAmB,YAAY,GAAG,MAAM,IAAI,MAAM,2BAA2B,aAAa,oEAAoE;CAEnK,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,GAAG;CAClD,MAAM,CAAC,MAAM,SAAS,eAAe,GAAA,CAAI,MAAM,GAAG;CAClD,MAAM,eAAe,IAAI,gBAAgB,QAAQ;CACjD,aAAa,IAAI,YAAY,YAAY;CACzC,MAAM,cAAc,aAAa,SAAS;CAC1C,OAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG;AAChE;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,OAAiC;CAChE,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,CAAC,MAAM,WAAW,GAAG,GAAG,OAAO;CACnC,IAAI,MAAM,WAAW,IAAI,GAAG,OAAO;CACnC,IAAI,MAAM,SAAS,IAAI,GAAG,OAAO;CACjC,OAAO;AACX;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,OAAgB,WAAW,KAAK;CAClE,MAAM,eAAe,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;CACvD,OAAO,mBAAmB,YAAY,IAAI,eAAe;AAC7D"}

package/dist/vue.d.ts

@@ -1,40 +1,38 @@
 import { Ref } from "vue";
 //#region src/vue.d.ts
 /**
- * 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.
  */
-declare function appendRedirectParamFromCurrentRouteToUrl(url: string): string;
+export declare function appendRedirectParamFromCurrentRouteToUrl(url: string): string;
 /**
- * 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`.
  */
-declare function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>): void;
+export declare function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>): void;
 /**
- * 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`.
  */
-declare function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>): void;
+export declare function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>): void;
 /**
- * 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.
  */
-declare function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>): void;
+export declare function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>): void;
 //#endregion
-export { appendRedirectParamFromCurrentRouteToUrl, clearIntervalRef, clearTimeoutRef, usePreserveScroll };
 //# sourceMappingURL=vue.d.ts.map

package/dist/vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vue.d.ts","names":[],"sources":["../src/vue.ts"],"mappings":";;;;;;;;;iBAgBgB,yCAAyC;;;;;;iBASzC,iBAAiB,aAAa,WAAW,kBAAkB;;;;;;iBAU3D,gBAAgB,YAAY,WAAW,kBAAkB;;;;;;;;;;;;;;;iBAmBzD,kBAAkB,UAAU,UAAU,aAAa,cAAc,WAAW"}
+{"version":3,"file":"vue.d.ts","names":[],"sources":["../src/vue.ts"],"mappings":";;;;;;;;;wBAgBgB,yCAAyC;;;;;;wBASzC,iBAAiB,aAAa,WAAW,kBAAkB;;;;;;wBAU3D,gBAAgB,YAAY,WAAW,kBAAkB;;;;;;;;;;;;;;wBAkBzD,kBAAkB,UAAU,UAAU,aAAa,cAAc,WAAW"}

package/dist/vue.js

@@ -3,46 +3,45 @@ import { onActivated } from "vue";
 import { onBeforeRouteLeave, useRoute } from "vue-router";
 //#region src/vue.ts
 /**
-* 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.
 */
 function appendRedirectParamFromCurrentRouteToUrl(url) {
 	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`.
 */
 function clearIntervalRef(intervalRef) {
 	if (intervalRef.value) clearInterval(intervalRef.value);
 	intervalRef.value = null;
 }
 /**
-* 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`.
 */
 function clearTimeoutRef(timeoutRef) {
 	if (timeoutRef.value) clearTimeout(timeoutRef.value);
 	timeoutRef.value = null;
 }
 /**
-* 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.
 */
 function usePreserveScroll(containerRef) {
 	let scrollLeft = 0;

package/dist/vue.js.map

@@ -1 +1 @@
-{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<null | ReturnType<typeof setInterval>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<null | ReturnType<typeof setTimeout>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * Designed for use with `<KeepAlive>` components. Scroll state is saved on\n * route leave and restored when the component is activated again.\n *\n * Note: Without `<KeepAlive>`, the component state is destroyed on unmount,\n * so scroll position will not be preserved.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement)\n *\n * @param {Ref<null | T>} containerRef - A ref to the scrollable HTML element\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAgB,yCAAyC,KAAa;CAClE,OAAO,yBAAyB,KAAK,SAAS,CAAC,CAAC,QAAQ;AAC5D;;;;;;AAOA,SAAgB,iBAAiB,aAAyD;CACtF,IAAI,YAAY,OAAO,cAAc,YAAY,KAAK;CACtD,YAAY,QAAQ;AACxB;;;;;;AAOA,SAAgB,gBAAgB,YAAuD;CACnF,IAAI,WAAW,OAAO,aAAa,WAAW,KAAK;CACnD,WAAW,QAAQ;AACvB;;;;;;;;;;;;;;;AAgBA,SAAgB,kBAAmD,cAA6B;CAC5F,IAAI,aAAa;CACjB,IAAI,YAAY;CAChB,kBAAkB;EACd,IAAI,CAAC,aAAa,OAAO;EACzB,aAAa,MAAM,aAAa;EAChC,aAAa,MAAM,YAAY;CACnC,CAAC;CAED,yBAAyB;EACrB,aAAa,aAAa,OAAO,cAAc;EAC/C,YAAY,aAAa,OAAO,aAAa;CACjD,CAAC;AACL"}
+{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's `fullPath` as the `redirect` query parameter to the given URL.\n *\n * @param url - The base URL to modify.\n *\n * @returns A new URL with the current route `fullPath` as the `redirect` parameter.\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to `null`.\n *\n * @param intervalRef - A Vue ref holding a timer handle or `null`.\n */\nexport function clearIntervalRef(intervalRef: Ref<null | ReturnType<typeof setInterval>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to `null`.\n *\n * @param timeoutRef - A Vue ref holding a timer handle or `null`.\n */\nexport function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof setTimeout>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * Registers hooks that save and restore a container's scroll position across kept-alive route changes.\n *\n * @remarks\n * Call within Vue component setup with Vue Router and `KeepAlive`.\n * Route leave saves the current offsets, and each activation restores them to the currently referenced element.\n * A missing element saves zero offsets and skips restoration. Without `KeepAlive`, unmounting discards the state.\n * The hooks follow the component lifecycle; there is no separate cleanup handle.\n *\n * @typeParam T - The scrollable element type.\n *\n * @param containerRef - The reference to the scrollable element, or `null` while it is unavailable.\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAgB,yCAAyC,KAAa;CAClE,OAAO,yBAAyB,KAAK,SAAS,CAAC,CAAC,QAAQ;AAC5D;;;;;;AAOA,SAAgB,iBAAiB,aAAyD;CACtF,IAAI,YAAY,OAAO,cAAc,YAAY,KAAK;CACtD,YAAY,QAAQ;AACxB;;;;;;AAOA,SAAgB,gBAAgB,YAAuD;CACnF,IAAI,WAAW,OAAO,aAAa,WAAW,KAAK;CACnD,WAAW,QAAQ;AACvB;;;;;;;;;;;;;;AAeA,SAAgB,kBAAmD,cAA6B;CAC5F,IAAI,aAAa;CACjB,IAAI,YAAY;CAChB,kBAAkB;EACd,IAAI,CAAC,aAAa,OAAO;EACzB,aAAa,MAAM,aAAa;EAChC,aAAa,MAAM,YAAY;CACnC,CAAC;CAED,yBAAyB;EACrB,aAAa,aAAa,OAAO,cAAc;EAC/C,YAAY,aAAa,OAAO,aAAa;CACjD,CAAC;AACL"}

package/dist/web.d.ts

@@ -2,22 +2,25 @@
 /**
  * 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.
  */
-declare function appendRedirectParamFromCurrentLocationToUrl(url: string): string;
+export declare function appendRedirectParamFromCurrentLocationToUrl(url: string): 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.
  */
-declare function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number): NodeJS.Timeout | undefined;
+export declare function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number): NodeJS.Timeout | undefined;
 //#endregion
-export { appendRedirectParamFromCurrentLocationToUrl, assignUrlWithRedirectParamFromCurrentLocation };
 //# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","names":[],"sources":["../src/web.ts"],"mappings":";;;;;;;;iBASgB,4CAA4C;;;;;;;;;;;iBAe5C,8CAA8C,aAAa,mBAAgB,OAAA"}
+{"version":3,"file":"web.d.ts","names":[],"sources":["../src/web.ts"],"mappings":";;;;;;;;wBASgB,4CAA4C;;;;;;;;;;;;;;;wBAmB5C,8CAA8C,aAAa,mBAAgB,OAAA"}

package/dist/web.js

@@ -3,23 +3,27 @@ import { appendRedirectParamToUrl } from "./url.js";
 /**
 * 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.
 */
 function appendRedirectParamFromCurrentLocationToUrl(url) {
 	const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;
 	return appendRedirectParamToUrl(url, currentPath);
 }
 /**
-* 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.
 */
 function assignUrlWithRedirectParamFromCurrentLocation(url, delayMs) {
 	if (delayMs === void 0) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));

package/dist/web.js.map

@@ -1 +1 @@
-{"version":3,"file":"web.js","names":[],"sources":["../src/web.ts"],"sourcesContent":["import { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current location as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentLocationToUrl(url: string) {\n    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;\n    return appendRedirectParamToUrl(url, currentPath);\n}\n\n/**\n * Navigates to the given URL, appending the current browser location\n * (path, query, and hash) as the `redirect` query parameter.\n *\n * Useful for redirecting to login or other gateways while preserving\n * the current location for post-auth navigation.\n *\n * @param {string} url - The destination URL to navigate to\n * @param {number} [delayMs] - Optional delay in milliseconds before navigation\n */\nexport function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number) {\n    if (delayMs === undefined) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));\n    else return setTimeout(() => window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url)), delayMs);\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,4CAA4C,KAAa;CACrE,MAAM,cAAc,GAAG,OAAO,SAAS,WAAW,OAAO,SAAS,SAAS,OAAO,SAAS;CAC3F,OAAO,yBAAyB,KAAK,WAAW;AACpD;;;;;;;;;;;AAYA,SAAgB,8CAA8C,KAAa,SAAkB;CACzF,IAAI,YAAY,KAAA,GAAW,OAAO,SAAS,OAAO,4CAA4C,GAAG,CAAC;MAC7F,OAAO,iBAAiB,OAAO,SAAS,OAAO,4CAA4C,GAAG,CAAC,GAAG,OAAO;AAClH"}
+{"version":3,"file":"web.js","names":[],"sources":["../src/web.ts"],"sourcesContent":["import { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.\n *\n * @param url - The base URL to modify.\n *\n * @returns A new URL with the current location as the `redirect` parameter.\n */\nexport function appendRedirectParamFromCurrentLocationToUrl(url: string) {\n    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;\n    return appendRedirectParamToUrl(url, currentPath);\n}\n\n/**\n * Navigates to a URL with the current browser path, query, and hash as its redirect parameter.\n *\n * @remarks\n * Omitting `delayMs` navigates immediately. Providing a delay, including `0`, schedules navigation;\n * the current location is read when the timer fires, not when the timer is created.\n * Requires a browser environment. Redirect-path validation errors propagate from the URL helper.\n *\n * @param url - The destination URL.\n * @param delayMs - The navigation delay in milliseconds, using native `setTimeout` timing rules.\n *\n * @returns A timer handle when delayed, which the caller can cancel with `clearTimeout`, or `undefined`\n * when navigation is immediate.\n */\nexport function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number) {\n    if (delayMs === undefined) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));\n    else return setTimeout(() => window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url)), delayMs);\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,4CAA4C,KAAa;CACrE,MAAM,cAAc,GAAG,OAAO,SAAS,WAAW,OAAO,SAAS,SAAS,OAAO,SAAS;CAC3F,OAAO,yBAAyB,KAAK,WAAW;AACpD;;;;;;;;;;;;;;;AAgBA,SAAgB,8CAA8C,KAAa,SAAkB;CACzF,IAAI,YAAY,KAAA,GAAW,OAAO,SAAS,OAAO,4CAA4C,GAAG,CAAC;MAC7F,OAAO,iBAAiB,OAAO,SAAS,OAAO,4CAA4C,GAAG,CAAC,GAAG,OAAO;AAClH"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "18.0.0",
+  "version": "18.1.0",
   "description": "A lightweight and modular utility library for modern JavaScript and TypeScript — includes secure hashing, flexible logging, datetime tools, Vue/web helpers, storage abstraction, and more.",
   "author": "kiki-kanri",
   "license": "MIT",
@@ -62,7 +62,7 @@
     "lint:fix": "eslint --fix --max-warnings 0",
     "prepack": "pnpm run build",
     "release": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && changelogen --hideAuthorEmail --push --release && npm publish",
-    "test": "cross-env TZ=UTC vitest run --coverage",
+    "test": "cross-env TZ=UTC vitest run --coverage && cross-env TZ='America/New_York' vitest run tests/classes/enhanced-date.test.ts",
     "test:watch": "cross-env TZ=UTC vitest watch --coverage",
     "typecheck": "tsc -b --noEmit"
   },
@@ -135,36 +135,36 @@
     }
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.3.0",
-    "@kikiutils/eslint-config": "^9.2.0",
+    "@antfu/eslint-config": "^9.5.1",
+    "@kikiutils/eslint-config": "^9.2.1",
     "@kikiutils/tsconfigs": "^7.0.0",
-    "@noble/hashes": "^2.3.0",
-    "@types/node": "^26.2.0",
-    "@types/ssh2": "^1.15.5",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@noble/hashes": "^2.4.0",
+    "@types/node": "^26.6.3",
+    "@types/ssh2": "^1.15.6",
+    "@vitest/coverage-v8": "^5.0.3",
     "async-validator": "^4.2.5",
-    "bson": "^7.3.2",
+    "bson": "^7.3.3",
     "changelogen": "^0.6.2",
     "consola": "^3.4.2",
     "cross-env": "^10.1.0",
     "date-fns": "^4.4.0",
     "decimal.js": "^10.6.0",
-    "element-plus": "^2.14.4",
-    "eslint": "^10.8.1",
-    "jsdom": "^30.0.1",
-    "knip": "^6.32.2",
-    "lru-cache": "^11.5.2",
+    "element-plus": "^2.14.7",
+    "eslint": "^10.11.0",
+    "jsdom": "^30.1.1",
+    "knip": "^6.39.0",
+    "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
-    "msgpackr": "^2.0.5",
+    "msgpackr": "^2.1.0",
     "node-ssh": "^13.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "publint": "^0.3.23",
-    "tsdown": "^0.22.14",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
     "unplugin-unused": "^0.6.0",
-    "vitest": "^4.1.10",
-    "vue": "^3.5.41",
-    "vue-router": "^5.2.0"
+    "vitest": "^5.0.3",
+    "vue": "^3.5.43",
+    "vue-router": "^5.3.1"
   }
 }

package/src/buffer.ts

@@ -3,33 +3,32 @@ import { Buffer } from 'node:buffer';
 import type { BinaryInput } from './types';
 
 /**
- * Converts various binary data types to a Node.js Buffer.
+ * Converts binary input to a Node.js `Buffer`.
  *
- * This function provides a unified, efficient way to convert different binary formats
- * (Blob, Buffer, File, ArrayBuffer, or Uint8Array) into a Node.js Buffer.
- * It prioritizes zero-copy conversions for TypedArrays and ArrayBuffers to ensure
- * optimal performance.
+ * @remarks
+ * An existing `Buffer` is returned unchanged. `ArrayBuffer` and `Uint8Array` inputs share their backing memory
+ * with the result, so changes are visible through both views. `Blob` and `File` inputs are read asynchronously.
  *
- * @param {ArrayBuffer | Blob | Buffer | File | Uint8Array} input - The binary data input to convert.
- * Supports Blob, Buffer, File, ArrayBuffer, and Uint8Array.
+ * @param input - The binary data to convert.
  *
- * @returns {Promise<Buffer>} A promise that resolves to a Node.js Buffer.
+ * @returns A promise resolving to the original buffer or a new buffer view after the input is available.
+ *
+ * @throws TypeError through promise rejection if the input is unsupported.
  *
  * @example
- * ```typescript
- * import { toBuffer } from '@kikiutils/shared/buffer';
  *
- * // From ArrayBuffer
- * const ab = new ArrayBuffer(8);
- * const bufferFromAB = await toBuffer(ab);
+ * ```ts
+ * import { toBuffer } from '@kikiutils/shared/buffer';
  *
- * // From Uint8Array (Zero-copy)
- * const u8 = new Uint8Array([10, 20, 30]);
- * const bufferFromU8 = await toBuffer(u8);
+ * const bytes = new Uint8Array([
+ *     10,
+ *     20,
+ *     30,
+ * ]);
  *
- * // From Blob or File
- * const blob = new Blob(['data'], { type: 'text/plain' });
- * const bufferFromBlob = await toBuffer(blob);
+ * const buffer = await toBuffer(bytes);
+ * bytes[0] = 40;
+ * console.log(buffer[0]); // => 40
  * ```
  */
 export async function toBuffer(input: BinaryInput) {