Skip to main content
Version: Current

ActOptions

@rotorsoft/act-root

@rotorsoft/act-root / act/src / ActOptions

Type Alias: ActOptions<TLanes>

ActOptions<TLanes> = object

Defined in: libs/act/src/act.ts:208

Options for Act construction (passed via ActBuilder.build).

Type Parameters​

TLanes​

TLanes extends string = string

Properties​

autocloseCycleMinutes?​

readonly optional autocloseCycleMinutes?: number

Defined in: libs/act/src/act.ts:270

Deprecated​

Since #1175 this knob is accepted, validated, and ignored. It paced the off-hours re-check of the pre-#1090 autoclose sweep; the synthesized autoclose reaction now derives its re-check directly from autocloseWindow — a tick landing outside the window parks until the exact instant the window opens, so there is no polling cadence to configure (and nothing minute-denominated on the close surface). Still validated as an integer [1, 1440] so typos keep failing loudly at act().build(). Will be removed in the next major.

autocloseWindow?​

readonly optional autocloseWindow?: object

Defined in: libs/act/src/act.ts:302

Optional off-hours window restricting when autoclose evaluates. A synthesized autoclose reaction that triggers outside the window defers to the next instant the window opens — derived from the window itself, no polling cadence. Hours are [0, 23] integers in timeZone (IANA, default "UTC", DST-correct); start > end is an overnight window (e.g. { start: 22, end: 6 }). Omit to evaluate regardless of clock time.

end​

readonly end: number

start​

readonly start: number

timeZone?​

readonly optional timeZone?: string

circuitBreaker?​

readonly optional circuitBreaker?: CircuitBreakerOptions

Defined in: libs/act/src/act.ts:258

Orchestrator circuit breaker for the drain loop (ACT-984). After failureThreshold consecutive store failures the breaker opens and the drain loop skips claim() for cooldownMs instead of hammering a down backend, then allows a half-open trial. Out-of-range values throw a ZodError at act().build(). Defaults: threshold 5, cooldown 30s.

closeBatchSize?​

readonly optional closeBatchSize?: number

Defined in: libs/act/src/act.ts:277

Deprecated​

Dead since #1090 replaced the autoclose sweep with a synthesized per-aggregate reaction — nothing pages the store in batches anymore, so nothing reads this. Accepted and validated ([1, 1024]) for compatibility; will be removed in the next major.

closeOnError?​

readonly optional closeOnError?: boolean

Defined in: libs/act/src/act.ts:292

Deprecated​

Dead since #1090 — the sweep-side predicate try/catch this flag steered no longer exists; a throwing policy predicate now follows the reaction retry path (blockOnError: false, three retries). Accepted for compatibility; will be removed in the next major.

closeYieldMs?​

readonly optional closeYieldMs?: number

Defined in: libs/act/src/act.ts:284

Deprecated​

Dead since #1090 — the sweep that yielded between successive Store.truncate calls no longer exists; closes are staged per stream by the autoclose reaction. Accepted and validated ([0, 1000]) for compatibility; will be removed in the next major.

correlator?​

readonly optional correlator?: Correlator

Defined in: libs/act/src/act.ts:229

Correlation-id generator for originating actions (ACT-404). When omitted, Act uses default_correlator, which produces a readable, time-monotonic-within-window, lowercase id of the form {state[:4]}-{action[:4]}-{ts}{rnd} (18 chars).

Reactions inherit reactingTo.meta.correlation so the chain stays intact — the delegate is only consulted on originating commits and for the close-the-books transaction.

drain?​

readonly optional drain?: boolean

Defined in: libs/act/src/act.ts:250

Run the local reaction pipeline on this instance (#803). Defaults to true. Set false on writer-only or sidecar instances: drain controllers' auto-cycle workers don't start, correlate() / drain() / settle() become no-ops, and the notify handler skips its drain-wakeup arm (but still emits the notified lifecycle event so observability sidecars work).

listen?​

readonly optional listen?: boolean

Defined in: libs/act/src/act.ts:241

Subscribe to Store.notify on this instance (#803). Defaults to true. Set false on instances that only commit and never react — the subscriber-connection budget is the practical scaling ceiling for the notify/listen pattern, and writer-only fleets spend it for nothing when they subscribe to a channel they never read. Commits still emit notifications (that's part of the store's commit protocol); only the subscriber side is gated.

maxSubscribedStreams?​

readonly optional maxSubscribedStreams?: number

Defined in: libs/act/src/act.ts:209

Cap for the LRU set tracking already- subscribed reaction streams. Default: DEFAULT_MAX_SUBSCRIBED_STREAMS.

onlyLanes?​

readonly optional onlyLanes?: ReadonlyArray<TLanes>

Defined in: libs/act/src/act.ts:231

Restrict this process to a subset of declared lanes (ACT-1103).

scoped?​

readonly optional scoped?: Scoped

Defined in: libs/act/src/act.ts:218

Per-Act ports (ACT-501). When set, this Act runs against the provided store + cache instead of the singletons — threaded via AsyncLocalStorage so internals are unchanged. Both are required together (a shared cache across distinct stores would collide on stream keys). Omit for the singleton path.

settleDebounceMs?​

readonly optional settleDebounceMs?: number

Defined in: libs/act/src/act.ts:210

Debounce window (ms) used by settle() when the caller doesn't pass SettleOptions.debounceMs. Tune this once per Act instance instead of threading the value through every call site. Default: DEFAULT_SETTLE_DEBOUNCE_MS.

validateFoldedState?​

readonly optional validateFoldedState?: boolean

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

Validate folded state against its declared Zod schema after every reduction (ACT-1238). Off by default.

When true, each time an event is folded into state — on the command path (do), on load/replay, and inside projection-fold projections — the merged full state is parsed against the owning state's state({ Name: schema }) schema. A reducer that produces schema-violating state (the calculator divide-by-zero NaN class, #1230) throws a ValidationError at the triggering event, whose target names the state and the event (<state>.<event>#<id>) — instead of the bad value propagating and surfacing hops later as a confusing downstream error.

This is a debugging / CI aid, not a production guard. Turn it on in development and CI to catch total-reducer bugs at the source; the framework already validates action inputs and emitted events, so the reduced state is the one shape it otherwise trusts. The per-event patch step is selected once at build() (the same way the orchestrator picks bare vs trace-decorated store ops from the log level): when false (the default) the fold loop is byte-identical to a bare reduction — the validating patch step is never selected, so there is no per-event cost, not even a branch.