@alwatr/local-storage 9.23.3 → 9.25.0

package/README.md

@@ -114,6 +114,19 @@ To completely remove the item from `localStorage`, use the `.remove()` method.
 userSettingsProvider.remove();
 ```
 
+### 6\. Storing Complex Types (Maps, Sets, Dates)
+
+By default, the provider uses `JSON.parse` and `JSON.stringify`. If you need to store types that aren't natively supported by JSON (like `Map`, `Set`, or `Date`), you can provide custom `parse` and `stringify` functions in the configuration.
+
+```typescript
+const mapProvider = createLocalStorageProvider<Map<string, number>>({
+  name: 'score-map',
+  schemaVersion: 1,
+  stringify: (map) => JSON.stringify(Array.from(map.entries())),
+  parse: (str) => new Map(JSON.parse(str)),
+});
+```
+
 ## Best Practices
 
 - **Always use the `createLocalStorageProvider` factory function.** It provides a stable API that protects your code from internal library changes.
@@ -278,6 +291,19 @@ if (LocalStorageProvider.has(formMeta)) {
 userSettingsProvider.remove();
 ```
 
+### ۶. ذخیره‌سازی انواع داده‌های پیچیده (Map, Set, Date)
+
+به طور پیش‌فرض، Provider از `JSON.parse` و `JSON.stringify` استفاده می‌کند. اگر نیاز به ذخیره نوع‌هایی دارید که به صورت ذاتی توسط JSON پشتیبانی نمی‌شوند (مانند `Map`، `Set` یا `Date`)، می‌توانید توابع سفارشی `parse` و `stringify` را در پیکربندی ارائه دهید.
+
+```typescript
+const mapProvider = createLocalStorageProvider<Map<string, number>>({
+  name: 'score-map',
+  schemaVersion: 1,
+  stringify: (map) => JSON.stringify(Array.from(map.entries())),
+  parse: (str) => new Map(JSON.parse(str)),
+});
+```
+
 ## بهترین روش‌ها (Best Practices)
 
 - **همیشه از تابع سازنده `createLocalStorageProvider` استفاده کنید.** این تابع یک API پایدار فراهم می‌کند که کد شما را در برابر تغییرات داخلی کتابخانه محافظت می‌کند.

package/dist/facade.d.ts

