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 { 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>;
}
| Name | Type | Description |
|---|---|---|
| runtime | | |
| definition | |
Properties
__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
| Name | Type | Description |
|---|---|---|
| answeredLocally | | Whether rows the db already holds answer the query, with no request |
| error | | |
| kind | | |
| loader | | Index of the loader in the collection's chain |
| local | | Conditions evaluated on the rows the db holds |
| sent | | Conditions sent to the backend |
| syncs | | 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
| Name | Type | Description |
|---|---|---|
| this | |
Returns
Promise<QueryState<QueryData<Result, Mode>>>
getSnapshot()
The current state. It keeps its identity until something changes, as
useSyncExternalStore
expects.
Preview
getSnapshot()
Returns
| Name | Type | Description |
|---|---|---|
| data | |
|
| error | | The last failure, also when a refresh failed and the rows stay |
| hasNextPage | | Whether a paginated query has another page |
| isFetching | | Whether a request for the query is in flight |
| stale | | Whether the rows may be out of date: their subset is stale or its syncs are disconnected |
| status | |
|
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
| Name | Type | Description |
|---|---|---|
| this | | |
| options | |
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: "inner" }
, results without a joined row
are left out. With
{ on: "postId" }
, 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("comments", db.comment, { by: (post) => post.id, on: "postId" })
. 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
| Name | Type | Description |
|---|---|---|
| name | | |
| collection | | |
| by | |
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
| Name | Type | Description |
|---|---|---|
| this | | |
| limit | |
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
| Name | Type | Description |
|---|---|---|
| this | | |
| callback | | |
| direction | |
Returns
Query<Row, Loaders, Result, Tokens, Eq, Order | Name, Mode, Local>
select()
Picks and renames the fields each result holds
Preview
select<Selection>(callback: (row: RowRefs<Row>) => Selection)
Parameters
| Name | Type | Description |
|---|---|---|
| callback | |
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
| Name | Type | Description |
|---|---|---|
| this | | |
| listener | |
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
| Name | Type | Description |
|---|---|---|
| this | | |
| callback | |
Returns
Query<Row, Loaders, Result, Tokens | ExtractConditionTokens<C>, Eq | ExtractConditionEq<C>, Order, Mode, Local>
