Typed Firebase Queries
Typed Firebase Queries
Constraints checked against your documents, and writes you can trust.
const { data } = await getTeas.send({
queryParams: (c) =>
c.where("type", "==", "Green").orderBy("year", "desc").limit(20),
});
A Firestore query is a list of strings and values that nobody checks until it runs. A typo in a field name returns an
empty list, not an error. In HyperFetch 10, @hyper-fetch/firebase and @hyper-fetch/firebase-admin build constraints
in a typed callback, and a long list of fixes makes writes and listeners behave the way the docs always said they did.
This post covers HyperFetch 10. Read the release overview for the rest of the series.
- Typed constraints: a
queryParamscallback checks field names, values and cursors against the document type. - Constraints array:
queryParamstakes the constraints directly, without the{ constraints }wrapper. - Listener query params: listeners filter with the same callback as requests.
- Reliable writes: every write method sends its payload again, in both packages.
- Reliable listeners: each snapshot arrives once, and stopping one listener leaves the others running.
- Tested in CI: the emulator suites of both packages now run on every change.
Typed constraints
Constraints used to be untyped helpers. $where("yaer", ">=", "2020") compiled, ran and quietly matched nothing, and the
only hint was an empty screen.
import type { FirestoreQueryParams } from "@hyper-fetch/firebase";
type Tea = {
name: string;
type: "Green" | "Black";
year: number;
origin: { country: string };
};
const getTeas = client.createRequest<{
response: (Tea & { __key: string })[];
queryParams?: FirestoreQueryParams<Tea>;
}>()({
endpoint: "teas",
method: "getDocs",
});
getTeas.setQueryParams((c) => c.where("year", ">=", 2020)); // ✓
getTeas.setQueryParams((c) => c.where("yaer", ">=", "2020")); // ✗ unknown field, and year is a number
getTeas.setQueryParams((c) => c.where("origin.country", "==", "Japan")); // ✓ nested fields use dots
The chain follows Firebase's own rules in its types:
wherechecks the value against the field, so"in"takes an array and"array-contains"takes one element.- Firestore cursors take one value per
orderBy, in order.orderBy("year").orderBy("name").startAfter(2023, "Sencha")compiles, a third value does not. - A Realtime Database query allows one
orderBy*, and its cursors andequalToare typed by the ordered value.
import type { RealtimeDBQueryParams } from "@hyper-fetch/firebase";
type Message = { text: string; sentAt: number };
const getMessages = client.createRequest<{
response: (Message & { __key: string })[];
queryParams?: RealtimeDBQueryParams<Message>;
}>()({
endpoint: "rooms/general/messages",
method: "get",
});
const { data } = await getMessages.send({
queryParams: (c) => c.orderByChild("sentAt").limitToLast(50),
});
The callback runs the moment you set it, and the request stores the constraints it returns. Cache keys, query keys and
toJSON() only ever see plain data, so each combination of filters gets its own cache entry. Rules the types cannot see, such as a missing composite index, come back in response.error.
This works through two new hooks: setQueryParamsResolver() on the core Adapter and
setListenerQueryParamsResolver() on the SocketAdapter. Custom adapters can use them to accept their own query params
callbacks.
Constraints as an array
Some queries are built step by step, from filters a user toggles on screen. A callback is awkward there, and the old
{ constraints: [...] } wrapper was a key with nothing beside it.
import { $orderBy, $where } from "@hyper-fetch/firebase";
import type { FirestoreConstraint } from "@hyper-fetch/firebase";
const constraints: FirestoreConstraint[] = [];
if (onlyGreen) constraints.push($where("type", "==", "Green"));
constraints.push($orderBy("year", "desc"));
getTeas.setQueryParams(constraints);
The array is what the callback resolves to, so both forms share the cache. Constraints apply in order. RealtimeDBConstraint
types the Realtime Database helpers, such as $orderByChild and $limitToLast, and mixing the two databases' helpers is
a type error.
Listeners use the same query params
Listeners took their constraints in options, apart from everything else that described the query. Now they use the
same setQueryParams as requests.
import { Socket } from "@hyper-fetch/sockets";
import { FirebaseSocketsAdapter } from "@hyper-fetch/firebase";
const socket = new Socket({
url: "",
adapter: FirebaseSocketsAdapter(getFirestore(app)),
});
const onGreenTeas = socket
.createListener<(Tea & { __key: string })[]>()({
topic: "teas",
options: { groupByChangeType: true },
})
.setQueryParams((c) =>
c.where("type", "==", "Green").orderBy("year", "desc").limit(20),
);
onGreenTeas.listen(({ data, extra }) => {
render(data); // the full current result, every time
extra.status; // "success" or "emptyResource", now typed
});
options keeps what is not part of the query: groupByChangeType for Firestore and onlyOnce for Realtime Database.
useListener from @hyper-fetch/react takes the listener as it is.
Upgrading
Nothing breaks. The { constraints } object on requests and options.constraints on listeners still work and are
marked @deprecated, so your editor points at every place to update.
const { data } = await getTeas.send({
queryParams: {
constraints: [$where("type", "==", "Green"), $orderBy("year"), $limit(20)],
},
queryParams: (c) => c.where("type", "==", "Green").orderBy("year").limit(20),
});
const onGreenTeas = socket
.createListener<Tea[]>()({
topic: "teas",
options: { constraints: [$where("type", "==", "Green")] },
})
.setQueryParams((c) => c.where("type", "==", "Green"));
To keep the $-helpers, pass the array itself: queryParams: [$where("type", "==", "Green"), $limit(20)]. Field names
are checked only by the callback on a request typed with FirestoreQueryParams<Doc> or RealtimeDBQueryParams<Doc>.
Reliability fixes
The emulator suites of both packages had been left out of CI, and they had drifted. Each fix below came with a spec that failed first, and both suites now run in CI on every change, with the release waiting for them.
- Writes send the payload.
setDoc,addDoc,updateDoc,set,pushandupdatesentundefinedsince v7. They send the payload again, in@hyper-fetch/firebaseand@hyper-fetch/firebase-admin. - Each snapshot arrives once. Socket listeners delivered every snapshot twice.
- Stopping a listener stops only that listener. In
@hyper-fetch/firebase-admin, unsubscribing a Realtime Database listener removed everyvaluelistener on the same path. - Cursors match. Firestore cursors with several values matched nothing, and Realtime Database cursors dropped the
optional key. Both now reach Firebase as written, and
$equalTotakes the optional key too. - Document listeners with
groupByChangeTypedeliver again, withextra.groupedResultset tonull. Collection listeners keep theadded,modifiedandremovedgroups. extra.statusis typed on Firestore and Realtime Database listeners.- Realtime Database requests default to
get. A request without amethodused to fail, and a method the database does not have now resolves withstatus: "error". - Types come from
firebase. The published declarations no longer import the internal@firebase/*packages, so projects that install onlyfirebasetypecheck.
The docs were rewritten alongside the fixes, with every example checked against the emulator or the type checker.
Learn more
Try it in the Firebase example.

