Class: Query<IS, OS, CTX>

Defined in: repo/query.ts:237

Extends

• Emitter<QueryEvent>

Type Parameters

Type Parameter
IS extends Schema
OS extends IS
CTX extends ReadonlyJSONValue

Constructors

Constructor

new Query<IS, OS, CTX>(config): Query<IS, OS, CTX>

Defined in: repo/query.ts:300

Creates a new Query instance.

Parameters

Parameter	Type	Description
config	QueryConfig<IS, OS, CTX>	The query configuration object containing:

Returns

Query<IS, OS, CTX>

Overrides

Emitter.constructor

Properties

Property	Modifier	Type	Default value	Description	Inherited from	Defined in
alwaysActive	readonly	boolean	undefined	-	Emitter.alwaysActive	base/emitter.ts:10
context	readonly	CTX	undefined	Optional context data passed to predicate and sort functions	-	repo/query.ts:249
db	readonly	GoatDB<Schema>	undefined	Database instance this query operates on	-	repo/query.ts:246
id	readonly	string	undefined	Unique identifier for this query	-	repo/query.ts:243
limit	readonly	number	0	Maximum number of results to return, 0 means unlimited	-	repo/query.ts:255
scheme?	readonly	IS	undefined	Schema type for items in this query	-	repo/query.ts:252

Accessors

age

Get Signature

get age(): number

Defined in: repo/query.ts:387

Gets the age (generation) of the query results, which is a monotonically increasing number. The age is incremented each time the query results are updated due to changes in the underlying data source. This allows tracking whether cached results are stale.

Returns

number

The current generation number of the query results, which only increases over time.

---

count

Get Signature

get count(): number

Defined in: repo/query.ts:363

Gets the number of items in the query results. This is more efficient than calling results().length since it directly returns the cached path count rather than constructing the results array first.

Returns

number

The number of items in the query results.

---

isActive

Get Signature

get isActive(): boolean

Defined in: base/emitter.ts:63

Returns

boolean

Inherited from

Emitter.isActive

---

loading

Get Signature

get loading(): boolean

Defined in: repo/query.ts:401

Gets whether a load/scan is currently in flight. Loading is lazy: it begins on the first subscription (onResultsChanged), a () wait, or the base Emitter's resume. A freshly created, unobserved query reports false. See () for waiting until loading completes.

Returns

boolean

true while the initial (or a re-)scan is running, false otherwise.

---

repo

Get Signature

get repo(): Repository

Defined in: repo/query.ts:349

Gets the repository associated with this query's data source.

Returns

Repository

The repository that this query operates on.

---

scanTimeMs

Get Signature

get scanTimeMs(): number

Defined in: repo/query.ts:374

Gets the total time spent scanning items during query execution.

Returns

number

The total scan time in milliseconds.

Methods

_onListenersChanged()

protected _onListenersChanged(event): void

Defined in: base/emitter.ts:321

Hook called whenever listeners change for a specific event (attach, detach, or detachAll). The event argument is the event whose listener set changed, or undefined for detachAll() with no argument. The default implementation keeps a subclass-owned _idleTimer in sync with DocumentChanged pins; _touchIdle() is the subclass-specific reset policy.

Parameters

Parameter	Type
event	string

Returns

void

Inherited from

Emitter._onListenersChanged

---

attach()

attach<C, E>(e, c): () => void

Defined in: base/emitter.ts:139

Type Parameters

Type Parameter
C extends Function
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
c	C

Returns

() => void

Inherited from

Emitter.attach

---

close()

close(): void

Defined in: repo/query.ts:770

Closes this query, releasing its memory and unregistering from persistence. This:

• Settles any pending loading waiters (resolves loadingFinished() if the query is closed mid-load)
• Emits a 'Closed' event
• Unregisters from query persistence to stop caching
• Removes the query's DocumentChanged listener on its source repo, which may make the source repo eligible for auto-close
• Marks the query as closed

After close(), the query stops tracking updates and results() returns the snapshot captured at close time. Calling any method on a closed query is undefined behavior, and a closed query cannot be reopened -- create a new query instance instead.

Callers MUST call close() when a query is no longer needed to release its event listeners. A FinalizationRegistry safety net exists for the live-updates listener, but GC timing is non-deterministic.

Returns

void

---

detach()

detach<C, E>(e, c): void

Defined in: base/emitter.ts:173

Type Parameters

Type Parameter
C extends Function
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
c	C

Returns

void

Inherited from

Emitter.detach

---

detachAll()

detachAll<E>(e?): void

Defined in: base/emitter.ts:214

Type Parameters

Type Parameter
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e?	E

Returns

void

Inherited from

Emitter.detachAll

---

emit()

emit<E>(e, a0?, a1?): void

Defined in: base/emitter.ts:88

