Skip to main content
Version: v10.0.0

Query

An immutable description of a query over one collection. Each method returns a new query, and two queries with the same structure are the same query, so a component can rebuild its query on every render.

The type parameters record what the query asks a backend for, so the types can check that a loader serves it.


Import
import { Query } from "@hyper-fetch/db"

Parameters​

class Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> {
constructor(runtime: DbRuntime, definition: QueryDefinition) {};
key: string;
definition: QueryDefinition;
__types: { eq: Eq; loaders: Loaders; local: Local; mode: Mode; order: Order; result: Result; row: Row; tokens: Tokens };
explain() => QueryExplanation;
fetchNextPage() => Promise<void>;
get(this: Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local>) => Promise<QueryState<QueryData<Result, Mode>>>;
getSnapshot() => QueryState<QueryData<Result, Mode>>;
infinite(this: Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local> & InfiniteCheck<Order, Mode>, options: InfiniteQueryOptions) => InfiniteQuery<Result>;
join<Name, Target, Field, On, Type>(name: Name, collection: Target, by: JoinSpec<Row, Field, JoinedMatchOf<Target, On>, On, Type>) => Query<Row, Loaders, Joined<Result, Name, JoinedValue<JoinedRowOf<Target>, On, Type>>, Tokens, Eq, Order, Mode, Local>;
limit(this: Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>, limit: number) => Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local>;
local() => Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, true>;
orderBy<Name>(this: Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>, callback: (row: RowRefs<Row>) => FieldRef<Name, Row[Name]>, direction: SortDirection) => Query<Row, Loaders, Result, Tokens, Eq, Order | Name, Mode, Local>;
refetch() => Promise<void>;
select<Selection>(callback: (row: RowRefs<Row>) => Selection) => Query<Row, Loaders, Selected<Selection>, Tokens, Eq, Order, Mode, Local>;
subscribe(this: Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local>, listener: () => void) => () => void;
where<C>(this: Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>, callback: (row: RowRefs<Row>) => C) => Query<Row, Loaders, Result, Tokens | ExtractConditionTokens<C>, Eq | ExtractConditionEq<C>, Order, Mode, Local>;
}
Parameters
NameTypeDescription
runtime
DbRuntime
definition
QueryDefinition

Properties​

definition​

Type
QueryDefinition

key​

Identifies the query by its structure

Type
string

__types​

Type-only carrier of the query's generics, never set at runtime

Type
{ eq: Eq; loaders: Loaders; local: Local; mode: Mode; order: Order; result: Result; row: Row; tokens: Tokens }

Methods​

explain()​

How the db serves the query: the loader, what is sent, what runs locally and which syncs keep it live

Preview
explain()
Returns
explain
NameTypeDescription
answeredLocally
boolean

Whether rows the db already holds answer the query, with no request

error
Error
kind
list | one | local | error
loader
number

Index of the loader in the collection's chain

local
ExpressionNode[]

Conditions evaluated on the rows the db holds

sent
SendableNode[]

Conditions sent to the backend

syncs
{ topic: string; type: (insert | update | delete | changes) }[]

The syncs that keep the result live


fetchNextPage()​

Loads the next page of a paginated query

Preview
fetchNextPage()
Returns
Promise<void>

get()​

Reads the query once: resolves with the first state that is not loading

Preview
get(this: Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local>)
Parameters
Parameters
NameTypeDescription
this
Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local>
Returns
Promise<QueryState<QueryData<Result, Mode>>>

getSnapshot()​

The current state. It keeps its identity until something changes, as useSyncExternalStore expects.

Preview
getSnapshot()
Returns
getSnapshot
NameTypeDescription
data
Data | undefined

undefined until the query has loaded, then the selected fields of every row

error
unknown

The last failure, also when a refresh failed and the rows stay

hasNextPage
boolean

Whether a paginated query has another page

isFetching
boolean

Whether a request for the query is in flight

stale
boolean

Whether the rows may be out of date: their subset is stale or its syncs are disconnected

status
QueryStatus

error only when a first load failed and there is nothing to show


