{"id":31646349,"url":"https://github.com/youglin-dev/electron-async-storage","last_synced_at":"2025-10-07T05:49:09.317Z","repository":{"id":316549796,"uuid":"1063824348","full_name":"YougLin-dev/electron-async-storage","owner":"YougLin-dev","description":"An electron async storage library based on unstorage","archived":false,"fork":false,"pushed_at":"2025-09-25T08:20:46.000Z","size":125,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T09:28:12.759Z","etag":null,"topics":["async","electron","storage"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/electron-async-storage","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YougLin-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T07:02:26.000Z","updated_at":"2025-09-25T09:26:06.000Z","dependencies_parsed_at":"2025-09-25T09:28:14.211Z","dependency_job_id":null,"html_url":"https://github.com/YougLin-dev/electron-async-storage","commit_stats":null,"previous_names":["youglin-dev/electron-async-storage"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/YougLin-dev/electron-async-storage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YougLin-dev%2Felectron-async-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YougLin-dev%2Felectron-async-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YougLin-dev%2Felectron-async-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YougLin-dev%2Felectron-async-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YougLin-dev","download_url":"https://codeload.github.com/YougLin-dev/electron-async-storage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YougLin-dev%2Felectron-async-storage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278727839,"owners_count":26035410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","electron","storage"],"created_at":"2025-10-07T05:49:05.097Z","updated_at":"2025-10-07T05:49:09.309Z","avatar_url":"https://github.com/YougLin-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# electron-async-storage\n\n[![npm version](https://img.shields.io/npm/v/electron-async-storage.svg?style=flat)](https://npmjs.com/package/electron-async-storage)\n[![npm downloads](https://img.shields.io/npm/dm/electron-async-storage.svg?style=flat)](https://npmjs.com/package/electron-async-storage)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/electron-async-storage?style=flat)](https://bundlephobia.com/package/electron-async-storage)\n\nA high-performance, type-safe asynchronous storage library for Electron applications, built on the unstorage architecture. Features a sophisticated driver-based system with advanced serialization, real-time watching, batching capabilities, full synchronous API support, and a powerful migration framework.\n\n## ✨ Key Features\n\n- **🏗️ Driver-Based Architecture**: Mount multiple storage backends with different drivers\n- **⚡ Dual API**: Full synchronous and asynchronous API support for maximum flexibility\n- **🚀 High Performance**: Built-in batching, queueing, and optimization strategies\n- **📡 Real-time Watching**: File system monitoring with chokidar integration\n- **🔄 Migration System**: Version-based migrations with hooks and error handling\n- **🏷️ Advanced TypeScript**: Conditional typing, storage definitions, and full type safety\n- **📦 Serialization Engine**: Complex object serialization using superjson (Date, RegExp, Set, Map, Error, URL, bigint)\n- **🔧 Tree-Shakable**: Modular architecture with individual driver imports\n- **⚡ Multiple Formats**: ESM, CJS with optimized builds\n\n## 🚀 Installation\n\n```bash\n# Using npm\nnpm install electron-async-storage\n\n# Using pnpm\npnpm add electron-async-storage\n\n# Using yarn\nyarn add electron-async-storage\n```\n\n## 📖 Quick Start\n\n### Basic Usage\n\n```typescript\nimport { createStorage } from \"electron-async-storage\";\n\n// Create storage with default memory driver\nconst storage = createStorage();\n\n// Asynchronous operations\nawait storage.setItem(\"user:profile\", {\n  name: \"John Doe\",\n  lastLogin: new Date(),\n  preferences: new Set([\"dark-mode\", \"notifications\"]),\n});\n\nconst profile = await storage.getItem(\"user:profile\");\nconsole.log(profile); // Full object with Date and Set preserved\n\n// Synchronous operations (great for configuration and caching)\nstorage.setItemSync(\"config:theme\", \"dark\");\nstorage.setItemSync(\"config:language\", \"en\");\n\nconst theme = storage.getItemSync(\"config:theme\");\nconst allConfigs = storage.getKeysSync(\"config:\");\nconsole.log(theme); // \"dark\"\nconsole.log(allConfigs); // [\"config:theme\", \"config:language\"]\n```\n\n### File System Storage\n\n```typescript\nimport { createStorage } from \"electron-async-storage\";\nimport fsDriver from \"electron-async-storage/drivers/fs\";\nimport { app } from \"electron\";\n\nconst storage = createStorage({\n  driver: fsDriver({\n    base: path.join(app.getPath(\"userData\"), \"storage\"),\n  }),\n});\n\n// All data persisted to disk with real-time watching\nawait storage.setItem(\"app:settings\", { theme: \"dark\", version: \"1.0.0\" });\n```\n\n### Multi-Driver Architecture\n\n```typescript\nimport { createStorage } from \"electron-async-storage\";\nimport fsDriver from \"electron-async-storage/drivers/fs\";\nimport memoryDriver from \"electron-async-storage/drivers/memory\";\nimport queueDriver from \"electron-async-storage/drivers/queue\";\n\nconst storage = createStorage({ driver: memoryDriver() });\n\n// Mount different drivers for different data types\nstorage.mount(\"cache\", memoryDriver()); // Fast in-memory cache\nstorage.mount(\"config\", fsDriver({ base: \"./config\" })); // Persistent config\nstorage.mount(\n  \"logs\",\n  queueDriver({\n    driver: fsDriver({ base: \"./logs\" }),\n    batchSize: 100,\n    flushInterval: 5000,\n  })\n); // Batched logging\n\n// Data automatically routed to appropriate driver\nawait storage.setItem(\"cache:user-session\", sessionData); // → Memory\nawait storage.setItem(\"config:app-settings\", settings); // → File system\nawait storage.setItem(\"logs:error\", errorData); // → Queued to disk\n```\n\n## 🏗️ Core Architecture\n\n### Storage Interface\n\nThe `Storage` interface provides a comprehensive dual API for data operations:\n\n```typescript\ninterface Storage\u003cT extends StorageValue = StorageValue\u003e {\n  // Asynchronous Core Operations\n  hasItem(key: string, opts?: TransactionOptions): Promise\u003cboolean\u003e;\n  getItem\u003cR = T\u003e(key: string, opts?: TransactionOptions): Promise\u003cR | null\u003e;\n  setItem(key: string, value: T, opts?: TransactionOptions): Promise\u003cvoid\u003e;\n  removeItem(key: string, opts?: TransactionOptions): Promise\u003cvoid\u003e;\n\n  // Synchronous Core Operations\n  hasItemSync(key: string, opts?: TransactionOptions): boolean;\n  getItemSync\u003cR = T\u003e(key: string, opts?: TransactionOptions): R | null;\n  setItemSync(key: string, value: T, opts?: TransactionOptions): void;\n  removeItemSync(key: string, opts?: TransactionOptions): void;\n\n  // Batch Operations (Async)\n  getItems(\n    items: string[],\n    commonOptions?: TransactionOptions\n  ): Promise\u003cArray\u003c{ key: string; value: T | null }\u003e\u003e;\n  setItems(\n    items: Array\u003c{ key: string; value: T; options?: TransactionOptions }\u003e,\n    commonOptions?: TransactionOptions\n  ): Promise\u003cvoid\u003e;\n\n  // Batch Operations (Sync)\n  getItemsSync(\n    items: string[],\n    commonOptions?: TransactionOptions\n  ): Array\u003c{ key: string; value: T | null }\u003e;\n  setItemsSync(\n    items: Array\u003c{ key: string; value: T; options?: TransactionOptions }\u003e,\n    commonOptions?: TransactionOptions\n  ): void;\n\n  // Raw Value Operations (Async)\n  getItemRaw\u003cT = any\u003e(\n    key: string,\n    opts?: TransactionOptions\n  ): Promise\u003cT | null\u003e;\n  setItemRaw\u003cT = any\u003e(\n    key: string,\n    value: T,\n    opts?: TransactionOptions\n  ): Promise\u003cvoid\u003e;\n\n  // Raw Value Operations (Sync)\n  getItemRawSync\u003cT = any\u003e(key: string, opts?: TransactionOptions): T | null;\n  setItemRawSync\u003cT = any\u003e(\n    key: string,\n    value: T,\n    opts?: TransactionOptions\n  ): void;\n\n  // Key Management (Async)\n  getKeys(base?: string, opts?: GetKeysOptions): Promise\u003cstring[]\u003e;\n  clear(base?: string, opts?: TransactionOptions): Promise\u003cvoid\u003e;\n\n  // Key Management (Sync)\n  getKeysSync(base?: string, opts?: GetKeysOptions): string[];\n  clearSync(base?: string, opts?: TransactionOptions): void;\n\n  // Mount System, Watching, Migration, Lifecycle (Async only)\n  mount(base: string, driver: Driver): Storage;\n  unmount(base: string, dispose?: boolean): Promise\u003cvoid\u003e;\n  watch(callback: WatchCallback): Promise\u003cUnwatch\u003e;\n  migrate(): Promise\u003cvoid\u003e;\n  dispose(): Promise\u003cvoid\u003e;\n\n  // Aliases (Async)\n  keys: typeof getKeys;\n  get: typeof getItem;\n  set: typeof setItem;\n  has: typeof hasItem;\n  del: typeof removeItem;\n  remove: typeof removeItem;\n\n  // Aliases (Sync)\n  keysSync: typeof getKeysSync;\n  getSync: typeof getItemSync;\n  setSync: typeof setItemSync;\n  hasSync: typeof hasItemSync;\n  delSync: typeof removeItemSync;\n  removeSync: typeof removeItemSync;\n}\n```\n\n### Driver System\n\nAll drivers implement the `Driver` interface with optional capabilities:\n\n```typescript\ninterface Driver\u003cOptionsT = any, InstanceT = any\u003e {\n  name?: string;\n  flags?: DriverFlags; // { maxDepth?: boolean; ttl?: boolean }\n  options?: OptionsT;\n  getInstance?: () =\u003e InstanceT;\n\n  // Required Methods\n  hasItem(key: string, opts: TransactionOptions): MaybePromise\u003cboolean\u003e;\n  getItem(key: string, opts?: TransactionOptions): MaybePromise\u003cStorageValue\u003e;\n  getKeys(base: string, opts: GetKeysOptions): MaybePromise\u003cstring[]\u003e;\n\n  // Optional Methods\n  setItem?(\n    key: string,\n    value: string,\n    opts: TransactionOptions\n  ): MaybePromise\u003cvoid\u003e;\n  removeItem?(key: string, opts: TransactionOptions): MaybePromise\u003cvoid\u003e;\n  getMeta?(\n    key: string,\n    opts: TransactionOptions\n  ): MaybePromise\u003cStorageMeta | null\u003e;\n  clear?(base: string, opts: TransactionOptions): MaybePromise\u003cvoid\u003e;\n  watch?(callback: WatchCallback): MaybePromise\u003cUnwatch\u003e;\n  dispose?(): MaybePromise\u003cvoid\u003e;\n\n  // Batch Operations (Performance Optimization)\n  getItems?(\n    items: Array\u003c{ key: string; options?: TransactionOptions }\u003e,\n    commonOptions?: TransactionOptions\n  ): MaybePromise\u003cArray\u003c{ key: string; value: StorageValue }\u003e\u003e;\n  setItems?(\n    items: Array\u003c{ key: string; value: string; options?: TransactionOptions }\u003e,\n    commonOptions?: TransactionOptions\n  ): MaybePromise\u003cvoid\u003e;\n\n  // Raw Value Support\n  getItemRaw?(key: string, opts: TransactionOptions): MaybePromise\u003cunknown\u003e;\n  setItemRaw?(\n    key: string,\n    value: any,\n    opts: TransactionOptions\n  ): MaybePromise\u003cvoid\u003e;\n}\n```\n\n## 🔧 Built-in Drivers\n\n### Memory Driver\n\nHigh-performance in-memory storage using JavaScript Map:\n\n```typescript\nimport memoryDriver from \"electron-async-storage/drivers/memory\";\n\nconst storage = createStorage({\n  driver: memoryDriver(),\n});\n\n// Instant read/write operations\n// Data lost on process restart\n// Perfect for caching and temporary data\n```\n\n### File System Driver\n\nFull-featured file system storage with watching capabilities:\n\n```typescript\nimport fsDriver from \"electron-async-storage/drivers/fs\";\n\nconst storage = createStorage({\n  driver: fsDriver({\n    base: \"./data\", // Base directory\n    ignore: [\"**/node_modules/**\"], // Ignore patterns (anymatch)\n    readOnly: false, // Read-only mode\n    noClear: false, // Disable clear operations\n    watchOptions: {\n      // Chokidar options\n      ignoreInitial: true,\n      persistent: true,\n    },\n  }),\n});\n\n// Features:\n// - Real-time file watching with chokidar\n// - Path traversal protection\n// - Recursive directory operations\n// - File metadata (atime, mtime, size, birthtime, ctime)\n// - Configurable ignore patterns\n```\n\n### File System Lite Driver\n\nLightweight file system storage without watching:\n\n```typescript\nimport fsLiteDriver from \"electron-async-storage/drivers/fs-lite\";\n\nconst storage = createStorage({\n  driver: fsLiteDriver({\n    base: \"./data\",\n    ignore: (path) =\u003e path.includes(\"temp\"),\n    readOnly: false,\n    noClear: false,\n  }),\n});\n\n// Smaller footprint, no chokidar dependency\n// Same file operations as fs driver\n// No real-time watching capability\n```\n\n### Queue Driver\n\nPerformance-optimized batching wrapper for any driver:\n\n```typescript\nimport queueDriver from \"electron-async-storage/drivers/queue\";\nimport fsDriver from \"electron-async-storage/drivers/fs\";\n\nconst storage = createStorage({\n  driver: queueDriver({\n    driver: fsDriver({ base: \"./logs\" }),\n    batchSize: 100, // Batch operations\n    flushInterval: 1000, // Auto-flush interval (ms)\n    maxQueueSize: 1000, // Maximum queue size\n    mergeUpdates: true, // Merge duplicate key updates\n  }),\n});\n\n// Benefits:\n// - Dramatically improved write performance\n// - Automatic batching and merging\n// - Configurable flush strategies\n// - Queue overflow protection\n// - Maintains operation order\n```\n\n## 📊 Advanced Features\n\n### Complex Object Serialization\n\nelectron-async-storage uses superjson for sophisticated object serialization:\n\n```typescript\n// All these types are preserved across storage operations\nawait storage.setItem(\"complex-data\", {\n  date: new Date(),\n  regex: /pattern/gi,\n  set: new Set([1, 2, 3]),\n  map: new Map([[\"key\", \"value\"]]),\n  bigint: 123n,\n  undefined: undefined,\n  error: new Error(\"test\"),\n  url: new URL(\"https://example.com\"),\n});\n\nconst data = await storage.getItem(\"complex-data\");\nconsole.log(data.date instanceof Date); // true\nconsole.log(data.regex instanceof RegExp); // true\nconsole.log(data.set instanceof Set); // true\n// All types perfectly preserved\n```\n\n### Raw Value Operations\n\nFor binary data and custom serialization:\n\n```typescript\n// Store raw binary data\nconst buffer = new Uint8Array([1, 2, 3, 4]);\nawait storage.setItemRaw(\"binary-data\", buffer);\n\n// Data is base64 encoded automatically\nconst restored = await storage.getItemRaw(\"binary-data\");\nconsole.log(restored instanceof Uint8Array); // true\n```\n\n### Real-Time Watching\n\nMonitor storage changes in real-time:\n\n```typescript\n// Watch for all changes\nconst unwatch = await storage.watch((event, key) =\u003e {\n  console.log(`${event}: ${key}`); // \"update: user:profile\"\n});\n\n// Watch specific keys\nawait storage.setItem(\"user:profile\", userData); // Triggers watcher\n\n// Cleanup\nawait unwatch();\n```\n\n### Key Management and Filtering\n\nSophisticated key operations with depth control:\n\n```typescript\n// Hierarchical keys with depth filtering\nawait storage.setItem(\"app:ui:theme\", \"dark\");\nawait storage.setItem(\"app:ui:layout:sidebar\", \"collapsed\");\nawait storage.setItem(\"app:data:cache:user\", userData);\n\n// Get keys at specific depths\nconst uiKeys = await storage.getKeys(\"app:ui\", { maxDepth: 1 });\n// Returns: ['app:ui:theme'] (excludes deeper nested keys)\n\nconst allAppKeys = await storage.getKeys(\"app\");\n// Returns: ['app:ui:theme', 'app:ui:layout:sidebar', 'app:data:cache:user']\n```\n\n### Metadata System\n\nRich metadata support for advanced use cases:\n\n```typescript\n// Set metadata\nawait storage.setMeta(\"cached-data\", {\n  ttl: Date.now() + 3_600_000, // TTL timestamp\n  source: \"api-v2\",\n  version: \"1.2.0\",\n  priority: \"high\",\n});\n\n// Retrieve with metadata\nconst meta = await storage.getMeta(\"cached-data\");\nconsole.log(meta.ttl, meta.source, meta.atime, meta.mtime);\n\n// File system drivers include native metadata\nconst fileMeta = await storage.getMeta(\"config.json\");\nconsole.log(fileMeta.size, fileMeta.birthtime, fileMeta.ctime);\n```\n\n## ⚡ Synchronous API\n\nThe library provides a complete synchronous API alongside the asynchronous methods, offering zero Promise overhead for performance-critical scenarios and simpler code when blocking operations are acceptable.\n\n### Core Benefits\n\n- **🚀 Zero Promise Overhead**: Direct return values without async/await\n- **📝 Simplified Code**: Cleaner logic for configuration and simple operations\n- **🎯 Better Performance**: Faster execution for memory and simple file operations\n- **🔄 Seamless Integration**: Works alongside async methods in the same storage instance\n\n### Usage Examples\n\n```typescript\nimport { createStorage } from \"electron-async-storage\";\nimport memoryDriver from \"electron-async-storage/drivers/memory\";\n\nconst storage = createStorage({ driver: memoryDriver() });\n\n// Configuration at startup (synchronous)\nstorage.setItemSync(\"app:theme\", \"dark\");\nstorage.setItemSync(\"app:language\", \"en\");\nstorage.setItemSync(\"app:debug\", true);\n\n// Quick cache operations\nconst theme = storage.getItemSync(\"app:theme\");\nif (storage.hasItemSync(\"cache:user-preferences\")) {\n  const prefs = storage.getItemSync(\"cache:user-preferences\");\n  console.log(\"Cached preferences:\", prefs);\n}\n\n// Batch operations\nstorage.setItemsSync([\n  { key: \"config:api-url\", value: \"https://api.example.com\" },\n  { key: \"config:timeout\", value: 5000 },\n  { key: \"config:retries\", value: 3 },\n]);\n\nconst allConfigs = storage.getItemsSync([\n  \"config:api-url\",\n  \"config:timeout\",\n  \"config:retries\",\n]);\n\n// Key management\nconst configKeys = storage.getKeysSync(\"config:\");\nstorage.clearSync(\"temp:\"); // Clear temporary data\n```\n\n### Driver Support\n\n| Driver  | Sync Support | Performance | Use Cases                      |\n| ------- | ------------ | ----------- | ------------------------------ |\n| Memory  | ✅ Full      | Excellent   | Caches, sessions, config       |\n| FS      | ✅ Full      | Good        | Persistent config, small files |\n| FS-Lite | ✅ Full      | Good        | Lightweight file operations    |\n| Queue   | ⚠️ Partial   | Variable    | Immediate operations only      |\n\n### Performance Comparison\n\n```typescript\n// Memory driver performance test\nconsole.time(\"sync-operations\");\nfor (let i = 0; i \u003c 10_000; i++) {\n  storage.setItemSync(`key-${i}`, { data: i });\n  storage.getItemSync(`key-${i}`);\n}\nconsole.timeEnd(\"sync-operations\"); // ~25ms\n\nconsole.time(\"async-operations\");\nfor (let i = 0; i \u003c 10_000; i++) {\n  await storage.setItem(`async-key-${i}`, { data: i });\n  await storage.getItem(`async-key-${i}`);\n}\nconsole.timeEnd(\"async-operations\"); // ~75ms (Promise overhead)\n```\n\n### Best Practices\n\n- **Use sync methods for**: Configuration loading, simple caches, startup data\n- **Use async methods for**: I/O intensive operations, large datasets, non-blocking scenarios\n- **Mixed usage**: Combine both APIs as needed in the same application\n\n```typescript\n// Application startup: sync for immediate needs\nconst theme = storage.getItemSync(\"app:theme\") || \"light\";\nconst language = storage.getItemSync(\"app:language\") || \"en\";\n\n// Runtime: async for user data\nconst userProfile = await storage.getItem(\"user:profile\");\nconst userSettings = await storage.getItem(\"user:settings\");\n\n// Caching: sync for quick access\nif (!storage.hasItemSync(\"cache:theme-config\")) {\n  storage.setItemSync(\"cache:theme-config\", buildThemeConfig(theme));\n}\n```\n\n## 🔄 Migration System\n\nPowerful version-based migration system with hooks:\n\n```typescript\nconst storage = createStorage({\n  driver: fsDriver({ base: \"./data\" }),\n  version: 3,\n  migrations: {\n    1: async (storage) =\u003e {\n      // Migrate to version 1\n      const oldData = await storage.getItem(\"legacy-format\");\n      await storage.setItem(\"new-format\", transformData(oldData));\n      await storage.removeItem(\"legacy-format\");\n    },\n    2: async (storage) =\u003e {\n      // Migrate to version 2\n      const users = await storage.getKeys(\"users:\");\n      for (const key of users) {\n        const user = await storage.getItem(key);\n        user.version = 2;\n        user.migrationDate = new Date();\n        await storage.setItem(key, user);\n      }\n    },\n    3: async (storage) =\u003e {\n      // Migrate to version 3\n      await storage.setItem(\"schema-version\", {\n        version: 3,\n        features: [\"new-api\"],\n      });\n    },\n  },\n  migrationHooks: {\n    beforeMigration: async (from, to, storage) =\u003e {\n      console.log(`Starting migration from v${from} to v${to}`);\n      await storage.setItem(\"migration:backup\", await snapshot(storage, \"\"));\n    },\n    afterMigration: async (from, to, storage) =\u003e {\n      console.log(`Migration complete: v${from} → v${to}`);\n      await storage.removeItem(\"migration:backup\");\n    },\n    onMigrationError: async (error, from, to, storage) =\u003e {\n      console.error(`Migration failed: v${from} → v${to}`, error);\n      // Restore from backup\n      const backup = await storage.getItem(\"migration:backup\");\n      await restoreSnapshot(storage, backup);\n    },\n  },\n});\n\n// Migrations run automatically\nawait storage.migrate();\n```\n\n## 🏷️ Advanced TypeScript\n\n### Storage Definitions\n\nDefine typed storage schemas for compile-time safety:\n\n```typescript\ninterface AppStorageSchema {\n  items: {\n    \"user:profile\": UserProfile;\n    \"app:settings\": AppSettings;\n    \"cache:api-response\": ApiResponse;\n  };\n}\n\nconst storage = createStorage\u003cAppStorageSchema\u003e();\n\n// Full type safety\nawait storage.setItem(\"user:profile\", userProfile); // ✅ Typed\nawait storage.setItem(\"user:unknown\", data); // ❌ Type error\n\nconst profile = await storage.getItem(\"user:profile\"); // UserProfile | null\n```\n\n### Conditional Types\n\nThe library uses sophisticated conditional types for flexible APIs:\n\n```typescript\n// Automatically infer return types based on storage definition\ntype ProfileType = Awaited\u003cReturnType\u003ctypeof storage.getItem\u003c\"user:profile\"\u003e\u003e\u003e;\n// ProfileType = UserProfile | null\n\n// Batch operations maintain type safety\nconst results = await storage.getItems([\"user:profile\", \"app:settings\"]);\n// results[0].value is UserProfile | null\n// results[1].value is AppSettings | null\n```\n\n### Driver Type Safety\n\nCustom drivers with full type safety:\n\n```typescript\ninterface CustomDriverOptions {\n  endpoint: string;\n  apiKey: string;\n  timeout?: number;\n}\n\nconst customDriver = defineDriver\u003cCustomDriverOptions\u003e((opts) =\u003e ({\n  name: \"custom-api\",\n  async getItem(key) {\n    const response = await fetch(`${opts.endpoint}/${key}`, {\n      headers: { Authorization: `Bearer ${opts.apiKey}` },\n    });\n    return response.json();\n  },\n  async setItem(key, value) {\n    await fetch(`${opts.endpoint}/${key}`, {\n      method: \"PUT\",\n      headers: { Authorization: `Bearer ${opts.apiKey}` },\n      body: JSON.stringify(value),\n    });\n  },\n  // ... other methods\n}));\n```\n\n## ⚡ Performance Optimization\n\n### Batching Operations\n\nOptimize performance with batch operations:\n\n```typescript\n// Instead of individual operations\nfor (const [key, value] of entries) {\n  await storage.setItem(key, value); // Slow: N disk operations\n}\n\n// Use batch operations\nawait storage.setItems(entries.map(([key, value]) =\u003e ({ key, value }))); // Fast: 1 batch operation\n```\n\n### Queue Driver Configuration\n\nOptimize queue driver for your use case:\n\n```typescript\n// High-throughput logging\nconst loggingStorage = createStorage({\n  driver: queueDriver({\n    driver: fsDriver({ base: \"./logs\" }),\n    batchSize: 1000, // Large batches for efficiency\n    flushInterval: 5000, // Less frequent flushes\n    maxQueueSize: 10_000, // Large queue\n    mergeUpdates: true, // Merge duplicate updates\n  }),\n});\n\n// Real-time configuration\nconst configStorage = createStorage({\n  driver: queueDriver({\n    driver: fsDriver({ base: \"./config\" }),\n    batchSize: 10, // Small batches for responsiveness\n    flushInterval: 100, // Frequent flushes\n    maxQueueSize: 100, // Small queue\n    mergeUpdates: false, // Preserve all updates\n  }),\n});\n```\n\n### Memory Management\n\n```typescript\n// Dispose resources properly\nconst storage = createStorage({ driver: fsDriver({ base: \"./data\" }) });\n\n// Use storage...\n\n// Cleanup\nawait storage.dispose(); // Closes file watchers, flushes queues, etc.\n```\n\n## 🔧 Build Integration\n\n### Bundler Configuration\n\n#### Webpack\n\n```javascript\nmodule.exports = {\n  resolve: {\n    alias: {\n      \"electron-async-storage/drivers/fs\": path.resolve(\n        __dirname,\n        \"node_modules/electron-async-storage/drivers/fs.mjs\"\n      ),\n    },\n  },\n};\n```\n\n#### Vite\n\n```javascript\nexport default defineConfig({\n  resolve: {\n    alias: {\n      \"electron-async-storage/drivers/fs\":\n        \"electron-async-storage/drivers/fs.mjs\",\n    },\n  },\n});\n```\n\n### Tree Shaking\n\nImport only the drivers you need:\n\n```typescript\n// ✅ Tree-shakable - only imports used drivers\nimport { createStorage } from \"electron-async-storage\";\nimport fsDriver from \"electron-async-storage/drivers/fs\";\n\n// ❌ Imports all drivers\nimport { createStorage, builtinDrivers } from \"electron-async-storage\";\n```\n\n## 📚 Additional Documentation\n\n- [**Architecture Guide**](./docs/ARCHITECTURE.md) - Deep dive into the internal architecture\n- [**Driver Development**](./docs/DRIVERS.md) - Creating custom drivers\n- [**Migration Guide**](./docs/MIGRATION.md) - Advanced migration patterns\n- [**API Reference**](./docs/API.md) - Complete API documentation\n- [**Performance Guide**](./docs/PERFORMANCE.md) - Optimization strategies\n- [**TypeScript Guide**](./docs/TYPESCRIPT.md) - Advanced TypeScript usage\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## 🙏 Acknowledgments\n\nBuilt on the solid foundation of [unstorage](https://github.com/unjs/unstorage) by the UnJS team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouglin-dev%2Felectron-async-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyouglin-dev%2Felectron-async-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouglin-dev%2Felectron-async-storage/lists"}