Class: Query<IS, OS, CTX>

Defined in: repo/query.ts:209

A Query represents a live view over a repository or another query, supporting:

• Query chaining: Queries can be chained together, where one query's results become the input for another query. This allows building complex data transformations through composition.

• Incremental updates: When the underlying data changes, queries automatically update their results. Changes propagate efficiently through query chains - only the affected results are recomputed rather than re-running the entire query.

• Persistent caching: Results are continuously cached to disk, both during the initial linear scan and as the source data changes. This allows queries to be efficiently resumed after being suspended or closed, without having to re-scan the entire dataset.

• Efficient indexing: When sorted by a field, queries act as persistent indexes enabling O(log n) lookups on that field. The index stays up-to-date as data changes and results are cached for immediate availability.

Query chaining example:

// Chain queries to find recent important todos
const importantTodos = new Query({
  source: repo,
  predicate: todo => todo.important
});
const recentImportant = new Query({
  source: importantTodos,
  predicate: todo => isRecent(todo.date)
});

You can also use queries as efficient indexes:

// Create an index over user emails
const usersByEmail = new Query({
  source: '/sys/users',
  schema: kSchemaUser,
  sortBy: 'email'
});

// O(log n) lookup by email after index is built
await usersByEmail.loadingFinished();
const user = usersByEmail.find('email', 'user@example.com');

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

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:9
context	readonly	CTX	undefined	Optional context data passed to predicate and sort functions	-	repo/query.ts:221
db	readonly	GoatDB<Schema>	undefined	Database instance this query operates on	-	repo/query.ts:218
id	readonly	string	undefined	Unique identifier for this query	-	repo/query.ts:215
limit	readonly	number	0	Maximum number of results to return, 0 means unlimited	-	repo/query.ts:227
scheme?	readonly	IS	undefined	Schema type for items in this query	-	repo/query.ts:224

Accessors

age

Get Signature

get age(): number

Defined in: repo/query.ts:360

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

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

Returns

boolean

Inherited from

Emitter.isActive

---

loading

Get Signature

get loading(): boolean

Defined in: repo/query.ts:373

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

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

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

Type Parameters

Type Parameter
C extends Function
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
c	C

Returns

(): void

Returns

void

Inherited from

Emitter.attach

---

close()

close(): void

Defined in: repo/query.ts:589

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.

Returns

void

---

detach()

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

Defined in: base/emitter.ts:123

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

Type Parameters

Type Parameter
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e?	E

Returns

void

Inherited from

Emitter.detachAll

---

emit()

emit<E>(e, ...args): void

Defined in: base/emitter.ts:54

Type Parameters

Type Parameter
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
...args	unknown[]

Returns

void

Inherited from

Emitter.emit

---

entries()

entries(): Generator<Entry<OS>>

Defined in: repo/query.ts:465

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

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

Checks if a given path is included in the query results.

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

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

Returns

void

Inherited from

Emitter.mute

---

once()

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

Defined in: base/emitter.ts:182

Type Parameters

Type Parameter
C extends Function
E extends QueryEvent | EmitterEvent

Parameters

Parameter	Type
e	E
c	C

Returns

(): void

Returns

void

Inherited from

Emitter.once

---

onLoadingFinished()

onLoadingFinished(handler): () => void

Defined in: repo/query.ts:495

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

Returns

void

---

onResultsChanged()

onResultsChanged(handler): () => void

Defined in: repo/query.ts:478

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

Returns

void

---

paths()

paths(): Iterable<string>

Defined in: repo/query.ts:399

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

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

Returns

Promise<void>

Overrides

Emitter.resume

---

suspend()

protected suspend(): void

Defined in: repo/query.ts:602

Returns

void

Overrides

Emitter.suspend

---

unmute()

unmute(): void

Defined in: base/emitter.ts:199

Returns

void

Inherited from

Emitter.unmute

---

valueForPath()

valueForPath(key): Item<OS>

Defined in: repo/query.ts:452

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
key	string	The path key to look up in the repository

Returns

Item<OS>

The item value if found, undefined otherwise