{"id":24138675,"url":"https://github.com/ajejey/use-db-state-hook","last_synced_at":"2026-04-09T16:43:27.174Z","repository":{"id":216672164,"uuid":"742059649","full_name":"ajejey/use-db-state-hook","owner":"ajejey","description":"A React Hook NPM Library that that uses IndexedDB in the browser to persistantly store and retrieve state.","archived":false,"fork":false,"pushed_at":"2024-06-18T17:18:01.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-12T17:18:12.098Z","etag":null,"topics":["indexeddb","persistant-storage","react"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/use-db-state","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajejey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-01-11T17:18:50.000Z","updated_at":"2024-08-02T06:28:44.000Z","dependencies_parsed_at":"2024-01-31T07:17:44.454Z","dependency_job_id":null,"html_url":"https://github.com/ajejey/use-db-state-hook","commit_stats":null,"previous_names":["ajejey/use-db-state-hook"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajejey%2Fuse-db-state-hook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajejey%2Fuse-db-state-hook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajejey%2Fuse-db-state-hook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajejey%2Fuse-db-state-hook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajejey","download_url":"https://codeload.github.com/ajejey/use-db-state-hook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241365014,"owners_count":19951080,"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","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":["indexeddb","persistant-storage","react"],"created_at":"2025-01-12T03:33:00.840Z","updated_at":"2026-04-09T16:43:27.169Z","avatar_url":"https://github.com/ajejey.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# useDbState\n\n[![npm version](https://img.shields.io/npm/v/use-db-state.svg)](https://www.npmjs.com/package/use-db-state)\n[![npm downloads](https://img.shields.io/npm/dm/use-db-state.svg)](https://www.npmjs.com/package/use-db-state)\n[![license](https://img.shields.io/npm/l/use-db-state.svg)](https://github.com/yourusername/use-db-state/blob/main/LICENSE)\n\n\u003e 🚀 A powerful React hook for persistent state management with IndexedDB, featuring global state management, automatic caching, and optimized performance.\n\n`useDbState` is a production-ready React hook that combines the simplicity of `useState` with the persistence of IndexedDB and power of global state management. It's perfect for managing application-wide state, offline-first applications, and sharing state between components.\n\n## 🆕 React 19 Support\n\n**✅ Fully compatible with React 19.x** (including React 19.1.1)\n\nThis package supports both React 18 and React 19, ensuring smooth upgrades:\n- **React 18.2.0+**: Full compatibility maintained\n- **React 19.0.0+**: Fully tested and compatible with all React 19 features\n- **No breaking changes**: Seamless upgrade from React 18 to 19\n- **Future-proof**: Automatically supports all React 19.x releases\n\n\u003e ## use-db-state@2.0.0 can now be used as a global state!\n\n## ✨ Features\n\n- 🌍 **Global State Management**: Share state seamlessly between components\n- 💾 **Persistent Storage**: Data persists through page reloads and browser restarts\n- ⚡ **Performance Optimized**: \n  - In-memory caching for fast reads\n  - Debounced writes to reduce database operations\n  - Queued operations to prevent race conditions\n- 🛡️ **Reliable**: Automatic error handling and recovery\n- 🔍 **Developer Friendly**: Comprehensive debugging support\n- 📱 **Universal**: Works in all modern browsers and React Native\n\n## 🎮 Live Examples\n\nHere are several live examples demonstrating different use cases and features of `useDbState`:\n\n### Basic Counter with Persistence\n[View Demo](https://stackblitz.com/edit/vitejs-vite-jnzmby?file=src%2FApp.jsx)\nA simple counter example showing how state persists across page refreshes. Perfect for getting started with `useDbState`.\n\n### String State Sharing\n[View Demo](https://stackblitz.com/edit/vitejs-vite-auyxlh?file=src%2FApp.jsx)\nDemonstrates how two components can share a string state, showing real-time updates between components.\n\n### Optimized Number Updates\n[View Demo](https://stackblitz.com/edit/vitejs-vite-rjq6uk?file=src%2FApp.jsx)\nShowcases the hook's handling of rapid state changes with numbers, featuring:\n- Race condition prevention\n- Internal debouncing\n- Optimized performance for fast updates\n\n### Array State Management\n[View Demo](https://stackblitz.com/edit/vitejs-vite-4rvslg?file=src%2FApp.jsx)\nShows how arrays are handled in shared state:\n- Adding elements to array\n- Real-time updates across components\n- Array manipulation with persistence\n\n### Object State Handling\n[View Demo](https://stackblitz.com/edit/vitejs-vite-zrd7jb?file=src%2FApp.jsx)\nDemonstrates working with complex object states:\n- Object property updates\n- Nested object handling\n- State synchronization between components\n\n### Image Storage and Sharing\n[View Demo](https://stackblitz.com/edit/vitejs-vite-z3hluk?file=src%2FApp.jsx)\nAdvanced example showing:\n- Binary data storage\n- Image handling in IndexedDB\n- Sharing images between components\n- Efficient large data management\n\nEach example is fully interactive and can be edited live on StackBlitz. They serve as both documentation and a playground for learning how to use `useDbState` effectively.\n\n## 📦 Installation\n\n```bash\nnpm install use-db-state\n# or\nyarn add use-db-state\n# or\npnpm add use-db-state\n```\n\n### Requirements\n\n- **React**: 18.2.0+ or 19.0.0+\n- **React DOM**: 18.2.0+ or 19.0.0+\n- **Browser**: Modern browsers with IndexedDB support\n\n## 🚀 Quick Start\n\n```jsx\nimport { useDbState } from 'use-db-state';\n\nfunction Counter() {\n  const [count, setCount] = useDbState('counter', 0);\n  \n  return (\n    \u003cbutton onClick={() =\u003e setCount(prev =\u003e prev + 1)}\u003e\n      Count: {count}\n    \u003c/button\u003e\n  );\n}\n```\n\n## 📖 Global State Usage\n\n```js\nimport { useDbState, useDbKeyRemover } from 'use-db-state';\n\nfunction ComponentOne() {\n  const [myValue, setMyValue] = useDbState('myValue', '');\n  const removeMyKey = useDbKeyRemover(); \n\n  const handleChange = (e) =\u003e {\n    setMyValue(e.target.value);\n  };\n\n  return (\n    \u003cdiv className=\"App\"\u003e\n      \u003ch1\u003eMy App\u003c/h1\u003e\n      \u003cdiv\u003e\n        \u003cinput type='text' value={myValue} onChange={handleChange} /\u003e\n        \u003cbutton onClick={() =\u003e removeMyKey('myValue')}\u003eRemove myValue\u003c/button\u003e\n      \u003c/div\u003e\n    \u003c/div\u003e\n  );\n}\n\nfunction ComponentTwo() {\n  const [myValue, setMyValue] = useDbState('myValue'); // You now have access to the myValue state from ComponentOne\n\n  return (\n    \u003cdiv className=\"App\"\u003e\n      \u003ch1\u003eMy App\u003c/h1\u003e\n      \u003cdiv\u003e\n        \u003cp\u003emyValue: {myValue}\u003c/p\u003e\n      \u003c/div\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nIn this example, `useDbState` is used to create a global state variable `myValue` that can be accessed and modified from any component. The state is persisted in IndexedDB, so it will be preserved across page reloads. The useDbKeyRemover hook is used to remove the key `myValue` from the IndexedDB object store when needed.\n\n## 📚 API Reference\n\n### useDbState\n\n```typescript\nfunction useDbState\u003cT\u003e(\n  key: string,\n  defaultValue?: T,\n  dbName?: string,\n  storeName?: string,\n  options?: {\n    debounceTime?: number;\n  }\n): [T, (value: T | ((prev: T) =\u003e T)) =\u003e void]\n```\n\n#### Parameters\n\n- `key` (required): Unique identifier for the state\n- `defaultValue`: Initial value if none exists in storage\n- `dbName`: Database name (default: 'userDatabase')\n- `storeName`: Store name (default: 'userData')\n- `options`: Configuration object\n  - `debounceTime`: Milliseconds to debounce writes (default: 100)\n\n#### Returns\n\nReturns a tuple containing:\n1. Current state value\n2. Setter function (accepts new value or updater function)\n\n### useDbKeyRemover\n\n```typescript\nfunction useDbKeyRemover(\n  dbName?: string,\n  storeName?: string\n): (key: string) =\u003e Promise\u003cvoid\u003e\n```\n\n## ⚡ Performance Considerations\n\n- **In-Memory Cache**: First reads are cached for instant access\n- **Debounced Writes**: Prevents excessive database operations\n- **Operation Queue**: Ensures write operations are atomic\n- **Cleanup**: Automatic subscription cleanup on unmount\n\n## 🔄 Migration Guide\n\n### Upgrading to React 19\n\nNo code changes required! Simply update your React dependencies:\n\n```bash\nnpm install react@^19.0.0 react-dom@^19.0.0\n```\n\nYour existing `useDbState` code will work identically in React 19:\n\n```jsx\n// This code works in both React 18 and 19\nconst [data, setData] = useDbState('myKey', defaultValue);\n```\n\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## 📄 License\n\nMIT © Ajey Nagarkatti\n\n## 🔍 Keywords\n\nreact, hook, indexeddb, state management, persistent storage, cross-tab synchronization, react-hooks, browser storage, offline-first, web storage, react state, database, web development, frontend, javascript\n\n---\n\n\u003cp align=\"center\"\u003eMade with ❤️ for the React community\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajejey%2Fuse-db-state-hook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajejey%2Fuse-db-state-hook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajejey%2Fuse-db-state-hook/lists"}