infinite()​

A window over the query's ordered result, widened one page at a time with fetchNextPage . Rows the db holds show at once, and the loader loads more only when the window runs past them. The query must have orderBy , so a page never shifts between renders.

Preview
infinite(this: Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local> & InfiniteCheck<Order, Mode>, options: InfiniteQueryOptions)
Parameters
Parameters
NameTypeDescription
this
Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local> & InfiniteCheck<Order, Mode>
options
InfiniteQueryOptions
Returns
InfiniteQuery<Result>

join()​

Adds the row of another collection whose key is the given field, as a left join: each result holds it under name , or undefined while it is not loaded or when there is none. With { type: &quot;inner&quot; } , results without a joined row are left out. With { on: &quot;postId&quot; } , the join matches that field of the joined collection instead of its key and holds an array of every matching row, loaded through a list loader that can send inArray on it. Options go in an object with the field as by , as in join(&quot;comments&quot;, db.comment, { by: (post) =&gt; post.id, on: &quot;postId&quot; }) . The db loads joined rows in batches through the joined collection's key loader, and a result updates whenever its joined row changes. Joined rows are loaded by key, so only syncs without where reach them.

Preview
join<Name, Target, Field, On, Type>(name: Name, collection: Target, by: JoinSpec<Row, Field, JoinedMatchOf<Target, On>, On, Type>)
Parameters
Parameters
NameTypeDescription
name
Name
collection
Target
by
JoinSpec<Row, Field, JoinedMatchOf<Target, On>, On, Type>
Returns
Query<Row, Loaders, Joined<Result, Name, JoinedValue<JoinedRowOf<Target>, On, Type>>, Tokens, Eq, Order, Mode, Local>

limit()​

Limits the number of results. A paginated loader that declares limit receives it as its page size.

Preview
limit(this: Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>, limit: number)
Parameters
Parameters
NameTypeDescription
this
Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>
limit
number
Returns
Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local>

local()​

Reads only the rows the db holds and never sends a request

Preview
local()
Returns
Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, true>

orderBy()​

Sorts rows by a field. Calling it again adds a sort that breaks ties of the previous ones.

Preview
orderBy<Name>(this: Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>, callback: (row: RowRefs<Row>) => FieldRef<Name, Row[Name]>, direction: SortDirection)
Parameters
Parameters
NameTypeDescription
this
Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>
callback
(row: RowRefs<Row>) => FieldRef<Name, Row[Name]>
direction
SortDirection
Returns
Query<Row, Loaders, Result, Tokens, Eq, Order | Name, Mode, Local>

refetch()​

Loads the query's subset again

Preview
refetch()
Returns
Promise<void>

select()​

Picks and renames the fields each result holds

Preview
select<Selection>(callback: (row: RowRefs<Row>) => Selection)
Parameters
Parameters
NameTypeDescription
callback
(row: RowRefs<Row>) => Selection
Returns
Query<Row, Loaders, Selected<Selection>, Tokens, Eq, Order, Mode, Local>

subscribe()​

Subscribes to the query's state. The first subscriber attaches the query to the subset that serves it, which loads when it is stale. Returns a function that unsubscribes.

Preview
subscribe(this: Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local>, listener: () => void)
Parameters
Parameters
NameTypeDescription
this
Query<Row, Loaders, Result, Tokens, Eq, Order, Mode, Local> & ServableCheck<Loaders, Tokens, Eq, Order, Mode, Local>
listener
() => void
Returns
() => void

where()​

Filters rows. The db splits the condition at its top-level and : conditions the loader declares are sent to the backend, and the rest run on the rows the db holds. Calling it again adds conditions.

Preview
where<C>(this: Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>, callback: (row: RowRefs<Row>) => C)
Parameters
Parameters
NameTypeDescription
this
Query<Row, Loaders, Result, Tokens, Eq, Order, list, Local>
callback
(row: RowRefs<Row>) => C
Returns
Query<Row, Loaders, Result, Tokens | ExtractConditionTokens<C>, Eq | ExtractConditionEq<C>, Order, Mode, Local>