Class: Query<IS, OS, CTX>

Defined in: repo/query.ts:221

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

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:233
db	readonly	GoatDB<Schema>	undefined	Database instance this query operates on	-	repo/query.ts:230
id	readonly	string	undefined	Unique identifier for this query	-	repo/query.ts:227
limit	readonly	number	0	Maximum number of results to return, 0 means unlimited	-	repo/query.ts:239
scheme?	readonly	IS	undefined	Schema type for items in this query	-	repo/query.ts:236

Accessors

age

Get Signature

get age(): number

Defined in: repo/query.ts:369

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

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

Returns

boolean

Inherited from

Emitter.isActive

---

loading

Get Signature

get loading(): boolean

Defined in: repo/query.ts:382

Gets the loading status of the query. Checking this status allows building more responsive interfaces by showing intermediate results while the full query loads. See () for waiting until loading completes.

Returns

boolean

true if the query is still loading results, false if loading is complete.

---

repo

Get Signature

get repo(): Repository

Defined in: repo/query.ts:331

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

Gets the total time spent scanning items during query execution.

Returns

number

The total scan time in milliseconds.

Methods

attach()

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

Defined in: base/emitter.ts:116

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

Closes this query and cleans up its resources. This:

• Emits a 'Closed' event
• Unregisters from query persistence to stop caching
• Removes source change listeners
• Marks the query as closed

Once closed, a 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:149

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

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

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

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

Finds the first item in the query results where the specified field matches the given value. If the field is the sort field, uses binary search for O(log n) lookup. Otherwise performs a linear scan.

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>

The first matching item, or undefined if no match found

---

has()

has(path): boolean

Defined in: repo/query.ts:393

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

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

Returns

void

Inherited from

Emitter.mute

---

once()

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

Defined in: base/emitter.ts:248

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

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

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

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

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

Returns

Promise<void>

Overrides

Emitter.resume

---

suspend()

protected suspend(): void

Defined in: repo/query.ts:653

Returns

void

Overrides

Emitter.suspend

---

unmute()

unmute(): void

Defined in: base/emitter.ts:292

Returns

void

Inherited from

Emitter.unmute

---

valueForPath()

valueForPath(path): Item<OS>

Defined in: repo/query.ts:477

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