{"_id":"@aivron/sync-storage","name":"@aivron/sync-storage","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aivron/sync-storage","version":"1.0.0","description":"A universal, synchronous storage solution for React (web & desktop) with support for core operations, bulk actions, JSON, TTL, and React hooks. For React Native, use @aivron/async-storage.","main":"lib/index.js","types":"lib/index.d.ts","repository":{"type":"git","url":"git+https://github.com/aivron/sync-storage.git"},"keywords":["sync-storage","webstorage","localStorage","sessionStorage","storage","react","desktop","ttl","json"],"author":{"name":"Favour Orukpe","url":"alphadevking"},"license":"MIT","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"devDependencies":{"@types/react":"^19.0.10","typescript":"^4.9.0"},"peerDependencies":{"react":"^16.8.0 || ^17.0.0 || ^18.0.0"},"gitHead":"b339b42dfa68c6985f7ca79476ea364aed84272c","bugs":{"url":"https://github.com/aivron/sync-storage/issues"},"homepage":"https://github.com/aivron/sync-storage#readme","_id":"@aivron/sync-storage@1.0.0","_nodeVersion":"16.20.2","_npmVersion":"8.19.4","dist":{"integrity":"sha512-qmXUYHT/dBwNzW8JqwbukvPSJZyv9ThapyHtVZ8ywO4F4Gzhco3kH7AJ/xPxpR9N3coWMbLEr7ySDcMrCQUReQ==","shasum":"6148bd9df285d73507376b5e75e9279de0f28bab","tarball":"https://registry.npmjs.org/@aivron/sync-storage/-/sync-storage-1.0.0.tgz","fileCount":18,"unpackedSize":18079,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHU49MeOcB/xlj1WmJCNzVCRgpdJB7RoALRS7mEXyvcXAiBHZ40I9EiZgnN6lU8cAubFYZMH2mzkohgklK3WGexIVw=="}]},"_npmUser":{"name":"alphadevking","email":"danielose266@gmail.com"},"directories":{},"maintainers":[{"name":"alphadevking","email":"danielose266@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sync-storage_1.0.0_1739890367753_0.4287406669099114"},"_hasShrinkwrap":false}},"time":{"created":"2025-02-18T14:52:47.676Z","1.0.0":"2025-02-18T14:52:47.939Z","modified":"2025-02-18T14:52:48.242Z"},"maintainers":[{"name":"alphadevking","email":"danielose266@gmail.com"}],"description":"A universal, synchronous storage solution for React (web & desktop) with support for core operations, bulk actions, JSON, TTL, and React hooks. For React Native, use @aivron/async-storage.","homepage":"https://github.com/aivron/sync-storage#readme","keywords":["sync-storage","webstorage","localStorage","sessionStorage","storage","react","desktop","ttl","json"],"repository":{"type":"git","url":"git+https://github.com/aivron/sync-storage.git"},"author":{"name":"Favour Orukpe","url":"alphadevking"},"bugs":{"url":"https://github.com/aivron/sync-storage/issues"},"license":"MIT","readme":"\n# sync-storage\n\n**sync-storage** is a universal, synchronous storage solution for React web and desktop (Electron) applications. It provides a consistent API for managing web storage—whether you're using `localStorage`, `sessionStorage`, or a custom storage interface—while supporting core operations, bulk actions, JSON handling, TTL (time-to-live), and even React hooks for automated cleanup.\n\nFor more details on the underlying Web Storage API, please refer to the [MDN Web Storage API documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API).\n\n## Features\n\n- **Core Storage Operations:** Get, set, update, and remove individual keys.\n- **Bulk Operations:** Filter, update, and remove multiple keys based on a predicate.\n- **JSON Support:** Seamlessly store and retrieve objects using automatic JSON serialization.\n- **TTL (Time-To-Live) Support:** Set expiration times for stored items.\n- **React Hooks:** Use built-in hooks for automatic storage cleanup in your React components.\n- **Universal:** Works with any Web Storage API–compatible storage (localStorage, sessionStorage, or custom adapters).\n\n## Installation\n\nInstall via npm:\n\n```bash\nnpm install @aivron/sync-storage\n```\n\nOr via yarn:\n\n```bash\nyarn add @aivron/sync-storage\n```\n\n## Usage\n\n### Importing the Library\n\nYou can import individual functions or the entire module:\n\n```ts\n// Import specific functions:\nimport { setStorageItem, getStorageItem } from '@aivron/sync-storage';\n\n// Or import the entire module:\nimport * as storage from '@aivron/sync-storage';\n```\n\n### Basic Storage Operations\n\n#### Store a Key-Value Pair\n\n```ts\nimport { setStorageItem } from '@aivron/sync-storage';\n\nsetStorageItem('userToken', 'abc123');\n```\n\n#### Retrieve a Stored Item\n\n```ts\nimport { getStorageItem } from '@aivron/sync-storage';\n\nconst token = getStorageItem('userToken');\nconsole.log(token); // Output: \"abc123\"\n```\n\n#### Update a Stored Item\n\n```ts\nimport { updateStorageItem } from '@aivron/sync-storage';\n\nupdateStorageItem('userToken', current =>\n  current ? current + '_v2' : 'defaultToken'\n);\n```\n\n#### Remove a Stored Item\n\n```ts\nimport { removeStorageItem } from '@aivron/sync-storage';\n\nremoveStorageItem('userToken');\n```\n\n### Bulk Operations\n\n#### Retrieve Multiple Items\n\nFor example, retrieve all keys that start with `\"app:\"`:\n\n```ts\nimport { getStorageItems } from '@aivron/sync-storage';\n\nconst appItems = getStorageItems(key => key.startsWith('app:'));\nconsole.log(appItems);\n```\n\n#### Update Multiple Items\n\n```ts\nimport { updateStorageItems } from '@aivron/sync-storage';\n\nupdateStorageItems(\n  key => key.startsWith('app:'),\n  current => (current ? current.toUpperCase() : '')\n);\n```\n\n#### Remove Multiple Items\n\n```ts\nimport { removeStorageKeys } from '@aivron/sync-storage';\n\nremoveStorageKeys(key => key.includes('temp'));\n```\n\n### JSON Operations\n\n#### Store a JSON Value\n\n```ts\nimport { setJSONItem } from '@aivron/sync-storage';\n\nsetJSONItem('userData', { name: 'Alice', age: 30 });\n```\n\n#### Retrieve a JSON Value\n\n```ts\nimport { getJSONItem } from '@aivron/sync-storage';\n\nconst userData = getJSONItem<{ name: string; age: number }>('userData');\nconsole.log(userData);\n```\n\n#### Update a JSON Value\n\n```ts\nimport { updateJSONItem } from '@aivron/sync-storage';\n\nupdateJSONItem<{ name: string; age: number }>('userData', current => ({\n  ...current,\n  age: (current?.age || 0) + 1,\n}));\n```\n\n### TTL (Time-To-Live) Operations\n\n#### Store an Item with TTL\n\nStore an item that expires in 1 hour:\n\n```ts\nimport { setStorageItemWithTTL } from '@aivron/sync-storage';\n\nsetStorageItemWithTTL('sessionData', 'sessionValue', 3600 * 1000);\n```\n\n#### Retrieve an Item with TTL\n\n```ts\nimport { getStorageItemWithTTL } from '@aivron/sync-storage';\n\nconst sessionValue = getStorageItemWithTTL('sessionData');\nconsole.log(sessionValue);\n```\n\n### React Hook for Storage Cleanup\n\nAutomatically remove storage keys that match a predicate when your component mounts:\n\n```tsx\nimport React from 'react';\nimport { useStorageCleanup } from '@aivron/sync-storage';\n\nfunction App() {\n  // Automatically remove any keys that start with \"old:\" when the component mounts.\n  useStorageCleanup(key => key.startsWith('old:'));\n\n  return <div>Your React Web/Desktop App</div>;\n}\n\nexport default App;\n```\n\n## MDN Documentation\n\nThis package is built in accordance with the [MDN Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) specification. For in-depth information on how the Web Storage API works, please review the MDN documentation linked above.\n\n## API Reference\n\nFor a detailed API reference, please consult the source code or visit the repository's documentation site.\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome!\nPlease see the [issues page](https://github.com/aivron/sync-storage/issues) for more details on how to contribute.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Repository\n\nFor the full source code and further documentation, visit the [sync-storage GitHub repository](https://github.com/aivron/sync-storage).\n\n---\n\nEnjoy using **@aivron/sync-storage** as your go-to solution for synchronous web storage in React web and desktop projects! If you have any questions or need assistance, feel free to open an issue on GitHub.\n","readmeFilename":"README.md"}