Overview
@hyper-fetch/dbkeeps your data in typed collections, one row per record, fed by the requests and socket listeners you already have. Components query collections instead of endpoints, and every write reaches every query that shows the row.
When to use it
Use the db when the same data shows in several views, changes from several places such as mutations, sockets and other
users, or has to work offline. For screens that each show their own data, useFetch is simpler.
A request used by both useFetch and a collection keeps two copies of its data, one in the Cache and one in the
collection, and they do not update each other.
Collections
A collection is a typed set of complete rows, defined by a Standard Schema such as a Zod, Valibot or ArkType schema, and a key. Every row has every field of the schema, so a query can use any of them.
import { collection, createDb, rowType } from "@hyper-fetch/db";
const Post = collection(PostSchema, { key: "id", version: "updatedAt" });
const Draft = collection(rowType<Draft>(), { key: "id" }); // no schema, writes are not validated
const db = createDb({ post: Post, draft: Draft });
When a list returns summaries and a detail returns more fields, they are two collections, such as postSummary and
post. version names a field that grows with every change on the server: a write never replaces fields with a newer
version.
Loaders
A loader is a request plus the way to read complete rows from its response. A list loader declares the operators each
field can send and whether it is paginated. A loader with byKey or byKeys reads rows by key.
const Post = collection(PostSchema, { key: "id" })
.load(getTeamPosts, {
rows: (response) => response.data.items,
where: {
teamId: { eq: (teamId) => ({ params: { teamId } }), required: true },
likes: { gt: (likes) => ({ queryParams: { likes_gt: likes } }) },
},
orderBy: {
createdAt: (direction) => ({
queryParams: { sort: `createdAt:${direction}` },
}),
},
})
.load(getPostsByIds, { byKeys: (ids) => ({ queryParams: { ids } }) });
- The rows
rowsreturns, or the response's items without it, must be exactly the schema's row. Otherwise the loader returns aRowMismatchandcreateDbdoes not compile. fixeddeclares conditions the endpoint applies on its own, such as{ archived: false }.serverOnlynames fields the backend compares differently from the client, so queries on them are never answered from rows the db holds..resource(sdk.posts, { item: "$postId" })derives the list, the by-key loader and the mutations from REST conventions of an SDK resource.
Queries
import { and, eq, gt } from "@hyper-fetch/db";
const query = db.post
.where((post) => and(eq(post.teamId, 1), gt(post.likes, 10)))
.orderBy((post) => post.createdAt, "desc")
.select((post) => ({ id: post.id, title: post.title }));
query.explain(); // the loader, what is sent, what runs locally and which syncs keep it live
- The db splits
whereat its top-leveland: conditions the loader declares go to the backend, the rest run on the returned rows. - A query that sets no loader's required filters does not compile. A paginated loader has to send every condition and order of a query.
findOne(key)reads a row by key, and.local()reads only rows the db holds.op("search", post.title, text)is a server-only operator, such as full-text search. The loader maps it like any operator, as intitle: { search: (text: string) => ({ queryParams: { q: text } }) }, and a query that uses one must send it. Its subset never answers other queries, and a new row marks it stale instead of joining it.- For lists that grow page by page, see
useLiveInfiniteQuery. subscribe,getSnapshotandgetwork without React. In React, useuseLiveQuery.
Syncs and ingest
const byTeam = { teamId: { eq: (teamId) => ({ params: { teamId } }) } };
collection(PostSchema, { key: "id" })
.sync(onPostCreated, { type: "insert", where: byTeam })
.sync(onPostChanged, { type: "update", where: byTeam })
.sync(onPostDeleted, { type: "delete", where: byTeam })
.ingest(searchPosts, { rows: (response) => response.results });
insert messages carry complete rows, update messages the key and changed fields, delete messages the key. A loaded
subset is fresh while its syncs deliver all three, and refetches after a reconnect unless the sync resumes.
Related data
const db = createDb({ post: Post, postSummary: PostSummary, user: User }, { links: [["post", "postSummary"]] });
db.postSummary.where((post) => eq(post.teamId, 1)).join("author", db.user, (post) => post.authorId);
Links keep two shapes of the same record in step, normalize writes nested records into their own collections, and
joins add the related row to each result. See Related data. For Firestore,
firestoreCollection declares a whole collection in one call, see Firestore.
Writes
collection(PostSchema, { key: "id" }).mutate({
update: {
request: updatePost,
map: (key, changes) => ({ params: { postId: key }, payload: changes }),
},
delete: {
request: deletePost,
map: (key) => ({ params: { postId: key } }),
onSuccess: "keep",
},
});
const result = await db.post.update(1, { title: "Renamed" });
A write shows at once as an optimistic layer and reverts exactly what it changed when it fails. Writes to one row go
out in order. A response that is not the row needs onSuccess: "keep", "refetch" or "sync". Like send(), a
write never rejects.
With offline: true, writes go through a persisted outbox that one tab replays in order. Each write's id is passed to
map, so it can be sent as an idempotency key.
Several writes that belong together go in one transaction, kept or reverted as a whole. An insert of a key the db already holds, and an update that changes a row's key, resolve with an error and send nothing.
Errors
Requests, writes and queries never throw. What fails is reported to db.onError:
db.onError(({ type, error, collection }) => report(type, error));
type | What failed |
|---|---|
mutation | A write the server rejected, or one dropped because a write it depends on was |
validation | A row or write the collection's schema rejected |
load | A load whose mapping threw, such as rows reading a response it did not expect |
sync | A sync event whose mapping threw. The next events still apply. |
outbox | A stored write this db cannot replay, or an outbox of another format |
persistence | Storage that failed or holds data this version cannot read |
subscriber | A query listener that threw. The other listeners are still notified. |
A failed load keeps the rows the query showed and sets error on it, and the next refetch tries again.
Server rendering and devtools
- On the server, create a db per request, load with
query.get()and senddb.dehydrate()with the page. See Server rendering. - Persisted and dehydrated values are stored as type-tagged JSON, so
Date,bigint,MapandSetcome back as they were. Other types need a codec in thecodecsoption ofcreateDb. db.inspect()describes what the db holds, and the devtools plugin'sdbsoption shows it in the DB Inspector of HyperFlow.
