Stores

A store is where zapo persists everything a session needs to survive a restart: pairing credentials, Signal protocol state, app-state collections, and optionally your message/thread/contact archive. You build one with createStore and pass it to the client.

import { createStore } from 'zapo-js'
import { createSqliteStore } from '@zapo-js/store-sqlite'

const store = createStore({
  backends: {
    sqlite: createSqliteStore({ path: '.auth/state.sqlite', driver: 'auto' })
  },
  providers: {
    auth: 'sqlite',
    signal: 'sqlite',
    preKey: 'sqlite',
    session: 'sqlite',
    identity: 'sqlite',
    senderKey: 'sqlite',
    appState: 'sqlite',
    privacyToken: 'sqlite',
    messages: 'sqlite',
    threads: 'sqlite',
    contacts: 'sqlite'
  }
})

The model

createStore separates backends (where data lives) from providers (which backend each domain uses). This lets you mix backends — e.g. keep hot signal state in Redis while archiving messages in Postgres.

createStore({
  backends: {
    redis: createRedisStore({ redis }),
    postgres: createPostgresStore({ pool })
  },
  providers: {
    auth: 'redis',
    signal: 'redis',
    preKey: 'redis',
    session: 'redis',
    identity: 'redis',
    senderKey: 'redis',
    appState: 'redis',
    privacyToken: 'redis',
    messages: 'postgres',
    threads: 'postgres',
    contacts: 'postgres'
  }
})

Providers are required when you set `backends`

As soon as backends contains at least one entry, every persistence domain must be assigned explicitly in providers. The required domains are auth, signal, preKey, session, identity, senderKey, appState, privacyToken, messages, threads, and contacts. Both the TypeScript types and a runtime check enforce this — createStore throws and lists the missing providers.* keys when any are omitted. Three values are valid for each domain:

A backend name from backends (e.g. 'sqlite') — persist that domain there.
'memory' — keep that domain in the in-tree memory provider for this run.
'none' — only valid for the optional archive domains (messages, threads, contacts); skips the domain entirely.

This guard exists because partial coverage is almost always a bug. If you persist only auth and let Signal state, app-state, or the mailbox fall back to memory, the device pairs once and then loses its protocol state on every restart. Pick 'memory' deliberately when that is what you want.

createStore({
  backends: { sqlite: createSqliteStore({ path: '.auth/state.sqlite' }) },
  providers: {
    auth: 'sqlite',
    signal: 'sqlite',
    preKey: 'sqlite',
    session: 'sqlite',
    identity: 'sqlite',
    senderKey: 'sqlite',
    appState: 'sqlite',
    privacyToken: 'sqlite',
    messages: 'none',  // skip the message archive
    threads: 'none',
    contacts: 'none'
  }
})

When backends is empty or omitted, every domain falls back to memory (mailbox domains to 'none') — useful for tests, but the device re-pairs on every restart.

Persisted domains

These hold the state required to keep a session alive. Back them with a durable backend in production.

Domain	Holds
`auth`	Pairing credentials and device identity. Persist this.
`signal`	Signal sessions (umbrella over the sub-stores below).
`preKey`	Signal pre-keys.
`session`	Signal sessions.
`identity`	Signal identity keys.
`senderKey`	Group sender keys.
`appState`	App-state collections (mute, pin, read, archive, …).
`privacyToken`	Trusted-contact / privacy tokens.

Optional archive domains

These accept 'none' to disable persistence entirely:

Domain	Holds
`messages`	Message archive (`B \| 'memory' \| 'none'`).
`threads`	Thread metadata.
`contacts`	Contact directory.

Cache domains

Configured under cacheProviders and default to bounded memory with TTLs:

Domain	Holds	Default
`retry`	Outbound message retry queue.	`'memory'`
`groupMetadata`	Group metadata cache.	`'memory'`
`chatMetadata`	Protocol-derived per-chat state (disappearing-message settings). Read on every 1:1 send to stamp `contextInfo`; rebuilt from history sync, `EPHEMERAL_SETTING` messages and incoming `ContextInfo`, so losing it costs freshness rather than data.	`'memory'`
`deviceList`	Device list cache.	`'memory'`
`messageSecret`	Message-secret cache for addons.	`'memory'`

createStore({
  backends: { sqlite },
  providers: { /* ... */ },
  cacheProviders: { groupMetadata: 'sqlite', deviceList: 'sqlite' },
  memory: {
    cacheTtlMs: { groupMetadataMs: 600_000, deviceListMs: 600_000 }
  }
})

Each backend evicts expired entries differently: memory runs an in-process sweep, Redis and MongoDB use native TTL, SQLite filters on read, and PostgreSQL/MySQL require an opt-in poller (result.startCleanup(sessionId)) or cache tables grow forever. See Cache expiry and cleanup for the per-backend matrix.

Read-through cache layer

When a hot signal domain points at a persistent backend, every send/recv round-trip pays the backend’s latency to fetch the same peer’s session, identity, or sender key. The cacheLayer option wraps the backend store with a bounded-LRU L1 (the in-tree memory provider) so repeated reads of the same peer skip the backend, while writes stay write-through so the backend remains authoritative. Four hot domains can be cached:

Domain	Strategy
`session`	Signal Double-Ratchet sessions. Read-through + write-through.
`identity`	Remote identity keys. Read-through + write-through.
`senderKey`	Per-(group, sender) sender keys. Read-through + write-through.
`privacyToken`	Trusted-contact tokens. Read-through + invalidate-on-write (the backend merges partial fields on upsert).

