Skip to main content

ScanOptions

@rotorsoft/act-root

@rotorsoft/act-root / act/src / ScanOptions

Type Alias: ScanOptions

ScanOptions = object

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

Options for the orchestrator's restore scan loop, consumed by IAct.restore (and threaded through to the internal scan). Adapters never see these — they're entirely interpreted on the orchestrator side.

Compaction flags (drop_snapshots, drop_closed_streams) and the migration overlay (event_migrations, stream_rename) all apply per event before the sink writes anything. Any throw aborts the whole scan — atomic rollback in the sink means a failing transform leaves the target byte-for-byte unchanged.

Properties​

batch_size?​

readonly optional batch_size?: number

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

Per-batch row count for the scan pagination loop (ACT-1133). Each call to source.query requests limit: batch_size and after: <last id seen>. Default 500. Lower values trade round trips for memory; higher values approach the cost of an unbounded query.

drop_closed_streams?​

readonly optional drop_closed_streams?: boolean

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

Compact streams that have been closed (tombstoned) via IAct.close (ACT-1126). The scan walks the source once upfront to collect streams with a __tombstone__ event, then the main loop drops every pre-close event whose stream is in that set. The tombstone itself is kept — it's the gate that makes IAct.do throw StreamClosedError in the rebuilt store, so dropping it would silently reopen the stream.

Useful for compaction during transfer: the new (migrated) store keeps the close gate but drops the historical detail.

Counted in ScanResult.dropped.closed_streams (pre-close events only; the tombstone is counted in kept).

Default false.

drop_snapshots?​

readonly optional drop_snapshots?: boolean

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

Skip events with name === SNAP_EVENT. The next snap policy regenerates snapshots against current code; useful for backups that should compact stale snapshot bytes. Counted in ScanResult.dropped.snapshots.

Single-pass: no source-shape implications. Default false.

dry_run?​

readonly optional dry_run?: boolean

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

When true, IAct.restore runs the scan loop without touching the store — events are validated and counted but no transaction is opened and no rows are written. Returned kept / dropped reflect what a subsequent destructive restore against the same source would land; a throw means the source has a blocker (the running index pinpoints it).

No Store.restore capability is required for a dry-run — the adapter is never called. Default false.

event_migrations?​

readonly optional event_migrations?: Record<string, EventMigration<any, any>>

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

Per-event migrations applied during scan (ACT-1126). Keys are source event names; values describe how to rewrite the event into its current-version form before the sink writes it.

Transfer-time only — never registered at app build time and never auto-applied to a live store. Operators configure migrations explicitly per-call (typically through the inspector's transfer dialog when moving from an old store to a new one).

Each row that matches a key:

  1. parses event.data against from_schema (validates source);
  2. runs migrate(parsed) to transform the payload;
  3. parses the result against to_schema (validates target);
  4. is rewritten with name = to and data = migrated.

Any throw aborts the whole scan — atomic transaction rollback in the sink means a failing migration leaves the target byte-for-byte unchanged.

on_progress?​

readonly optional on_progress?: (p) => void

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

Optional progress callback. The scan loop fires it once per event during iteration. Three fields:

  • processed — running 1-based count of events processed.
  • id — current event's id.
  • max_id — highest id in the source, probed once at scan start via source.query(noop, { backward: true, limit: 1 }). O(1) on indexed stores. Left undefined when the probe can't determine it (e.g. CsvFile-style sources that ignore the filter and stream more than one event from the probe call).

UIs render either processed / ? (event count) or id / max_id (position through the id space) depending on need.

Synchronous handler — the scan loop calls it directly. Throttling / batching is the caller's responsibility: for a million-event restore, debounce in the handler rather than expecting the loop to coalesce calls. Keeping it unthrottled means callers that want every-event reporting get it without a config knob.

Parameters​

p​
id​

number

max_id?​

number

processed​

number

Returns​

void

stream_rename?​

readonly optional stream_rename?: (stream) => string

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

Per-stream rename applied during scan (ACT-1126). Called once per event; the returned string replaces event.stream. Useful for tenant relocation (s => s.replace(/^old-tenant-/, "new-tenant-")) or prefix cleanup.

Applied AFTER event_migrations so the migration sees the original stream name (in case the migration's migrate function inspects it).

Parameters​

stream​

string

Returns​

string