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

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

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

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

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

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

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

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

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

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

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

Cap for the LRU tracking what each dynamically resolved reaction target was last subscribed at. Statically declared targets are held outside it and never evicted, so their lane and priority stay owned by the build-time subscribe (#1582). Default: DEFAULT_MAX_SUBSCRIBED_STREAMS.

onlyLanes?​

readonly optional onlyLanes?: ReadonlyArray<TLanes>

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

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

scoped?​

readonly optional scoped?: Scoped

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

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

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

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.