@@ -21,5 +21,5 @@ import type { LocalStorageProviderConfig } from './type.js';
  * console.log(currentSettings); // { theme: 'dark', notifications: false }
  * ```
  */
-export declare function createLocalStorageProvider<T>(config: LocalStorageProviderConfig): LocalStorageProvider<T>;
+export declare function createLocalStorageProvider<T>(config: LocalStorageProviderConfig<T>): LocalStorageProvider<T>;
 //# sourceMappingURL=facade.d.ts.map

package/dist/facade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../src/facade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,oBAAoB,EAAC,MAAM,6BAA6B,CAAC;AAEjE,OAAO,KAAK,EAAC,0BAA0B,EAAC,MAAM,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,MAAM,EAAE,0BAA0B,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAEzG"}
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../src/facade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,oBAAoB,EAAC,MAAM,6BAA6B,CAAC;AAEjE,OAAO,KAAK,EAAC,0BAA0B,EAAC,MAAM,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAE5G"}

package/dist/local-storage.provider.d.ts

@@ -22,17 +22,25 @@ export declare class LocalStorageProvider<T> {
     static readonly version: string;
     private readonly key__;
     protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
-    constructor(config: LocalStorageProviderConfig);
+    protected readonly parse_: (value: string) => T;
+    protected readonly stringify_: (value: T) => string;
+    constructor(config: LocalStorageProviderConfig<T>);
     /**
      * Generates the versioned storage key.
-     * @param meta - An object containing the name and schemaVersion.
+     * @param config - An object containing the name and schemaVersion.
      * @returns The versioned key string.
      */
-    static getKey(config: LocalStorageProviderConfig): string;
+    static getKey(config: {
+        name: string;
+        schemaVersion: number;
+    }): string;
     /**
      * Manages data migration by removing all previous versions of the item.
      */
-    static clearPreviousStorageVersions(config: LocalStorageProviderConfig): void;
+    static clearPreviousStorageVersions(config: {
+        name: string;
+        schemaVersion: number;
+    }): void;
     /**
      * Checks if a versioned item exists in localStorage for the given configuration.
      * This static method allows checking for the existence of a specific versioned item

package/dist/local-storage.provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-storage.provider.d.ts","sourceRoot":"","sources":["../src/local-storage.provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,0BAA0B,EAAC,MAAM,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IACjC,gBAAuB,OAAO,SAAuB;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAC;gBAEf,MAAM,EAAE,0BAA0B;IAO9C;;;;OAIG;WACW,MAAM,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM;IAIhE;;OAEG;WACW,4BAA4B,CAAC,MAAM,EAAE,0BAA0B,GAAG,IAAI;IAUpF;;;;;;;;;;;;OAYG;WACW,GAAG,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO;IAK9D;;;;;;;;;;;;OAYG;IACI,GAAG,IAAI,OAAO;IAIrB;;;OAGG;IACI,IAAI,IAAI,CAAC,GAAG,IAAI;IAwBvB;;OAEG;IACI,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAiB5B;;OAEG;IACI,MAAM,IAAI,IAAI;CAGtB"}
+{"version":3,"file":"local-storage.provider.d.ts","sourceRoot":"","sources":["../src/local-storage.provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,0BAA0B,EAAC,MAAM,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IACjC,gBAAuB,OAAO,SAAuB;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAAC;IAC3B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;IAChD,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;gBAExC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC;IAUjD;;;;OAIG;WACW,MAAM,CAAC,MAAM,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAC,GAAG,MAAM;IAI3E;;OAEG;WACW,4BAA4B,CAAC,MAAM,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI;IAU/F;;;;;;;;;;;;OAYG;WACW,GAAG,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO;IAK9D;;;;;;;;;;;;OAYG;IACI,GAAG,IAAI,OAAO;IAIrB;;;OAGG;IACI,IAAI,IAAI,CAAC,GAAG,IAAI;IAwBvB;;OAEG;IACI,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAiB5B;;OAEG;IACI,MAAM,IAAI,IAAI;CAGtB"}

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/local-storage v9.23.3 */
-import{createLogger as z}from"@alwatr/logger";class j{static version="9.23.3";key__;logger_;constructor(x){this.logger_=z(`local-storage-provider: ${x.name}, v: ${x.schemaVersion}`),this.logger_.logMethodArgs?.("constructor",{config:x}),this.key__=j.getKey(x),j.clearPreviousStorageVersions(x)}static getKey(x){return`${x.name}.v${x.schemaVersion}`}static clearPreviousStorageVersions(x){if(x.schemaVersion<1)return;for(let b=0;b<x.schemaVersion;b++){let q=j.getKey({name:x.name,schemaVersion:b});localStorage.removeItem(q)}}static has(x){let b=j.getKey(x);return localStorage.getItem(b)!==null}has(){return localStorage.getItem(this.key__)!==null}read(){let x=null;try{x=localStorage.getItem(this.key__)}catch(b){this.logger_.error("read","read_local_storage_error",{err:b})}if(!x)return this.logger_.logMethod?.("read//no_value"),null;try{let b=JSON.parse(x);return this.logger_.logMethodFull?.("read//value",void 0,{parsedValue:b}),b}catch(b){return this.logger_.error("read","read_parse_error",{err:b}),null}}write(x){this.logger_.logMethodArgs?.("write",{value:x});let b;try{b=JSON.stringify(x)}catch(q){throw this.logger_.error("write","write_stringify_error",{err:q}),Error("write_stringify_error")}try{localStorage.setItem(this.key__,b)}catch(q){this.logger_.error("write","write_local_storage_error",{err:q})}}remove(){localStorage.removeItem(this.key__)}}function E(x){return new j(x)}export{E as createLocalStorageProvider,j as LocalStorageProvider};
+/* 📦 @alwatr/local-storage v9.25.0 */
+import{createLogger as z}from"@alwatr/logger";class j{static version="9.25.0";key__;logger_;parse_;stringify_;constructor(x){this.logger_=z(`local-storage-provider: ${x.name}, v: ${x.schemaVersion}`),this.logger_.logMethodArgs?.("constructor",{config:x}),this.key__=j.getKey(x),j.clearPreviousStorageVersions(x),this.parse_=x.parse??JSON.parse,this.stringify_=x.stringify??JSON.stringify}static getKey(x){return`${x.name}.v${x.schemaVersion}`}static clearPreviousStorageVersions(x){if(x.schemaVersion<1)return;for(let b=0;b<x.schemaVersion;b++){let q=j.getKey({name:x.name,schemaVersion:b});localStorage.removeItem(q)}}static has(x){let b=j.getKey(x);return localStorage.getItem(b)!==null}has(){return localStorage.getItem(this.key__)!==null}read(){let x=null;try{x=localStorage.getItem(this.key__)}catch(b){this.logger_.error("read","read_local_storage_error",{err:b})}if(!x)return this.logger_.logMethod?.("read//no_value"),null;try{let b=this.parse_(x);return this.logger_.logMethodFull?.("read//value",void 0,{parsedValue:b}),b}catch(b){return this.logger_.error("read","read_parse_error",{err:b}),null}}write(x){this.logger_.logMethodArgs?.("write",{value:x});let b;try{b=this.stringify_(x)}catch(q){throw this.logger_.error("write","write_stringify_error",{err:q}),Error("write_stringify_error")}try{localStorage.setItem(this.key__,b)}catch(q){this.logger_.error("write","write_local_storage_error",{err:q})}}remove(){localStorage.removeItem(this.key__)}}function E(x){return new j(x)}export{E as createLocalStorageProvider,j as LocalStorageProvider};
 
-//# debugId=EB536AE279DDB01C64756E2164756E21
+//# debugId=B157F3AB96F5AC3164756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -2,10 +2,10 @@
   "version": 3,
   "sources": ["../src/local-storage.provider.ts", "../src/facade.ts"],
   "sourcesContent": [
-    "import {createLogger} from '@alwatr/logger';\n\nimport type {LocalStorageProviderConfig} from './type.js';\n\n/**\n * A provider class for managing a specific, versioned item in localStorage.\n * It encapsulates the logic for key generation, serialization, and migration.\n *\n * @example\n * ```typescript\n * const userSettings = new LocalStorageProvider({\n *   name: 'user-settings',\n *   version: 1\n * });\n *\n * // Write new settings\n * userSettings.write({ theme: 'dark', notifications: false });\n *\n * // Read the current settings\n * const currentSettings = userSettings.read();\n * console.log(currentSettings); // { theme: 'dark', notifications: false }\n * ```\n */\nexport class LocalStorageProvider<T> {\n  public static readonly version = __package_version__;\n\n  private readonly key__: string;\n  protected readonly logger_;\n\n  constructor(config: LocalStorageProviderConfig) {\n    this.logger_ = createLogger(`local-storage-provider: ${config.name}, v: ${config.schemaVersion}`);\n    this.logger_.logMethodArgs?.('constructor', {config});\n    this.key__ = LocalStorageProvider.getKey(config);\n    LocalStorageProvider.clearPreviousStorageVersions(config);\n  }\n\n  /**\n   * Generates the versioned storage key.\n   * @param meta - An object containing the name and schemaVersion.\n   * @returns The versioned key string.\n   */\n  public static getKey(config: LocalStorageProviderConfig): string {\n    return `${config.name}.v${config.schemaVersion}`;\n  }\n\n  /**\n   * Manages data migration by removing all previous versions of the item.\n   */\n  public static clearPreviousStorageVersions(config: LocalStorageProviderConfig): void {\n    if (config.schemaVersion < 1) return;\n\n    // Iterate from v1 up to the version just before the current one and remove them.\n    for (let i = 0; i < config.schemaVersion; i++) {\n      const oldKey = LocalStorageProvider.getKey({name: config.name, schemaVersion: i});\n      localStorage.removeItem(oldKey);\n    }\n  }\n\n  /**\n   * Checks if a versioned item exists in localStorage for the given configuration.\n   * This static method allows checking for the existence of a specific versioned item\n   * without instantiating the provider.\n   *\n   * @param config - The configuration object containing the name and schemaVersion.\n   * @returns `true` if the item exists in localStorage, otherwise `false`.\n   *\n   * @example\n   * ```typescript\n   * const exists = LocalStorageProvider.has({ name: 'user-form', schemaVersion: 1 });\n   * ```\n   */\n  public static has(config: LocalStorageProviderConfig): boolean {\n    const key = LocalStorageProvider.getKey(config);\n    return localStorage.getItem(key) !== null;\n  }\n\n  /**\n   * Checks if the current versioned item exists in localStorage.\n   *\n   * @returns `true` if the item exists in localStorage, otherwise `false`.\n   *\n   * @example\n   * ```typescript\n   * const provider = new LocalStorageProvider({ name: 'profile', schemaVersion: 2 });\n   * if (provider.has()) {\n   *   // Item exists\n   * }\n   * ```\n   */\n  public has(): boolean {\n    return localStorage.getItem(this.key__) !== null;\n  }\n\n  /**\n   * Reads and parses the value from localStorage.\n   * If the item doesn't exist or is invalid JSON, returns null.\n   */\n  public read(): T | null {\n    let value: string | null = null;\n\n    try {\n      value = localStorage.getItem(this.key__);\n    } catch (err) {\n      this.logger_.error('read', 'read_local_storage_error', {err});\n    }\n\n    if (!value) {\n      this.logger_.logMethod?.('read//no_value');\n      return null;\n    }\n\n    try {\n      const parsedValue = JSON.parse(value) as T;\n      this.logger_.logMethodFull?.('read//value', undefined, {parsedValue});\n      return parsedValue;\n    } catch (err) {\n      this.logger_.error('read', 'read_parse_error', {err});\n      return null;\n    }\n  }\n\n  /**\n   * Serializes and writes a value to localStorage.\n   */\n  public write(value: T): void {\n    this.logger_.logMethodArgs?.('write', {value});\n    let valueStr: string;\n    try {\n      valueStr = JSON.stringify(value);\n    } catch (err) {\n      this.logger_.error('write', 'write_stringify_error', {err});\n      throw new Error('write_stringify_error');\n    }\n\n    try {\n      localStorage.setItem(this.key__, valueStr);\n    } catch (err) {\n      this.logger_.error('write', 'write_local_storage_error', {err});\n    }\n  }\n\n  /**\n   * Removes the item from localStorage.\n   */\n  public remove(): void {\n    localStorage.removeItem(this.key__);\n  }\n}\n",
-    "import {LocalStorageProvider} from './local-storage.provider.js';\n\nimport type {LocalStorageProviderConfig} from './type.js';\n\n/**\n * Factory function to create a new LocalStorageProvider.\n *\n * @param config - The configuration for the provider.\n * @returns An instance of LocalStorageProvider.\n *\n * @example\n * ```typescript\n * const userSettings = createLocalStorageProvider({\n *   name: 'user-settings',\n *   schemaVersion: 1\n * });\n *\n * // Write new settings\n * userSettings.write({ theme: 'dark', notifications: false });\n *\n * // Read the current settings\n * const currentSettings = userSettings.read();\n * console.log(currentSettings); // { theme: 'dark', notifications: false }\n * ```\n */\nexport function createLocalStorageProvider<T>(config: LocalStorageProviderConfig): LocalStorageProvider<T> {\n  return new LocalStorageProvider<T>(config);\n}\n"
+    "import {createLogger} from '@alwatr/logger';\n\nimport type {LocalStorageProviderConfig} from './type.js';\n\n/**\n * A provider class for managing a specific, versioned item in localStorage.\n * It encapsulates the logic for key generation, serialization, and migration.\n *\n * @example\n * ```typescript\n * const userSettings = new LocalStorageProvider({\n *   name: 'user-settings',\n *   version: 1\n * });\n *\n * // Write new settings\n * userSettings.write({ theme: 'dark', notifications: false });\n *\n * // Read the current settings\n * const currentSettings = userSettings.read();\n * console.log(currentSettings); // { theme: 'dark', notifications: false }\n * ```\n */\nexport class LocalStorageProvider<T> {\n  public static readonly version = __package_version__;\n\n  private readonly key__: string;\n  protected readonly logger_;\n  protected readonly parse_: (value: string) => T;\n  protected readonly stringify_: (value: T) => string;\n\n  constructor(config: LocalStorageProviderConfig<T>) {\n    this.logger_ = createLogger(`local-storage-provider: ${config.name}, v: ${config.schemaVersion}`);\n    this.logger_.logMethodArgs?.('constructor', {config});\n    this.key__ = LocalStorageProvider.getKey(config);\n    LocalStorageProvider.clearPreviousStorageVersions(config);\n\n    this.parse_ = config.parse ?? (JSON.parse as (value: string) => T);\n    this.stringify_ = config.stringify ?? JSON.stringify;\n  }\n\n  /**\n   * Generates the versioned storage key.\n   * @param config - An object containing the name and schemaVersion.\n   * @returns The versioned key string.\n   */\n  public static getKey(config: {name: string; schemaVersion: number}): string {\n    return `${config.name}.v${config.schemaVersion}`;\n  }\n\n  /**\n   * Manages data migration by removing all previous versions of the item.\n   */\n  public static clearPreviousStorageVersions(config: {name: string; schemaVersion: number}): void {\n    if (config.schemaVersion < 1) return;\n\n    // Iterate from v1 up to the version just before the current one and remove them.\n    for (let i = 0; i < config.schemaVersion; i++) {\n      const oldKey = LocalStorageProvider.getKey({name: config.name, schemaVersion: i});\n      localStorage.removeItem(oldKey);\n    }\n  }\n\n  /**\n   * Checks if a versioned item exists in localStorage for the given configuration.\n   * This static method allows checking for the existence of a specific versioned item\n   * without instantiating the provider.\n   *\n   * @param config - The configuration object containing the name and schemaVersion.\n   * @returns `true` if the item exists in localStorage, otherwise `false`.\n   *\n   * @example\n   * ```typescript\n   * const exists = LocalStorageProvider.has({ name: 'user-form', schemaVersion: 1 });\n   * ```\n   */\n  public static has(config: LocalStorageProviderConfig): boolean {\n    const key = LocalStorageProvider.getKey(config);\n    return localStorage.getItem(key) !== null;\n  }\n\n  /**\n   * Checks if the current versioned item exists in localStorage.\n   *\n   * @returns `true` if the item exists in localStorage, otherwise `false`.\n   *\n   * @example\n   * ```typescript\n   * const provider = new LocalStorageProvider({ name: 'profile', schemaVersion: 2 });\n   * if (provider.has()) {\n   *   // Item exists\n   * }\n   * ```\n   */\n  public has(): boolean {\n    return localStorage.getItem(this.key__) !== null;\n  }\n\n  /**\n   * Reads and parses the value from localStorage.\n   * If the item doesn't exist or is invalid JSON, returns null.\n   */\n  public read(): T | null {\n    let value: string | null = null;\n\n    try {\n      value = localStorage.getItem(this.key__);\n    } catch (err) {\n      this.logger_.error('read', 'read_local_storage_error', {err});\n    }\n\n    if (!value) {\n      this.logger_.logMethod?.('read//no_value');\n      return null;\n    }\n\n    try {\n      const parsedValue = this.parse_(value);\n      this.logger_.logMethodFull?.('read//value', undefined, {parsedValue});\n      return parsedValue;\n    } catch (err) {\n      this.logger_.error('read', 'read_parse_error', {err});\n      return null;\n    }\n  }\n\n  /**\n   * Serializes and writes a value to localStorage.\n   */\n  public write(value: T): void {\n    this.logger_.logMethodArgs?.('write', {value});\n    let valueStr: string;\n    try {\n      valueStr = this.stringify_(value);\n    } catch (err) {\n      this.logger_.error('write', 'write_stringify_error', {err});\n      throw new Error('write_stringify_error');\n    }\n\n    try {\n      localStorage.setItem(this.key__, valueStr);\n    } catch (err) {\n      this.logger_.error('write', 'write_local_storage_error', {err});\n    }\n  }\n\n  /**\n   * Removes the item from localStorage.\n   */\n  public remove(): void {\n    localStorage.removeItem(this.key__);\n  }\n}\n",
+    "import {LocalStorageProvider} from './local-storage.provider.js';\n\nimport type {LocalStorageProviderConfig} from './type.js';\n\n/**\n * Factory function to create a new LocalStorageProvider.\n *\n * @param config - The configuration for the provider.\n * @returns An instance of LocalStorageProvider.\n *\n * @example\n * ```typescript\n * const userSettings = createLocalStorageProvider({\n *   name: 'user-settings',\n *   schemaVersion: 1\n * });\n *\n * // Write new settings\n * userSettings.write({ theme: 'dark', notifications: false });\n *\n * // Read the current settings\n * const currentSettings = userSettings.read();\n * console.log(currentSettings); // { theme: 'dark', notifications: false }\n * ```\n */\nexport function createLocalStorageProvider<T>(config: LocalStorageProviderConfig<T>): LocalStorageProvider<T> {\n  return new LocalStorageProvider<T>(config);\n}\n"
   ],
