@reatom/persist

An abstract persistence layer for your reactive state. Supports storage mocking, custom serializers/deserializers, migrations and storage subscriptions.

Check out @reatom/persist-web-storage for adapters for localStorage and sessionStorage.

Installation

npm i @reatom/persist

Usage

First of all, you need a persistence adapter. Every adapter is an operator which you can apply to an atom to persist its value. Most likely, the adapter you want is already implemented in withLocalStorage from @reatom/persist-web-storage. reatomPersist function can be used to create a custom persist adapter.

Creating an adapter

To create a custom persist adapter, implement the following interface:

export const reatomPersist = (
  storage: PersistStorage,
): WithPersist & {
  storageAtom: AtomMut<PersistStorage>
}

export interface WithPersist {
  <T extends Atom>(
    options: string | WithPersistOptions<AtomState<T>>
  ): (anAtom: T) => T
}

export interface PersistStorage {
  name: string
  get(ctx: Ctx, key: string): PersistRecord | null
  set(ctx: Ctx, key: string, rec: PersistRecord): void
  clear?(ctx: Ctx, key: string): void
  subscribe?(ctx: Ctx, key: string, callback: Fn<[]>): Unsubscribe
}

export interface PersistRecord<T = unknown> {
  data: T
  id: number
  timestamp: number
  version: number
  to: number
}

See createMemStorage for an example of PersistStorage implementation.

Adapter options

Every adapter accepts the following set of options. Passing a string is identical to only passing the key option.

export interface WithPersistOptions<T> {
  /**
   * Key of the storage record.
   */
  key: string
  /**
   * Custom snapshot serializer.
   */
  toSnapshot?: Fn<[ctx: Ctx, state: T], unknown>
  /**
   * Custom snapshot deserializer.
   */
  fromSnapshot?: Fn<[ctx: Ctx, snapshot: unknown, state?: T], T>
  /**
   * A callback to call if the version of a stored snapshot is older than `version` option.
   */
  migration?: Fn<[ctx: Ctx, persistRecord: PersistRecord], T>
  /**
   * Determines whether the atom is updated on storage updates.
   * @defaultValue true
   */
  subscribe?: boolean
  /**
   * Number of milliseconds from the snapshot creation time after which it will be deleted.
   * @defaultValue MAX_SAFE_TIMEOUT
   */
  time?: number
  /**
   * Version of the stored snapshot. Triggers `migration`.
   * @defaultValue 0
   */
  version?: number
}

Testing

Every persist adapter has the storageAtom atom which allows you to mock an adapter's storage when testing persisted atoms. createMemStorage function can be used to create such mocked storage.

// feature.ts
import { atom } from '@reatom/framework'
import { withLocalStorage } from '@reatom/persist-web-storage'

export const tokenAtom = atom('', 'tokenAtom').pipe(withLocalStorage('token'))

// feature.test.ts
import { test } from 'uvu'
import * as assert from 'uvu/assert'
import { createTestCtx } from '@reatom/testing'
import { createMemStorage } from '@reatom/persist'
import { withLocalStorage } from '@reatom/persist-web-storage'
import { tokenAtom } from './feature'

test('token', () => {
  const ctx = createTestCtx()
  const mockStorage = createMemStorage({ token: '123' })
  withLocalStorage.storageAtom(ctx, mockStorage)

  assert.is(ctx.get(tokenAtom), '123')
})

test.run()

SSR

A fully-featured SSR example with Next.js can be found here.

The example below shows how simple it is to implement an SSR adapter. To do so, create an in-memory storage with createMemStorage, use it to persist your atoms, and populate it before rendering the app.

// src/ssr.ts
import { createMemStorage, reatomPersist } from '@reatom/persist'

const ssrStorage = createMemStorage({ name: 'ssr', subscribe: false })
export const { snapshotAtom } = ssrStorage
export const withSsr = reatomPersist(ssrStorage)

// src/features/goods/model.ts
import { atom } from '@reatom/core'
import { withSsr } from 'src/ssr'

export const filtersAtom = atom('').pipe(withSsr('goods/filters'))

export const listAtom = atom(new Map()).pipe(
  withSsr({
    key: 'goods/list',
    toSnapshot: (ctx, list) => [...list],
    fromSnapshot: (ctx, snapshot) => new Map(snapshot),
  }),
)

// src/root.ts
import { createCtx } from '@reatom/core'
import { snapshotAtom } from 'src/ssr'

export const ssrHandler = async () => {
  const ctx = createCtx()

  await doAsyncStuffToFillTheState(ctx)

  const snapshot = ctx.get(snapshotAtom)

  return { snapshot }
}

export const render = ({ snapshot }) => {
  export const ctx = createCtx()
  snapshotAtom(ctx, snapshot)

  runFeaturesAndRenderTheApp(ctx)
}