Skip to main content
Version: Current

QueryStatsOptions

@rotorsoft/act-root

@rotorsoft/act-root / act/src / QueryStatsOptions

Type Alias: QueryStatsOptions<E>

QueryStatsOptions<E> = object

Defined in: libs/act/src/types/ports.ts:433

Options for Store.query_stats. All stat fields default to false except head, which is always returned.

Cost model: With no opt-in flags (or tail alone), each requested stat resolves via an index-backed lookup — O(K) cost where K is the number of matched streams. Setting count and/or names triggers a full event scan over the matched streams (O(N) where N is total events); both share the same scan and so requesting one is the same cost as requesting both.

Type Parameters​

E​

E extends Schemas = Schemas

Event schemas; defaults to Schemas. When the caller narrows E, exclude is type-checked against the schema's event names — typos like ["TOMBSTON_EVENT"] fail at compile time.

Properties​

after?​

readonly optional after?: string

Defined in: libs/act/src/types/ports.ts:439

Keyset pagination cursor: return only streams whose name sorts strictly after this value (lexicographic). Pass the last stream name from the previous page to fetch the next. Pairs with limit; the result Map preserves stream-name order so the next cursor is [...result.keys()].at(-1).

before?​

readonly optional before?: number

Defined in: libs/act/src/types/ports.ts:438

Time-travel cutoff: only consider events with id < before. Omitted = current state. Useful for "what did this stream look like at event N?" historical queries without changing the call shape. Cheap on both code paths (cheap-heads path narrows the index scan; full-scan path adds a WHERE id < ? predicate).

count?​

readonly optional count?: boolean

Defined in: libs/act/src/types/ports.ts:435

Include the total non-excluded event count per stream. Triggers full scan.

exclude?​

readonly optional exclude?: ReadonlyArray<EventName<E>>

Defined in: libs/act/src/types/ports.ts:437

Event names to skip — e.g. [TOMBSTONE_EVENT, SNAP_EVENT] to ignore framework markers. Applies to all returned stats (head, tail, count, names) consistently.

limit?​

readonly optional limit?: number

Defined in: libs/act/src/types/ports.ts:440

Maximum number of streams to return; omitted, every matching stream (see the writing-a-store guide § Paginating query_stats). A bound, applied before a stream is added to the result: limit: 0 returns none. A non-negative integer: other values aren't validated, and adapters treat them differently.

names?​

readonly optional names?: boolean

Defined in: libs/act/src/types/ports.ts:436

Include a name → count map per stream. Triggers full scan (shares cost with count).

tail?​

readonly optional tail?: boolean

Defined in: libs/act/src/types/ports.ts:434

Include the earliest non-excluded event per stream. Cheap when alone (indexed); free when count/names also set (already scanning).