-  "mappings": ";AAAA,uBAAQ,uBAuBD,MAAM,CAAwB,OACZ,SAAU,SAEhB,MACE,QAEnB,WAAW,CAAC,EAAoC,CAC9C,KAAK,QAAU,EAAa,2BAA2B,EAAO,YAAY,EAAO,eAAe,EAChG,KAAK,QAAQ,gBAAgB,cAAe,CAAC,QAAM,CAAC,EACpD,KAAK,MAAQ,EAAqB,OAAO,CAAM,EAC/C,EAAqB,6BAA6B,CAAM,QAQ5C,OAAM,CAAC,EAA4C,CAC/D,MAAO,GAAG,EAAO,SAAS,EAAO,sBAMrB,6BAA4B,CAAC,EAA0C,CACnF,GAAI,EAAO,cAAgB,EAAG,OAG9B,QAAS,EAAI,EAAG,EAAI,EAAO,cAAe,IAAK,CAC7C,IAAM,EAAS,EAAqB,OAAO,CAAC,KAAM,EAAO,KAAM,cAAe,CAAC,CAAC,EAChF,aAAa,WAAW,CAAM,SAiBpB,IAAG,CAAC,EAA6C,CAC7D,IAAM,EAAM,EAAqB,OAAO,CAAM,EAC9C,OAAO,aAAa,QAAQ,CAAG,IAAM,KAgBhC,GAAG,EAAY,CACpB,OAAO,aAAa,QAAQ,KAAK,KAAK,IAAM,KAOvC,IAAI,EAAa,CACtB,IAAI,EAAuB,KAE3B,GAAI,CACF,EAAQ,aAAa,QAAQ,KAAK,KAAK,EACvC,MAAO,EAAK,CACZ,KAAK,QAAQ,MAAM,OAAQ,2BAA4B,CAAC,KAAG,CAAC,EAG9D,GAAI,CAAC,EAEH,OADA,KAAK,QAAQ,YAAY,gBAAgB,EAClC,KAGT,GAAI,CACF,IAAM,EAAc,KAAK,MAAM,CAAK,EAEpC,OADA,KAAK,QAAQ,gBAAgB,cAAe,OAAW,CAAC,aAAW,CAAC,EAC7D,EACP,MAAO,EAAK,CAEZ,OADA,KAAK,QAAQ,MAAM,OAAQ,mBAAoB,CAAC,KAAG,CAAC,EAC7C,MAOJ,KAAK,CAAC,EAAgB,CAC3B,KAAK,QAAQ,gBAAgB,QAAS,CAAC,OAAK,CAAC,EAC7C,IAAI,EACJ,GAAI,CACF,EAAW,KAAK,UAAU,CAAK,EAC/B,MAAO,EAAK,CAEZ,MADA,KAAK,QAAQ,MAAM,QAAS,wBAAyB,CAAC,KAAG,CAAC,EAChD,MAAM,uBAAuB,EAGzC,GAAI,CACF,aAAa,QAAQ,KAAK,MAAO,CAAQ,EACzC,MAAO,EAAK,CACZ,KAAK,QAAQ,MAAM,QAAS,4BAA6B,CAAC,KAAG,CAAC,GAO3D,MAAM,EAAS,CACpB,aAAa,WAAW,KAAK,KAAK,EAEtC,CC1HO,SAAS,CAA6B,CAAC,EAA6D,CACzG,OAAO,IAAI,EAAwB,CAAM",
-  "debugId": "EB536AE279DDB01C64756E2164756E21",
+  "mappings": ";AAAA,uBAAQ,uBAuBD,MAAM,CAAwB,OACZ,SAAU,SAEhB,MACE,QACA,OACA,WAEnB,WAAW,CAAC,EAAuC,CACjD,KAAK,QAAU,EAAa,2BAA2B,EAAO,YAAY,EAAO,eAAe,EAChG,KAAK,QAAQ,gBAAgB,cAAe,CAAC,QAAM,CAAC,EACpD,KAAK,MAAQ,EAAqB,OAAO,CAAM,EAC/C,EAAqB,6BAA6B,CAAM,EAExD,KAAK,OAAS,EAAO,OAAU,KAAK,MACpC,KAAK,WAAa,EAAO,WAAa,KAAK,gBAQ/B,OAAM,CAAC,EAAuD,CAC1E,MAAO,GAAG,EAAO,SAAS,EAAO,sBAMrB,6BAA4B,CAAC,EAAqD,CAC9F,GAAI,EAAO,cAAgB,EAAG,OAG9B,QAAS,EAAI,EAAG,EAAI,EAAO,cAAe,IAAK,CAC7C,IAAM,EAAS,EAAqB,OAAO,CAAC,KAAM,EAAO,KAAM,cAAe,CAAC,CAAC,EAChF,aAAa,WAAW,CAAM,SAiBpB,IAAG,CAAC,EAA6C,CAC7D,IAAM,EAAM,EAAqB,OAAO,CAAM,EAC9C,OAAO,aAAa,QAAQ,CAAG,IAAM,KAgBhC,GAAG,EAAY,CACpB,OAAO,aAAa,QAAQ,KAAK,KAAK,IAAM,KAOvC,IAAI,EAAa,CACtB,IAAI,EAAuB,KAE3B,GAAI,CACF,EAAQ,aAAa,QAAQ,KAAK,KAAK,EACvC,MAAO,EAAK,CACZ,KAAK,QAAQ,MAAM,OAAQ,2BAA4B,CAAC,KAAG,CAAC,EAG9D,GAAI,CAAC,EAEH,OADA,KAAK,QAAQ,YAAY,gBAAgB,EAClC,KAGT,GAAI,CACF,IAAM,EAAc,KAAK,OAAO,CAAK,EAErC,OADA,KAAK,QAAQ,gBAAgB,cAAe,OAAW,CAAC,aAAW,CAAC,EAC7D,EACP,MAAO,EAAK,CAEZ,OADA,KAAK,QAAQ,MAAM,OAAQ,mBAAoB,CAAC,KAAG,CAAC,EAC7C,MAOJ,KAAK,CAAC,EAAgB,CAC3B,KAAK,QAAQ,gBAAgB,QAAS,CAAC,OAAK,CAAC,EAC7C,IAAI,EACJ,GAAI,CACF,EAAW,KAAK,WAAW,CAAK,EAChC,MAAO,EAAK,CAEZ,MADA,KAAK,QAAQ,MAAM,QAAS,wBAAyB,CAAC,KAAG,CAAC,EAChD,MAAM,uBAAuB,EAGzC,GAAI,CACF,aAAa,QAAQ,KAAK,MAAO,CAAQ,EACzC,MAAO,EAAK,CACZ,KAAK,QAAQ,MAAM,QAAS,4BAA6B,CAAC,KAAG,CAAC,GAO3D,MAAM,EAAS,CACpB,aAAa,WAAW,KAAK,KAAK,EAEtC,CC/HO,SAAS,CAA6B,CAAC,EAAgE,CAC5G,OAAO,IAAI,EAAwB,CAAM",
+  "debugId": "B157F3AB96F5AC3164756E2164756E21",
   "names": []
 }

