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:325

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:353

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:329

Event that created this snapshot (undefined for initial state)

---

patch?

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

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

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

---

patches

readonly patches: number

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

Number of patches applied since last snapshot

---

replayed

readonly replayed: number

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

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:343

Number of snapshots taken for this stream

---

state

readonly state: TState

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

Current state data

---

version

readonly version: number

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

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.