Simple Jotai interface for IndexedDB key-value storage
Simple but fully functional way to persist key-value data in IndexedDb for Jotai. Analogues to atomWithStorage but when localStorage is not enough.
> ⚠️ IMPORTANT: This package was initially created to experiment with Jotai v2 API and currently doesn't support v1. Please open an issue if you are interested to use it with v1.
- IndexedDB persistency
- TypeScript support
- Cross-tab sync (changes in one browser tab are automatically synced to other tabs)
- Data migrations (if you have some local data you will have to migrate it sooner or later)
``
yarn add jotai-minidb jotai
First, you need to create instance of a MiniDb class.
`js`
import { MiniDb } from "jotai-minidb";
const myDb = new MiniDb();
After MiniDb instance is created it provides set of atoms to Interact with IndexedDB storage:
`js
function MyComponent() {
const [user, setUser] = useAtom(myDb.item("user-123"));
return (
onChange={(e) => setUser({ ...user, name: e.target.value })}
/>
);
}
`
- myDb.keys - read-only atom with an array of stored keys Atom
- - read-only atom with an array of stored values Atom
- - - read-only atom with an key/value cache Atom
- - read-only atom with [key, value] entries Atom<[string, T][]>
`js`
const [item, setItem] = useAtom(myDb.item(key));
`js`
const set = useSetAtom(myDb.set);
set(key, value);
`js`
const setMany = useSetAtom(myDb.setMany)
setMany([
['key-1', 1],
['key-2', 33],
...
])
`js`
const delete = useSetAtom(myDb.delete)
delete(key)
`js`
const clear = useSetAtom(myDb.clear);
clear();
`js
// Jotai V2 API!
import { useAtom, useAtomValue, useSetAtom } from "jotai/react";
import { MiniDb } from "jotai-minidb";
// Type of an item in key-value store
type Item = {
name: string;
};
// 1. Create a minidb instance
const myDb = new MiniDb
// 2. Get all keys, values or entries
export function Entries() {
const keys = useAtomValue(myDb.keys);
const values = useAtomValue(myDb.values);
const entries = useAtomValue(myDb.entries);
return (
Values:
Entries:
// 3. Get, or set item in a store
export function Entry() {
const [item, setItem] = useAtom(myDb.item("some-item-key"));
if (!item) {
return null;
}
return (
onChange={(e) => setItem({ ...item, name: e.target.value })}
/>
);
}
// 4. Create new item or delete item
export function CreateUpdateOrDelete() {
const set = useSetAtom(simpleStore.set);
const del = useSetAtom(simpleStore.delete);
return (
<>
);
}
`
MiniDb constructor takes an optional configuration object with the following parameters:
default: jotai-minidb
Database name. If you need multiple collections you can simply define multiple storages with different names:
`
const books = new MiniDb({ name: 'books' })
const authors = new MiniDb({ name: 'authors' })
default: 0
Schema version is used to introduce breaking change to a shape of the data stored in a database. If data in IndexedDb has a version lower than version then it is migrated with set of migrations. If version is lower than version of the data in IndexedDb then exception is thrown and onVersionMissmatch handler is called
type: Record
default: {}
Populate database with some initial data when it is created
default: {}
If version is greater than 0 you should provide a migration function for each version in migrations object where a key is version and value is a migration function
`
const myDb = new MiniDb
version: 2,
migrations: {
1: (item) => {
item.age = 18
return item
},
2: (item) => {
// migrate from 1 => 2
}
},
});
default: () => {
alert("Data has been migrated. Page will be reloaded");
window.location.reload();
}
Callback that is called when migration is completed in _other browser tab or window_. For instance when user opens a new tab with the new version of the app.
In simple cases the easiest way is to refresh the page because the old code likely can not work with migrated data anyway
deafult: () => {}
Callback that is called when version of the data in IndexedDb is _higher_ than the version. Should not happen in normal situations