Snapshot

@rotorsoft/act-root

---

@rotorsoft/act-root / act/src / Snapshot

Type Alias: Snapshot<TState, TEvents>

Snapshot<TState, TEvents> = object

Defined in: libs/act/src/types/action.ts:331

Snapshot of state at a specific point in time.

Snapshots represent the current state after applying events. They include metadata about how many events have been applied (patches) and how many snapshots have been taken for optimization.

Examples

const snapshot = await app.load(Counter, "counter-1");

console.log(snapshot.state);     // { count: 42 }
console.log(snapshot.patches);   // 8 (events since last snapshot)
console.log(snapshot.snaps);     // 1 (1 snapshot taken)
console.log(snapshot.event);     // Last event that created this snapshot

Using snapshot in action handler

.on({ increment: z.object({ by: z.number() }) })
  .emit((action, snapshot) => {
    console.log("Current count:", snapshot.state.count);
    console.log("Events applied:", snapshot.patches);
    return ["Incremented", { amount: action.by }];
  })

Type Parameters

TState

TState extends Schema

State schema

TEvents

TEvents extends Schemas

Event schemas

Properties

cache_hit

readonly cache_hit: boolean

Defined in: libs/act/src/types/action.ts:372

true when the state was reconstructed from a cached checkpoint (skipping full event replay). Set by load(); propagated unchanged to every snapshot action() returns since they all derive from the same initial load. Always false for time-travel loads, which bypass the cache by design.

---

event?

readonly optional event?: Committed<TEvents, keyof TEvents>

Defined in: libs/act/src/types/action.ts:335

Event that created this snapshot (undefined for initial state)

---

id

readonly id: number

Defined in: libs/act/src/types/action.ts:358

Global event id (cross-stream sequence) of the stream-head event this snapshot folds to — the same value as event?.id, but always defined even on a warm cache hit where event is undefined. -1 for a brand-new stream with no events. Populated atomically with state inside load(): from the cached checkpoint's event_id on a hit-with-no-new-events, or from the last replayed event on a cache miss. Consumers that pair a loaded state with its head event id (the fold engine's first-sight path) read this instead of a separate cache lookup, which would open a TOCTOU window where a concurrent commit lands between the two reads and pairs older state with a newer id.

---

patch?

readonly optional patch?: Readonly<Patch<TState>>

Defined in: libs/act/src/types/action.ts:364

Domain patch applied by this event (undefined for initial/loaded state)

---

patches

readonly patches: number

Defined in: libs/act/src/types/action.ts:360

Number of patches applied since last snapshot

---

replayed

readonly replayed: number

Defined in: libs/act/src/types/action.ts:381

Number of events processed by the load() call that produced this snapshot — counts every snap and patch event applied past the cache point. 0 after a cache hit with no new events; equals the event count from snap/start after a cache miss. Distinct from patches, which is the snap-distance accumulator used by snap policies. Propagated unchanged by action().

---

snaps

readonly snaps: number

Defined in: libs/act/src/types/action.ts:362

Number of snapshots taken for this stream

---

state

readonly state: TState

Defined in: libs/act/src/types/action.ts:333

Current state data

---

version

readonly version: number

Defined in: libs/act/src/types/action.ts:345

Stream head version (sequence number of the last event in the stream). -1 for a brand-new stream with no events. Always defined — populated from the cache on hit-with-no-new-events, from the last replayed event on cache miss, or from the just-committed event on snapshots returned by action(). Use this instead of event?.version when you need the version even after a cache hit skipped the event replay entirely.