@kikiutils/shared 9.2.0 → 9.3.1

package/dist/storage/lru/keyed-store.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * Creates a reusable, type-safe keyed store wrapper for an LRUCache instance.
+ *
+ * This utility allows structured access to cache entries using a dynamic key-generation function.
+ *
+ * @template D - The specific value type exposed by this store (must extend `V`).
+ * @template K - The type of keys used in the LRU cache (default: string).
+ * @template V - The type of values stored in the LRU cache.
+ * @template FC - The value used by `lru-cache` fetch context (if any).
+ *
+ * @param {LRUCache<K, V, FC>} lruInstance - An instance of `lru-cache`.
+ *
+ * @returns A factory that accepts a key generator and returns a scoped, type-safe LRU-based store.
+ *
+ * @example
+ * ```typescript
+ * const lruCache = new LRUCache<string, { id: number }>();
+ * const userStore = createKeyedLruStore<User>(lruCache)((id: number) => `user:${id}`);
+ * userStore.setItem({ id: 1 }, 1);
+ * const user = userStore.getItem(1);
+ * ```
+ */
+// eslint-disable-next-line ts/no-empty-object-type
+function createKeyedLruStore(lruInstance) {
+    return (getKeyFunction) => Object.freeze({
+        /**
+         * Return a value from the cache. Will update the recency of the cache entry found.
+         *
+         * If the key is not found, returns `null`.
+         */
+        getItem(...args) {
+            const rawValue = lruInstance.get(getKeyFunction(...args));
+            return rawValue ?? null;
+        },
+        getItemTtl: (...args) => lruInstance.getRemainingTTL(getKeyFunction(...args)),
+        hasItem: (...args) => lruInstance.has(getKeyFunction(...args)),
+        removeItem: (...args) => lruInstance.delete(getKeyFunction(...args)),
+        /**
+         * Resolves the full cache key from the given arguments.
+         */
+        resolveKey: (...args) => getKeyFunction(...args),
+        setItem: (value, ...args) => lruInstance.set(getKeyFunction(...args), value),
+    });
+}
+
+exports.createKeyedLruStore = createKeyedLruStore;
+//# sourceMappingURL=keyed-store.cjs.map

package/dist/storage/lru/keyed-store.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-store.cjs","sources":["../../../src/storage/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a reusable, type-safe keyed store wrapper for an LRUCache instance.\n *\n * This utility allows structured access to cache entries using a dynamic key-generation function.\n *\n * @template D - The specific value type exposed by this store (must extend `V`).\n * @template K - The type of keys used in the LRU cache (default: string).\n * @template V - The type of values stored in the LRU cache.\n * @template FC - The value used by `lru-cache` fetch context (if any).\n *\n * @param {LRUCache<K, V, FC>} lruInstance - An instance of `lru-cache`.\n *\n * @returns A factory that accepts a key generator and returns a scoped, type-safe LRU-based store.\n *\n * @example\n * ```typescript\n * const lruCache = new LRUCache<string, { id: number }>();\n * const userStore = createKeyedLruStore<User>(lruCache)((id: number) => `user:${id}`);\n * userStore.setItem({ id: 1 }, 1);\n * const user = userStore.getItem(1);\n * ```\n */\n// eslint-disable-next-line ts/no-empty-object-type\nexport function createKeyedLruStore<D extends V, K extends {}, V extends {}, FC = unknown>(\n    lruInstance: LRUCache<K, V, FC>,\n) {\n    return <P extends any[]>(getKeyFunction: (...args: P) => K) => Object.freeze({\n        /**\n         * Return a value from the cache. Will update the recency of the cache entry found.\n         *\n         * If the key is not found, returns `null`.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(getKeyFunction(...args));\n            return rawValue ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(getKeyFunction(...args)),\n        hasItem: (...args: P) => lruInstance.has(getKeyFunction(...args)),\n        removeItem: (...args: P) => lruInstance.delete(getKeyFunction(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => getKeyFunction(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(getKeyFunction(...args), value),\n    });\n}\n"],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH;AACM,SAAU,mBAAmB,CAC/B,WAA+B,EAAA;IAE/B,OAAO,CAAkB,cAAiC,KAAK,MAAM,CAAC,MAAM,CAAC;AACzE;;;;AAIG;QACH,OAAO,CAAC,GAAG,IAAO,EAAA;AACd,YAAA,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;YACzD,OAAO,QAAQ,IAAI,IAAI;SAC1B;AACD,QAAA,UAAU,EAAE,CAAC,GAAG,IAAO,KAAK,WAAW,CAAC,eAAe,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AAChF,QAAA,OAAO,EAAE,CAAC,GAAG,IAAO,KAAK,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AACjE,QAAA,UAAU,EAAE,CAAC,GAAG,IAAO,KAAK,WAAW,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AACvE;;AAEG;QACH,UAAU,EAAE,CAAC,GAAG,IAAO,KAAK,cAAc,CAAC,GAAG,IAAI,CAAC;QACnD,OAAO,EAAE,CAAC,KAAQ,EAAE,GAAG,IAAO,KAAK,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC;AACrF,KAAA,CAAC;AACN;;;;"}