All flags default to false. A flag is a no-op unless that domain resolves to a real backend in providers — caching 'memory' or 'none' in front of itself buys nothing and is skipped.

createStore({
  backends: { postgres, redis },
  providers: {
    auth: 'postgres',
    signal: 'postgres',
    preKey: 'postgres',
    session: 'postgres',
    identity: 'postgres',
    senderKey: 'postgres',
    appState: 'postgres',
    privacyToken: 'postgres',
    messages: 'postgres',
    threads: 'postgres',
    contacts: 'postgres'
  },
  cacheLayer: {
    session: true,
    identity: true,
    senderKey: true,
    privacyToken: true,
    limits: {
      session: 10_000,
      identity: 10_000,
      senderKey: 5_000,
      privacyToken: 5_000
    }
  }
})

limits caps per-domain entry counts; once exceeded, the L1 evicts LRU. When unset, each domain defaults to the matching memory-provider cap.

When to enable it

Turn it on when your backend is a network hop (Redis, Postgres, MySQL, MongoDB) and you send or receive at a rate where the same peers repeat — typical for bots, group fan-out, and multi-tenant gateways. With a local SQLite backend the wins are smaller; measure before flipping it on.

Single-writer assumption

The L1 is per-process and has no cross-process invalidation channel. Enable cacheLayer only when a single process owns a given sessionId’s backend rows — the library’s standard connection model. Different sessions sharing one backend are fine; the same session opened from two processes is not.

Do not enable cacheLayer when multiple processes share one backend for the same sessionId. Another process’s writes would leave this cache stale and corrupt the Signal ratchet.

Why not every domain?

signal, appState, and preKey are deliberately excluded:

signal — the per-send registration read is already memoized inside the signal lock; a second cache adds nothing.
appState — the sync client already caches collection state for the sync-context lifetime, the only scope where reads both repeat and stay coherent.
preKey — one-time pre-keys are read exactly once then consumed. Serving a consumed key from a stale cache would reuse it and break forward secrecy.

Backends

SQLite

@zapo-js/store-sqlite — local, single-process.

PostgreSQL

@zapo-js/store-postgres — distributed, relational.

MySQL

@zapo-js/store-mysql — distributed, relational.

Redis

@zapo-js/store-redis — cache + persistence.

MongoDB

@zapo-js/store-mongo — document store.

Memory

Built in. Great for tests; does not survive a restart.

See the stores reference for each backend’s config options.

Memory-only (tests)

For quick experiments or tests, omit backends entirely — every domain falls back to memory:

const store = createStore({})
const client = new WaClient({ store, sessionId: 'test' }, logger)

A memory-only store loses all credentials on restart, so you re-pair every boot. Use a durable backend for anything long-lived.

Custom backends

The backend contract is WaStoreBackend<S, C>, parametrized by the persistence domains (S extends WaStoreDomain) and cache domains (C extends WaCacheDomain) the bundle actually implements. Both default to the full matrix, so a bare WaStoreBackend still means every domain — that’s what every in-tree @zapo-js/store-* package ships. To cover part of the matrix, name the domains you implement:

import type { WaStoreBackend } from 'zapo-js'

const vault = {
  stores: { auth: (sessionId: string) => new MyAuthStore(sessionId) },
  caches: {}
} satisfies WaStoreBackend<'auth', never>

createStore({
  backends: { vault, sqlite },
  providers: {
    auth: 'vault',       // ok — vault declares 'auth'
    signal: 'sqlite',
    // signal: 'vault',  // compile error — vault does not declare 'signal'
    // ...
  }
})

createStore() now infers the backend map (not just the backend names), so routing an undeclared domain — or misspelling a backend name — fails at compile time instead of throwing does not provide <kind>.<domain> on the first session(). The mandatory coverage of every persistence domain once backends is set is unchanged, and 'none' still resolves to the noop store.

A hand-written full backend has to declare the new chatMetadata cache alongside the other cache domains, or narrow itself with WaStoreBackend<S, C>. A bare satisfies WaStoreBackend without the cache factory no longer compiles.

A hand-written WaContactStore needs to read and write the new WaStoredContactRecord.username field — the contact handle without the display-only @, populated when the server surfaces one. The in-tree @zapo-js/store-* packages migrate their schemas automatically on connect (via ensurePgMigrations and its per-backend siblings), so consumers of those packages do not need to do anything.

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

The model

Providers are required when you set `backends`

Persisted domains

Optional archive domains

Cache domains

Read-through cache layer

When to enable it

Single-writer assumption

Why not every domain?

Backends

SQLite

PostgreSQL

MySQL

Redis

MongoDB

Memory

Memory-only (tests)

Custom backends

​The model

​Providers are required when you set backends

​Persisted domains

​Optional archive domains

​Cache domains

​Read-through cache layer

​When to enable it

​Single-writer assumption

​Why not every domain?

​Backends

SQLite

PostgreSQL

MySQL

Redis

MongoDB

Memory

​Memory-only (tests)

​Custom backends

The model

Providers are required when you set `backends`

Persisted domains

Optional archive domains

Cache domains

Read-through cache layer

When to enable it

Single-writer assumption

Why not every domain?

Backends

Memory-only (tests)

Custom backends