package/dist/type.d.ts

@@ -1,7 +1,7 @@
 /**
  * Configuration options for a local storage provider.
  */
-export interface LocalStorageProviderConfig {
+export interface LocalStorageProviderConfig<T = unknown> {
     /**
      * The unique name for the storage item.
      */
@@ -11,5 +11,17 @@ export interface LocalStorageProviderConfig {
      * Start from 1 for production, 0 for development mode, and increment by 1 for each new data schema change.
      */
     schemaVersion: number;
+    /**
+     * Custom parser function for deserializing the stored string.
+     * Useful for specialized data types like Maps, Sets, or Dates.
+     * Defaults to `JSON.parse`.
+     */
+    parse?: (value: string) => T;
+    /**
+     * Custom stringifier function for serializing the value.
+     * Useful for specialized data types like Maps, Sets, or Dates.
+     * Defaults to `JSON.stringify`.
+     */
+    stringify?: (value: T) => string;
 }
 //# sourceMappingURL=type.d.ts.map

package/dist/type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,CAAC,GAAG,OAAO;IACrD;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;IAE7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;CAClC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/local-storage",
-  "version": "9.23.3",
+  "version": "9.25.0",
   "description": "A modern, simple, and robust solution for managing versioned JSON objects in the browser's `localStorage`. This package provides a clean, class-based API with a factory function to ensure your application's data persistence is safe, maintainable, and future-proof.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,10 +21,10 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/logger": "9.23.3"
+    "@alwatr/logger": "9.25.0"
   },
   "devDependencies": {
-    "@alwatr/nano-build": "9.14.0",
+    "@alwatr/nano-build": "9.25.0",
     "@alwatr/standard": "9.16.0",
     "@alwatr/type-helper": "9.14.0",
     "typescript": "^6.0.3"
@@ -73,5 +73,5 @@
     "utility",
     "versioning"
   ],
-  "gitHead": "e38ea606b08ee85402fe112d4e32e741a446dcad"
+  "gitHead": "a49ae304180faab79539b5ddfe62d18ac91a232e"
 }