package/dist/storage/lru/keyed-store.d.ts

@@ -0,0 +1,40 @@
+import type { LRUCache } from 'lru-cache';
+/**
+ * Creates a reusable, type-safe keyed store wrapper for an LRUCache instance.
+ *
+ * This utility allows structured access to cache entries using a dynamic key-generation function.
+ *
+ * @template D - The specific value type exposed by this store (must extend `V`).
+ * @template K - The type of keys used in the LRU cache (default: string).
+ * @template V - The type of values stored in the LRU cache.
+ * @template FC - The value used by `lru-cache` fetch context (if any).
+ *
+ * @param {LRUCache<K, V, FC>} lruInstance - An instance of `lru-cache`.
+ *
+ * @returns A factory that accepts a key generator and returns a scoped, type-safe LRU-based store.
+ *
+ * @example
+ * ```typescript
+ * const lruCache = new LRUCache<string, { id: number }>();
+ * const userStore = createKeyedLruStore<User>(lruCache)((id: number) => `user:${id}`);
+ * userStore.setItem({ id: 1 }, 1);
+ * const user = userStore.getItem(1);
+ * ```
+ */
+export declare function createKeyedLruStore<D extends V, K extends {}, V extends {}, FC = unknown>(lruInstance: LRUCache<K, V, FC>): <P extends any[]>(getKeyFunction: (...args: P) => K) => Readonly<{
+    /**
+     * Return a value from the cache. Will update the recency of the cache entry found.
+     *
+     * If the key is not found, returns `null`.
+     */
+    getItem(...args: P): V | null;
+    getItemTtl: (...args: P) => number;
+    hasItem: (...args: P) => boolean;
+    removeItem: (...args: P) => boolean;
+    /**
+     * Resolves the full cache key from the given arguments.
+     */
+    resolveKey: (...args: P) => K;
+    setItem: (value: D, ...args: P) => LRUCache<K, V, FC>;
+}>;
+//# sourceMappingURL=keyed-store.d.ts.map

package/dist/storage/lru/keyed-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-store.d.ts","sourceRoot":"","sources":["../../../src/storage/lru/keyed-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,EAAE,EAAE,GAAG,OAAO,EACrF,WAAW,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAEvB,CAAC,SAAS,GAAG,EAAE,EAAE,gBAAgB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC;IACtD;;;;OAIG;qBACc,CAAC;0BAII,CAAC;uBACJ,CAAC;0BACE,CAAC;IACvB;;OAEG;0BACmB,CAAC;qBACN,CAAC,WAAW,CAAC;GAErC"}

package/dist/storage/lru/keyed-store.mjs

