@kikiutils/shared 18.3.0 → 20.0.0

package/dist/storages/redis/msgpack.js

@@ -1,12 +1,13 @@
 import { decode, encode, isNativeAccelerationEnabled } from "msgpackr";
-//#region src/storages/redis/msgpack.ts
+// src/storages/redis/msgpack.ts
 if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled for msgpackr, verify that install finished properly");
 /**
 * Creates a frozen Redis-like storage facade using MessagePack serialization.
 *
 * @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`;
+* Reads resolve to `null` when no raw value exists; `getAndRemoveItem` reads and deletes in one atomic adapter call.
+* 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.
 *
@@ -25,6 +26,11 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 * const adapter: RedisLikeAdapter = {
 *     delete: async (key) => values.delete(key) ? 1 : 0,
 *     getBuffer: async (key) => values.get(key) ?? null,
+*     getBufferAndDelete: async (key) => {
+*         const value = values.get(key) ?? null;
+*         values.delete(key);
+*         return value;
+*     },
 *     has: async (key) => values.has(key),
 *     setBuffer: async (key, value) => {
 *         values.set(key, value);
@@ -33,6 +39,9 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 *     setBufferEx: async () => {
 *         throw new Error('TTL writes are not supported by this example adapter');
 *     },
+*     setBufferExNx: async () => {
+*         throw new Error('TTL writes are not supported by this example adapter');
+*     },
 *     ttl: async (key) => values.has(key) ? -1 : -2,
 * };
 *
@@ -44,6 +53,10 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 */
 function createRedisMsgpackStorage(adapter) {
 	return Object.freeze({
+		async getAndRemoveItem(key) {
+			const rawValue = await adapter.getBufferAndDelete(key);
+			return rawValue ? decode(rawValue) : null;
+		},
 		async getItem(key) {
 			const rawValue = await adapter.getBuffer(key);
 			return rawValue ? decode(rawValue) : null;
@@ -54,10 +67,12 @@ function createRedisMsgpackStorage(adapter) {
 		setItem: async (key, value) => await adapter.setBuffer(key, encode(value)) === "OK",
 		async setItemWithTtl(key, ttlSeconds, value) {
 			return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === "OK";
+		},
+		async setItemWithTtlIfAbsent(key, ttlSeconds, value) {
+			return await adapter.setBufferExNx(key, ttlSeconds, encode(value)) === "OK";
 		}
 	});
 }
-//#endregion
 export { createRedisMsgpackStorage };
 
 //# sourceMappingURL=msgpack.js.map

package/dist/storages/redis/msgpack.js.map

@@ -1 +1 @@
-{"version":3,"file":"msgpack.js","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"sourcesContent":["import {\n    decode,\n    encode,\n    isNativeAccelerationEnabled,\n} from 'msgpackr';\n\nimport type {\n    RedisLikeAdapter,\n    RedisLikeStorage,\n} from './types';\n\nif (!isNativeAccelerationEnabled) {\n    console.warn('Native acceleration not enabled for msgpackr, verify that install finished properly');\n}\n\n/**\n * Creates a frozen Redis-like storage facade using MessagePack serialization.\n *\n * @remarks\n * Adapter rejections and MessagePack serialization errors propagate to the caller.\n * Reads resolve to `null` when no raw value exists. Writes resolve to `true` only when the adapter returns `OK`;\n * removal resolves to `true` only when exactly one key is deleted.\n * The adapter remains caller-owned; creating the facade does not open or close a connection.\n *\n * @param adapter - The caller-owned adapter for raw binary operations.\n *\n * @returns A new frozen facade sharing the supplied adapter.\n *\n * @example\n *\n * ```ts\n * import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';\n * import type { RedisLikeAdapter } from '@kikiutils/shared/storages/redis/types';\n *\n * // This in-memory adapter demonstrates non-expiring operations without an external service.\n * const values = new Map<string, Uint8Array>();\n * const adapter: RedisLikeAdapter = {\n *     delete: async (key) => values.delete(key) ? 1 : 0,\n *     getBuffer: async (key) => values.get(key) ?? null,\n *     has: async (key) => values.has(key),\n *     setBuffer: async (key, value) => {\n *         values.set(key, value);\n *         return 'OK';\n *     },\n *     setBufferEx: async () => {\n *         throw new Error('TTL writes are not supported by this example adapter');\n *     },\n *     ttl: async (key) => values.has(key) ? -1 : -2,\n * };\n *\n * const storage = createRedisMsgpackStorage(adapter);\n * await storage.setItem('profile', { name: 'Alice' });\n * const profile = await storage.getItem<{ name: string }>('profile');\n * console.log(profile); // => { name: 'Alice' }\n * ```\n */\nexport function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {\n    return Object.freeze({\n        async getItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBuffer(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        getItemTtl: (key: string) => adapter.ttl(key),\n        hasItem: (key: string) => adapter.has(key),\n        removeItem: async (key: string) => await adapter.delete(key) === 1,\n        setItem: async (key: string, value: any) => await adapter.setBuffer(key, encode(value)) === 'OK',\n        async setItemWithTtl(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n    });\n}\n"],"mappings":";;AAWA,IAAI,CAAC,6BACD,QAAQ,KAAK,qFAAqF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CtG,SAAgB,0BAA0B,SAAuD;CAC7F,OAAO,OAAO,OAAO;EACjB,MAAM,QAAqB,KAAa;GACpC,MAAM,WAAW,MAAM,QAAQ,UAAU,GAAG;GAC5C,OAAO,WAAW,OAAO,QAAQ,IAAS;EAC9C;EACA,aAAa,QAAgB,QAAQ,IAAI,GAAG;EAC5C,UAAU,QAAgB,QAAQ,IAAI,GAAG;EACzC,YAAY,OAAO,QAAgB,MAAM,QAAQ,OAAO,GAAG,MAAM;EACjE,SAAS,OAAO,KAAa,UAAe,MAAM,QAAQ,UAAU,KAAK,OAAO,KAAK,CAAC,MAAM;EAC5F,MAAM,eAAe,KAAa,YAAoB,OAAY;GAC9D,OAAO,MAAM,QAAQ,YAAY,KAAK,YAAY,OAAO,KAAK,CAAC,MAAM;EACzE;CACJ,CAAC;AACL"}
+{"version":3,"file":"msgpack.js","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"sourcesContent":["import {\n    decode,\n    encode,\n    isNativeAccelerationEnabled,\n} from 'msgpackr';\n\nimport type {\n    RedisLikeAdapter,\n    RedisLikeStorage,\n} from './types';\n\nif (!isNativeAccelerationEnabled) {\n    console.warn('Native acceleration not enabled for msgpackr, verify that install finished properly');\n}\n\n/**\n * Creates a frozen Redis-like storage facade using MessagePack serialization.\n *\n * @remarks\n * Adapter rejections and MessagePack serialization errors propagate to the caller.\n * Reads resolve to `null` when no raw value exists; `getAndRemoveItem` reads and deletes in one atomic adapter call.\n * Writes resolve to `true` only when the adapter returns `OK`;\n * removal resolves to `true` only when exactly one key is deleted.\n * The adapter remains caller-owned; creating the facade does not open or close a connection.\n *\n * @param adapter - The caller-owned adapter for raw binary operations.\n *\n * @returns A new frozen facade sharing the supplied adapter.\n *\n * @example\n *\n * ```ts\n * import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';\n * import type { RedisLikeAdapter } from '@kikiutils/shared/storages/redis/types';\n *\n * // This in-memory adapter demonstrates non-expiring operations without an external service.\n * const values = new Map<string, Uint8Array>();\n * const adapter: RedisLikeAdapter = {\n *     delete: async (key) => values.delete(key) ? 1 : 0,\n *     getBuffer: async (key) => values.get(key) ?? null,\n *     getBufferAndDelete: async (key) => {\n *         const value = values.get(key) ?? null;\n *         values.delete(key);\n *         return value;\n *     },\n *     has: async (key) => values.has(key),\n *     setBuffer: async (key, value) => {\n *         values.set(key, value);\n *         return 'OK';\n *     },\n *     setBufferEx: async () => {\n *         throw new Error('TTL writes are not supported by this example adapter');\n *     },\n *     setBufferExNx: async () => {\n *         throw new Error('TTL writes are not supported by this example adapter');\n *     },\n *     ttl: async (key) => values.has(key) ? -1 : -2,\n * };\n *\n * const storage = createRedisMsgpackStorage(adapter);\n * await storage.setItem('profile', { name: 'Alice' });\n * const profile = await storage.getItem<{ name: string }>('profile');\n * console.log(profile); // => { name: 'Alice' }\n * ```\n */\nexport function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {\n    return Object.freeze({\n        async getAndRemoveItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBufferAndDelete(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        async getItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBuffer(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        getItemTtl: (key: string) => adapter.ttl(key),\n        hasItem: (key: string) => adapter.has(key),\n        removeItem: async (key: string) => await adapter.delete(key) === 1,\n        setItem: async (key: string, value: any) => await adapter.setBuffer(key, encode(value)) === 'OK',\n        async setItemWithTtl(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n        async setItemWithTtlIfAbsent(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferExNx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n    });\n}\n"],"mappings":";;AAWA,IAAI,CAAC,6BACD,QAAQ,KAAK,qFAAqF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDtG,SAAgB,0BAA0B,SAAuD;CAC7F,OAAO,OAAO,OAAO;EACjB,MAAM,iBAA8B,KAAa;GAC7C,MAAM,WAAW,MAAM,QAAQ,mBAAmB,GAAG;GACrD,OAAO,WAAW,OAAO,QAAQ,IAAS;EAC9C;EACA,MAAM,QAAqB,KAAa;GACpC,MAAM,WAAW,MAAM,QAAQ,UAAU,GAAG;GAC5C,OAAO,WAAW,OAAO,QAAQ,IAAS;EAC9C;EACA,aAAa,QAAgB,QAAQ,IAAI,GAAG;EAC5C,UAAU,QAAgB,QAAQ,IAAI,GAAG;EACzC,YAAY,OAAO,QAAgB,MAAM,QAAQ,OAAO,GAAG,MAAM;EACjE,SAAS,OAAO,KAAa,UAAe,MAAM,QAAQ,UAAU,KAAK,OAAO,KAAK,CAAC,MAAM;EAC5F,MAAM,eAAe,KAAa,YAAoB,OAAY;GAC9D,OAAO,MAAM,QAAQ,YAAY,KAAK,YAAY,OAAO,KAAK,CAAC,MAAM;EACzE;EACA,MAAM,uBAAuB,KAAa,YAAoB,OAAY;GACtE,OAAO,MAAM,QAAQ,cAAc,KAAK,YAAY,OAAO,KAAK,CAAC,MAAM;EAC3E;CACJ,CAAC;AACL"}

package/dist/storages/redis/types.d.ts

@@ -1,4 +1,3 @@
-//#region src/storages/redis/types.d.ts
 /**
  * A caller-owned asynchronous adapter for Redis-like binary operations.
  *
@@ -15,6 +14,11 @@ export interface RedisLikeAdapter {
    * Reads a key and resolves to its raw bytes, or `null` when the key is missing.
    */
   getBuffer: (key: string) => Promise<null | Uint8Array>;
+  /**
+   * Atomically reads and deletes a key, such as with Redis `GETDEL`,
+   * and resolves to its raw bytes, or `null` when the key is missing.
+   */
+  getBufferAndDelete: (key: string) => Promise<null | Uint8Array>;
   /**
    * Checks a key and resolves to whether it exists.
    */
@@ -31,6 +35,15 @@ export interface RedisLikeAdapter {
    * @param value - The raw bytes to store.
    */
   setBufferEx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | void>;
+  /**
+   * Writes raw bytes with an expiry only when the key is missing, such as with Redis `SET key value EX ttl NX`,
+   * and resolves to the backend acknowledgment, or `null` or no value when the key already exists.
+   *
+   * @param key - The storage key.
+   * @param ttlSeconds - The expiry duration in seconds.
+   * @param value - The raw bytes to store.
+   */
+  setBufferExNx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | null | void>;
   /**
    * Reads a key's remaining TTL in seconds, or `-1` for no expiry and `-2` for a missing key.
    */
@@ -44,6 +57,13 @@ export interface RedisLikeAdapter {
  * `-1` means no expiry, and `-2` means the key is missing. Connection cleanup remains caller-owned.
  */
 export interface RedisLikeStorage {
+  /**
+   * Atomically reads and removes a deserialized value and resolves to `null` when the key is missing.
+   * Concurrent callers on the same key receive the value at most once.
+   *
+   * @typeParam T - The expected value type; deserialization does not validate this type.
+   */
+  getAndRemoveItem: <T = unknown>(key: string) => Promise<null | T>;
   /**
    * Reads a deserialized value and resolves to `null` when the key is missing.
    *
@@ -74,6 +94,14 @@ export interface RedisLikeStorage {
    * @param value - The value to serialize and store.
    */
   setItemWithTtl: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
+  /**
+   * Atomically stores a value with an expiry only when the key is missing
+   * 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.
+   */
+  setItemWithTtlIfAbsent: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
 }
-//#endregion
 //# sourceMappingURL=types.d.ts.map

package/dist/storages/redis/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/storages/redis/types.ts"],"mappings":";;;;;;;;iBAOiB;;;;EAIb,SAAS,gBAAgB;;;;EAKzB,YAAY,gBAAgB,eAAe;;;;EAK3C,MAAM,gBAAgB;;;;EAKtB,YAAY,aAAa,OAAO,eAAe;;;;;;;;EAS/C,cAAc,aAAa,oBAAoB,OAAO,eAAe;;;;EAKrE,MAAM,gBAAgB;;;;;;;;;iBAUT;;;;;;EAMb,UAAU,aAAa,gBAAgB,eAAe;;;;EAKtD,aAAa,gBAAgB;;;;EAK7B,UAAU,gBAAgB;;;;EAK1B,aAAa,gBAAgB;;;;EAK7B,UAAU,aAAa,eAAe;;;;;;;;EAStC,iBAAiB,aAAa,oBAAoB,eAAe"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/storages/redis/types.ts"],"mappings":";;;;;;;iBAOiB;;;;EAIb,SAAS,gBAAgB;;;;EAKzB,YAAY,gBAAgB,eAAe;;;;;EAM3C,qBAAqB,gBAAgB,eAAe;;;;EAKpD,MAAM,gBAAgB;;;;EAKtB,YAAY,aAAa,OAAO,eAAe;;;;;;;;EAS/C,cAAc,aAAa,oBAAoB,OAAO,eAAe;;;;;;;;;EAUrE,gBAAgB,aAAa,oBAAoB,OAAO,eAAe;;;;EAKvE,MAAM,gBAAgB;;;;;;;;;iBAUT;;;;;;;EAOb,mBAAmB,aAAa,gBAAgB,eAAe;;;;;;EAO/D,UAAU,aAAa,gBAAgB,eAAe;;;;EAKtD,aAAa,gBAAgB;;;;EAK7B,UAAU,gBAAgB;;;;EAK1B,aAAa,gBAAgB;;;;EAK7B,UAAU,aAAa,eAAe;;;;;;;;EAStC,iBAAiB,aAAa,oBAAoB,eAAe;;;;;;;;;EAUjE,yBAAyB,aAAa,oBAAoB,eAAe"}

package/dist/string.d.ts

@@ -1,4 +1,3 @@
-//#region src/string.d.ts
 /**
  * Character-set presets supported by `randomString`.
  */
@@ -28,5 +27,4 @@ export type RandomStringMode = 'alphabetic' | 'alphanumeric' | 'lowercase' | 'lo
  * ```
  */
 export declare function randomString(length: number, mode?: RandomStringMode): string;
-//#endregion
 //# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","names":[],"sources":["../src/string.ts"],"mappings":";;;;YAGY;;;;;;;;;;;;;;;;;;;;;;;;;wBA8CI,aAAa,gBAAgB,OAAM"}
+{"version":3,"file":"string.d.ts","names":[],"sources":["../src/string.ts"],"mappings":";;;YAGY;;;;;;;;;;;;;;;;;;;;;;;;;wBA8CI,aAAa,gBAAgB,OAAM"}

package/dist/string.js

@@ -1,4 +1,4 @@
-//#region src/string.ts
+// src/string.ts
 const DIGITS = "0123456789";
 const LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
 const UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
@@ -41,7 +41,6 @@ function randomString(length, mode = "alphabetic") {
 	if (!charset) throw new Error(`Unsupported mode: ${mode}`);
 	return Array.from({ length }, () => charset[Math.floor(Math.random() * charset.length)]).join("");
 }
-//#endregion
 export { randomString };
 
 //# sourceMappingURL=string.js.map

package/dist/time.d.ts

@@ -1,4 +1,3 @@
-//#region src/time.d.ts
 /**
  * Waits until a duration elapses or cancellation occurs without rejecting on cancellation.
  *
@@ -45,5 +44,4 @@ export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
  * ```
  */
 export declare function delayOrThrow(ms: number, signal?: AbortSignal): Promise<void>;
-//#endregion
 //# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time.d.ts","names":[],"sources":["../src/time.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;wBAoBgB,MAAM,YAAY,SAAS,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;wBA2CzC,aAAa,YAAY,SAAS,cAAc"}
+{"version":3,"file":"time.d.ts","names":[],"sources":["../src/time.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;wBAoBgB,MAAM,YAAY,SAAS,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;wBA2CzC,aAAa,YAAY,SAAS,cAAc"}

package/dist/time.js

@@ -1,4 +1,4 @@
-//#region src/time.ts
+// src/time.ts
 /**
 * Waits until a duration elapses or cancellation occurs without rejecting on cancellation.
 *
@@ -75,7 +75,6 @@ function delayOrThrow(ms, signal) {
 		signal?.addEventListener("abort", onAbort, { once: true });
 	});
 }
-//#endregion
 export { delay, delayOrThrow };
 
 //# sourceMappingURL=time.js.map

package/dist/types/filtered-key-path.d.ts

@@ -1,5 +1,4 @@
 import { ObjectId } from "bson";
-//#region src/types/filtered-key-path.d.ts
 type ConditionalPath<K extends number | string, V, U> = V extends U ? `${K}` : DefaultPath<K, V, U, never>;
 type DefaultPath<K extends number | string, V, U = never, RK = `${K}`> = V extends TerminalType ? RK : `${K}.${FilteredKeyPath<V, U>}`;
 /**
@@ -13,6 +12,5 @@ type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false
 type PathImpl<K extends number | string, V, U> = [U] extends [never] ? DefaultPath<K, V> : ConditionalPath<K, V, U>;
 type TerminalType = bigint | Blob | boolean | Date | File | null | number | ObjectId | RegExp | string | symbol | undefined;
 type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, keyof any[]>;
-//#endregion
 export {};
 //# sourceMappingURL=filtered-key-path.d.ts.map

package/dist/types/filtered-key-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered-key-path.d.ts","names":[],"sources":["../../src/types/filtered-key-path.ts"],"mappings":";;KAKK,gBAAgB,2BAA2B,GAAG,KAAK,UAAU,OAAO,MAAM,YAAY,GAAG,GAAG;KAC5F,YACD,2BACA,GACA,WACA,QAAQ,OACR,UAAU,eAAe,QAAQ,KAAK,gBAAgB,GAAG;;;;;;;YAUjD,gBAAgB,GAAG,aAAa,UAAU,oBAAoB,MAAM,QAAQ,qBAAqB,KAAK,SAAS,OAAO,SAAS,QAAQ,YAAY,EAAE,IAAI,MAAK,SAAS,MAAM,iBAAiB,GAAG,SAAS,WAAW,MAAM,SAAS,QAAQ,YAAY,EAAE,IAAI,YAAW;KAGhR,QAAQ,UAAU,qCAAqC;KACvD,SAAS,2BAA2B,GAAG,MAAM,qBAAqB,YAAY,GAAG,KAAK,gBAAgB,GAAG,GAAG;KAC5G,wBAED,iBAEA,OACA,uBAGA,WACA;KAKC,SAAS,UAAU,sBAAsB,cAAc"}
+{"version":3,"file":"filtered-key-path.d.ts","names":[],"sources":["../../src/types/filtered-key-path.ts"],"mappings":";KAKK,gBAAgB,2BAA2B,GAAG,KAAK,UAAU,OAAO,MAAM,YAAY,GAAG,GAAG;KAC5F,YACD,2BACA,GACA,WACA,QAAQ,OACR,UAAU,eAAe,QAAQ,KAAK,gBAAgB,GAAG;;;;;;;YAUjD,gBAAgB,GAAG,aAAa,UAAU,oBAAoB,MAAM,QAAQ,qBAAqB,KAAK,SAAS,OAAO,SAAS,QAAQ,YAAY,EAAE,IAAI,MAAK,SAAS,MAAM,iBAAiB,GAAG,SAAS,WAAW,MAAM,SAAS,QAAQ,YAAY,EAAE,IAAI,YAAW;KAGhR,QAAQ,UAAU,qCAAqC;KACvD,SAAS,2BAA2B,GAAG,MAAM,qBAAqB,YAAY,GAAG,KAAK,gBAAgB,GAAG,GAAG;KAC5G,wBAED,iBAEA,OACA,uBAGA,WACA;KAKC,SAAS,UAAU,sBAAsB,cAAc"}

package/dist/types/index.d.ts

@@ -1,10 +1,5 @@
 import { FilteredKeyPath } from "./filtered-key-path.js";
 import { Blob as Blob$1, Buffer, File as File$1 } from "node:buffer";
-//#region src/types/index.d.ts
-/**
- * A generic string-keyed object for utility APIs that intentionally accept any value shape.
- */
-export type AnyRecord = Record<string, any>;
 /**
  * Binary-like inputs accepted by `toBuffer` across browser and Node.js runtimes.
  */
@@ -21,10 +16,6 @@ export type MaybePartial<T> = Partial<T> | T;
  * Accepts either a mutable value or a readonly view of that value.
  */
 export type MaybeReadonly<T> = Readonly<T> | T;
-/**
- * Number-like value represented as a number or a numeric string.
- */
-export type Numberish = number | string;
 /**
  * A `Record` where every key is optional.
  */
@@ -37,6 +28,5 @@ export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialReco
  * A readonly `Record`.
  */
 export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;
-//#endregion
 export type { FilteredKeyPath };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"index.d.ts","names":["NodeBlob","NodeFile"],"sources":["../../src/types/index.ts"],"mappings":";;;;;YAWY,cAAc,cAAc,OAAO,SAAS,OAAOA,SAAWC,SAAW;;;;YAKzE;;;;YAKA,aAAa,KAAK,QAAQ,KAAK;;;;YAK/B,cAAc,KAAK,SAAS,KAAK;;;;YAKjC,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,5 +1,4 @@
 import { GlobalComponents } from "vue";
-//#region src/types/vue.d.ts
 /**
  * A nullable reference to an instance of a globally registered Vue component.
  *
@@ -15,5 +14,4 @@ import { GlobalComponents } from "vue";
  * ```
  */
 export type ComponentRef<K extends keyof GlobalComponents> = InstanceType<GlobalComponents[K]> | null;
-//#endregion
 //# 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":";;;;;;;;;;;;;;;;YAgBY,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

@@ -1,4 +1,3 @@
-//#region src/url.d.ts
 /**
  * Appends or updates the `redirect` query parameter on a given URL.
  *
@@ -39,5 +38,4 @@ export declare function isSafeRedirectPath(value: unknown): value is string;
  * @returns The validated input path, or the unvalidated fallback path.
  */
 export declare function normalizeRedirectPath(value: unknown, fallback?: string): string;
-//#endregion
 //# 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":";;;;;;;;;;;;;;wBAagB,yBAAyB,aAAa;;;;;;;;;;;;;wBAwBtC,mBAAmB,iBAAiB;;;;;;;;;;;;;wBAoBpC,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

@@ -1,4 +1,4 @@
-//#region src/url.ts
+// src/url.ts
 /**
 * Appends or updates the `redirect` query parameter on a given URL.
 *
@@ -56,7 +56,6 @@ function normalizeRedirectPath(value, fallback = "/") {
 	const redirectPath = Array.isArray(value) ? value[0] : value;
 	return isSafeRedirectPath(redirectPath) ? redirectPath : fallback;
 }
-//#endregion
 export { appendRedirectParamToUrl, isSafeRedirectPath, normalizeRedirectPath };
 
 //# sourceMappingURL=url.js.map

package/dist/vue.d.ts

@@ -1,5 +1,4 @@
 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.
  *
@@ -34,5 +33,4 @@ export declare function clearTimeoutRef(timeoutRef: Ref<null | ReturnType<typeof
  * @param containerRef - The reference to the scrollable element, or `null` while it is unavailable.
  */
 export declare function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<null | T>): void;
-//#endregion
 //# 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":";;;;;;;;;wBAgBgB,yCAAyC;;;;;;wBASzC,iBAAiB,aAAa,WAAW,kBAAkB;;;;;;wBAU3D,gBAAgB,YAAY,WAAW,kBAAkB;;;;;;;;;;;;;;wBAkBzD,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

@@ -1,7 +1,7 @@
 import { appendRedirectParamToUrl } from "./url.js";
 import { onActivated } from "vue";
 import { onBeforeRouteLeave, useRoute } from "vue-router";
-//#region src/vue.ts
+// src/vue.ts
 /**
 * Appends the current Vue Router route's `fullPath` as the `redirect` query parameter to the given URL.
 *
@@ -56,7 +56,6 @@ function usePreserveScroll(containerRef) {
 		scrollTop = containerRef.value?.scrollTop || 0;
 	});
 }
-//#endregion
 export { appendRedirectParamFromCurrentRouteToUrl, clearIntervalRef, clearTimeoutRef, usePreserveScroll };
 
 //# sourceMappingURL=vue.js.map

package/dist/web.d.ts

@@ -1,4 +1,3 @@
-//#region src/web.d.ts
 /**
  * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
  *
@@ -22,5 +21,4 @@ export declare function appendRedirectParamFromCurrentLocationToUrl(url: string)
  * when navigation is immediate.
  */
 export declare function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number): NodeJS.Timeout | undefined;
-//#endregion
 //# 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":";;;;;;;;wBASgB,4CAA4C;;;;;;;;;;;;;;;wBAmB5C,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

@@ -1,5 +1,5 @@
 import { appendRedirectParamToUrl } from "./url.js";
-//#region src/web.ts
+// src/web.ts
 /**
 * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.
 *
@@ -29,7 +29,6 @@ function assignUrlWithRedirectParamFromCurrentLocation(url, delayMs) {
 	if (delayMs === void 0) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));
 	else return setTimeout(() => window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url)), delayMs);
 }
-//#endregion
 export { appendRedirectParamFromCurrentLocationToUrl, assignUrlWithRedirectParamFromCurrentLocation };
 
 //# sourceMappingURL=web.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "18.3.0",
+  "version": "20.0.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",
@@ -27,12 +27,60 @@
     "crypto",
     "hashing",
     "storage",
-    "logging",
-    "consola",
-    "pino"
+    "logging"
   ],
   "sideEffects": false,
   "exports": {
+    "./logger": {
+      "types": "./dist/logger/index.d.ts",
+      "import": "./dist/logger/index.js",
+      "require": null
+    },
+    "./logger/_internals/formatter": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/_internals/levels": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/_internals/logger": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/_internals/types": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/index": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/node": {
+      "types": "./dist/logger/node/index.d.ts",
+      "import": "./dist/logger/node/index.js",
+      "require": null
+    },
+    "./logger/node/_internals/file-writer": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/node/_internals/formatter": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
+    "./logger/node/index": {
+      "types": null,
+      "import": null,
+      "require": null
+    },
     "./package.json": "./package.json",
     "./types": {
       "types": "./dist/types/index.d.ts",
@@ -67,40 +115,30 @@
     "typecheck": "tsc -b --noEmit"
   },
   "peerDependencies": {
-    "@noble/hashes": "^2.3.0",
-    "@types/ssh2": "^1.15.5",
+    "@noble/hashes": "^2.4.0",
     "async-validator": "^4.2.5",
-    "bson": "^7.3.2",
-    "consola": "^3.4.2",
+    "bson": "^7.3.3",
     "date-fns": "^4.4.0",
     "decimal.js": "^10.6.0",
-    "element-plus": "^2.14.4",
-    "file-type": "^22.1.1",
-    "lru-cache": "^11.5.2",
+    "element-plus": "^2.14.7",
+    "file-type": "^22.2.0",
+    "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
-    "msgpackr": "^2.0.5",
-    "node-ssh": "^13.2.1",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "vue": "^3.5.41",
+    "msgpackr": "^2.1.0",
+    "rotating-file-stream": "^3.2.10",
+    "vue": "^3.5.44",
     "vue-router": ">= 4.6.4"
   },
   "peerDependenciesMeta": {
     "@noble/hashes": {
       "optional": true
     },
-    "@types/ssh2": {
-      "optional": true
-    },
     "async-validator": {
       "optional": true
     },
     "bson": {
       "optional": true
     },
-    "consola": {
-      "optional": true
-    },
     "date-fns": {
       "optional": true
     },
@@ -122,13 +160,7 @@
     "msgpackr": {
       "optional": true
     },
-    "node-ssh": {
-      "optional": true
-    },
-    "pino": {
-      "optional": true
-    },
-    "pino-pretty": {
+    "rotating-file-stream": {
       "optional": true
     },
     "vue": {
@@ -139,37 +171,33 @@
     }
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.5.1",
-    "@kikiutils/eslint-config": "^9.3.0",
+    "@antfu/eslint-config": "^10.0.0",
+    "@kikiutils/eslint-config": "^9.3.2",
     "@kikiutils/tsconfigs": "^7.0.0",
     "@noble/hashes": "^2.4.0",
     "@types/node": "^26.6.5",
-    "@types/ssh2": "^1.15.6",
-    "@vitest/coverage-v8": "^5.0.4",
+    "@vitest/coverage-v8": "^5.0.5",
     "async-validator": "^4.2.5",
     "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.7",
-    "eslint": "^10.12.0",
-    "file-type": "^22.1.1",
-    "jsdom": "^30.1.2",
-    "knip": "^6.41.0",
+    "eslint": "^10.13.0",
+    "file-type": "^22.2.0",
+    "jsdom": "^30.1.3",
+    "knip": "^6.43.0",
     "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
-    "msgpackr": "^2.1.0",
-    "node-ssh": "^13.2.1",
-    "pino": "^10.4.0",
-    "pino-pretty": "^13.2.0",
+    "msgpackr": "^2.1.2",
     "publint": "^0.3.25",
-    "tsdown": "^0.23.1",
+    "rotating-file-stream": "^3.2.10",
+    "tsdown": "^0.23.3",
     "typescript": "^6.0.3",
     "unplugin-unused": "^0.6.0",
-    "vitest": "^5.0.4",
-    "vue": "^3.5.43",
+    "vitest": "^5.0.5",
+    "vue": "^3.5.44",
     "vue-router": "^5.4.0"
   }
 }

package/src/logger/_internals/formatter.ts

@@ -0,0 +1,80 @@
+import {
+    getLoggerStreamName,
+    loggerMethods,
+} from './levels';
+import type { LoggerRecord } from './types';
+
+// Functions
+
+/** Native console formatting keeps user strings literal and objects expandable. */
+export function formatLoggerConsoleArgs(record: LoggerRecord): unknown[] {
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        const target = process[getLoggerStreamName(record.type)];
+        const parts = formatLoggerParts(record, supportsLoggerColor(target));
+        return [
+            parts.map((part) => typeof part === 'string' ? '%s' : '%O').join(' '),
+            ...parts,
+        ];
+    }
+
+    const format: string[] = [];
+    const args: unknown[] = [];
+    const decorate = (text: string, color: string) => {
+        format.push('%c%s%c');
+        args.push(`color: ${color}`, text, '');
+    };
+
+    if (record.icons) decorate(loggerMethods[record.type].icon, loggerMethods[record.type].cssColor);
+    if (record.timestamp) decorate(formatLoggerTime(record.date), '#808080');
+    if (record.prefix) decorate(record.prefix, '#0891b2');
+    for (const arg of record.args) {
+        format.push(typeof arg === 'string' ? '%s' : '%o');
+        args.push(arg);
+    }
+
+    if (record.suffix) decorate(record.suffix, '#0891b2');
+    return [
+        format.join(' '),
+        ...args,
+    ];
+}
+
+/** Keeps data arguments intact so browser developer tools can expand objects. */
+export function formatLoggerParts(record: LoggerRecord, colors = false): unknown[] {
+    const parts: unknown[] = [];
+    const paint = (text: string, color: string) => colors ? `\u001B[${color}m${text}\u001B[0m` : text;
+    if (record.icons) parts.push(paint(loggerMethods[record.type].icon, loggerMethods[record.type].ansiColor));
+    if (record.timestamp) parts.push(paint(formatLoggerTime(record.date), '90'));
+    if (record.prefix) parts.push(paint(record.prefix, '36'));
+    parts.push(...record.args);
+    if (record.suffix) parts.push(paint(record.suffix, '36'));
+    return parts;
+}
+
+/** Fixed local-time representation, deliberately without a per-second cache. */
+export function formatLoggerTime(date: Date): string {
+    const pad = (value: number, width = 2) => String(value).padStart(width, '0');
+    const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    const time = `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+    return `[${day} ${time}.${pad(date.getMilliseconds(), 3)}]`;
+}
+
+/** Use native terminal detection; redirected streams still honor FORCE_COLOR. */
+export function supportsLoggerColor(target: { hasColors?: () => boolean; isTTY?: boolean }): boolean {
+    if (target.hasColors) return target.hasColors();
+    const forced = process.env.FORCE_COLOR;
+    if (forced !== undefined) {
+        return [
+            '',
+            '1',
+            '2',
+            '3',
+            'true',
+        ].includes(forced);
+    }
+
+    return Boolean(target.isTTY)
+      && !process.env.NO_COLOR
+      && !process.env.NODE_DISABLE_COLORS
+      && process.env.TERM !== 'dumb';
+}