API reference

Look up package entrypoints, query states, configuration defaults, and runtime limits below. For the database query builders themselves, see Read and write data.

Schema-bound constructors, callables and the direct database come from your generated modules. Input<typeof fn> and Output<typeof fn> work with declarations, generated callables and optimistic wrappers. Output describes resolved data rather than an invocation handle; query results are recursively readonly.

Import defineConfig from @hulla/db/config. The shipped config and browser startup accept different kinds of connection address:

Keep the two URLs separate from user/session state. See the service setup and authentication guide.

Both query and mutation accept { input?, handler, output?, limits? }, or a handler alone. Handlers receive (ctx, input). Queries get ReadDatabase; mutations get WriteDatabase. Both receive identity from the configured credential verifier, or null for an anonymous caller.

.extend(handler) and .extend({ input?, handler }) prepare context/input in declaration order. They cannot set limits or output validation. Returned context keys cannot overwrite reserved or previously prepared keys. Parsed input keys cannot be redeclared by another stage or the final input schema. See queries and mutations.

No-input functions omit the input argument. Query call options accept a signal; submitted mutations do not accept cancellation signals or a per-call optimistic mode. Handles are thenables: use await or Promise.resolve(handle) when you need a standard promise’s methods.

Optimistic targets

Pass target objects to mutation.withOptimistic(...targets). Each identifies a query and returns its replacement result through update:

update(current, mutationInput, queryInput) receives the selected query result and typed inputs. A match target needs no input mapper. Only already-cached results are predicted; the mutation still returns its server-confirmed result. See optimistic updates for complete examples.

Query states

status is pending, success or error. Success includes data; pending/error may retain data according to lifecycle and error policy. isStale marks a result that is not current, and isOptimistic marks predicted data.

Mutation states

status is pending, recovering, success or error. Success includes data; error includes error. Framework mutation bindings start at idle before the first call. recovering checks the original submitted result; it does not rerun the mutation. See live result behavior.

database.client takes a public service url, optional credentials mode and timeouts. Generation emits lazy browser setup. Use generated setHeaders for current bearer credentials. Call setAuth(null | { key, expiresAt? } | promise) when provider state changes. expiresAt is optional Unix milliseconds. No manual loading status is needed.

Inactive query results have a five-minute grace period, bounded to 128 entries and 16 MiB of encoded keys/results. Active queries remain pinned. A fresh browser page has no persisted result cache. One live set supports 128 distinct queries; loaded page ranges share that budget. Separate tabs have separate caches.

Configure defaults in defineConfig({ limits }) and optional per-function overrides on final declarations. These bound server work, not network latency:

Read budgets count fetched rows/payloads, including write returning data; they do not count every row scanned by PostgreSQL. Combined live rounds and page lists have additional bounds. See pagination.

Intentional DatabaseError({ code, message, details? }) instances preserve their fields across calls, subscriptions and mutation failure recovery. Details must be JSON-safe and the serialized payload must fit in 16 KiB. Larger errors fail with execution_limit. Stack traces, causes, ordinary exceptions and native database diagnostics remain private. Only declare information safe for the caller. Application codes never control transport retries or cache identity.

Declared mutations can retry confirmed serializable conflicts up to three times after the first attempt. Direct db.transaction defaults to zero retries; opt in per call. Neither replays arbitrary application failures or uncertain commits. A mutation confirmation timeout is not proof of rollback.

Most applications use generated code instead of constructing these pieces:

Generated code imports its binding factories, declaration constructor and worker installer through internal package entrypoints. Applications do not import or configure those pieces. The entries above support programmatic generation, direct database integrations and custom UI bindings. The native Rust facade has its own authoring and runtime guide.