Node.js, memory persistence

@atolljs/node/redis persists a shared-memory contract's field regions to Redis, restart durability out of the box, and cross-process replication when a subscriber is attached. The SharedArrayBuffer stays the synchronous source of truth; Redis mirrors it behind the scenes.

Wiring

src/incidents.tsbackend
// persistence as a pool option: attaches after bind, stops on terminate()
import { createNodePool } from '@atolljs/node';
import { redisMemoryAdapter, ioRedisSubscriber } from '@atolljs/node/redis';
import { incidentsMemory } from './incidents.contract';

const pool = createNodePool({
  worker: () => new Worker(new URL('./incidents.worker.ts', import.meta.url)),
  sharedMemory: incidentsMemory,
  persistence: redisMemoryAdapter(redis, {
    name: 'incidents',       // hash: atoll:mem:incidents
    syncIntervalMs: 100,
    subscriber: ioRedisSubscriber(redis.duplicate()), // optional replication
  }),
});
await pool.persistence?.ready; // state restored into the buffer

persistence is a factory the pool invokes right after the contract binds: redisMemoryAdapter(client, opts) produces one. Or attach standalone with persistSharedMemory(memory, opts) anywhere a bound contract exists (e.g. an Express bootstrap that shares the buffer).

What lands in Redis

  • atoll:mem:<name>, a hash; member = field path (state.metrics), value = base64 of the field's byte region.
  • atoll:mem:<name>:ops, the pub/sub channel; each dirty field publishes { src, path, b64 }.
  • The version-counter block is not persisted: per-process coordination, not state.

Client surface

Three hash commands plus optional publish: deliberately narrow so any Redis client qualifies:

backend
// the client surface, ioredis and node-redis both satisfy it
interface RedisHashClient {
  hset(key: string, field: string, value: string): Promise<unknown>;
  hgetall(key: string): Promise<Record<string, string>>;
  publish?(channel: string, message: string): Promise<unknown>; // replication only
}
// values are base64 strings, any client works, no Buffer mode needed

For replication pass a subscriber: node-redis's subscribe(channel, listener) already matches; wrap an ioredis connection with ioRedisSubscriber(client).

Caveats

  • Restore is async, await persistence.ready (or pool.persistence?.ready) before serving traffic that depends on restored state.
  • List writeAt only becomes visible to the flush loop after commit(), same rule as observers.
  • Replication is last-write-wins per field, coordination, not consensus.
  • One process's adapter instance does the flushing, workers write to the shared buffer, the main thread's adapter sees the version bumps.

NestJS usage, including injecting the client via registerPoolAsync, is under NestJS → Persistence.