Emits an event to all registered listeners in registration (FIFO) order. This ordering is a stable contract -- chained query listeners depend on it.

Type Parameters

Type Parameter
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
a0?	unknown
a1?	unknown

Returns

void

Inherited from

Emitter.emit

---

entries()

entries(): Generator<Entry<OS>>

Defined in: repo/query.ts:517

Returns a generator that yields key-value pairs for all items in the query results. Each entry contains the item's path key and its corresponding value.

Returns

Generator<Entry<OS>>

A generator yielding [key, value] tuples for each item in the query

---

find()

find(fieldName, value): ManagedItem<OS, Schema>

Defined in: repo/query.ts:620

Finds an item in the query results whose field equals the given value according to core-value equality (epsilon < Number.EPSILON near-zero; distinct Invalid Date instances and NaN never match in coreValueEquals). If the field is the sort field, uses binary search (total-order) for O(log n) lookup then scans the epsilon-neighborhood. Otherwise performs a linear scan. When multiple epsilon-equal values exist, any may be returned.

Parameters

Parameter	Type	Description
fieldName	keyof OS["fields"]	The name of the field to search on
value	SchemaDataType<OS>[keyof OS["fields"]]	The value to search for

Returns

ManagedItem<OS, Schema>

A matching item, or undefined if no match found

---

has()

has(path): boolean

Defined in: repo/query.ts:412

Returns true if path matches this query's predicate, regardless of the limit setting. Use results() to get the bounded result set.

Parameters

Parameter	Type	Description
path	string	The path to check.

Returns

boolean

true if the path is included in the query results, false otherwise.

---

loadingFinished()

loadingFinished(): Promise<true>

Defined in: repo/query.ts:598

Returns a promise that resolves to true when the query finishes loading its initial results. If loading is already finished, the promise resolves on the next event loop cycle.

Returns

Promise<true>

A promise that resolves to true when loading is finished

---

mute()

mute(): void

Defined in: base/emitter.ts:344

Returns

void

Inherited from

Emitter.mute

---

once()

once<C, E>(e, c): () => void

Defined in: base/emitter.ts:278

Type Parameters

Type Parameter
C extends Function
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
c	C

Returns

() => void

Inherited from

Emitter.once

---

onLoadingFinished()

onLoadingFinished(handler): () => void

Defined in: repo/query.ts:582

Registers a callback to be invoked when the query finishes loading its initial results. If loading is already finished, the callback will be scheduled to run on the next event loop cycle.

Parameters

Parameter	Type	Description
handler	() => void	The callback function to execute when loading finishes

Returns

A cleanup function that removes the event listener when called

() => void

---

onResultsChanged()

onResultsChanged(handler): () => void

Defined in: repo/query.ts:567

Registers a callback to be invoked when the query results change due to updates in the underlying data source.

Parameters

Parameter	Type	Description
handler	() => void	The callback function to execute when results change

Returns

A cleanup function that removes the event listener when called

() => void

---

paths()

paths(): Iterable<string>

Defined in: repo/query.ts:426

Gets an iterable of all paths included in the query results.

Returns

Iterable<string>

An iterable containing all paths that match the query criteria.

Remarks

The returned paths may change during iteration if the underlying data source changes. Consider using () for a stable snapshot if consistency is needed during iteration.

---

results()

results(): readonly ManagedItem<OS, Schema>[]

Defined in: repo/query.ts:438

Gets the results of the query as an array of managed items. The returned items are mutable - any changes made to them will automatically trigger the query to update its results.

Returns

readonly ManagedItem<OS, Schema>[]

An array of managed items that match the query criteria.

---

resume()

protected resume(): Promise<void>

Defined in: repo/query.ts:700

Returns

Promise<void>

Overrides

Emitter.resume

---

suspend()

protected suspend(): void

Defined in: repo/query.ts:804

Returns

void

Overrides

Emitter.suspend

---

unmute()

unmute(): void

Defined in: base/emitter.ts:348

Returns

void

Inherited from

Emitter.unmute

---

valueForPath()

valueForPath(path): Item<OS>

Defined in: repo/query.ts:500

Gets the item value for a given path key. The value is retrieved from the repository's committed head or temporary records.

Parameters

Parameter	Type	Description
path	string	The path key to look up in the repository

Returns

Item<OS>

The item value if found, undefined otherwise

Events

listenerCount()

listenerCount(event): number

Defined in: base/emitter.ts:74

Returns the number of live (non-null) callbacks registered for a given event. Used by lifecycle policies (e.g. auto-close) to derive listener 'pins' from the Emitter's own registrations instead of parallel counters, so detachAll / dedup / missing-detach semantics are always respected.

Parameters

Parameter	Type
event	QueryEvent | EmitterEvent

Returns

number

Inherited from

Emitter.listenerCount