Skip to main content
Version: v10.0.0

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
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>;
}
Parameters
NameTypeDescription
config
CollectionConfig

Properties​

config​

Type
CollectionConfig

__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
Parameters
NameTypeDescription
request
Req
options
IngestOptions<Req, Mapped, Type>
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
Parameters
NameTypeDescription
request
Req
options
LoaderOptions<Row, NonNullable<Row[KeyField]>, Req, Mapped, Where, Order, Cursor, Limit, ByKey, ByKeys, LoaderNotation>
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
Parameters
NameTypeDescription
mutations
{ delete?: DeleteMutation<Row, KeyField, DeleteReq>; insert?: InsertMutation<Row, InsertReq, InsertMapped, InsertSuccess>; update?: UpdateMutation<Row, KeyField, UpdateReq, UpdateMapped, UpdateSuccess> }
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
Parameters
NameTypeDescription
target
{ __types?: { row: TargetRow }; config: CollectionConfig }
extract
(row: Row) => readonly Mapped[]
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
Parameters
NameTypeDescription
node
Node
options
ResourceOptions<Row, Node, Item, Mapped, Filters, Cursor, InsertSuccess, UpdateSuccess> & { list?: ListOption }
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
Parameters
NameTypeDescription
listener
Listener
options
SyncOptions<Row, KeyField, Listener, Type, Mapped>
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
Parameters
NameTypeDescription
listener
Listener
options
SyncChangesOptions<Row, KeyField, Listener, Mapped>
Returns
([Mapped] extends [never] ? true : IsExactRow<Mapped, Row>) extends true ? Collection<Row, Input, KeyField, Loaders, Mutations> : RowMismatch<Mapped, Row>