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

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

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

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

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

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

Maximum number of streams to return. Defaults to unbounded (every matching stream) — unlike QueryStreams.limit, which defaults to 100. Omitting it preserves the historical "return everything" behavior; set it (with after) to page through large stream sets a bounded chunk at a time.

names?​

readonly optional names?: boolean

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

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

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