package/src/facade.ts

@@ -23,6 +23,6 @@ import type {LocalStorageProviderConfig} from './type.js';
  * console.log(currentSettings); // { theme: 'dark', notifications: false }
  * ```
  */
-export function createLocalStorageProvider<T>(config: LocalStorageProviderConfig): LocalStorageProvider<T> {
+export function createLocalStorageProvider<T>(config: LocalStorageProviderConfig<T>): LocalStorageProvider<T> {
   return new LocalStorageProvider<T>(config);
 }

package/src/local-storage.provider.ts

@@ -26,27 +26,32 @@ export class LocalStorageProvider<T> {
 
   private readonly key__: string;
   protected readonly logger_;
+  protected readonly parse_: (value: string) => T;
+  protected readonly stringify_: (value: T) => string;
 
-  constructor(config: LocalStorageProviderConfig) {
+  constructor(config: LocalStorageProviderConfig<T>) {
     this.logger_ = createLogger(`local-storage-provider: ${config.name}, v: ${config.schemaVersion}`);
     this.logger_.logMethodArgs?.('constructor', {config});
     this.key__ = LocalStorageProvider.getKey(config);
     LocalStorageProvider.clearPreviousStorageVersions(config);
+
+    this.parse_ = config.parse ?? (JSON.parse as (value: string) => T);
+    this.stringify_ = config.stringify ?? JSON.stringify;
   }
 
   /**
    * Generates the versioned storage key.
-   * @param meta - An object containing the name and schemaVersion.
+   * @param config - An object containing the name and schemaVersion.
    * @returns The versioned key string.
    */
-  public static getKey(config: LocalStorageProviderConfig): string {
+  public static getKey(config: {name: string; schemaVersion: number}): string {
     return `${config.name}.v${config.schemaVersion}`;
   }
 
   /**
    * Manages data migration by removing all previous versions of the item.
    */
-  public static clearPreviousStorageVersions(config: LocalStorageProviderConfig): void {
+  public static clearPreviousStorageVersions(config: {name: string; schemaVersion: number}): void {
     if (config.schemaVersion < 1) return;
 
     // Iterate from v1 up to the version just before the current one and remove them.
@@ -110,7 +115,7 @@ export class LocalStorageProvider<T> {
     }
 
     try {
-      const parsedValue = JSON.parse(value) as T;
+      const parsedValue = this.parse_(value);
       this.logger_.logMethodFull?.('read//value', undefined, {parsedValue});
       return parsedValue;
     } catch (err) {
@@ -126,7 +131,7 @@ export class LocalStorageProvider<T> {
     this.logger_.logMethodArgs?.('write', {value});
     let valueStr: string;
     try {
-      valueStr = JSON.stringify(value);
+      valueStr = this.stringify_(value);
     } catch (err) {
       this.logger_.error('write', 'write_stringify_error', {err});
       throw new Error('write_stringify_error');

package/src/type.ts

@@ -2,7 +2,7 @@
 /**
  * Configuration options for a local storage provider.
  */
-export interface LocalStorageProviderConfig {
+export interface LocalStorageProviderConfig<T = unknown> {
   /**
    * The unique name for the storage item.
    */
@@ -13,4 +13,18 @@ export interface LocalStorageProviderConfig {
    * Start from 1 for production, 0 for development mode, and increment by 1 for each new data schema change.
    */
   schemaVersion: number;
+
+  /**
+   * Custom parser function for deserializing the stored string.
+   * Useful for specialized data types like Maps, Sets, or Dates.
+   * Defaults to `JSON.parse`.
+   */
+  parse?: (value: string) => T;
+
+  /**
+   * Custom stringifier function for serializing the value.
+   * Useful for specialized data types like Maps, Sets, or Dates.
+   * Defaults to `JSON.stringify`.
+   */
+  stringify?: (value: T) => string;
 }