use-indexed-db

Create a small promise-based key-value store on one IndexedDB object store.


Package	`@vizejs/composable/use-indexed-db`
Own the source	`vize lib pull composable:use-indexed-db`
Runtime exports	`createIndexedDBKeyval`, `useIndexedDB`
Gzip budget	3840 B

Usage

import { createIndexedDBKeyval, useIndexedDB } from "@vizejs/composable/use-indexed-db";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`createIndexedDBKeyval`	storage	experimental	safe	not-applicable	returned-value	web, desktop	`window`	—
`useIndexedDB`	storage	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`window`	`createIndexedDBKeyval`, `tryOnScopeDispose`

API

`createIndexedDBKeyval`

Create a small promise-based key-value store on one IndexedDB object store. The connection opens lazily on the first operation, the store is created on demand, and writes resolve once their transaction commits. Without IndexedDB (server rendering, privacy modes) every operation rejects with a tagged [VIZE_COMPOSE_INDEXED_DB_UNAVAILABLE] error.

function createIndexedDBKeyval(options: IndexedDBKeyvalOptions = {}): IndexedDBKeyval

`useIndexedDB`

Synchronize a reactive value with one IndexedDB key. Values are stored by structured clone, so objects, arrays, Map, Set, Date, typed arrays, and Blobs round-trip without a serializer. The value is loaded asynchronously: state holds the default until ready becomes true. Loaded values pass validate before they are accepted. Assignments and nested mutations are written back; changing the reactive key loads the new key (stale loads are discarded). Server rendering: without a browser window nothing is opened, state is the default, and ready stays false, so server and client first render identically. The connection closes and watchers stop with the owning reactive scope. Failures never reject; they are exposed through error and onError.

function useIndexedDB<Value>( key: MaybeRefOrGetter<IDBValidKey>, defaultValue: Value, options: UseIndexedDBOptions<Value> = {}, ): IndexedDBControls<Value>

const { state: draft, ready } = useIndexedDB("draft", { title: "", body: "" });

Types

`IndexedDBRequestLike`

Minimal structural view of an IDBRequest.

Member	Type	Description
`result`	`Result`	Result available after the `success` event.
`error`	`unknown`	Failure available after the `error` event.

`IndexedDBObjectStoreLike`

Minimal structural view of an IDBObjectStore using out-of-line keys.

Member	Type	Description
`get`	`(key: IDBValidKey) => IndexedDBRequestLike<unknown>`	Read the value stored under `key`.
`put`	`(value: unknown, key: IDBValidKey) => IndexedDBRequestLike<IDBValidKey>`	Store `value` under `key`.
`delete`	`(key: IDBValidKey) => IndexedDBRequestLike<undefined>`	Delete `key`.
`getAllKeys`	`() => IndexedDBRequestLike<IDBValidKey[]>`	List every key.
`clear`	`() => IndexedDBRequestLike<undefined>`	Delete every entry.

`IndexedDBTransactionLike`

Minimal structural view of an IDBTransaction (complete/error/abort events).

Member	Type	Description
`objectStore`	`(name: string) => IndexedDBObjectStoreLike`	Access an object store in the transaction scope.
`error`	`unknown`	Failure available after `error`/`abort`.

`IndexedDBDatabaseLike`

Minimal structural view of an IDBDatabase.

Member	Type	Description
`version`	`number`	Current schema version.
`objectStoreNames`	`{ readonly contains: (name: string) => boolean }`	Names of the existing object stores.
`createObjectStore`	`(name: string) => unknown`	Create an object store; only valid during `upgradeneeded`.
`transaction`	`(store: string, mode: "readonly" \| "readwrite") => IndexedDBTransactionLike`	Start a transaction on one store.
`close`	`() => void`	Close the connection.

`IndexedDBFactoryLike`

Minimal structural view of an IDBFactory; window.indexedDB satisfies it.

Member	Type	Description
`open`	`(name: string, version?: number) => IndexedDBRequestLike<IndexedDBDatabaseLike>`	Open (and possibly upgrade) a database; fires `upgradeneeded`, `success`, `error`.

`IndexedDBKeyvalOptions`

Options for createIndexedDBKeyval.

Member	Type	Description
`database`?	`string`	Database name.
`store`?	`string`	Object store name; created on demand.
`factory`?	`IndexedDBFactoryLike \| null`	IndexedDB implementation.

`IndexedDBKeyval`

Promise-based key-value store returned by createIndexedDBKeyval.

Member	Type	Description
`get`	`(key: IDBValidKey) => Promise<unknown>`	Read a structured-cloned value, or `undefined` when absent.
`set`	`(key: IDBValidKey, value: unknown) => Promise<void>`	Store a structured-cloneable value. Resolves when the transaction commits.
`delete`	`(key: IDBValidKey) => Promise<void>`	Delete a key. Resolves when the transaction commits.
`keys`	`() => Promise<IDBValidKey[]>`	List every key.
`clear`	`() => Promise<void>`	Delete every entry.
`close`	`() => void`	Close the connection; the next operation reopens it.

`IndexedDBFailure`

Failure observed while synchronizing a value with IndexedDB.

Member	Type	Description
`code`	`IndexedDBErrorCode`	Which synchronization step failed.
`key`	`IDBValidKey`	Key involved in the failure.
`cause`	`unknown`	Exact rejection, or the rejected candidate for `"invalid-value"`.

`UseIndexedDBOptions`

Options for useIndexedDB.

Member	Type	Description
`database`?	`string`	Database name.
`store`?	`string`	Object store name; created on demand.
`factory`?	`MaybeRefOrGetter<IndexedDBFactoryLike \| null \| undefined>`	Reactive IndexedDB implementation. `null`/`undefined` keeps the default value, which is also what happens during server rendering.
`validate`?	`(candidate: unknown) => candidate is Value`	Validation hook applied to every loaded value.
`writeDefaults`?	`boolean`	Persist the default value when the key is absent.
`deep`?	`boolean`	Watch nested mutations of object values.
`flush`?	`"pre" \| "post" \| "sync"`	Write timing relative to component rendering.
`onError`?	`(failure: IndexedDBFailure) => void`	Observe failures. Failures never reject out of the composable.

`IndexedDBControls`

Reactive state and controls returned by useIndexedDB.

Member	Type	Description
`state`	`Ref<Value>`	Writable value; assignments and nested mutations are persisted.
`supported`	`Readonly<Ref<boolean>>`	Whether an IndexedDB implementation is attached.
`ready`	`Readonly<Ref<boolean>>`	Whether the stored value for the current key has been loaded.
`error`	`Readonly<ShallowRef<IndexedDBFailure \| undefined>>`	Most recent failure, cleared by the next success.
`refresh`	`() => Promise<void>`	Reload the stored value. Never rejects.
`remove`	`() => Promise<void>`	Delete the key and restore the default value. Never rejects.