Collection
A typed set of complete rows, defined by a schema and a key. It declares how its backend loads rows (
load
), keeps
them live (
sync
), feeds them from other responses (
ingest
) and changes them (
mutate
). A collection is
immutable: every method returns a new collection, so it is defined in one chain and passed to
createDb
.
When rows a method reads do not match the row type, it returns a
RowMismatch
instead of a collection, so the chain
and
createDb
do not compile.
import { Collection } from "@hyper-fetch/db"
Parameters
class Collection<Row, Input, KeyField, Loaders, Mutations> {
constructor(config: CollectionConfig) {};
config: CollectionConfig;
__types: { input: Input; key: KeyField; loaders: Loaders; mutations: Mutations; row: Row };
ingest<Req, Mapped, Type>(request: Req, options?: IngestOptions<Req, Mapped, Type>) => IsIngestRow<Row, KeyField, (Inferred<Type, insert> & IngestType), Inferred<Mapped, DefaultRows<Req>>> extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Inferred<Mapped, DefaultRows<Req>>, Row>;
load<Req, Mapped, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>(request: Req, options?: LoaderOptions<Row, NonNullable<Row[KeyField]>, Req, Mapped, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>) => IsExactRow<Inferred<Mapped, DefaultRows<Req>>, Row> extends true ? Collection<Row, Input, KeyField, Loaders | DescribeLoader<Row, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>, Mutations> : RowMismatch<Inferred<Mapped, DefaultRows<Req>>, Row>;
mutate<InsertReq, UpdateReq, DeleteReq, InsertMapped, UpdateMapped, InsertSuccess, UpdateSuccess>(mutations: { delete?: DeleteMutation<Row, KeyField, DeleteReq>; insert?: InsertMutation<Row, InsertReq, InsertMapped, InsertSuccess>; update?: UpdateMutation<Row, KeyField, UpdateReq, UpdateMapped, UpdateSuccess> }) => [IsWriteHandled<InsertReq, IsExactRow<Inferred<InsertMapped, ExtractResponseType<InsertReq>>, Row>, InsertSuccess>, IsWriteHandled<UpdateReq, IsPartialRow<Inferred<UpdateMapped, ExtractResponseType<UpdateReq>>, Row, KeyField>, UpdateSuccess>] extends [true, true] ? Collection<Row, Input, KeyField, Loaders, Mutations & (IsGiven<InsertReq> extends true ? { insert: Input } : {}) & (IsGiven<UpdateReq> extends true ? { update: PayloadChanges<Row, UpdateReq> } : {}) & (IsGiven<DeleteReq> extends true ? { delete: true } : {})> : RowMismatch<ExtractResponseType<InsertReq> | ExtractResponseType<UpdateReq>, Row>;
normalize<TargetRow, Mapped>(target: { __types?: { row: TargetRow }; config: CollectionConfig }, extract: (row: Row) => readonly Mapped[]) => ([Mapped] extends [never] ? true : IsExactRow<Mapped, TargetRow>) extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Mapped, TargetRow>;
resource<Node, Item, Mapped, Filters, Cursor, InsertSuccess, UpdateSuccess, ListOption>(node: Node, options: ResourceOptions<Row, Node, Item, Mapped, Filters, Cursor, InsertSuccess, UpdateSuccess> & { list?: ListOption }) => IsResourceValid<Row, KeyField, Node, Item, Mapped, (ListOption extends false ? false : true), InsertSuccess, UpdateSuccess> extends true ? Collection<Row, Input, KeyField, Loaders | ResourceLoaders<Row, Node, Item, Filters, Cursor, (ListOption extends false ? false : true)>, Mutations & (Node extends { $post: RequestInstance } ? { insert: Input } : {}) & ([UpdateRequestOf<Node, Item>] extends [never] ? {} : { update: Partial<Row> }) & (ItemNode<Node, Item> extends { $delete: RequestInstance } ? { delete: true } : {})> : RowMismatch<unknown, Row>;
sync<Listener, Type, Mapped>(listener: Listener, options: SyncOptions<Row, KeyField, Listener, Type, Mapped>) => IsSyncRow<Row, KeyField, Type, Inferred<Mapped, SyncMessage<Listener>>> extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Inferred<Mapped, SyncMessage<Listener>>, Row>;
syncChanges<Listener, Mapped>(listener: Listener, options: SyncChangesOptions<Row, KeyField, Listener, Mapped>) => ([Mapped] extends [never] ? true : IsExactRow<Mapped, Row>) extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Mapped, Row>;
}
| Name | Type | Description |
|---|---|---|
| config | |
Properties
__types
Type-only carrier of the collection's generics, never set at runtime
Type
{ input: Input; key: KeyField; loaders: Loaders; mutations: Mutations; row: Row }
Methods
ingest()
Writes the rows of another request's responses into the collection, for example a search endpoint or a
useSubmit
whose response is the changed row. The request does not become a loader.
Preview
ingest<Req, Mapped, Type>(request: Req, options: IngestOptions<Req, Mapped, Type>)
Parameters
| Name | Type | Description |
|---|---|---|
| request | | |
| options | |
Returns
IsIngestRow<Row, KeyField, (Inferred<Type, insert> & IngestType), Inferred<Mapped, DefaultRows<Req>>> extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Inferred<Mapped, DefaultRows<Req>>, Row>
load()
Adds a loader: a request plus the way to read complete rows from its response. A list loader declares the filters
and orders it can send and whether it is paginated. A loader with
byKey
or
byKeys
reads rows by key.
Preview
load<Req, Mapped, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>(request: Req, options: LoaderOptions<Row, NonNullable<Row[KeyField]>, Req, Mapped, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>)
Parameters
| Name | Type | Description |
|---|---|---|
| request | | |
| options | |
Returns
IsExactRow<Inferred<Mapped, DefaultRows<Req>>, Row> extends true ? Collection<Row, Input, KeyField, Loaders | DescribeLoader<Row, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>, Mutations> : RowMismatch<Inferred<Mapped, DefaultRows<Req>>, Row>
mutate()
Declares how inserts, updates and deletes reach the backend. Each
map
turns the write into the request's params,
query params and payload. A response that is not the row needs
onSuccess
.
Preview
mutate<InsertReq, UpdateReq, DeleteReq, InsertMapped, UpdateMapped, InsertSuccess, UpdateSuccess>(mutations: { delete?: DeleteMutation<Row, KeyField, DeleteReq>; insert?: InsertMutation<Row, InsertReq, InsertMapped, InsertSuccess>; update?: UpdateMutation<Row, KeyField, UpdateReq, UpdateMapped, UpdateSuccess> })
Parameters
| Name | Type | Description |
|---|---|---|
| mutations | |
Returns
[IsWriteHandled<InsertReq, IsExactRow<Inferred<InsertMapped, ExtractResponseType<InsertReq>>, Row>, InsertSuccess>, IsWriteHandled<UpdateReq, IsPartialRow<Inferred<UpdateMapped, ExtractResponseType<UpdateReq>>, Row, KeyField>, UpdateSuccess>] extends [true, true] ? Collection<Row, Input, KeyField, Loaders, Mutations & (IsGiven<InsertReq> extends true ? { insert: Input } : {}) & (IsGiven<UpdateReq> extends true ? { update: PayloadChanges<Row, UpdateReq> } : {}) & (IsGiven<DeleteReq> extends true ? { delete: true } : {})> : RowMismatch<ExtractResponseType<InsertReq> | ExtractResponseType<UpdateReq>, Row>
normalize()
Writes the rows nested in this collection's rows into another collection, for example the author of a post into
the
user
collection. It runs on every complete write from the server: loads, inserts, ingested responses and
mutation responses. The target is the collection itself, so renaming or removing it breaks the build.
Preview
normalize<TargetRow, Mapped>(target: { __types?: { row: TargetRow }; config: CollectionConfig }, extract: (row: Row) => readonly Mapped[])
Parameters
| Name | Type | Description |
|---|---|---|
| target | | |
| extract | |
Returns
([Mapped] extends [never] ? true : IsExactRow<Mapped, TargetRow>) extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Mapped, TargetRow>
resource()
Derives loaders and mutations from an SDK resource that follows REST conventions:
$get
lists,
item.$get
reads
by key,
$post
inserts,
item.$patch
or
item.$put
updates and
item.$delete
deletes. Path params of the list
endpoint become required
eq
filters, and the query params listed in
list.where
become
eq
filters.
Preview
resource<Node, Item, Mapped, Filters, Cursor, InsertSuccess, UpdateSuccess, ListOption>(node: Node, options: ResourceOptions<Row, Node, Item, Mapped, Filters, Cursor, InsertSuccess, UpdateSuccess> & { list?: ListOption })
Parameters
| Name | Type | Description |
|---|---|---|
| node | | |
| options | |
Returns
IsResourceValid<Row, KeyField, Node, Item, Mapped, (ListOption extends false ? false : true), InsertSuccess, UpdateSuccess> extends true ? Collection<Row, Input, KeyField, Loaders | ResourceLoaders<Row, Node, Item, Filters, Cursor, (ListOption extends false ? false : true)>, Mutations & (Node extends { $post: RequestInstance } ? { insert: Input } : {}) & ([UpdateRequestOf<Node, Item>] extends [never] ? {} : { update: Partial<Row> }) & (ItemNode<Node, Item> extends { $delete: RequestInstance } ? { delete: true } : {})> : RowMismatch<unknown, Row>
sync()
Keeps rows current from a listener.
insert
messages carry complete rows,
update
messages the key and some
fields, and
delete
messages the key. One listener can sync several collections.
Preview
sync<Listener, Type, Mapped>(listener: Listener, options: SyncOptions<Row, KeyField, Listener, Type, Mapped>)
Parameters
| Name | Type | Description |
|---|---|---|
| listener | | |
| options | |
Returns
IsSyncRow<Row, KeyField, Type, Inferred<Mapped, SyncMessage<Listener>>> extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Inferred<Mapped, SyncMessage<Listener>>, Row>
syncChanges()
Keeps rows current from a listener whose events carry several changes at once, such as a Firestore snapshot.
changes
reads the complete rows to write and the keys to delete. With
notation
, the sync covers every subset
by sending its conditions to the listener. Adapter presets such as
firestoreCollection
use it.
Preview
syncChanges<Listener, Mapped>(listener: Listener, options: SyncChangesOptions<Row, KeyField, Listener, Mapped>)
Parameters
| Name | Type | Description |
|---|---|---|
| listener | | |
| options | |
Returns
([Mapped] extends [never] ? true : IsExactRow<Mapped, Row>) extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Mapped, Row>
