@natsail/session

@natsail/session shares one managed source across keyed consumers. It owns source lifecycle, immutable snapshots, serial reducers, and idle cleanup.

pnpm add @natsail/core @natsail/session

React and RxJS adapters can use the same registry and key. This sharing prevents duplicate source subscriptions.

Prefer a validated definition when more than one caller can acquire a session. The registry rejects a key reused with a different delivery contract instead of silently sharing the wrong source:

import { defineSession } from '@natsail/session'

const conversation = defineSession({
  key: 'conversation:123',
  contract: 'conversation-events:v2',
  source,
})

const handle = sessions.acquire(conversation)

Call handle.restart() or registry.restart(key) to reopen a terminal source. The session keeps its handle and latest accepted value.

A restart rejects deliveries from the prior source generation. A restart does not occur automatically after an application handler fails.

Graceful session close accepts the draining source's final values until its lease finishes, then marks the snapshot closed. Use await closeNatsResources({ runtime, sessions }) from @natsail/session when disposing both lifetimes. It starts both close operations even if one throws synchronously, so registry cleanup cannot postpone the runtime shutdown deadline. Both rejections are observed; the first failure rejects the helper. See the lifecycle upgrade notes; explicit cancellation does not promise buffered delivery.

registry.inspect() reports active keys, contracts, phases, reference counts, revisions, and idle state. registry.events emits lifecycle and reference-count changes so applications can detect leaks and unexpected restarts without reaching into an adapter.

Pass telemetry to createSessionRegistry() to report active session and reference gauges plus open, retain, release, restart, and close counters. Session keys and contracts remain available through explicit inspection/events but are never included in default telemetry attributes:

const sessions = createSessionRegistry({
  idleCloseMs: 250,
  telemetry,
  telemetryAttributes: { service: 'orders-ui' },
})

The sink is synchronous and failure-isolated. It should enqueue measurements instead of performing blocking I/O. telemetryClock provides deterministic timestamps in tests.

createReducingSessionSource() accepts an optional workBudget. Reducer calls remain strictly serial and ordered across yields. A failed reducer value is not published; later calls continue from the last successfully applied state.

See the NATSail README for the registry model.

License

Apache-2.0