@cubux/effector-persistent

Persist data in effector store.

import { createStore } from "effector";
import { withPersistent } from "@cubux/effector-persistent";
import { createLocalStorageDriver } from "@cubux/storage-driver";

const $accessToken = withPersistent(
  createStore(""),
  createLocalStorageDriver(),
  "accessToken"
);

Install

npm i @cubux/effector-persistent

API

See also @cubux/storage-driver. It supports localStorage/sessionStorage and indexedDB.

withPersistent()

Register persistent data handling for the given store with the given driver. Data from store will be stored in driver with the given key. Function returns input store, so it can be used inline.

Type of store can be Store only when wakeUp options is defined. Otherwise a StoreWritable is needed.

function withPersistent<Key, Value, Serialized = Value>(
  store:    Store<Value>
          | StoreWritable<Value>,
  driver:   StoreDriverSingle<Key, Serialized>
          | Promise<StoreDriverSingle<Key, Serialized>>,
  key:      Key,
  options?: WithPersistentOptions<Value, Value, Serialized>
): typeof store

Example:

import { createStore } from "effector";
import { withPersistent } from "@cubux/effector-persistent";
import { createLocalStorageDriver } from "@cubux/storage-driver";

const lsDriver = createLocalStorageDriver();
const $storeA = withPersistent(createStore(0), lsDriver, "keyA");
const $storeB = withPersistent(createStore(""), lsDriver, "keyB");

In the example above $storeA and $storeB will use localStorage for persistent data with keys "persistent:keyA" and "persistent:keyB" respectively.

withPersistentMap()

Register persistent data handling for the given ReadonlyMap store with the given driver. Data from store will be stored in driver with corresponding keys from ReadonlyMap. Function returns input store, so it can be used inline.

Type of store can be Store only when wakeUp options is defined. Otherwise a StoreWritable is needed.

function withPersistentMap<Key, Value, Serialized = Value>(
  store:    Store<ReadonlyMap<Key, Value>>
          | StoreWritable<ReadonlyMap<Key, Value>>,
  driver:   StoreDriver<Key, Serialized>
          | Promise<StoreDriver<Key, Serialized>>,
  options?: WithPersistentOptions<ReadonlyMap<Key, Value>, Value, Serialized>
): typeof store

Under the hood on every store change it will detect changes in underlying Map entries and will send to driver only those was changed.

Notice: Serialization when used with options will be applied to individual values Value rather than to whole Map<Key, Value>.

Example:

import { createStore } from "effector";
import { withPersistentMap } from "@cubux/effector-persistent";
import { createLocalStorageDriver } from "@cubux/storage-driver";

const $storeMap = withPersistentMap(
  createStore<ReadonlyMap<string, number>>(new Map()),
  createLocalStorageDriver()
);

In the example above $storeMap will use localStorage for persistent data with keys starting with "persistent:", so every entry from ReadonlyMap will have its own row in localStorage.

interface WithPersistentFlushEvent

A payload for flush events.

| Property | Type | Description | |----------|----------|-----------------------------------| | id | symbol | Identifier for current flush flow |

interface WithPersistentFlushFailEvent

A payload for flush events.

This interface extends WithPersistentFlushEvent with the following additional properties:

| Property | Type | Description | |----------|-----------|-----------------------| | error | unknown | Reason of the failure |

interface WithPersistentOptions

Common options for persistent storage.

interface WithPersistentOptions<
  State = any,
  Value = State,
  Serialized = Value
>

| Options | Type | Default | Description | |------------------|-------------------------------------------------------------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | flushDelay | number | undefined | Debounce subsequent store updates and flush only after latest change. If set to undefined (default), no debounce will be used, so every store update will be flushed to driver. | | onFlushStart | EventCallable<WithPersistentFlushEvent> | undefined | An Event to trigger before flushing to driver. An id in payload can be used in all the rest "flush" events to identify the flow when it's needed. | | onFlushDone | EventCallable<WithPersistentFlushEvent> | undefined | An Event to trigger when flush succeeds. An id in payload refers to id from appropriate onFlushStart payload. | | onFlushFail | EventCallable<WithPersistentFlushFailEvent> | undefined | An Event to trigger when flush fails. An id in payload refers to id from appropriate onFlushStart payload. | | onFlushFinally | EventCallable<WithPersistentFlushEvent> | undefined | An Event to trigger before flushing to driver. This al always triggering after either onFlushDone or onFlushFail. An id in payload refers to id from appropriate onFlushStart payload. | | readOnly | EventCallable<boolean> | undefined | A filter Store to disable writes to Driver. | | wakeUp | StoreWritable<State> | ((state: State) => void) | undefined | Alternative target which will receive initial state read from driver on initialization. When undefined, the source StoreWritable will be used. | | onBeforeWakeUp | () => void | undefined | A callback to be called before "wake up" prodecure. | | onAfterWakeUp | () => void | undefined | A callback to be called after "wake up" prodecure. | | serialize | (input: Value) => Serialized | Promise<Serialized> | undefined | Serialization before writing data to driver. | | unserialize | (output: Serialized) => Value | Promise<Value> | undefined | Unserialization after reading data from driver. |

Helper API

flushDelayed()

Setup delayed flushes from source unit to target unit with whe given debounce interval.

Prefer patronum debounce() instead.

function flushDelayed<T>(options: Options<T>): (() => void);

It takes options described below and returns a function to stop watching and interrupt planned flush.

| Options | Type | Default | Description | |--------------|---------------------------------------------------|--------------|---------------------------------------------------------------------------| | source | Store<T> | Event<T> | Required | Source unit to watch | | target | (payload: T) => void | Required | Receiver to flush data to | | flushDelay | number | Store<number> | 1000 | Debounce timeout to await before flush | | filter | Store<boolean> | undefined | When specified, flushes will work only when this filter Store is true |

Actual flush target will be called only after source unit will stop triggering for at least duration in flushDelay. That is while source is keeping triggering continuous within this duration, flush target will never be called.

When flushDelay is Store<number>, it's value will take effect only on next source update.

When filter is used, it will abort current planned flush, when its value becomes false.