@cubux/storage-driver

Simple storage driver abstraction for @cubux/effector-persistent. Persist you effector Store with localStorage/sessionStorage, indexedDB, or implement a custom driver.

Install

npm i @cubux/storage-driver

API

interface StoreDriverSingle<K, V, VOut = V>

Driver interface to read/write data by single item.

Methods

getItem(key: K): Promise<VOut | undefined>

Get value of specific item with the given key.

removeItem(key: K): Promise<void>

Remove item with the given key.

setItem(key: K, value: V): Promise<void>

Store the given value in item with the given key.

interface StoreDriverMapped<K, V, VOut = V>

Driver interface to read/write all items at once.

Methods

getAll(): Promise<ReadonlyMap<K, VOut>>

Get all items.

setAll(items: ReadonlyMap<K, V>): Promise<void>

Replace all stored items with the given new items. That is keys became missing will be removed from storage.

interface StoreDriver<K, V, VOut = V>

Generalized interface covering all specific interfaces above.

createLocalStorageDriver()

Create driver to interact with localStorage-like storage. Actual storage can be set in options, so it could be sessionStorage for example or another compatible alternative.

function createLocalStorageDriver<V>(
  options?: LocalStorageOptions<V>,
): StoreDriver<string, V>

Options LocalStorageOptions<V> to customize driver:

| Option | Type | Default | Description | |---------------|------------------------|-----------------------|--------------------------------------------------------------------------------------| | storage | Storage | window.localStorage | Actual data storage. | | prefix | string | "persistent" | Key prefix in storage to distinguish only related keys. | | serialize | (value: V) => string | JSON.stringify | Custom function to serialize input value to string before putting it into storage. | | unserialize | (data: string) => V | JSON.parse | Custom function to unserialize data read from storage. |

createIndexedDBDriver()

Create driver to interact with indexedDB-like storage. Actual storage can be overridden in options.

function createIndexedDBDriver<K, V, S = V>(
  options: IndexedDBOptions<K, V, S>
): Promise<StoreDriver<K, V>>

Options IndexedDBOptions<K, V, S> to customize driver:

| Option | Type | Default | Description | |---------------|---------------------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | dbName | string | Required | Database name. | | dbVersion | number | 1 | Database version. Probably, this option should internal. | | table | string | Required | Object store name (aka table name). | | indexedDB | IDBFactory | window.indexedDB | Actual indexedDB factory. Default is window.indexedDB. Can be used in tests to mock implementation or to use custom polyfill implementation. | | serialize | (value: V, key: K) => S | (v) => v | Custom function to serialize input value before putting it into DB. | | unserialize | (data: S, key: K) => V | (v) => v | Custom function to unserialize data read from DB. |

createNullDriver()

Create dummy no-op driver. Can be used for example in test environment to omit actual driver. This driver always contains nothing in reads and does nothing on writes.

function createNullDriver<K = any, V = any>(): StoreDriver<K, V, never>