@alwatr/local-storage 5.5.9 → 6.0.0

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [6.0.0](https://github.com/Alwatr/nanolib/compare/@alwatr/local-storage@5.5.10...@alwatr/local-storage@6.0.0) (2025-09-13)
+
+### ⚠ BREAKING CHANGES
+
+* **local-storage:** The provider's constructor config shape and public methods have changed.
+Existing callers must be updated to the new API:
+- Update imports/instantiation to use the new LocalStorageProvider<T>(config: LocalStorageProviderConfig<T>).
+- Replace any old config fields / method names with the new ones (e.g. versioned key handling, defaultValue handling).
+- Data migration behavior changed: previous-version keys are automatically removed when version > 1.
+- Update call sites that relied on prior serialization, error handling, or return semantics.
+
+Suggested migration steps:
+1. Inspect the new LocalStorageProviderConfig<T> type and adapt object literal passed to the constructor.
+2. Replace old read/write/remove calls with the new method names and signatures.
+3. Ensure stored values match the new serialization expectations (JSON-serializable).
+4. Run tests and rehydrate any persisted data if necessary (previous keys are removed for versions >1).
+
+### ✨ Features
+
+* **local-storage:** add factory function to create LocalStorageProvider with detailed documentation ([eb4a04d](https://github.com/Alwatr/nanolib/commit/eb4a04de84d69497e7489b756c172ed2b0af008d))
+* **local-storage:** add static method to check existence of versioned items in localStorage ([8e05938](https://github.com/Alwatr/nanolib/commit/8e059382d085aa691f296b2267a372925868f974))
+
+### 🐛 Bug Fixes
+
+* **local-storage:** correct typo in writeDefault method name ([c0b05c0](https://github.com/Alwatr/nanolib/commit/c0b05c0417ec75e7d9bc57c224380f34472ec467))
+* **local-storage:** simplify read method by removing type check for parsed value ([23826ef](https://github.com/Alwatr/nanolib/commit/23826ef70eb22e6f092ba2c6ce11c28b3628f2f2))
+* **local-storage:** standardize key naming convention in LocalStorageProvider ([043cf27](https://github.com/Alwatr/nanolib/commit/043cf27881b840d5adeb79ea4a840a15ea23e262))
+
+### 🔨 Code Refactoring
+
+* **local-storage:** complete API rewrite for LocalStorageProvider ([29d01d8](https://github.com/Alwatr/nanolib/commit/29d01d84fbb3ed405ce46d1870d1a929de1c838c))
+* **local-storage:** enhance logging in read and write methods for better error tracking ([2cbf404](https://github.com/Alwatr/nanolib/commit/2cbf4042fcef74de016fd1ae80f8263f9de5c610))
+* **local-storage:** rename private key variable and update its initialization method ([e25a8ea](https://github.com/Alwatr/nanolib/commit/e25a8ea4a4b75aeac0702fc0a9ef39a5f441e54c))
+* **local-storage:** update key generation method to static and enhance documentation ([e36fd53](https://github.com/Alwatr/nanolib/commit/e36fd5355ad4b7fa7b4e629568b9a878ae868c3e))
+* **types:** reorganize StorageMeta and LocalStorageProviderConfig interfaces ([d3d001e](https://github.com/Alwatr/nanolib/commit/d3d001ef041ea59981551204d84bee7635cfc192))
+
+### 🧹 Miscellaneous Chores
+
+* add @jest/globals dependency for testing ([a024449](https://github.com/Alwatr/nanolib/commit/a024449366e6b4aa246603528dde6586dda3379e))
+
+## [5.5.10](https://github.com/Alwatr/nanolib/compare/@alwatr/local-storage@5.5.9...@alwatr/local-storage@5.5.10) (2025-09-09)
+
+### 🧹 Miscellaneous Chores
+
+* remove trailing newlines from contributing sections in README files ([e8ab1bc](https://github.com/Alwatr/nanolib/commit/e8ab1bc43e0addea5ccd4c897c2cec597cb9e15f))
+
 ## [5.5.9](https://github.com/Alwatr/nanolib/compare/@alwatr/local-storage@5.5.8...@alwatr/local-storage@5.5.9) (2025-09-06)
 
 ### 🐛 Bug Fixes

package/README.md

@@ -1,71 +1,268 @@
-# localJsonStorage
+# Alwatr Local Storage Provider
 
-`localJsonStorage` is a utility object in our TypeScript package that provides methods for interacting with the local storage in a structured and versioned manner.
+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.
 
-## Installation
+It's designed to handle data structure migrations automatically, preventing issues when your application updates and the shape of your stored data changes.
 
-Before you can use `localJsonStorage`, you need to install the package. If you're using npm, you can do this with:
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/local-storage)
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/nanolib)
+[](https://www.google.com/search?q=alwatr+local+storage)
+[](https://www.google.com/search?q=alwatr+nanolib)
+[](https://www.google.com/search?q=alwatr)
 
-```bash
-npm install @alwatr/local-storage
-```
+## Core Concepts
+
+This library is built upon a few simple but powerful concepts:
 
-If you're using Yarn, you can do this with:
+1. **Provider Pattern**: Instead of using static functions, you create an _instance_ of a `LocalStorageProvider` for each unique data item you want to manage. This instance is configured once with a name, version, and default value, and then used to interact with that specific item.
+
+2. **Versioning & Automatic Migration**: When you initialize a provider with a new `version` number, it automatically removes all older versions of that data from `localStorage`. This prevents conflicts and ensures the application is working with the correct data structure.
+
+3. **Facade Factory Function**: The `createLocalStorageProvider` function acts as a clean entry point (Facade) to the library. This simplifies the API and decouples your code from the internal class implementation, making future library upgrades safer and easier.
+
+4. **Static Existence Check**: The static method `LocalStorageProvider.has()` allows you to check if data exists _before_ creating a provider instance. This is highly efficient for scenarios where you only need to know if the data is present, without needing the data itself or a default value.
+
+## Installation
 
 ```bash
+# Using yarn
 yarn add @alwatr/local-storage
+
+# Using npm
+npm install @alwatr/local-storage
 ```
 
-## Usage
+## API and Usage
+
+### 1\. Creating a Storage Provider
 
-First, you need to import `localJsonStorage` from the package:
+The recommended way to get started is by using the `createLocalStorageProvider` factory function. It encapsulates the instantiation logic and provides a clean API.
 
 ```typescript
-import {localJsonStorage} from '@alwatr/local-storage';
+import {createLocalStorageProvider} from '@alwatr/local-storage';
+
+// Define the shape of your data
+interface UserSettings {
+  theme: 'light' | 'dark';
+  notifications: boolean;
+  lastLogin: number | null;
+}
+
+// Create a provider for user settings
+const userSettingsProvider = createLocalStorageProvider<UserSettings>({
+  name: 'user-settings',
+  version: 1,
+  defaultValue: {
+    theme: 'light',
+    notifications: true,
+    lastLogin: null,
+  },
+});
 ```
 
-Or for CommonJS:
+### 2\. Writing Data
 
-```javascript
-const {localJsonStorage} = require('@alwatr/local-storage');
+Use the `.write()` method on the provider instance to save data. The value will be automatically serialized to a JSON string.
+
+```typescript
+userSettingsProvider.write({
+  theme: 'dark',
+  notifications: false,
+  lastLogin: Date.now(),
+});
 ```
 
-### Getting an Item
+### 3\. Reading Data
+
+Use the `.read()` method to retrieve the data.
 
-You can get an item from local storage and parse it as JSON using the `getItem` method. If the item is not found, it will return a default value:
+- If a value exists in `localStorage` and is valid JSON, it will be parsed and returned.
+- If no value exists or if the stored value is corrupted (invalid JSON), the `defaultValue` will be written to `localStorage` and then returned. This guarantees you always receive a value of the correct type.
+
+<!-- end list -->
 
 ```typescript
-const defaultValue = {a: 1, b: 2};
-const value = localJsonStorage.getItem('item-name', defaultValue);
+const currentSettings = userSettingsProvider.read();
+console.log(currentSettings.theme); // "dark"
 ```
 
-### Setting an Item
+### 4\. Checking for Data Existence (The Recommended Way)
+
+This is a critical feature for many applications. Before rendering a component or creating a full provider instance, you might need to check if the user has already saved data. Use the static `LocalStorageProvider.has()` method for this.
 
-You can set an item in local storage as JSON using the `setItem` method:
+This method is highly efficient as it **does not** require a `defaultValue` and does not create a class instance.
 
 ```typescript
-const value = {a: 1, b: 2};
-localJsonStorage.setItem('item-name', value);
+import {LocalStorageProvider} from '@alwatr/local-storage';
+
+const formMeta = {name: 'user-survey-form', version: 1};
+
+if (LocalStorageProvider.has(formMeta)) {
+  // The user has already filled out the form.
+  // Show a "Thank you" message instead of the form.
+  showThankYouMessage();
+} else {
+  // No data found, so render the form.
+  renderSurveyForm();
+}
 ```
 
-### Removing an Item
+### 5\. Removing Data
 
-You can remove an item from local storage using the `removeItem` method:
+To completely remove the item from `localStorage`, use the `.remove()` method.
 
 ```typescript
-localJsonStorage.removeItem('item-name');
+userSettingsProvider.remove();
 ```
 
-## Future Plans
+## Best Practices
+
+- **Always use the `createLocalStorageProvider` factory function.** It provides a stable API that protects your code from internal library changes.
+- **Prefer `LocalStorageProvider.has()` for existence checks.** It's the most performant and cleanest way to check for data without the overhead of creating an instance and providing a `defaultValue`.
+- **Increment the `version` number** whenever you make a breaking change to your data structure. The library will handle the cleanup of old data automatically.
 
-We plan to add more methods to `localJsonStorage` for directly interacting with local storage. Stay tuned for updates!
+---
 
 ## Sponsors
 
-The following companies, organizations, and individuals support Nanolib ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
+The following companies, organizations, and individuals support flux ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
 
-### Contributing
+## Contributing
 
 Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting a pull request.
 
+---
+
+<br>
+<br>
+<br>
+
+# Alwatr Local Storage Provider (راهنمای فارسی)
+
+یک راهکار مدرن، ساده و قدرتمند برای مدیریت آبجکت‌های JSON نسخه‌بندی شده در `localStorage` مرورگر. این پکیج یک API تمیز و مبتنی بر کلاس به همراه یک تابع سازنده (Factory Function) ارائه می‌دهد تا اطمینان حاصل شود که پایداری داده‌های اپلیکیشن شما امن، قابل نگهداری و آماده برای آینده است.
+
+این کتابخانه طوری طراحی شده است که مهاجرت (migration) ساختار داده را به صورت خودکار مدیریت کند و از بروز مشکل در هنگام به‌روزرسانی اپلیکیشن و تغییر شکل داده‌های ذخیره شده جلوگیری نماید.
+
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/local-storage)
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/local-storage)
+[](https://www.google.com/search?q=alwatr+local+storage)
+[](https://www.google.com/search?q=alwatr)
+
+## مفاهیم اصلی
+
+این کتابخانه بر پایه چند مفهوم ساده اما قدرتمند بنا شده است:
+
+1. **الگوی Provider (ارائه‌دهنده)**: به جای استفاده از توابع استاتیک، شما برای هر آیتم داده‌ای که می‌خواهید مدیریت کنید، یک _نمونه (instance)_ از `LocalStorageProvider` می‌سازید. این نمونه یک بار با `name`, `version` و `defaultValue` پیکربندی شده و سپس برای تعامل با آن آیتم خاص استفاده می‌شود.
+
+2. **نسخه‌بندی و مهاجرت خودکار**: هنگامی که شما یک Provider را با شماره `version` جدیدی مقداردهی اولیه می‌کنید، این کتابخانه به طور خودکار تمام نسخه‌های قدیمی‌تر آن داده را از `localStorage` حذف می‌کند. این کار از تداخل جلوگیری کرده و تضمین می‌کند که اپلیکیشن همیشه با ساختار داده صحیح کار می‌کند.
+
+3. **تابع سازنده Facade**: تابع `createLocalStorageProvider` به عنوان یک نقطه ورود تمیز (Facade) به کتابخانه عمل می‌کند. این کار API را ساده کرده و کد شما را از پیاده‌سازی داخلی کلاس‌ها جدا (decouple) می‌سازد، که باعث می‌شود ارتقاء کتابخانه در آینده امن‌تر و آسان‌تر باشد.
+
+4. **بررسی استاتیک وجود داده**: متد استاتیک `LocalStorageProvider.has()` به شما اجازه می‌دهد وجود داده را _قبل_ از ساختن یک نمونه از Provider بررسی کنید. این روش برای سناریوهایی که فقط نیاز دارید بدانید داده‌ای وجود دارد یا نه (بدون نیاز به خود داده یا مقدار پیش‌فرض) بسیار کارآمد است.
+
+## نصب
+
+```bash
+# با استفاده از yarn
+yarn add @alwatr/local-storage
+
+# با استفاده از npm
+npm install @alwatr/local-storage
+```
+
+## API و راهنمای استفاده
+
+### ۱. ساختن یک Storage Provider
+
+بهترین روش برای شروع، استفاده از تابع سازنده `createLocalStorageProvider` است. این تابع منطق ساخت نمونه را کپسوله کرده و یک API تمیز ارائه می‌دهد.
+
+```typescript
+import {createLocalStorageProvider} from '@alwatr/local-storage';
+
+// ساختار داده خود را تعریف کنید
+interface UserSettings {
+  theme: 'light' | 'dark';
+  notifications: boolean;
+  lastLogin: number | null;
+}
+
+// یک provider برای تنظیمات کاربر بسازید
+const userSettingsProvider = createLocalStorageProvider<UserSettings>({
+  name: 'user-settings',
+  version: 1,
+  defaultValue: {
+    theme: 'light',
+    notifications: true,
+    lastLogin: null,
+  },
+});
+```
+
+### ۲. نوشتن داده (Write)
+
+از متد `.write()` روی نمونه Provider برای ذخیره داده استفاده کنید. مقدار داده به صورت خودکار به رشته JSON تبدیل می‌شود.
+
+```typescript
+userSettingsProvider.write({
+  theme: 'dark',
+  notifications: false,
+  lastLogin: Date.now(),
+});
+```
+
+### ۳. خواندن داده (Read)
+
+از متد `.read()` برای بازیابی داده استفاده کنید.
+
+- اگر مقداری در `localStorage` وجود داشته باشد و JSON معتبر باشد، آن مقدار parse شده و برگردانده می‌شود.
+- اگر مقداری وجود نداشته باشد یا مقدار ذخیره شده خراب باشد (JSON نامعتبر)، `defaultValue` در `localStorage` نوشته شده و سپس برگردانده می‌شود. این تضمین می‌کند که شما همیشه یک مقدار با نوع صحیح دریافت می‌کنید.
+
+<!-- end list -->
+
+```typescript
+const currentSettings = userSettingsProvider.read();
+console.log(currentSettings.theme); // "dark"
+```
+
+### ۴. بررسی وجود داده (روش پیشنهادی)
+
+این یک قابلیت حیاتی برای بسیاری از اپلیکیشن‌ها است. قبل از رندر کردن یک کامپوننت یا ساختن یک نمونه کامل از Provider، ممکن است لازم باشد بررسی کنید که آیا کاربر قبلاً داده‌ای ذخیره کرده است یا خیر. برای این کار از متد استاتیک `LocalStorageProvider.has()` استفاده کنید.
+
+این متد بسیار کارآمد است زیرا **نیازی** به `defaultValue` ندارد و یک نمونه از کلاس نمی‌سازد.
+
+```typescript
+import {LocalStorageProvider} from '@alwatr/local-storage';
+
+const formMeta = {name: 'user-survey-form', version: 1};
+
+if (LocalStorageProvider.has(formMeta)) {
+  // داده وجود دارد. کاربر قبلاً فرم را پر کرده است.
+  // به جای فرم، یک پیام تشکر نمایش دهید.
+  showThankYouMessage();
+} else {
+  // داده‌ای یافت نشد، بنابراین فرم را نمایش دهید.
+  renderSurveyForm();
+}
+```
+
+### ۵. حذف داده (Remove)
+
+برای حذف کامل یک آیتم از `localStorage`، از متد `.remove()` استفاده کنید.
+
+```typescript
+userSettingsProvider.remove();
+```
+
+## بهترین روش‌ها (Best Practices)
+
+- **همیشه از تابع سازنده `createLocalStorageProvider` استفاده کنید.** این تابع یک API پایدار فراهم می‌کند که کد شما را در برابر تغییرات داخلی کتابخانه محافظت می‌کند.
+- **برای بررسی وجود داده، `LocalStorageProvider.has()` را ترجیح دهید.** این کارآمدترین و تمیزترین روش برای بررسی وجود داده بدون سربار ساختن یک نمونه و تعریف `defaultValue` است.
+- **هر زمان که یک تغییر ساختاری در داده‌های خود ایجاد کردید که با نسخه‌های قبلی ناسازگار است، شماره `version` را افزایش دهید.** کتابخانه پاک‌سازی داده‌های قدیمی را به صورت خودکار انجام خواهد داد.
+
+## حامیان (Sponsors)
+
+شرکت‌ها، سازمان‌ها و افراد زیر از نگهداری و توسعه مداوم flux حمایت می‌کنند. با تبدیل شدن به یک حامی، لوگوی خود را در README و وب‌سایت ما قرار دهید.
+
+## مشارکت (Contributing)
 
+از مشارکت‌ها استقبال می‌شود! لطفاً قبل از ارسال pull request، [راهنمای مشارکت ما](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) را مطالعه کنید.

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

@@ -0,0 +1,74 @@
+import type { LocalStorageProviderConfig, StorageMeta } from './type.js';
+/**
+ * A provider class for managing a specific, versioned item in localStorage.
+ * It encapsulates the logic for key generation, serialization, and migration.
+ *
+ * @example
+ * ```typescript
+ * const userSettings = new LocalStorageProvider({
+ *   name: 'user-settings',
+ *   version: 1,
+ *   defaultValue: { theme: 'light', notifications: true }
+ * });
+ *
+ * // Write new settings
+ * userSettings.write({ theme: 'dark', notifications: false });
+ *
+ * // Read the current settings
+ * const currentSettings = userSettings.read();
+ * console.log(currentSettings); // { theme: 'dark', notifications: false }
+ * ```
+ */
+export declare class LocalStorageProvider<T extends JsonValue> {
+    protected readonly config_: LocalStorageProviderConfig<T>;
+    private readonly key__;
+    protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
+    constructor(config_: LocalStorageProviderConfig<T>);
+    /**
+     * Generates the versioned storage key.
+     * @param meta - An object containing the name and version.
+     * @returns The versioned key string.
+     */
+    static getKey(meta: StorageMeta): string;
+    /**
+     * Statically checks if a versioned item exists in localStorage.
+     * This method provides a high-performance way to check for data existence without the overhead of creating a full provider instance.
+     *
+     * @param meta - An object containing the name and version of the item to check.
+     * @returns `true` if the item exists, otherwise `false`.
+     *
+     * @example
+     * ```typescript
+     * const formExists = LocalStorageProvider.has({ name: 'user-form', version: 1 });
+     * if (formExists) {
+     *   // Show the "Thank you" message
+     * } else {
+     *   // Show the form
+     * }
+     * ```
+     */
+    static has(meta: StorageMeta): boolean;
+    /**
+     * Writes the default value to localStorage and returns it.
+     */
+    private writeDefault__;
+    /**
+     * Reads and parses the value from localStorage.
+     * If the item doesn't exist, is invalid JSON, or doesn't match the expected type,
+     * it writes and returns the default value.
+     */
+    read(): T;
+    /**
+     * Serializes and writes a value to localStorage.
+     */
+    write(value: T): void;
+    /**
+     * Removes the item from localStorage.
+     */
+    remove(): void;
+    /**
+     * Manages data migration by removing all previous versions of the item.
+     */
+    private migrate__;
+}
+//# sourceMappingURL=local-storage.provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage.provider.d.ts","sourceRoot":"","sources":["../src/local-storage.provider.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,0BAA0B,EAAE,WAAW,EAAC,MAAM,WAAW,CAAC;AAIvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,oBAAoB,CAAC,CAAC,SAAS,SAAS;IAIhC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC,CAAC;IAH5E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAA4F;gBAEhF,OAAO,EAAE,0BAA0B,CAAC,CAAC,CAAC;IAM5E;;;;OAIG;WACW,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM;IAI/C;;;;;;;;;;;;;;;;OAgBG;WACW,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO;IAK7C;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;;;OAIG;IACI,IAAI,IAAI,CAAC;IAmBhB;;OAEG;IACI,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAU5B;;OAEG;IACI,MAAM,IAAI,IAAI;IAIrB;;OAEG;IACH,OAAO,CAAC,SAAS;CASlB"}

package/dist/main.cjs

@@ -1,4 +1,4 @@
-/* @alwatr/local-storage v5.5.9 */
+/* @alwatr/local-storage v6.0.0 */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -21,113 +21,116 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/main.ts
 var main_exports = {};
 __export(main_exports, {
-  localJsonStorage: () => localJsonStorage
+  LocalStorageProvider: () => LocalStorageProvider,
+  createLocalStorageProvider: () => createLocalStorageProvider
 });
 module.exports = __toCommonJS(main_exports);
+
+// src/local-storage.provider.ts
+var import_logger = require("@alwatr/logger");
 var import_package_tracer = require("@alwatr/package-tracer");
-__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/local-storage", "5.5.9");
-function parseJson(content) {
-  try {
-    return JSON.parse(content);
-  } catch (err) {
-    console.error("parseJson", "invalid_json", err);
-    return null;
+__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/local-storage", "6.0.0");
+var LocalStorageProvider = class _LocalStorageProvider {
+  constructor(config_) {
+    this.config_ = config_;
+    this.logger_ = (0, import_logger.createLogger)(`local-storage-provider: ${this.config_.name}, v: ${this.config_.version}`);
+    this.logger_.logMethodArgs?.("constructor", { config: this.config_ });
+    this.key__ = _LocalStorageProvider.getKey(this.config_);
+    this.migrate__();
   }
-}
-var localJsonStorage = {
   /**
-   * Generate local storage key.
-   *
-   * @param name - Name of the item.
-   * @param version - Version of the item (default: 1).
-   * @returns The generated local storage key.
-   * @example
-   * ```typescript
-   * localJsonStorage.key_('myItem', 1); // myItem.v1
-   * ```
+   * Generates the versioned storage key.
+   * @param meta - An object containing the name and version.
+   * @returns The versioned key string.
    */
-  key_(name, version = 1) {
-    return `${name}.v${version}`;
-  },
+  static getKey(meta) {
+    return `${meta.name}.v${meta.version}`;
+  }
   /**
-   * Get the local storage item and parse it as JSON.
-   * If the item is not found, return the default value.
-   * If the version is greater than 1, remove the previous version.
-   * If the item is not a valid JSON object, return the default value.
+   * Statically checks if a versioned item exists in localStorage.
+   * This method provides a high-performance way to check for data existence without the overhead of creating a full provider instance.
+   *
+   * @param meta - An object containing the name and version of the item to check.
+   * @returns `true` if the item exists, otherwise `false`.
    *
-   * @param name - The name of the item.
-   * @param defaultValue - The default value of the item.
-   * @param version - The data structure version of the item (default: 1).
-   * @returns The parsed JSON value or the default value if the item is not found.
    * @example
    * ```typescript
-   * const value = localJsonStorage.getItem('myItem', {a: 1, b: 2});
+   * const formExists = LocalStorageProvider.has({ name: 'user-form', version: 1 });
+   * if (formExists) {
+   *   // Show the "Thank you" message
+   * } else {
+   *   // Show the form
+   * }
    * ```
    */
-  getItem(name, defaultValue, version = 1) {
-    if (version > 1) {
-      this.removeItem(name, version - 1);
-    }
-    if (version > 1) {
-      this.removeItem(name, version - 1);
-    }
-    const key = this.key_(name, version);
-    const value = localStorage.getItem(key);
-    if (value === null) {
-      localStorage.setItem(key, JSON.stringify(defaultValue));
-      return defaultValue;
+  static has(meta) {
+    const key = _LocalStorageProvider.getKey(meta);
+    return localStorage.getItem(key) !== null;
+  }
+  /**
+   * Writes the default value to localStorage and returns it.
+   */
+  writeDefault__() {
+    this.logger_.logMethodArgs?.("writeDefaultــ", this.config_.defaultValue);
+    this.write(this.config_.defaultValue);
+    return this.config_.defaultValue;
+  }
+  /**
+   * Reads and parses the value from localStorage.
+   * If the item doesn't exist, is invalid JSON, or doesn't match the expected type,
+   * it writes and returns the default value.
+   */
+  read() {
+    try {
+      const value = localStorage.getItem(this.key__);
+      if (value === null) {
+        this.logger_.logMethod?.("read//no_value");
+        return this.writeDefault__();
+      }
+      const parsedValue = JSON.parse(value);
+      this.logger_.logMethodFull?.("read//value", void 0, { parsedValue });
+      return parsedValue;
+    } catch (err) {
+      this.logger_.error("read", "read_parse_error", { err });
+      return this.writeDefault__();
     }
-    const json = parseJson(value);
-    if (json === null) return defaultValue;
-    return json;
-  },
+  }
   /**
-   * Check if an item exists in local storage.
-   *
-   * @param name - The name of the item.
-   * @param version - The version of the item (default: 1).
-   * @returns True if the item exists, false otherwise.
-   * @example
-   * ```typescript
-   * const exists = localJsonStorage.hasItem('myItem');
-   * ```
+   * Serializes and writes a value to localStorage.
    */
-  hasItem(name, version = 1) {
-    const key = this.key_(name, version);
-    return localStorage.getItem(key) !== null;
-  },
+  write(value) {
+    this.logger_.logMethodArgs?.("write", { value });
+    try {
+      localStorage.setItem(this.key__, JSON.stringify(value));
+    } catch (err) {
+      this.logger_.error("write", "write_stringify_error", { err });
+    }
+  }
   /**
-   * Set local storage item as JSON.
-   *
-   * @param name - Name of the item.
-   * @param value - Value of the item.
-   * @param version - Version of the item.
-   * @example
-   * ```typescript
-   * localJsonStorage.setItem('myItem', {a: 1, b: 2});
-   * ```
+   * Removes the item from localStorage.
    */
-  setItem(name, value, version = 1) {
-    const key = this.key_(name, version);
-    localStorage.setItem(key, JSON.stringify(value));
-  },
+  remove() {
+    localStorage.removeItem(this.key__);
+  }
   /**
-   * Removes an item from the local storage.
-   *
-   * @param name - The name of the item to remove.
-   * @param version - The version of the item to remove. Default is 1.
-   * @example
-   * ```typescript
-   * localJsonStorage.removeItem('myItem');
-   * ```
+   * Manages data migration by removing all previous versions of the item.
    */
-  removeItem(name, version = 1) {
-    const key = this.key_(name, version);
-    localStorage.removeItem(key);
+  migrate__() {
+    if (this.config_.version <= 1) return;
+    for (let i = 1; i < this.config_.version; i++) {
+      const oldKey = _LocalStorageProvider.getKey({ name: this.config_.name, version: i });
+      localStorage.removeItem(oldKey);
+    }
   }
 };
+
+// src/main.ts
+function createLocalStorageProvider(config) {
+  return new LocalStorageProvider(config);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  localJsonStorage
+  LocalStorageProvider,
+  createLocalStorageProvider
 });
 //# sourceMappingURL=main.cjs.map