@@ -0,0 +1,47 @@
+/**
+ * Creates a reusable, type-safe keyed store wrapper for an LRUCache instance.
+ *
+ * This utility allows structured access to cache entries using a dynamic key-generation function.
+ *
+ * @template D - The specific value type exposed by this store (must extend `V`).
+ * @template K - The type of keys used in the LRU cache (default: string).
+ * @template V - The type of values stored in the LRU cache.
+ * @template FC - The value used by `lru-cache` fetch context (if any).
+ *
+ * @param {LRUCache<K, V, FC>} lruInstance - An instance of `lru-cache`.
+ *
+ * @returns A factory that accepts a key generator and returns a scoped, type-safe LRU-based store.
+ *
+ * @example
+ * ```typescript
+ * const lruCache = new LRUCache<string, { id: number }>();
+ * const userStore = createKeyedLruStore<User>(lruCache)((id: number) => `user:${id}`);
+ * userStore.setItem({ id: 1 }, 1);
+ * const user = userStore.getItem(1);
+ * ```
+ */
+// eslint-disable-next-line ts/no-empty-object-type
+function createKeyedLruStore(lruInstance) {
+    return (getKeyFunction) => Object.freeze({
+        /**
+         * Return a value from the cache. Will update the recency of the cache entry found.
+         *
+         * If the key is not found, returns `null`.
+         */
+        getItem(...args) {
+            const rawValue = lruInstance.get(getKeyFunction(...args));
+            return rawValue ?? null;
+        },
+        getItemTtl: (...args) => lruInstance.getRemainingTTL(getKeyFunction(...args)),
+        hasItem: (...args) => lruInstance.has(getKeyFunction(...args)),
+        removeItem: (...args) => lruInstance.delete(getKeyFunction(...args)),
+        /**
+         * Resolves the full cache key from the given arguments.
+         */
+        resolveKey: (...args) => getKeyFunction(...args),
+        setItem: (value, ...args) => lruInstance.set(getKeyFunction(...args), value),
+    });
+}
+
+export { createKeyedLruStore };
+//# sourceMappingURL=keyed-store.mjs.map

