https://github.com/astoilkov/local-db-storage
IndexedDB wrapper that mimics localStorage API
https://github.com/astoilkov/local-db-storage
indexeddb localstorage persistent
Last synced: 12 months ago
JSON representation
IndexedDB wrapper that mimics localStorage API
- Host: GitHub
- URL: https://github.com/astoilkov/local-db-storage
- Owner: astoilkov
- License: mit
- Created: 2023-11-28T08:05:48.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-04T12:14:43.000Z (over 1 year ago)
- Last Synced: 2025-04-14T02:07:46.288Z (12 months ago)
- Topics: indexeddb, localstorage, persistent
- Language: TypeScript
- Homepage:
- Size: 24.4 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# `local-db-storage`
> `IndexedDB` wrapper that mimics `localStorage` API
[](https://bundlephobia.com/result?p=local-db-storage)
[](https://github.com/astoilkov/local-db-storage/actions/workflows/main.yml)
## Install
```bash
npm install local-db-storage
```
## Why
- **Simple.** `localStorage` like API, without the complications of `IndexedDB`.
- **Capacity.** `IndexedDB` can store hundred of megabytes to gigabytes of data. `localStorage` limit is around 5-10MB.
- **Performance.** `IndexedDB` is async and doesn't block the UI. `IndexedDB` can store objects without serialization which shaves off the time to do `JSON.parse()` and `JSON.stringify()` that's needed when working with `localStorage`.
- **No good alternatives.** The most popular library [`localForage`](https://github.com/localForage/localForage) (25k stars) is complex and unmaintained.
- **Availability.** `IndexedDB` is available both in Web Worker and Service Worker, `localStorage` is not. You can write data in those places and then access it in the main thread.
- **Maintenance.** I've been consistently maintaining many open-source libraries including [`use-local-storage-state`](https://github.com/astoilkov/use-local-storage-state) with ~500k downloaders per month.
## Usage
```ts
import dbStorage from 'local-db-storage'
async function addTodo(todo): Promise {
await dbStorage.setItem(todo.id, todo)
}
async function getTodo(id: string): Promise {
await dbStorage.getItem(id)
}
```
## API
#### `getItem(key: string): Promise`
Like `localStorage.getItem()` but async.
#### `setItem(key: string, value: any): Promise`
Like `localStorage.setItem()` but async.
_Note:_ It supports non-primitive values (ex: objects). It also supports circular references.
#### `removeItem(key: string): Promise`
Like `localStorage.removeItem()` but async.
#### `clear(): Promise`
Like `localStorage.clear()` but async.
#### `DBStorage(name: string)`
Creates a new `DBStorage` instance.
```ts
import { DBStorage } from 'local-db-storage'
const dbStorage = new DBStorage('my-custom-db-storage')
await dbStorage.setItem('initial', 'hello world')
```
## Related
- [`use-db`](https://github.com/astoilkov/use-db) — React hook for `IndexedDB` that uses this library and mimics `setState` API.
- [`use-local-storage-state`](https://github.com/astoilkov/use-local-storage-state) — React hook that persists data in `localStorage`.
- [`use-session-storage-state`](https://github.com/astoilkov/use-session-storage-state) — React hook that persists data in `sessionStorage`.