KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #codex #typescript #ai-agents #claude-code #dsh #dsh-plugin #open-source #cli #deepseek-harness #macos #ai-agent

effector-storage

★ 109 Open GitHub ↗

Module for Effector ☄️ to sync stores with `localStorage` (or `sessionStorage`)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# effector-storage

[![Build Status](https://github.com/yumauri/effector-storage/workflows/build/badge.svg)](https://github.com/yumauri/effector-storage/actions?workflow=build)
[![License](https://img.shields.io/github/license/yumauri/effector-storage.svg?color=yellow)](https://raw.githubusercontent.com/yumauri/effector-storage/main/LICENSE)
[![NPM](https://img.shields.io/npm/v/effector-storage.svg)](https://www.npmjs.com/package/effector-storage)
![Made with Love](https://img.shields.io/badge/made%20with-❤-red.svg)

Small module for [Effector](https://github.com/effector/effector) ☄️ to sync stores with different storage backends (local storage, session storage, async storage, IndexedDB, cookies, server-side storage, etc).

## Table of Contents

- [Install](#install)
- [Usage](#usage)
  - [with `localStorage`](#with-localstorage)
  - [with `sessionStorage`](#with-sessionstorage)
  - [with query string](#with-query-string)
  - [with `BroadcastChannel`](#with-broadcastchannel)
  - [extra adapters](#extra-adapters)
- [Usage with domains](#usage-with-domains)
- [Formulae](#formulae)
  - [Units](#units)
  - [Options](#options)
  - [Returns](#returns)
  - [Contracts](#contracts)
  - [Notes](#notes)
- [`createPersist` factory](#createpersist-factory)
  - [Options](#options-1)
  - [Returns](#returns-1)
- [Advanced usage](#advanced-usage)
- [Storage adapters](#storage-adapters)
  - [Synchronous storage adapter example](#synchronous-storage-adapter-example)
  - [Asynchronous storage adapter example](#asynchronous-storage-adapter-example)
  - [Storage with external updates example](#storage-with-external-updates-example)
  - [Update from non-reactive storage](#update-from-non-reactive-storage)
  - [Local storage adapter with values expiration](#local-storage-adapter-with-values-expiration)
  - [Custom `Storage` adapter](#custom-storage-adapter)
- [FAQ](#faq)
  - [Can I persist part of the store?](#can-i-persist-part-of-the-store)
- [TODO](#todo)
- [Sponsored](#sponsored)

## Install

Depending on your package manager

```bash
# using `pnpm` ↓
$ pnpm add effector-storage

# using `yarn` ↓
$ yarn add effector-storage

# using `npm` ↓
$ npm install --save effector-storage
```

## Usage

### with `localStorage`

Docs: [effector-storage/local](https://github.com/yumauri/effector-storage/tree/main/src/local/README.md)

```javascript
import { persist } from 'effector-storage/local'

// persist store `$counter` in `localStorage` with key 'counter'
persist({ store: $counter, key: 'counter' })

// if your storage has a name, you can omit `key` field
persist({ store: $counter })
```

Stores, persisted in `localStorage`, are automatically synced between two (or more) windows/tabs. Also, they are synced between instances, so if you will persist two stores with the same key — each store will receive updates from another one.

ℹ️ If you need just basic bare-minimum functionality, you can take a look at [`effector-localstorage`](https://github.com/ilyalesik/effector-localstorage) library. It has a similar API, and it is much simpler and smaller.

### with `sessionStorage`

Docs: [effector-storage/session](https://github.com/yumauri/effector-storage/tree/main/src/session/README.md)

Same as above, just import `persist` from `'effector-storage/session'`:

```javascript
import { persist } from 'effector-storage/session'
```

Stores, persisted in `sessionStorage`, are synced between instances, but not between different windows/tabs.

### with query string

Docs: [effector-storage/query](https://github.com/yumauri/effector-storage/tree/main/src/query/README.md)

You can _reflect_ a plain string store value in a query string parameter using this adapter. Think of it as synchronizing a store value with a query string parameter.

```javascript
import { persist } from 'effector-storage/query'

// persist store `$id` in query string parameter 'id'
persist({ store: $id, key: 'id' })
```

If two (or more) stores are persisted in query string with the same key — they are synced between themselves.

### with `BroadcastChannel`

Docs: [effector-storage/broadcast](https://github.com/yumauri/effector-storage/tree/main/src/broadcast/README.md)

You can sync stores across different browsing contexts (tabs, windows, workers), just import `persist` from `'effector-storage/broadcast'`:

```javascript
import { persist } from 'effector-storage/broadcast'
```

### extra adapters

You can find a collection of useful adapters in [effector-storage-extras](https://github.com/yumauri/effector-storage-extras). That side repository was created to avoid bloating `effector-storage` with dependencies and adapters that depend on other libraries.

## Usage with domains

You can use `persist` inside Domain's `onCreateStore` hook:

```javascript
import { createDomain } from 'effector'
import { persist } from 'effector-storage/local'

const app = createDomain('app')

// this hook will persist every store, created in domain,
// in `localStorage`, using stores' names as keys
app.onCreateStore((store) => persist({ store }))

const $store = app.createStore(0, { name: 'store' })
```

## Formulae

```javascript
import { persist } from 'effector-storage/<adapter>'
```

- `persist({ store, ...options }): Subscription`
- `persist({ source, target, ...options }): Subscription`

### Units

In order to synchronize _something_, you need to specify Effector units. Depending on requirements, you may want to use the `store` parameter, or `source` and `target` parameters:

- `store` ([_Store_]): Store to synchronize with local/session storage.
- `source` ([_Event_] | [_Effect_] | [_Store_]): Source unit, which updates will be sent to local/session storage.
- `target` ([_Event_] | [_Effect_] | [_Store_]): Target unit, which will receive updates from local/session storage (as well as initial value). Must be different than `source` to avoid circular updates — `source` updates are passed directly to `target`.

### Options

> [!NOTE]
> These are common options, valid for any adapter. However, individual storage adapters may define and use their own specific options. Please reference the documentation for your exact adapter for more information.

- `key`? ([_string_]): Key for local/session storage, to store value in. If omitted — `store` name is used. **Note!** If `key` is not specified, `store` _must_ have a `name`! You can use `'effector/babel-plugin'` to have those names automatically.
- `keyPrefix`? ([_string_]): Prefix, used in adapter, to be concatenated to `key`. By default = `''`.
- `clock`? ([_Event_] | [_Effect_] | [_Store_]): Unit, if passed – then value from `store`/`source` will be stored in the storage only upon its trigger.
- `pickup`? ([_Event_] | [_Effect_] | [_Store_], or array of these units): Unit (or array of units), which you can specify to update `store` value from storage. This unit can also set a special context for adapter. **Note!** When you add `pickup`, `persist` _will not_ get initial value from storage automatically!
- `context`? ([_Event_] | [_Effect_] | [_Store_]): Unit, which can set a special context for adapter.
- `contract`? ([_Contract_]): Rule to statically validate data from storage.
- `done`? ([_Event_] | [_Effect_] | [_Store_]): Unit, which will be triggered on each successful read or write to/from storage. 
 Payload structure:
 - `key` ([_string_]): Same `key` as above.
 - `keyPrefix` ([_string_]): Prefix, used in adapter, to be concatenated to `key`. By default = `''`.
 - `operation` (_`'set'`_ | _`'get'`_): Type of operation, read (get) or write (set).
 - `value` (_State_): Value set to `store` or got from `store`.
- `fail`? ([_Event_] | [_Effect_] | [_Store_]): Unit, which will be triggered in case of any error (serialization/deserialization error, storage is full and so on). **Note!** If `fail` unit is not specified, any errors will be printed using `console.error(Error)`. 
 Payload structure:
 - `key` ([_string_]): Same `key` as above.
 - `keyPrefix` ([_string_]): Prefix, used in adapter, to be concatenated to `key`. By default = `''`.
 - `operation` (_`'set'`_ | _`'get'`_ | _`'validate'`_): Type of operation, read (get), write (set) or validation against contract (validate).
 - `error` ([_Error_]): Error instance
 - `value`? (_any_): In case of _'set'_ operation — value from `store`. In case of _'get'_ operation could contain raw value from storage or could be empty.
- `finally`? ([_Event_] | [_Effect_] | [_Store_]): Unit, which will be triggered either in case of success or error. 
 Payload structure:
 - `key` ([_string_]): Same `key` as above.
 - `keyPrefix` ([_string_]): Prefix, used in adapter, to be concatenated to `key`. By default = `''`.
 - `operation` (_`'set'`_ | _`'get'`_ | _`'validate'`_): Type of operation, read (get), write (set) or validation against contract (validate).
 - `status` (_`'done'`_ | _`'fail'`_): Operation status.
 - `error`? ([_Error_]): Error instance, in case of error.
 - `value`? (_any_): Value, if it exists (see above).

### Returns

- ([_Subscription_]): You can use this subscription to remove store association with storage, if you don't need them to be synced anymore. It is a function.

### Contracts

You can use `contract` option to validate data from storage. Contract has the following type definition:

```typescript
export type Contract<Data> =
 | ((raw: unknown) => raw is Data)
 | StandardSchemaV1<unknown, Data>
 | {
 isData: (raw: unknown) => raw is Data
 getErrorMessages: (raw: unknown) => string[]
 }
```

So, it could be simple type guard function in trivial use cases, a [Standard Schema](https://standardschema.dev/schema) compatible validator, or more complex object with `isData` type guard and `getErrorMessages` function, which returns array of error messages. This format is fully compatible with [Farfetched contracts](https://withease.effector.dev/protocols/contract.html), so you can use any adapter from Farfetched ([runtypes](https://ff.effector.dev/api/contracts/runtypes.html), [zod](https://ff.effector.dev/api/contracts/zod.html), [io-ts](https://ff.effector.dev/api/contracts/io-ts.html), [superstruct](https://ff.effector.dev/api/contracts/superstruct.html), [typed-contracts](https://ff.effector.dev/api/contracts/typed-contracts.html), [valibot](https://ff.effector.dev/api/contracts/valibot.html)) with `persist` and `contract` option:

```typescript
// simple type guard
persist({
  store: $counter,
  key: 'counter',
  contract: (raw): raw is number => typeof raw === 'number',
})
```

```typescript
// complex contract with Farfetched adapter
import * as s from 'superstruct'
import { superstructContract } from '@farfetched/superstruct'

const Asteroid = s.type({
  type: s.literal('asteroid'),
  mass: s.number(),
})

persist({
  store: $asteroid,
  key: 'asteroid',
  contract: superstructContract(Asteroid),
})
```

There are two gotchas with contracts:

1. From `effector-storage` point of view, it is absolutely normal when there is no persisted value in storage yet. So, `undefined` is _always valid_, even if a contract does not explicitly allow it.
2. `effector-storage` does not prevent persisting invalid data to the storage, but it will validate it nonetheless, after persisting, so, if you write invalid data to the storage, `fail` will be triggered, but data will be persisted.

### Notes

Without specifying the `pickup` property, calling `persist` will immediately call the adapter to get the initial value. In case of synchronous storage (like `localStorage` or `sessionStorage`), this action will synchronously set store value and call `done`/`fail`/`finally` right away. You should take that into account if you add logic based on `done`; for example, place `persist` after that logic (see issue [#38](https://github.com/yumauri/effector-storage/issues/38) for more details).

You can modify adapter to be asynchronous to mitigate this behavior with [`async`](https://github.com/yumauri/effector-storage/tree/main/src/tools/README.md#async) function.

## `createPersist` factory

In rare cases you might want to use `createPersist` factory. It allows you to specify some adapter options, like `keyPrefix`.

```javascript
import { createPersist } from 'effector-storage/local'

const persist = createPersist({
  keyPrefix: 'app/',
})

// ---8<---

persist({
  store: $store1,
  key: 'store1', // localStorage key will be `app/store1`
})
persist({
  store: $store2,
  key: 'store2', // localStorage key will be `app/store2`
})
```

### Options

- `pickup`? ([_Event_] | [_Effect_] | [_Store_], or array of these units): Unit (or array of units), which you can specify to update `store` value from storage. This unit can also set a special context for adapter. **Note!** When you add `pickup`, `persist` _will not_ get initial value from storage automatically!
- `context`? ([_Event_] | [_Effect_] | [_Store_]): Unit, which can set a special context for adapter.
- `keyPrefix`? ([_string_]): Key prefix for adapter. It will be concatenated with any `key`, given to returned `persist` function.
- `contract`? ([_Contract_]): Rule to statically validate data from storage.

### Returns

- Custom `persist` function, with predefined adapter options.

## Advanced usage

`effector-storage` consists of a _core_ module and _adapter_ modules.

The core module itself does nothing with actual storage; it just connects Effector units to the storage adapter using a couple of _Effects_ and a bunch of connections.

The storage adapter _gets_ and _sets_ values, and also can asynchronously emit values on storage updates.

```javascript
import { persist } from 'effector-storage'
```

Core function `persist` accepts all **common** options, as `persist` functions from sub-modules, plus additional one:

- `adapter` (_StorageAdapter_ | _StorageAdapterFactory_): Storage adapter or storage adapter factory to use.

## Storage adapters

Adapter is a function that is called by the core `persist` function and has the following interface:

```typescript
interface StorageAdapter {
 <State>(
 key: string,
 update: (raw?: any) => void
 ): {
 get(raw?: any, ctx?: any): State | undefined | Promise<State | undefined>
 set(value: State, ctx?: any): void | Promise<void>
 }
 keyArea?: any
 noop?: boolean
}
```

#### Arguments

- `key` ([_string_]): Unique key to distinguish values in storage.
- `update` ([_Function_]): Function that can be called to get a value from storage. In fact, this is an `Effect` with the `get` function as a handler. In other words, any argument passed to `update` will end up as an argument in `get`.

#### Returns

- `{ get, set }` (_{ Function, Function }_): Getter from and setter to storage. These functions are used as Effect handlers and can be sync or async. Also, you do not have to catch exceptions and errors inside those functions; Effects will do that for you. 
 As mentioned above, calling `update` triggers `get` with the same argument. So you can handle cases when `get` is called during initial `persist` execution (without arguments), or after an external update. Check out [example below](#storage-with-external-updates-example). 
 Also, getter and setter both accept an optional _context_ as a second argument; it can be any value. This context can be useful if an adapter depends on some external environment; for example, it can contain _Request_ and _Response_ from Express middleware to get/set cookies from/to. (TODO: isomorphic cookies adapter example).

#### keyArea

Adapter function can have static field `keyArea`; this can be any value of any type, but it should be unique for the _keys namespace_. For example, two local storage adapters can have different settings, but both of them use the same _storage area_ — `localStorage`. So, different stores persisted in local storage with the same key (but possibly with different adapters) should be synced. That is what `keyArea` is responsible for. Value of that field is used as a key in the cache `Map`. 
If it is omitted, the adapter instance is used instead.

#### noop

Marks adapter as "no-op" for [`either`](https://github.com/yumauri/effector-storage/tree/main/src/tools/README.md#either) function.

### Synchronous storage adapter example

For example, a simplified _localStorage_ adapter might look like this. This is an over-simplified example; do not do that in real code. There is no serialization or deserialization, and no checks for edge cases. This is just to show the idea.

```javascript
import { createStore } from 'effector'
import { persist } from 'effector-storage'

const adapter = (key) => ({
  get: () => localStorage.getItem(key),
  set: (value) => localStorage.setItem(key, value),
})

const store = createStore('', { name: 'store' })
persist({ store, adapter }) // <- use adapter
```

### Asynchronous storage adapter example

Using asynchronous storage is just as simple. Once again, this is just a bare example, without serialization or edge-case checks. If you need to use React Native Async Storage, try the [@effector-storage/react-native-async-storage](https://github.com/yumauri/effector-storage-extras/tree/main/packages/react-native-async-storage) adapter instead.

```javascript
import AsyncStorage from '@react-native-async-storage/async-storage'
import { createStore } from 'effector'
import { persist } from 'effector-storage'

const adapter = (key) => ({
  get: async () => AsyncStorage.getItem(key),
  set: async (value) => AsyncStorage.setItem(key, value),
})

const store = createStore('', { name: '@store' })
persist({ store, adapter }) // <- use adapter
```

### Storage with external updates example

If your storage can be updated from an _external source_, then the adapter needs a way to inform/update the connected store. That is where you will need a second `update` argument.

```javascript
import { createStore } from 'effector'
import { persist } from 'effector-storage'

const adapter = (key, update) => {
  addEventListener('storage', (event) => {
    if (event.key === key) {
      // kick update
      // this will call `get` function from below ↓
      // wrapped in Effect, to handle any errors
      update(event.newValue)
    }
  })

return {
    // `get` function will receive `newValue` argument
    // from `update`, called above ↑
    get: (newValue) => newValue || localStorage.getItem(key),
    set: (value) => localStorage.setItem(key, value),
  }
}

const store = createStore('', { name: 'store' })
persist({ store, adapter }) // <- use adapter
```

### Update from non-reactive storage

If your storage can be updated from an _external source_ and does not have any events to react to, but you are still able to know about updates somehow.

You can use optional `pickup` parameter to specify unit to trigger update (keep in mind, that when you add `pickup`, `persist` _will not_ get initial value from storage automatically):

```javascript
import { createEvent, createStore } from 'effector'
import { persist } from 'effector-storage/session'

// event, which will be used to trigger update
const pickup = createEvent()

const store = createStore('', { name: 'store' })
persist({ store, pickup }) // <- set `pickup` parameter

// --8<--

// when you are sure, that storage was updated,
// and you need to update `store` from storage with new value
pickup()
```

Another option, if you have your own adapter, you can add this feature right into it:

```javascript
import { createEvent, createStore } from 'effector'
import { persist } from 'effector-storage'

// event, which will be used in adapter to react to
const pickup = createEvent()

const adapter = (key, update) => {
  // if `pickup` event was triggered -> call an `update` function
  // this will call `get` function from below ↓
  // wrapped in Effect, to handle any errors
  pickup.watch(update)
  return {
    get: () => localStorage.getItem(key),
    set: (value) => localStorage.setItem(key, value),
  }
}

const store = createStore('', { name: 'store' })
persist({ store, adapter }) // <- use your adapter

// --8<--

// when you are sure, that storage was updated,
// and you need to force update `store` from storage with new value
pickup()
```

### Local storage adapter with values expiration

> I want to sync my store with `localStorage`, but I need smart synchronization, not a dumb one. Each storage update should contain the last write timestamp. And when reading the value, I need to check if it has expired and fill the store with the default value in that case.

You can implement it with custom adapter, something like this:

```javascript
import { createStore } from 'effector'
import { persist } from 'effector-storage'

const adapter = (timeout) => (key) => ({
 get() {
 const item = localStorage.getItem(key)
 if (item === null) return // no value in localStorage
 const { time, value } = JSON.parse(item)
 if (time + timeout * 1000 < Date.now()) return // value has expired
 return value
 },

set(value) {
    localStorage.setItem(key, JSON.stringify({ time: Date.now(), value }))
  },
})

const store = createStore('', { name: 'store' })

// use adapter with timeout = 1 hour ↓↓↓
persist({ store, adapter: adapter(3600) })
```

### Custom `Storage` adapter

Both `'effector-storage/local'` and `'effector-storage/session'` use a common `storage` adapter factory. If you want to use _other storage_ that implements the [`Storage`](https://developer.mozilla.org/en-US/docs/Web/API/Storage) interface (in fact, synchronous `getItem` and `setItem` methods are enough), you can use this factory.

```javascript
import { storage } from 'effector-storage/storage'
```

```javascript
adapter = storage(options)
```

#### Options

- `storage` (_Storage_): Storage to communicate with.
- `sync`? ([_boolean_] | 'force'): Add [`'storage'`] event listener or no. Default = `false`. In case of `'force'` value adapter will always read new value from _Storage_, instead of event.
- `serialize`? (_(value: any) => string_): Custom serialize function. Default = `JSON.stringify`
- `deserialize`? (_(value: string) => any_): Custom deserialize function. Default = `JSON.parse`

#### Returns

- (StorageAdapter): Storage adapter, which can be used with the core `persist` function.

## FAQ

### Can I persist part of the store?

The issue here is that it is hardly possible to create a universal mapping to/from storage for only part of a store within the library implementation. But with the `persist` form that uses `source`/`target`, and a little help from the Effector API, you can do it:

```javascript
import { persist } from 'effector-storage/local'

const setX = createEvent()
const setY = createEvent()
const $coords = createStore({ x: 123, y: 321 })
  .on(setX, ({ y }, x) => ({ x, y }))
  .on(setY, ({ x }, y) => ({ x, y }))

// persist X coordinate in `localStorage` with key 'x'
persist({
  source: $coords.map(({ x }) => x),
  target: setX,
  key: 'x',
})

// persist Y coordinate in `localStorage` with key 'y'
persist({
  source: $coords.map(({ y }) => y),
  target: setY,
  key: 'y',
})
```

⚠️ **BIG WARNING!** 
Use this approach with caution, beware of infinite circular updates. To avoid them, persist _only plain values_ in storage. So, mapped store in `source` will not trigger update, if object in original store has changed. Also, you can take a look at [`updateFilter` option](https://effector.dev/docs/api/effector/createStore).

## TODO

- [x] [localStorage] support (docs: [effector-storage/local](https://github.com/yumauri/effector-storage/tree/main/src/local/README.md))
- [x] [sessionStorage] support (docs: [effector-storage/session](https://github.com/yumauri/effector-storage/tree/main/src/session/README.md))
- [x] [query string](https://developer.mozilla.org/en-US/docs/Web/API/Location/search) support (docs: [effector-storage/query](https://github.com/yumauri/effector-storage/tree/main/src/query/README.md))
- [x] [BroadcastChannel] support (docs: [effector-storage/broadcast](https://github.com/yumauri/effector-storage/tree/main/src/broadcast/README.md))
- [x] [AsyncStorage] support (extras: [@effector-storage/react-native-async-storage](https://github.com/yumauri/effector-storage-extras/tree/main/packages/react-native-async-storage))
- [x] [EncryptedStorage] support (extras: [@effector-storage/react-native-encrypted-storage](https://github.com/yumauri/effector-storage-extras/tree/main/packages/react-native-encrypted-storage))
- [x] [IndexedDB] support (extras: [@effector-storage/idb-keyval](https://github.com/yumauri/effector-storage-extras/tree/main/packages/idb-keyval))
- [ ] [Cookies] support
- [ ] you-name-it support

## Sponsored

[<img src="https://setplex.com/wp-content/uploads/2025/03/logo.svg" alt="Setplex OTT Platform" width="236">](https://setplex.com/en/)

[Setplex OTT Platform](https://setplex.com/en/)

[localstorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
[sessionstorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage
[`'storage'`]: https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent
[indexeddb]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
[broadcastchannel]: https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
[asyncstorage]: https://react-native-async-storage.github.io/async-storage/
[encryptedstorage]: https://github.com/emeraldsanto/react-native-encrypted-storage
[cookies]: https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie
[_subscription_]: https://effector.dev/docs/glossary#subscription
[_effect_]: https://effector.dev/docs/api/effector/effect
[_event_]: https://effector.dev/docs/api/effector/event
[_store_]: https://effector.dev/docs/api/effector/store
[_string_]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
[_function_]: https://developer.mozilla.org/en-US/docs/Glossary/Function
[_boolean_]: https://developer.mozilla.org/en-US/docs/Glossary/Boolean
[_error_]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
[_Contract_]: #contracts

effector-storage

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README