package/dist/storage/lru/keyed-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-store.mjs","sources":["../../../src/storage/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a reusable, type-safe keyed store wrapper for an LRUCache instance.\n *\n * This utility allows structured access to cache entries using a dynamic key-generation function.\n *\n * @template D - The specific value type exposed by this store (must extend `V`).\n * @template K - The type of keys used in the LRU cache (default: string).\n * @template V - The type of values stored in the LRU cache.\n * @template FC - The value used by `lru-cache` fetch context (if any).\n *\n * @param {LRUCache<K, V, FC>} lruInstance - An instance of `lru-cache`.\n *\n * @returns A factory that accepts a key generator and returns a scoped, type-safe LRU-based store.\n *\n * @example\n * ```typescript\n * const lruCache = new LRUCache<string, { id: number }>();\n * const userStore = createKeyedLruStore<User>(lruCache)((id: number) => `user:${id}`);\n * userStore.setItem({ id: 1 }, 1);\n * const user = userStore.getItem(1);\n * ```\n */\n// eslint-disable-next-line ts/no-empty-object-type\nexport function createKeyedLruStore<D extends V, K extends {}, V extends {}, FC = unknown>(\n    lruInstance: LRUCache<K, V, FC>,\n) {\n    return <P extends any[]>(getKeyFunction: (...args: P) => K) => Object.freeze({\n        /**\n         * Return a value from the cache. Will update the recency of the cache entry found.\n         *\n         * If the key is not found, returns `null`.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(getKeyFunction(...args));\n            return rawValue ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(getKeyFunction(...args)),\n        hasItem: (...args: P) => lruInstance.has(getKeyFunction(...args)),\n        removeItem: (...args: P) => lruInstance.delete(getKeyFunction(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => getKeyFunction(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(getKeyFunction(...args), value),\n    });\n}\n"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH;AACM,SAAU,mBAAmB,CAC/B,WAA+B,EAAA;IAE/B,OAAO,CAAkB,cAAiC,KAAK,MAAM,CAAC,MAAM,CAAC;AACzE;;;;AAIG;QACH,OAAO,CAAC,GAAG,IAAO,EAAA;AACd,YAAA,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;YACzD,OAAO,QAAQ,IAAI,IAAI;SAC1B;AACD,QAAA,UAAU,EAAE,CAAC,GAAG,IAAO,KAAK,WAAW,CAAC,eAAe,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AAChF,QAAA,OAAO,EAAE,CAAC,GAAG,IAAO,KAAK,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AACjE,QAAA,UAAU,EAAE,CAAC,GAAG,IAAO,KAAK,WAAW,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AACvE;;AAEG;QACH,UAAU,EAAE,CAAC,GAAG,IAAO,KAAK,cAAc,CAAC,GAAG,IAAI,CAAC;QACnD,OAAO,EAAE,CAAC,KAAQ,EAAE,GAAG,IAAO,KAAK,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,CAAC;AACrF,KAAA,CAAC;AACN;;;;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
-  "version": "9.2.0",
-  "description": "A lightweight modular utility library for JavaScript and TypeScript, offering secure hashing, flexible logging, date utilities, Vue/web helpers, and more.",
+  "version": "9.3.1",
+  "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",
   "repository": {
@@ -9,25 +9,26 @@
     "url": "git+https://github.com/kikiutils/node-shared.git"
   },
   "keywords": [
+    "utils",
+    "utilities",
+    "javascript",
+    "typescript",
+    "node",
     "browser",
-    "consola",
-    "crypto",
-    "datetime",
-    "enum",
+    "web",
+    "vue",
     "env",
-    "hashing",
-    "javascript",
-    "logging",
+    "datetime",
     "math",
-    "node",
-    "pino",
     "string",
-    "typescript",
+    "enum",
     "url",
-    "utilities",
-    "utils",
-    "vue",
-    "web"
+    "crypto",
+    "hashing",
+    "storage",
+    "logging",
+    "consola",
+    "pino"
   ],
   "sideEffects": false,
   "exports": {
@@ -35,6 +36,16 @@
       "types": "./dist/*.d.ts",
       "import": "./dist/*.mjs",
       "require": "./dist/*.cjs"
+    },
+    "./storage/enhanced/local": {
+      "types": "./dist/storage/enhanced/local/index.d.ts",
+      "import": "./dist/storage/enhanced/local/index.mjs",
+      "require": "./dist/storage/enhanced/local/index.cjs"
+    },
+    "./storage/enhanced/redis": {
+      "types": "./dist/storage/enhanced/redis/index.d.ts",
+      "import": "./dist/storage/enhanced/redis/index.mjs",
+      "require": "./dist/storage/enhanced/redis/index.cjs"
     }
   },
   "files": [
@@ -45,7 +56,7 @@
     "node": ">=18.12.1"
   },
   "scripts": {
-    "build": "ts-project-builder './src/**/*.ts' --clean --sourcemaps",
+    "build": "ts-project-builder './src/**/*.ts' --clean --preserve-modules --sourcemaps",
     "bumplog": "changelogen --bump --hideAuthorEmail",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
@@ -56,20 +67,23 @@
   },
   "devDependencies": {
     "@kikiutils/changelogen": "^0.8.0",
-    "@kikiutils/eslint-config": "^1.0.1",
+    "@kikiutils/eslint-config": "^1.0.2",
     "@kikiutils/tsconfigs": "^5.0.1",
     "@noble/hashes": "^1.8.0",
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.15.3",
+    "@types/node": "^22.15.14",
     "consola": "^3.4.2",
     "cross-env": "^7.0.3",
     "date-fns": "^4.1.0",
     "decimal.js": "^10.5.0",
+    "ioredis": "^5.6.1",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "lru-cache": "^11.1.0",
     "millify": "^6.1.0",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
+    "superjson": "^2.2.2",
     "ts-jest": "^29.3.2",
     "ts-project-builder": "5.0.1",
     "typescript": "^5.8.3",

package/src/env.ts

@@ -22,9 +22,12 @@ export class EnvironmentNotFoundError extends Error {
 }
 
 /**
- * Retrieves the value of an environment variable, or throws an error if not set.
+ * Retrieves the value of an environment variable, or throws an error if it is not defined.
  *
- * @param {string} key - The environment variable key to check.
+ * Only checks for `process.env[key] === undefined`. An empty string (e.g. '') or any falsy string
+ * value like `'0'` or `'false'` is considered a valid (defined) value.
+ *
+ * @param {string} key - The environment variable key to retrieve.
  *
  * @returns {string} The value of the environment variable.
  *
@@ -32,20 +35,14 @@ export class EnvironmentNotFoundError extends Error {
  *
  * @example
  * ```typescript
- * import { checkAndGetEnvValue } from '@kikiutils/shared/env';
- *
- * // When the environment variable 'API_KEY' is set:
- * console.log(checkAndGetEnvValue('API_KEY')); // value of API_KEY
+ * process.env.API_KEY = '';
+ * checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered "defined")
  *
- * // When the environment variable 'API_KEY' is not set:
- * try {
- *   const apiKey = checkAndGetEnvValue('API_KEY');
- * } catch (error) {
- *   console.error(error); // Missing environment variable: API_KEY
- * }
+ * delete process.env.API_KEY;
+ * checkAndGetEnvValue('API_KEY'); // ❌ Throws EnvironmentNotFoundError
  * ```
  */
 export function checkAndGetEnvValue(key: string): string {
-    if (!process.env[key]) throw new EnvironmentNotFoundError(key);
+    if (process.env[key] === undefined) throw new EnvironmentNotFoundError(key);
     return process.env[key];
 }

package/src/storage/enhanced/local/core.ts

@@ -0,0 +1,104 @@
+import {
+    deserialize,
+    serialize,
+} from 'superjson';
+
+enum StorageValueEncodingType {
+    Json = '0',
+    String = '1',
+}
+
+const customValueHeader = '​⁠';
+const customValueHeaderLength = customValueHeader.length + 1;
+const toCustomValue = (type: StorageValueEncodingType, payload: string) => `${customValueHeader}${type}${payload}`;
+
+/**
+ * An enhanced localStorage wrapper that supports storing
+ * complex data types (e.g. Dates, Maps, Sets) using SuperJSON encoding.
+ *
+ * This utility preserves type structure when saving and retrieving values.
+ *
+ * @example
+ * ```typescript
+ * enhancedLocalStorage.setItem('user', { name: 'user', createdAt: new Date() });
+ * const user = enhancedLocalStorage.getItem<{ name: string, createdAt: Date }>('user');
+ * ```
+ */
+export const enhancedLocalStorage = Object.freeze({
+    /**
+     * Removes all items from localStorage.
+     */
+    clear: () => window.localStorage.clear(),
+    /**
+     * Retrieves a value by key and decodes it using SuperJSON or raw string.
+     *
+     * @template T - The expected type of the value.
+     *
+     * @param {string} key - The key of the value to retrieve.
+     *
+     * @returns {null | T} The decoded value or null if not found.
+     */
+    getItem<T = unknown>(key: string) {
+        const rawValue = window.localStorage.getItem(key);
+        return rawValue ? decodeStorageValue(rawValue) as T : null;
+    },
+    /**
+     * Checks whether a key exists in localStorage.
+     *
+     * @param {string} key - The key to check.
+     *
+     * @returns {boolean} True if the key exists, false otherwise.
+     */
+    hasItem: (key: string) => window.localStorage.getItem(key) !== null,
+    /**
+     * Returns the number of items stored in localStorage.
+     *
+     * @returns {number} The number of items stored in localStorage.
+     */
+    get length() {
+        return window.localStorage.length;
+    },
+    /**
+     * Removes a specific key from localStorage.
+     *
+     * @param {string} key - The key to remove.
+     */
+    removeItem: (key: string) => window.localStorage.removeItem(key),
+    /**
+     * Stores a value in localStorage with automatic serialization.
+     *
+     * @param {string} key - The key to store the value under.
+     * @param {any} value - The value to store.
+     */
+    setItem: (key: string, value: any) => window.localStorage.setItem(key, encodeToStorageValue(value)),
+});
+
+function decodeStorageValue(data: string) {
+    if (!isCustomFormat(data)) return data;
+    const payload = data.substring(customValueHeaderLength);
+    const type = data.charAt(customValueHeader.length);
+    switch (type) {
+        case StorageValueEncodingType.Json:
+            try {
+                return deserialize(JSON.parse(payload));
+            } catch {
+                throw new Error('[EnhancedLocalStorage] Failed to parse JSON payload.');
+            }
+        case StorageValueEncodingType.String: return payload;
+        default:
+            throw new Error(`[EnhancedLocalStorage] Unknown encoding type: ${type}.`);
+    }
+}
+
+function encodeToStorageValue(value: any) {
+    if (typeof value === 'string') return toCustomValue(StorageValueEncodingType.String, value);
+    return toCustomValue(StorageValueEncodingType.Json, JSON.stringify(serialize(value)));
+}
+
+function isCustomFormat(data: string) {
+    return (
+        data.length >= customValueHeaderLength
+        && data[0] === customValueHeader[0]
+        && data[1] === customValueHeader[1]
+    );
+}

package/src/storage/enhanced/local/index.ts

@@ -0,0 +1,2 @@
+export { enhancedLocalStorage } from './core';
+export { createKeyedEnhancedLocalStore } from './keyed-store';

package/src/storage/enhanced/local/keyed-store.ts

@@ -0,0 +1,34 @@
+import { enhancedLocalStorage } from './core';
+
+/**
+ * Creates a reusable, type-safe storage interface based on `enhancedLocalStorage`
+ * and a dynamic key-generation function.
+ *
+ * This utility allows you to abstract away key construction logic and work directly
+ * with scoped key-value operations like `getItem`, `setItem`, and `removeItem`.
+ *
+ * @template D - The value type to store.
+ *
+ * @returns A factory that accepts a key generator function and returns a scoped storage interface.
+ *
+ * @example
+ * ```typescript
+ * const userStore = createKeyedEnhancedLocalStore<User>()((id: number) => `user:${id}`);
+ * userStore.setItem({ id: 123, name: 'user' }, 123);
+ * const user = userStore.getItem(123);
+ * ```
+ */
+export function createKeyedEnhancedLocalStore<D = unknown>() {
+    return <P extends any[]>(getKeyFunction: (...args: P) => string) => Object.freeze({
+        getItem: (...args: P) => enhancedLocalStorage.getItem<D>(getKeyFunction(...args)),
+        hasItem: (...args: P) => enhancedLocalStorage.hasItem(getKeyFunction(...args)),
+        removeItem: (...args: P) => enhancedLocalStorage.removeItem(getKeyFunction(...args)),
+        /**
+         * Resolves the storage key from the given arguments.
+         *
+         * @returns {string} The final string key used internally.
+         */
+        resolveKey: (...args: P) => getKeyFunction(...args),
+        setItem: (value: D, ...args: P) => enhancedLocalStorage.setItem(getKeyFunction(...args), value),
+    });
+}

package/src/storage/enhanced/redis/core.ts

@@ -0,0 +1,149 @@
+import { Buffer } from 'node:buffer';
+
+import { Redis } from 'ioredis';
+import {
+    deserialize,
+    serialize,
+} from 'superjson';
+
+enum StorageValueEncodingType {
+    Buffer = 0,
+    Json = 1,
+    String = 2,
+}
+
+const customValueHeader = Buffer.of(
+    0xE2,
+    0x81,
+    0xA0,
+);
+
+const customValueHeaderLength = customValueHeader.byteLength + 1;
+
+/**
+ * Creates an enhanced Redis-based storage interface using SuperJSON encoding.
+ *
+ * This utility provides a typed, serializable key-value store backed by Redis,
+ * supporting TTL operations and safe deserialization of complex types (e.g. Date, Map).
+ *
+ * @param {Redis | string} ioRedisInstanceOrUrl - Either an existing `ioredis` instance or a Redis connection string.
+ *
+ * @returns A frozen object that wraps Redis commands with typed get/set logic and encoding.
+ *
+ * @example
+ * ```typescript
+ * const redisStorage = createEnhancedRedisStorage('redis://localhost');
+ * await redisStorage.setItem('user:1', { name: 'user' });
+ * const user = await redisStorage.getItem<{ name: string }>('user:1');
+ * ```
+ */
+export function createEnhancedRedisStorage(ioRedisInstanceOrUrl: Redis | string) {
+    const instance = ioRedisInstanceOrUrl instanceof Redis ? ioRedisInstanceOrUrl : new Redis(ioRedisInstanceOrUrl);
+    return Object.freeze({
+        /**
+         * Retrieves a value from Redis and decodes it.
+         *
+         * @template T - The expected return type.
+         *
+         * @param {string} key - The Redis key.
+         *
+         * @returns {Promise<null | T>} The decoded value or null if not found.
+         */
+        async getItem<T = unknown>(key: string) {
+            const rawValue = await instance.getBuffer(key);
+            return rawValue ? decodeStorageValue(rawValue) as T : null;
+        },
+        /**
+         * Gets the remaining TTL (in seconds) for a given key.
+         *
+         * @param {string} key - The Redis key.
+         *
+         * @returns {Promise<number>} The number of seconds until the key expires, or -1 if no expiration is set.
+         */
+        getItemTtl: (key: string) => instance.ttl(key),
+        /**
+         * Checks whether a key exists in Redis.
+         *
+         * @param {string} key - The Redis key.
+         *
+         * @returns {Promise<boolean>} True if the key exists, false otherwise.
+         */
+        hasItem: async (key: string) => await instance.exists(key) === 1,
+        /**
+         * The underlying Redis instance, exposed for advanced operations.
+         * Use with caution; most use cases should rely on the wrapper methods.
+         *
+         * @returns {Redis} The underlying Redis instance.
+         */
+        get instance() {
+            return instance;
+        },
+        /**
+         * Removes a key from Redis.
+         *
+         * @param {string} key - The Redis key to delete.
+         *
+         * @returns {Promise<boolean>} A Promise that resolves to `true` if the key was removed,
+         * or `false` if it did not exist.
+         */
+        removeItem: async (key: string) => await instance.del(key) === 1,
+        /**
+         * Stores a value in Redis without expiration.
+         *
+         * @param {string} key - The Redis key.
+         * @param {any} value - The value to store. Will be serialized.
+         */
+        setItem: (key: string, value: any) => instance.set(key, encodeToStorageValue(value)),
+        /**
+         * Stores a value in Redis with a time-to-live (TTL).
+         *
+         * @param {string} key - The Redis key.
+         * @param {number} seconds - Expiration time in seconds.
+         * @param {any} value - The value to store. Will be serialized.
+         */
+        setItemWithTtl(key: string, seconds: number, value: any) {
+            return instance.setex(key, seconds, encodeToStorageValue(value));
+        },
+    });
+}
+
+function decodeStorageValue(data: Buffer) {
+    if (!isCustomFormat(data)) return data;
+    const payload = data.subarray(customValueHeaderLength);
+    const type = data[customValueHeader.byteLength];
+    switch (type) {
+        case StorageValueEncodingType.Buffer: return payload;
+        case StorageValueEncodingType.Json:
+            try {
+                return deserialize(JSON.parse(payload.toString()));
+            } catch {
+                throw new Error('[RedisStorage] Failed to parse JSON payload.');
+            }
+        case StorageValueEncodingType.String: return payload.toString();
+        default:
+            throw new Error(`[RedisStorage] Unknown encoding type: ${type}.`);
+    }
+}
+
+function encodeToStorageValue(value: any) {
+    if (Buffer.isBuffer(value)) return toCustomValue(StorageValueEncodingType.Buffer, value);
+    if (typeof value === 'string') return toCustomValue(StorageValueEncodingType.String, Buffer.from(value));
+    return toCustomValue(StorageValueEncodingType.Json, Buffer.from(JSON.stringify(serialize(value))));
+}
+
+function isCustomFormat(buffer: Buffer) {
+    return (
+        buffer.length >= customValueHeaderLength
+        && buffer[0] === customValueHeader[0]
+        && buffer[1] === customValueHeader[1]
+        && buffer[2] === customValueHeader[2]
+    );
+}
+
+function toCustomValue(type: StorageValueEncodingType, payload: Buffer) {
+    return Buffer.concat([
+        customValueHeader,
+        Buffer.of(type),
+        payload,
+    ]);
+}

package/src/storage/enhanced/redis/index.ts

@@ -0,0 +1,2 @@
+export { createEnhancedRedisStorage } from './core';
+export { createKeyedEnhancedRedisStore } from './keyed-store';

package/src/storage/enhanced/redis/keyed-store.ts

@@ -0,0 +1,41 @@
+import type { createEnhancedRedisStorage } from './core';
+
+/**
+ * Creates a reusable, type-safe Redis-backed storage interface based on `createEnhancedRedisStorage`
+ * and a dynamic key-generation function.
+ *
+ * This utility abstracts away key construction and provides high-level access
+ * to Redis operations such as `getItem`, `setItem`, `setItemWithTtl`, and `getItemTtl`.
+ * It is ideal for namespaced data, caching, and session handling.
+ *
+ * @template D - The value type to store.
+ *
+ * @param {ReturnType<typeof createEnhancedRedisStorage>} storage - The enhanced Redis storage instance.
+ *
+ * @returns A factory that accepts a key generator function and returns a scoped Redis storage interface.
+ *
+ * @example
+ * ```typescript
+ * const userStore = createKeyedEnhancedRedisStore<User>(redisStorage)((id: number) => `user:${id}`);
+ * await userStore.setItem({ id: 123, name: 'user' }, 123);
+ * const user = await userStore.getItem(123);
+ * ```
+ */
+export function createKeyedEnhancedRedisStore<D = unknown>(storage: ReturnType<typeof createEnhancedRedisStorage>) {
+    return <P extends any[]>(getKeyFunction: (...args: P) => string) => Object.freeze({
+        getItem: (...args: P) => storage.getItem<D>(getKeyFunction(...args)),
+        getItemTtl: (...args: P) => storage.getItemTtl(getKeyFunction(...args)),
+        hasItem: (...args: P) => storage.hasItem(getKeyFunction(...args)),
+        removeItem: (...args: P) => storage.removeItem(getKeyFunction(...args)),
+        /**
+         * Resolves the storage key from the given arguments.
+         *
+         * @returns {string} The final string key used internally.
+         */
+        resolveKey: (...args: P) => getKeyFunction(...args),
+        setItem: (value: D, ...args: P) => storage.setItem(getKeyFunction(...args), value),
+        setItemWithTtl(seconds: number, value: D, ...args: P) {
+            return storage.setItemWithTtl(getKeyFunction(...args), seconds, value);
+        },
+    });
+}