Temporal values

A field stays nullable until you call .required(). OpenAPI widens the type of a nullable field to ["string", "null"]. The format does not change.

Every rule below is about f.datetime() unless it names another type. The other two need no wire handling, because a string survives a JSON hop unchanged.

import { collection } from "#questpie/factories";

export const events = collection("events").fields(({ f }) => ({
	startsAt: f.datetime().required(),
	dateOnly: f.date().required(),
	opensAt: f.time(),
}));

Writing

The datetime schema is a union of z.date() and an RFC 3339 string. That string must carry a zone, and it becomes a Date before the write. The date schema is z.string().date(), which takes that one string shape and nothing else.

QUESTPIE never guesses a timezone. An offset-less string is a validation error. It is never read as local time on whichever machine ran the write.

Filtering

eq, ne, not, gt, gte, lt, lte, in and notIn normalize their operand before the query is built.

in and notIn normalize each element. not: null passes through as a null check. isNull and isNotNull are outside the set. A field carrying .array() skips normalization entirely.

Reading

Every read parses stored datetime values back into Date. That covers values nested in an f.object() and items inside .array(). A null passes straight through. A stored value that does not parse as an instant throws a TypeError before it reaches your code. Date and time values pass through untouched.

Typed HTTP

createClient() opts into the typed envelope by default. Nested Date values survive the hop, and a string that merely looks like a timestamp stays a string.

const startsAt = new Date("2026-10-25T00:30:00.456Z");
const created = await client.collections.events.create({
	startsAt,
	dateOnly: "2026-10-25",
});

created.startsAt instanceof Date; // true
created.startsAt.getTime() === startsAt.getTime(); // true
created.dateOnly; // "2026-10-25"

createClient({ useSuperJSON: false }) is the plain-JSON mode. Requests go out as JSON.stringify output and datetime values come back as RFC 3339 strings. Any caller that never asks for the envelope gets that same plain contract. A client built from your OpenAPI spec is one of them.

For a JSON boundary your own code owns, questpie/shared exports stringifyTypedWire() and parseTypedWire(). Use the pair together.

Realtime and Channels

SSE frames, ordered Channel events, Channel replay and Pusher presence member info share one codec. It leaves JSON.stringify output as it was. It then adds one reserved top-level key, __questpieTypedWire, holding a wire version and the exact paths that were Date.

Wire version 1 is the only one accepted. The codec fails closed. On the way out it throws when the payload already carries the reserved key. On the way in it throws on any of four faults.

• an unknown version
• a malformed or duplicated path
• a marked value that is not its own toISOString()
• more than 16,384 marked paths

A normal string is never revived by appearance.

The 10,000-byte Channel event limit is measured on the envelope with the metadata in it.

Query realtime over Pusher or Soketi carries invalidation notices on questpie:invalidate rather than rows. The Date arrives with the typed HTTP refetch that follows.

TanStack and SSR

@questpie/tanstack-query receives the typed client's values. dehydrate() keeps Date instances in JavaScript state. The package pins one hydration path with a test: dehydrate, Seroval round trip, hydrate. The Date survives and an ISO-looking string stays a string.

@questpie/tanstack-db writes find() and live-snapshot docs straight into the collection. No JSON clone stands between the row and your query.

A JSON-only hop you add yourself is yours: a cookie, a script tag, your own cache. Use a serializer that keeps Date, such as the typed-wire pair.

Related

f.datetime() is the field itself, its two config keys, its methods and its admin control.

f.date() is the calendar day.

f.time() is the clock reading.

Client SDK covers createClient() and the rest of its config.

Channels covers the ordered event surface this codec carries.

Arrays covers what .array() does to columns and operators.