Skip to main content
Version: v10.0.0

Overview

@hyper-fetch/db keeps 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 rows returns, or the response's items without it, must be exactly the schema's row. Otherwise the loader returns a RowMismatch and createDb does not compile.
  • fixed declares conditions the endpoint applies on its own, such as { archived: false }.
  • serverOnly names 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 where at its top-level and: 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 in title: { 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, getSnapshot and get work without React. In React, use useLiveQuery.

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.


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));
typeWhat failed
mutationA write the server rejected, or one dropped because a write it depends on was
validationA row or write the collection's schema rejected
loadA load whose mapping threw, such as rows reading a response it did not expect
syncA sync event whose mapping threw. The next events still apply.
outboxA stored write this db cannot replay, or an outbox of another format
persistenceStorage that failed or holds data this version cannot read
subscriberA 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 send db.dehydrate() with the page. See Server rendering.
  • Persisted and dehydrated values are stored as type-tagged JSON, so Date, bigint, Map and Set come back as they were. Other types need a codec in the codecs option of createDb.
  • db.inspect() describes what the db holds, and the devtools plugin's dbs option shows it in the DB Inspector of HyperFlow.