Snapshot policies

Snapshot policies reduce cumulative snapshot work, including JSON serialization for parse(), when a consumer does not need an update for every source chunk. They are optional. Omitting snapshotPolicy retains the 4.0 behavior: one snapshot for every input chunk.

The same options work with both parse() and iterate():

parser.parse({ snapshotPolicy: { mode: "bytes", bytes: 256 * 1024 } })

for await (const snapshot of parser.iterate(source, {
  snapshotPolicy: { mode: "value" }
})) {
  renderProgress(snapshot)
}

Modes

chunk

{
  mode: "chunk"
}

Emits after every input chunk. This is the default and is snapshot-for-snapshot compatible with omitting the option. The default stringBufferSize is 0, so SchemaStream adds no fixed-size string buffer, but source chunks remain the cadence boundary. A provider or network chunk can contain one or many characters; character-by-character snapshots require the upstream source itself to emit one Unicode code point per chunk.

value

{
  mode: "value"
}

Emits after an input chunk completes at least one primitive JSON value. Several values completed in one source chunk produce one snapshot. This is useful for long streamed strings because incomplete characters do not repeatedly materialize or serialize the entire accumulated object.

bytes

{ mode: "bytes", bytes: 256 * 1024 }

Emits when source bytes received since the previous snapshot meet or exceed the positive integer threshold. Thresholds are evaluated at source-chunk boundaries; SchemaStream does not split input chunks. At flush, parser state not represented by the previous snapshot is emitted below the threshold; structural-only trailing bytes do not create a duplicate snapshot.

final

{
  mode: "final"
}

Emits once after the JSON parser reaches a complete document. As in 4.0, SchemaStream does not apply the Zod schema as authoritative output validation. Validate the result explicitly or use the settled, validated output from the producing SDK.

Errors, callbacks, and backpressure

• parse() rejects invalid byte thresholds synchronously. iterate() rejects on first advancement, before locking the source.
• Malformed and truncated JSON reject under every policy.
• onValueComplete and legacy onKeyComplete cadence are independent of snapshot cadence. See Completion events for their different cost and ordering contracts.
• iterate() preserves source backpressure at emission boundaries and cancels its source when the consumer returns early.
• Every yielded iterate() value is an independent JSON-equivalent copy, so consumer mutation cannot affect later snapshots. Parser-owned JSON-domain state is cloned directly; exotic custom defaults retain the exact stringify/parse fallback behavior.
• Timer-based policies are intentionally excluded because asynchronous controller lifetime, cancellation, and deterministic backpressure semantics require a separate design.