Create an extension
Build a typed extension from the narrowest parts that do the job
An extension is one named, immutable contribution to a client. Pick the part
that owns the boundary you need, add only that part, and apply the extension
with $extends().
What an extension is
extension(name, ...parts) builds an extension. client.$extends(extension)
returns a new client that carries it:
import { around, extension } from "viborm";
const timing = extension(
"timing",
around((c) => async (run) => {
const startedAt = performance.now();
try {
return await run();
} finally {
const subject = c.model ?? c.kind;
console.info(`${subject}.${c.operation}: ${performance.now() - startedAt}ms`);
}
})
);
const measured = client.$extends(timing);
measured is a new client. client remains unchanged, and both clients share
the same schema, driver, and pool.
- One spelling.
$extends()takes an extension value and nothing else: no object literal, no function of the client. An official extension is a function that returns an extension, applied the same way:client.$extends(softDelete(config)). - A name. It must be non-empty and unique inside one chain.
- Up to eight parts, in order. Each part is built by a function imported
from
viborm. A part sees what the parts before it in the same extension declare, so putargs(...)before theruleor thecallthat reads those arguments. The types take eight parts; split a larger extension in two. - Two parts of one kind in one extension compose as two extensions would: each is a layer, filters conjoin, and a default set later wins.
Write the extension inside $extends(...) when it names models or
operations: every handler, filter and default is then typed from the client
it is applied to. An extension that names no model (timing above) can be
written anywhere. To write a model-specific extension away from its client,
see Extensions written apart.
A part pays only for itself
What you do not import is not in your bundle. Each part, and each word you use inside a part, brings the code that runs it and nothing else; the client names no optional capability, so an application that applies no extension carries none of this code.
Each row below is one extension made of that part alone (with the words it names) applied to a PostgreSQL application, and what it adds to that application’s bundle, minified and gzipped. The rows do not add up: parts share the chain’s own code, so a second part costs less than its row.
| You import | Your bundle carries | Adds (min) | Adds (gzip) |
|---|---|---|---|
methods |
Client method factories and their collision checks | 2.4 kB | 1.2 kB |
args, oneOf |
Argument admission: taken out of the call, validated once | 3.1 kB | 1.4 kB |
call, target(reads) |
The chain, the first moment: argument patches and refusals | 3.4 kB | 1.6 kB |
fields |
Computed fields: planning their needs, attaching them to rows | 4.5 kB | 1.9 kB |
unit |
The runner around physical units | 4.9 kB | 2.1 kB |
unit with { rewrites: true }, statement |
Statement rewriting | 5.0 kB | 2.1 kB |
defaults with create or orderBy |
Default data or default order, without filter code or argument admission | 5.2 kB | 2.3 kB |
defaults with omitted |
Default omission | 5.5 kB | 2.4 kB |
around |
The second moment around the prepared call, and the admission of $transaction([...]) members |
6.6 kB | 2.8 kB |
around with again |
Making a failed call again | 6.8 kB | 2.9 kB |
around, target(reads) |
The second moment, on the calls a target selects | 6.9 kB | 3.0 kB |
call, target(writes), watch, settled |
The rows a write wrote, the hook after its commit | 7.1 kB | 3.1 kB |
rule with root and related filters |
Row filters, prepared once per schema | 7.9 kB | 3.5 kB |
rule with args, when, arg |
Row filters that read an argument, folded per call | 14.5 kB | 6.0 kB |
rule with keep, now |
Kept deleted rows | 14.6 kB | 6.2 kB |
rule with gate |
Gated fields | 15.4 kB | 6.6 kB |
rule with check |
The judgement of the rows a write produces | 17.8 kB | 7.3 kB |
The official extensions, measured the same way:
| Extension | Adds (min) | Adds (gzip) |
|---|---|---|
defaultOmit() |
5.7 kB | 2.2 kB |
on() |
9.7 kB | 3.9 kB |
instrumentation() |
14.8 kB | 5.4 kB |
softDelete() |
20.6 kB | 8.1 kB |
cache() |
26.9 kB | 10.1 kB |
ordering() |
26.9 kB | 11.0 kB |
permissions() |
63.3 kB | 24.9 kB |
on, ordering, permissions and softDelete together |
99.1 kB | 38.4 kB |
The PostgreSQL application they are added to weighs 508.1 kB minified (168.0 kB gzip) and carries 646 bytes of this code, chiefly how a transaction scope runs. The figures are those of this release; later releases may lower them.
An extension that only patches or refuses arguments (call) does not pay
for the second moment. A rule made of where filters alone does not pay for
the judgement of written rows, gated fields or kept rows.
Choose the narrowest part
Six primitives build an extension (call, unit, args, rule, defaults,
methods). around is call with a second moment, modelMethods is
methods for model delegates, fields adds computed fields, and
disclosure says what a thrown error may carry:
| Need | Part | Contract |
|---|---|---|
| Patch or refuse a call’s arguments | call |
Synchronous shallow patch, before validation |
| Wrap one prepared logical call | around |
Asynchronous continuation around execution |
| Receive the rows a write wrote, act after its commit | call with watch, settled |
Rows once every write of the call is made; a function after the durable commit |
| Make a failed call again, send a read elsewhere | around with again, via |
Allowed only where nothing was written; reads outside a transaction |
| Store answers beside the database | around with key, codec, database |
A key per prepared statement, the driver’s rows of the answer stored as JSON data; the official cache’s stale-while-revalidate is its own value, staleWhileRevalidate from viborm/cache |
| Observe physical work | unit |
Around a real unit: next() lets it run and returns its end |
| Emit and present work of your own | work, note, notes; database, VIBORM_VERSION |
A unit of your own kind; the official instrumentation traces and logs it from its notes |
| Present a failure in a log or a span | unit with failure, disclosed |
A copy of the error with what the application’s disclosure allows |
| Rewrite a statement | unit with { rewrites: true } |
Trusted Sql → Sql, before rendering |
| Run SQL as a transaction opens | unit on "transaction" with run |
First in every transaction |
| Accept a new call argument | args with oneOf, accepts, bound |
Declared, validated once; only your parts and the chain’s rules read it; a bound one comes from the client ($bind) |
| Hide rows, judge writes, gate fields, keep deleted rows | rule |
Per model, in the ORM’s own where and data; binds the caller |
| Confine the sets your predicates compute | rule with confine: within(where) |
What every row of a set computed over the whole table holds; takes rows away, never adds |
| Order reads, write fields, omit fields by default | defaults |
Per model; holds when the caller says nothing, and the caller can override it |
| Add client methods, model methods | methods, modelMethods |
A factory returning $-prefixed client methods; a factory returning each model’s methods |
| Add fields computed from a row | fields |
needs and compute per field; on every row of the model a call returns |
Do not put every concern into around. Each part exposes only the facts
and authority appropriate to its boundary, and carries only its own code.
call: a function on a call
call(handler, target?) runs handler once per call it concerns,
synchronously, before validation. This is the first moment:
import { call, extension, target } from "viborm";
const db = client.$extends(
extension(
"bounded-reads",
call((c) => {
c.set({ take: Math.min(c.args.take ?? 100, 100) });
}, target("post", "findMany"))
)
);
On c |
Meaning |
|---|---|
c.kind |
"model" or "raw" |
c.model, c.operation |
The model (absent on a raw query) and the operation |
c.schema |
The schema the extension is applied to |
c.args |
The call’s arguments, read-only and shallow |
c.values |
The values of the arguments this extension declares (args), and only those |
c.set(patch) |
Merges a shallow patch into the arguments |
throw |
Refuses the call, before any validation |
- The patch is merged over the current arguments, then validation runs. Later extensions’ first moments see earlier patches.
c.setrefuses a key that decides the shape of the result (select,include,omit, count and aggregate selectors,groupBy.by) and the name of an extension argument, with aQueryError. VibORM keeps the caller’s exact result shape. A raw query’s arguments cannot be patched:c.setis refused there too.- The read-only contract is shallow. Nested caller values are borrowed, so
build a patch instead of mutating
c.argsor anything inside it. - The handler is synchronous. A handler that returns a promise, or returns a
function, is refused with a
QueryError: returning a function is whataroundis for. - What the handler throws refuses the call: a VibORM error as it is, any
other error as the cause of a
QueryErrorthat names the extension.
Use call for argument defaults, normalization and refusals. A root filter
alone is not complete authorization: nested relations, writes, raw SQL, and
field use require a graph-wide policy
(viborm/permissions).
A call part sees only the calls its target selects. One that masks a field of
user.findMany does not run for user.findFirst, nor for users read through
include or select from another model, so the field still reaches those
results. To hide a field by default from every result of a client, use
omitted or
defaultOmit(), which apply to root results and
nested relation payloads alike.
Which calls: target
Without a target, a call part runs for every model operation and for raw
queries (c.kind === "raw"), so a refusal written with call holds for
$executeRawUnsafe too. target(...) narrows it:
| Selector | Calls |
|---|---|
target("post", "findMany") |
One model, one operation |
target("post", ["findMany", "findFirst"]), target(["post", "user"], reads) |
Models, with a list or a set of operations |
target(reads), target(writes), target(deletes) |
A set of operations on every model |
target(selecting) |
Every operation that selects rows: all but create and createMany |
target(models) |
Every model operation, and no raw query |
target is typed against the client: a misspelt model or operation is
refused in your editor, on the string itself, and by $extends() when it
runs. (It is not called on: that name is
viborm/on’s.)
The second moment: around
around(handler, target?, options?) is a call part whose first moment may
return a function that wraps the prepared call. That function runs after
validation and preparation:
import { around, extension, target } from "viborm";
const db = client.$extends(
extension(
"around-posts",
around((c) => async (run) => {
beforeRead(run.mode, run.input);
const posts = await run();
afterRead(posts.length);
return posts;
}, target("post", "findMany"))
)
);
around is its own import, not a member of call: a program that only
patches or refuses calls does not carry the code of the second moment.
On run |
Meaning |
|---|---|
run() |
Executes the call and resolves to its result |
run.input |
The validated arguments, detached |
run.mode |
"direct", "transaction" or "array" |
run()at most once, unlessagain(run)allows another. Writes, raw queries and every member of$transaction([...])must call it. A read outside an array may return without it, to answer in its place.- The child is authoritative. Once
run()starts, its result or its error stands. After a successful child, the handler’s returned value is published, so a handler can map or mask those rows. A child that fails fails the call with its error, whatever the handler returns or throws after. There is no aggregated error. An error your handler throws after a successful child is rethrown unchanged; a value that is not anErroris the cause of aQueryErrornaming the extension. - Typed by one result when the target names one model and one
operation. Then
run()resolves to that operation’s result on the client the extension is applied to (its rules, omissions and computed fields included), and a handler cannot return another result. Without a target, or for several operations, the result is opaque: return whatrun()returns. - Nested in chain order. The first extension applied is the outermost.
{ inner: true }places a part closest to the core instead, whatever the order of the chain; it is for a part that may answer in place of the core (a cache), so every other part still sees each call. - One late run. A direct read may call
run()again after its handler has returned, for stale-while-revalidate: that replay executes the core alone, no other part sees it, and the call does not wait for it. - In
$transaction([...]), every member finishes its first moments and reachesrun()in its second before any driver work. A refusal, a secondrun(), a late detached call or a rejected handler aborts the array, and nothing is sent.
Receive the rows a write wrote: watch
watch(c, watcher), called in the first moment, asks for the rows the call
writes:
import { call, extension, settled, target, watch, writes } from "viborm";
const outbox = extension(
"outbox",
call((c) => {
const rows: { model: string; kind: string; row: object }[] = [];
watch(c, {
// Rows nobody wants are not read.
wants: (model, kind) => model === "order",
// Whole rows, once every write of the call is made.
rows(model, kind, written, nested) {
for (const row of written) rows.push({ model, kind, row: structuredClone(row) });
},
});
// After the commit. Awaited before the call's promise resolves.
settled(c, async ({ certainty }) => {
await publish(rows, certainty);
});
}, target(writes))
);
wants(model, kind)says which rows to show:kindis"create","update"or"delete". A call nothing wants a row of sends exactly the statements it sends unwatched. A wanted row is read through the write’s ownRETURNINGwhere the database has one.rows(model, kind, rows, nested)receives every scalar field of each row: as the write left it, or as it was before a delete. The call’s own rows come first, then the rows its nested writes reach (nestedistrue), in write order.kindis what happened: an upsert reports"create"or"update", and a delete that a rule turns into an update (keep) reports"update". The values are also the caller’s, so copy what you keep.watchandsettledwork in the first moment of a model call, in acallor anaroundwhose target is a set of writes:target(writes),target(deletes), ortarget("order", writes). The set brings what tells them, so a part that never watches carries none of it. Anywhere else they are refused with aTypeError, never ignored (a raw query’ssettledin anaroundwith no target excepted, below):target("order", "update")names an operation, not a set, and brings nothing that watches.- A call that fails calls neither
rowsnorsettled, with one exception: a write whose statement failed after it was sent may have committed, sosettledis told (certainty: "may-have-committed") androwsis not. Several extensions can watch; each is told in the order the extensions were applied.viborm/onis built on this word.
Act after the commit: settled
settled(c, fn), called in the first moment, runs fn(outcome) when the
write is durable: after the call’s own commit, after the outermost commit
inside a transaction, and never after a rollback. outcome.certainty is
"committed", or "may-have-committed" when a statement failed after it was
sent and the write may have been made: fn is told of that write too, so a
cache invalidates for it.
- VibORM awaits it before the call’s promise (or the transaction’s) resolves.
A VibORM error it throws rejects that promise as it is; anything else,
a value that is not an
Errorincluded, is the cause of aQueryError. The write is not undone. - Every function runs, in chain order, those of one extension included, whatever an earlier one did. The first failure rejects the call.
- In an
aroundwith no target,settledalso hears$executeRawand$executeRawUnsafe, which may have written anything. settled(scope, fn)in a method runsfnat once outside a transaction, and returns its promise; inside one it runs after the outermost commit, and its failure rejects that transaction’s promise.- Inside a transaction, what
settledregisters waits in that transaction until it ends, whatever else the client carries: a savepoint rolled back drops it, and the outermost commit tells it. The word brings that code: an extension that never importssettledcarries none of it.
Make a failed call again: again
again(run), in the second moment, is true when the call may be made again:
outside a transaction, not a member of $transaction([...]), and with nothing
written or possibly written. Only then may run() be called again:
import { again, around, extension } from "viborm";
const resilience = extension(
"resilience",
around(() => async (run) => {
for (let attempt = 1; ; attempt++) {
try {
return await run();
} catch (error) {
if (attempt >= 3 || !again(run) || !isRetryableError(error)) throw error;
}
}
})
);
Bound it yourself: VibORM allows another run as long as again answers
true. A call inside a transaction is never made again (the transaction is
the caller’s to make again), nor a write that committed or may have. A write
sent as one statement outside a transaction that fails is held to be possibly
made, so it is not made again, unless its failure proves it was not (a key
already taken, UniqueConstraintError): reads are made again, and so are
writes whose own transaction rolled back.
Send a read to another driver: via
via(run, driver), in the second moment, executes a read outside a
transaction on another driver and resolves to its result. Anywhere else it
executes the call where it goes:
import { around, extension, reads, target, via } from "viborm";
const replicas = extension(
"replicas",
around(() => (run) => via(run, replica), target(reads))
);
The driver must be of the client’s dialect and hold the same schema. Writes,
reads inside a transaction and raw queries are never routed: via then runs
the call where it would have run.
Store answers: key, codec, database
Three words serve an extension that stores answers beside the database, as the official cache does:
import { around, codec, database, extension, key, reads, target } from "viborm";
const answers = new Map<string, unknown>();
const memo = extension(
"memo",
around(
(c) => async (run) => {
const id = key(run);
if (id === undefined) return run(); // nothing to key: run it
const { dialect, namespace } = database(c);
const slot = `${dialect}:${namespace ?? ""}:${id}`;
const rows = codec(run);
if (answers.has(slot)) return rows.materialize(answers.get(slot));
const value = await rows.run(); // runs it, keeping the driver's rows
answers.set(slot, rows.snapshot());
return value;
},
target(reads),
{ inner: true }
)
);
key(run)is the canonical key of the prepared call: the model, the operation, the validated arguments and the statement the engine will send, text and parameters. Two calls have the same key exactly when they would send the same statement for the same arguments. Reading it prepares the call, andrun()sends exactly that preparation, so a value its caller changes later changes neither.- A rule enters the key through the statement it produces, and an argument a
rule reads through that rule. An argument read only by your own parts
(
c.values) is not in the key: declare it.volatile()when answers depend on it. key(run)isundefinedfor a raw query, on a chain with a unit that rewrites statements, for a call that carries a value of a.volatile()argument, and for an operation that is not one statement (a write, a read that needs several).codec(run)stores a read’s answer as the rows the driver returned for its one statement, and restores it.run()executes the call asrundoes and keeps those rows;snapshot()gives them as JSON data (a value JSON cannot carry, such as a bigint, aDateor bytes, written as a tagged array), and throws aTypeErrorwhen the lastrun()kept no rows or a row holds a value it cannot store;materialize(stored)hands stored rows to the driver’s result parser and the engine’s decoder, as if the driver had just returned them, and gives a fresh answer on every call. It throws whenstoredis not such rows or the decoder refuses a value. A call that is not a model’s read (a raw query, a write) has none:codecrefuses it with anUnsupportedOperationError.database(x), on a first moment’sc, arunor a method’s scope, gives the database’sdialectand SQLnamespace(a PostgreSQL schema, a MySQL database;undefinedwhere the dialect qualifies nothing) and thedriverName(pg,postgres,mysql2, …), never a connection string. Partition what you store by it when one store serves several databases; name the database in your own telemetry with it.VIBORM_VERSIONis the version of thevibormpackage: name the library in your telemetry with it, or partition stored data written by one release from another’s.
unit: around physical work
unit(handler, kinds?, options?) runs handler(u, next) around each unit of
real work: operation, statement, batch, transaction, savepoint,
connection, and the kinds extensions emit (the official cache emits
cache). A kind is an open string. Without kinds, every kind.
import { extension, failure, unit } from "viborm";
const durations = extension(
"durations",
unit(async (u, next) => {
const end = await next();
record(u.kind, u.model, u.operation, end.status, end.duration, failure(u));
return end;
})
);
next()exactly once. The unit’s work starts only whennext()is called, and VibORM awaits the handler’s promise. Its end hasstatus,duration,certaintywhere there is a commit, andrecovered. It is never the application’s result.- A unit that throws fails the call. VibORM does not contain a unit’s faults: an observer contains its own. Its synchronous code runs on the application thread, and its promise is awaited, so keep it small.
- Facts are read on demand. A word reads a fact of the unit; a fact no word
reads is never produced (a parameter snapshot is taken only when
parameters(u)reads it).
| Word | Meaning |
|---|---|
text(u), parameters(u), driver(u) |
A statement’s rendered text, a bounded snapshot of its parameters, the driver (driver(u) on any kind) |
statement(u) |
The statement as an Sql, before rewriting |
statements(u) |
The members of a native batch sent as one unit |
failure(u) |
The raw error, after the end: present it through disclosed |
disclosed(error, { sql?, parameters? }) |
The copy of an error a log or a span may show (below) |
correlation(u), table(u) |
The call’s correlation, the statement’s table |
origin(error) |
The unit an error comes from |
notes(u) |
Facts an extension attached to the unit with note, in order |
- A
statementunit is one physical send: a native batch is one, andstatements(u)lists its members. It begins after rewriting, rendering, the parameter snapshot and taking a connection, around the driver call alone. - An unsafe raw query (
$queryRawUnsafe) is observed like any other statement:text(u)returns the text it sends. It is never rewritten. - The word is
text(u), notsql(u):sqlis the tagged template a rewrite writes its replacement with.
Rewrite statements
A part declared { rewrites: true } may pass a replacement to next(sql).
It runs for each logical statement, before rendering:
import { extension, raw, sql, statement, unit } from "viborm";
const labels = extension(
"statement-labels",
unit(
(u, next) => {
if (u.model !== "post") return next();
return next(sql`${raw("/* posts */ ")}${statement(u)}`);
},
["statement"],
{ rewrites: true }
)
);
- The replacement is an
Sqlvalue. Rewrites run in chain order, each one reading the previous one’s statement. - It covers materialized ORM statements and tagged safe raw statements, never
the verbatim text of
$queryRawUnsafeand$executeRawUnsafe. - A rewrite is trusted last-mile SQL authority. Do not use
raw()with untrusted values. - The official cache steps aside from a chain that rewrites: the rewrite’s effect on an answer cannot be fingerprinted safely.
Run SQL as a transaction opens
run(u, sql), in a transaction unit, executes a statement in the
transaction that opens, before anything else runs in it, and resolves to its
rows:
import { extension, run, sql, unit } from "viborm";
const tenantSession = (tenant: string) =>
extension(
"tenant-session",
unit(async (u, next) => {
await run(u, sql`SET LOCAL app.tenant = ${tenant}`);
return next();
}, ["transaction"])
);
It runs for a $transaction callback, an array run in a transaction, and the
transaction a multi-statement write opens for itself. What it throws fails
the transaction. A savepoint is no transaction. A driver that sends a unit as
one batch (D1, neon-http) opens none, so the part does not run there.
Emit your own units
An extension that does measurable work of its own (a cache, a queue, an HTTP call) can present it as a unit of its own kind:
import { around, extension, note, notes, unit, work } from "viborm";
const lookups = extension(
"lookups",
around(() => async (run) => {
// A unit of kind "lookup", seen by every unit part that listens to it.
const hint = await work(run, { kind: "lookup", operation: "hint" }, async (u) => {
note(u, { source: "edge" });
return "warm";
});
note(run, { hint }); // on the call's own operation unit
return run();
})
);
const report = extension(
"report",
unit(async (u, next) => {
const end = await next();
console.info(u.kind, u.operation, end.status, notes(u));
return end;
}, ["operation", "lookup"])
);
work(origin, { kind, operation, model?, note? }, fn)runsfnas a unit under everyunitpart of the chainoriginbelongs to:originis a call’scorrun, a unit aunit()received, oneworkmade, or a method’s scope (whose unit is an execution of its own, with its own correlation). When no part listens,fnruns alone.note, given, is the unit’s first fact, noted before any handler sees it. The official instrumentation traces and logs a unit from what is noted on it.note(target, fact)attaches a fact to a unit still running:targetis a unit, or a call’srun, which notes on the call’soperationunit. It returnsfalsewhen there is no such unit or it has ended.notes(u)reads a unit’s facts, in order, typically afternext().
disclosure({ sql, parameters, providerDetails, callsite }) is the part
that says what an error thrown by a call of the chain may carry, each flag
false unless given. The official
instrumentation puts its diagnostics
there. Without it, errors disclose none of these.
Present a failure: disclosed
A unit that logs or traces holds what the application may not want shown:
failure(u) is the error itself, with whatever a provider put in it, and
text(u) and parameters(u) are the statement. What it shows of the
statement is its own setting, like the official instrumentation’s
includeSql and includeParams. What it shows of a failure goes through
disclosed, which follows the application’s disclosure:
import { disclosed, extension, failure, parameters, text, unit } from "viborm";
const statementLog = (show: { sql?: boolean; parameters?: boolean }) =>
extension(
"statement-log",
unit(
async (u, next) => {
// Before next(): the provider may change what it was handed.
const values = show.parameters ? parameters(u) : undefined;
const end = await next();
record({
sql: show.sql ? text(u) : undefined,
values,
error: end.status === "failure" ? disclosed(failure(u), show) : undefined,
});
return end;
},
["statement"]
)
);
disclosed(error, { sql?, parameters? }) returns a new Error, the one to
log or put on a span, never the error itself. It is a security boundary:
- Kept. Of an error VibORM made (every error it throws): its
name,message,code,prismaCode,timestamp, themetakeys VibORM knows, and its causes, as VibORM recorded them when it built the error. Of any otherError: the name"Error", the message"Error details redacted", and those of its owncode,errno,sqlState,status,statusCodethat have the shape of a code (ECONNRESET, a SQLSTATE, an HTTP status). - Removed. The stack, always, and every other property. A cause’s
message,
detailandhint(a provider’s words), unless the application’sdisclosureallowedproviderDetails; then they are kept, with the credentials in URLs,password=…,token=…,secret=…andBearer …redacted. Acallsite, unless the application allowedcallsite. The statement text inmeta, unlesssql; the parameter values inmeta, unlessparameters. What the application’sdisclosurehid was never put in the error, sosqlandparameterscan only hide more. - Bounded. A cause seen twice (a cycle) becomes an error
"[Circular]", a chain deeper than eight causes"[Truncated]". A string is cut at 4,096 characters, the copy at 32,768. - Any value. A failure that is not an
Error(a thrown string, an object,undefined) givesError: Error details redacted; nothing of it is read but its prototype chain. - What it reads. Its own data properties, through their descriptors: a
getter on them never runs.
causeandoriginalCauseare read as properties, so a getter there runs, at most once per error of the chain. Each call reads again: call it once per failure. It never throws.
parameters(u) is bounded the same way and needs no word: each value is a
string, a number, a boolean, null, an array of at most 128 items, a record
of its own data properties (a getter on them never runs: "[Unreadable]"),
or a marker ("[Circular]", "[Truncated]", "[Undefined]",
"[Function]"); a BigInt becomes its digits,
a Date its ISO string, bytes { type: "binary", byteLength, bytes } with at
most 128 of them. It is taken once per unit: a hostile value is read once,
however many extensions read it.
args: arguments a call passes
args(declarations) declares arguments a call may pass. VibORM takes them out
of the arguments before any first moment, validates them once, and shows them
only to the parts of the extension that declares them (c.values) and to the
chain’s rules (arg(name)). No other extension sees them, and no c.set can
add or change them.
import { args, around, extension, oneOf, writes } from "viborm";
const db = client.$extends(
extension(
"audit-reason",
args({ reason: oneOf("typo", "moderation", "legal").on(writes) }),
around((c) => async (run) => {
const result = await run();
if (c.kind === "model") recordAudit(c.model, c.operation, c.values.reason);
return result;
})
)
);
await db.post.update({ where: { id }, data: { title }, reason: "typo" });
A declaration is oneOf(...values) (a closed list), accepts(schema) (any
Standard Schema, such as v.string(), with the modifiers of oneOf), or
bound(schema). Each word brings the code that admits its values, so an
extension of oneOf arguments carries no schema admission:
| Modifier | Meaning |
|---|---|
.on(reads), .on(writes), .on(deletes), .on(selecting), .on([...operations]) |
Where it is accepted; every operation without it |
.models([...]) |
Only on these models |
.required(), .required([...models]) |
A call that leaves it out is refused: everywhere it is accepted, or on these models only |
.default(value) |
The value of a call that passes none |
.volatile() |
A read that carries it is neither served from the cache nor stored there |
bound(schema) |
The value comes from the client (scope.$bind), never from a call; it takes .required() and .volatile() |
- A bare Standard Schema is refused when the extension is written (a
TypeErrorthat says to writeaccepts(schema)). A list held in a variable keeps its literal values only withas const. - TypeScript flags an argument where it is not accepted. At runtime a misplaced or undeclared argument is refused as an unknown argument is.
- A value outside the declaration is a
ValidationErrorat the argument’s path. A schema that throws, is asynchronous or cannot be read is aQueryError; a VibORM error it throws passes through unchanged. - A required argument left out is a
ValidationErrorat its path, before anything runs..required([...models])asks for it on those models only; every other model still accepts it where.onplaces it. - A
boundargument is a value of the client rather than of the call: a call that passes it is refused as an unknown argument, and only a binding supplies it (below). Required, a client that binds none refuses every call it is required on. - Argument names are one space per chain: a name an earlier extension
declares, or another
argspart of the same extension, is refused when the extension is applied (ClientInitializationError, naming both). Do not take a name core already uses as an argument (where,data,select, …). Argument names never enter the operation’s own schemas. - The official cache declares its mutation
cacheoption this way. A cached read is keyed on the statement it would send, so an argument a rule reads enters its key through that statement, and one only your own parts read does not. A read that carries a.volatile()argument runs uncached, without an error. Declare.volatile()an argument whose answers must be judged when they are read.
Bind arguments to a client: $bind
A method factory’s scope has $bind(values): it admits values of the
extension’s own bound arguments once, against their declarations, and
returns the client the method is called on, every call of which admits those
values as if it passed them:
import { args, bound, extension, methods } from "viborm";
import { v } from "viborm/validation";
type Requests = { $as<Self>(this: Self, actor: string): Self };
const db = client.$extends(
extension(
"requests",
args({ actor: bound(v.string()).required() }),
methods((scope) => {
const added: Requests = {
// `$bind` returns `unknown`: the `this` parameter types the result.
$as: (actor) => scope.$bind({ actor }) as never,
};
return added;
})
)
);
const call = db.$as(session.userId); // per request: nothing shared changes
await call.post.findMany(); // as if every call passed `actor`
- The bound client shares
db’s chain, its prepared rules and its scope: an array transaction may mix operations ofdband of any client bound from it, each under its own values. An interactive transaction from it, and a client its$extends()derives, keep the values; calling$asagain replaces them. Its cached reads are keyed on them, unless a bound argument is.volatile(). - A value the declaration refuses is a
ValidationError; binding an argument the extension does not declare withbound(schema)(another extension’s, or one of its ownoneOforacceptsarguments) is aClientInitializationError. $bindreturnsunknown: the method that returns the bound client types it with athisparameter, so each client sees itself. Declare the methods apart from the returned object, as above: written inline, the factory’s own type makes thatthisvoid.- A bound client is not a sandbox: it still runs raw SQL as written, and code holding it can bind other values.
rule: what binds the caller
rule({ [model]: entry }) declares, per model, what every call of the client
is held to: which rows it sees and may write, what the rows it writes must
hold, which fields it may read, and what a delete does instead.
import { accepts, arg, args, extension, rule } from "viborm";
import { v } from "viborm/validation";
const db = client.$extends(
extension(
"tenancy",
args({ tenant: accepts(v.string()).required(["post", "comment"]) }),
rule({
post: { read: { where: { tenantId: arg("tenant") } } },
comment: { read: { where: { tenantId: arg("tenant") } } },
})
)
);
await db.post.findMany({ tenant: "acme" }); // acme's posts, acme's comments in them
await db.post.findMany(); // ValidationError: "tenant" is required
| Key | Meaning |
|---|---|
read.where |
Holds wherever the model’s rows are read, and is conjoined with everything else |
root, related |
A filter for the rows the call selects itself, and one for the rows reached through a relation |
read.fields |
{ notes: gate(where) }: the field is present where the predicate holds |
read.select |
{ $access: facts({ … }) }: a key a select or include may ask for |
create.check |
What a created row must hold |
update.where, delete.where |
The rows a write may take |
update.fields |
{ [field]: { where?, check? } }, for an update that writes that field |
update.check |
What the row an update leaves must hold |
delete.instead |
keep(data): the update that replaces the delete |
acyclic |
Self relations an update may not turn into a cycle |
confine |
within(where): what every row of a set computed over the whole table holds |
- Leaves are the ORM’s own
whereanddata.$extends()checks each one once against its model’s schema: a misspelt key anywhere inside it, an unknown model or an unknown field is refused there, naming the model and the path. A filter that names an argument no extension of the chain declares is refused there too. TypeScript flags the same mistakes in your editor. - Filters may go through relations,
some/every/none/isandrecurseincluded. Arecursemust write itsdepth(falsefor the whole closure, or a number);trueand{}are refused. - A model without an entry reads as before. A key an entry leaves out adds no
restriction: an entry with only
read.wherelets a call update and delete every row it can read. To refuse an action, write a filter that takes no row:update: { where: only(nothing) }. rulealso takes a function of the schema,rule((schema) => entries), for an extension that builds its entries from the schema it is applied to. Its entries are checked when it runs, not typed by your editor.
Values a rule reads
| Word | Where | Meaning |
|---|---|---|
arg(name, path?) |
a value | The value the call passed; path reads a field of an object argument (arg("actor", "userId")) |
now |
a value | The call’s instant, the same for all its rows |
row(column, up?) |
a value | The column of the row up relation bodies above (up: 0 is the same row) |
exists({ [model]: where }) |
a filter | Some row of that model holds the where, read under the other extensions’ rules |
nothing |
a filter | No row: only(nothing) refuses an action |
when(arg, test, filter) |
a filter | filter applies when the test holds; otherwise every row passes |
unless(arg, test, filter) |
a filter | filter applies when the test does not hold |
provided(arg, test, filter?) |
a filter | Holds only when the test holds (and filter, if given); false otherwise |
A test is a value, or exactly one of { exists }, { in }, { equals },
{ has }, { hasSome }; any other object, one with an extra key included,
is refused where the entry is checked (at $extends(), or when a lazy
entry is first read). It is folded before any row is read: a test that does not hold
removes its arm, the values inside it included.
- An argument can sit anywhere a filter takes a value: on a field
(
{ tenantId: arg("tenant") }), under one of its operators ({ tenantId: { in: arg("tenants") } }), on a field insideAND,ORandNOT, and insideexists. Your editor types the field and its operators; deeper (a relation’s ownwhere),$extends()checks the word. Declare the argument in this extension or in one applied before it, so one value serves both (an audit stamp can take the actor another extension declares). arg("user")written away from the rule (a shared constant, a function that builds entries) is not typed by the rule’s arguments:$extends()refuses it if no extension of the chain declares that name.- A call that does not pass an argument drops every filter that names it:
that filter hides nothing. Make the argument required when a missing value
must be refused instead:
.required([...models])on the models whose filters read it, or.required()on every model that accepts it. A model it is required on is then never read without it: a call that reaches that model’s rows through a relation of another model, where it is not required, and does not pass it, matches none of them.null, and a path the value does not have, are a missing value: a filter never compares withIS NULL. exists({ member: { userId: arg("user") } })reads no row of the statement, so a driver that shares repeated bodies (PostgreSQL, D1) writes it once per statement. It is read under every other extension’srelatedrows and never this one’s.row("orgId", 1)reads the column of the row one relation body above (anexistsbody counts as one):exists({ member: { orgId: row("orgId", 1) } })asks for a member of this row’s organization. It never reaches past the rule, across arecurserelation or a polymorphic one, and compares columns of the same type (a string with an enum). A write changing a column a body reads this way is judged on its new row.- Each filter is prepared once for every call: a value is read when the statement is built, so no tenant, version or actor takes room or pushes another out.
An argument with a default
An argument with a default, read by when and unless, chooses what a call
sees when it says nothing. The caller writes archived: "only" to see
something else:
import { arg, args, extension, oneOf, rule, selecting, unless, when } from "viborm";
const db = client.$extends(
extension(
"archiving",
args({ archived: oneOf("hide", "show", "only").default("hide").on(selecting) }),
rule({
project: {
root: [
when(arg("archived"), "hide", { archivedAt: null }),
when(arg("archived"), "only", { archivedAt: { not: null } }),
],
related: unless(arg("archived"), "show", { archivedAt: null }),
},
})
)
);
await db.project.findMany(); // projects not archived
await db.project.findMany({ archived: "only" }); // archived projects
rootfilters the rows the call itself selects;relatedfilters rows reached through a relation. Each takes awhereor a list of them, which conjoin.whenandunlessare folded per call: a test that does not hold removes its filter for that call, and calls that pass the sameoneOfvalue share their prepared filters..on(selecting)accepts the argument where it means something: every operation that selects rows (reads,count,aggregate,groupBy, updates,upsert, deletes), and notcreateorcreateMany. An argument is accepted only where its own.on(…)and.models([…])say; without them, on every operation of every model.- Inside a filter’s own relation reads, every other extension’s rules apply
with each argument that has a default read at that default, whatever the
call passes and whether it was declared with
oneOforaccepts, and the filter’s own extension does not apply:deleted: "with"revives no tombstoned row a filter reads through, and a filter over its own model’s relation (a parent) reads that row unfiltered. Write “visible if the parent is visible” as arecurseover the parent.
Where rules apply
Rules are not a moment of the call: the engine applies them everywhere a
model appears in a query. That is root reads and writes, aggregates, cursors,
include/select of every relation, some/none/every and is/isNot,
relation counts and ordering, recursive reads, and the targets of nested
writes, disconnect and set included: a member the call cannot see keeps
its link.
- A to-one relation whose target is filtered out reads
null. So on a client whose chain has aread.where,root,relatedor lazy entry for a model, TypeScript types a to-one relation to that model as| null, required or not, whatever the call’s arguments. A reference to a row that does not exist at all is still an error. OperationResult,InferDatabaseandrenderOperationResultTypedescribe the schema alone: on such a client they type a to-one relation as present where it can readnull.ExtendedOperationResulttypes the client’s own results, and so does a typedaround’srun(), which also reads the rules of the parts before it in its own extension. A rule placed after anaroundin the same extension is not seen by its types: put rules first.- A rule may follow any other part: it applies to every call of the chain, methods’ calls included. TypeScript refuses a rule that hides rows only after a part typed against the client it extends, whose types it would make lie (compose).
- A rule decides which rows are visible. It is not authorization by itself:
any caller can pass another value of an argument, unless that value
is a
bound, required argument (asviborm/permissions’ actor), and raw SQL is not filtered. Pass a tenant from your own server’s session, never from the request: the rule keeps a call inside the tenant it names, it does not check that the caller may name it.
Judge writes: only
read.where decides which rows a call reads. update.where, delete.where
and update.fields[f].where decide what a call may do to them, each written
with the word only(where). Share a predicate between keys by sharing the
object:
import { accepts, arg, args, extension, only, rule } from "viborm";
import { v } from "viborm/validation";
const seen = { OR: [{ public: true }, { ownerId: arg("user") }] };
const own = { ownerId: arg("user") };
const archivist = { archivistId: arg("user") };
const db = client.$extends(
extension(
"sharing",
args({ user: accepts(v.string()).required(["document"]) }),
rule({
document: {
read: { where: seen },
update: { where: only(own), fields: { archivedAt: { where: only(archivist) } } },
delete: { where: only(own) },
},
})
)
);
await db.document.findMany({ user: "ada" }); // public documents and Ada's own
await db.document.update({ user: "ada", where: { id }, data: { title } }); // own only
await db.document.update({ user: "ada", where: { id }, data: { archivedAt: new Date() } }); // archivist only
read.whereis conjoined with every write key: a write never takes a row its call cannot see.onlyis a word, not a bare filter, so that a rule that never judges a write carries none of that code.- A delete takes
delete.where, kept rows included. An update takes, for each field itsdatawrites, that field’supdate.fieldsentry, which replacesupdate.wherefor that field, elseupdate.where, all of them at once. An update that writes a field akeepmanages (by hand or through a restore) also takesdelete.where. A relation write counts as a write of the relation on the row whose foreign key it changes, and a join row’s change as a write on both rows it links. - Defaults and schema values (
updatedAt,defaultsdata) never change which key judges:data: {}on a row they touch is judged atupdate, as is a parent a nested write bumps. A row only addressed to reach its children is read. - A row a write may not take is a row it cannot find:
updateanddeleteareNotFoundError, andupdateManyanddeleteManycount only the others. Aconnect,setordisconnectnaming a linked row the call may not write isNestedWriteError.set: []refuses a visible link the call may not write the same way; a hidden one keeps its link.
Lazy entries: lazy
A model’s entry may be read later, for entries that are expensive to build
(viborm/permissions compiles its policy this way):
import { extension, lazy, rule } from "viborm";
const db = client.$extends(
extension(
"documents",
rule({ document: lazy(() => ({ read: { where: { public: true } } })) })
)
);
The function is called the first time a call needs that model, which includes
every model the call’s filters read through a relation, and its entry is
checked then: a refusal fails that call, and every later call on the model,
instead of $extends(). A bare function in place of an entry is refused:
lazy is the word that brings this code. Your editor types a lazy entry like
an inline one, but does not read the facts names or gated fields inside it.
Judge the rows a write produces: check, acyclic
check(where) judges the row a write leaves behind, as a value, against the
rows as they stand before the write, inside the statement that writes it:
import { accepts, arg, args, check, extension, only, rule } from "viborm";
import { v } from "viborm/validation";
const placed = { ownerId: arg("user") };
const judged = client.$extends(
extension(
"judged-sharing",
args({ user: accepts(v.string()).required(["document"]) }),
rule({
document: {
read: { where: seen },
update: {
where: only(own),
check: check({ AND: [seen, own] }), // the row an update leaves
fields: { folderId: { check: check(placed) } }, // an update writing folderId
},
create: { check: check(placed) }, // every created row
acyclic: ["parent"], // a document never moves under itself
},
})
)
);
- Nothing is implied.
update.wheresays which rows an update may take;update.checksays what the row it leaves must hold. To keep an updated row inside what its call could have written, writeupdate.checkwith the read predicate and the update predicate, as above. - A created row is judged at
create.check; a model with none is not judged on create. An updated row is judged atupdate.checkwhere the update writes a field the predicate reads, and at each written field’scheck: an update that writes nothing the predicate reads cannot move the row out of it, and its statement carries no judgement. acyclicis judged with the rows a write produces, so it needs acheckon the same model (create.check,update.checkor a field’scheck): without one,$extends()refuses it.acyclicmay be a function returning the list: it is called the first time an update writes the key of one of the model’s self relations.- A refused row is written by no statement: at the root
ForbiddenError, in a nested writeNestedWriteError, before any constraint, so a unique key or a missing target never answers first.createManyandupdateManyrefuse the whole statement when one row is refused; a row the write does not take is never judged. - Nothing a statement writes is visible to its own judgement: a row cannot
justify itself, and one row of a
createManyorupdateManynever decides another. A child created under a parent the same call created is judged with that parent as written. - A value only the database computes cannot be judged before it exists: a
list
push/unshiftor an exact decimal’smultiply/divideis refused before any statement where the row’s judgement reads that field (write the whole value instead), and so is a row of defaults only on a model with acreate.check.
Report and gate: facts, gate
The same predicates can answer per row. facts declares a key a call may put
in any select or include, at any depth, on reads and on the rows a write
returns; gate makes a field present only where a predicate holds:
import { accepts, args, extension, facts, gate, rule } from "viborm";
import { v } from "viborm/validation";
const db = client.$extends(
extension(
"sharing",
args({ user: accepts(v.string()).required(["document"]) }),
rule({
document: {
read: {
where: seen,
fields: { notes: gate(own) },
select: { $access: facts({ seen, own, archivist }) },
},
},
})
)
);
await db.document.findMany({
user: "ada",
include: { $access: true, children: { include: { $access: ["own"] } } },
}); // each row: { …, $access: { seen: true, own: boolean, archivist: boolean } }
await db.document.findMany({ user: "ada" }); // `notes` only on Ada's own
await db.document.findMany({ user: "ada", select: { id: true, notes: true } }); // ValidationError if a row is not hers
- The key is spelled
$and an identifier, so no field of the model can take its name. Each name reports whether its predicate holds on the row besideread.where, computed in the statement that reads the row (for a write, when its result row is read).$access: ["own"]asks for some names only. - The key is admitted by the operation’s own validation, as a field of the
model is, for the calls of a chain that declares it: a
selectholding only$access: falseis empty and refused (ValidationError), the key comes back where theselectwrote it, and nodatamay write it. - A gated field is present where its predicate holds and absent elsewhere; the
row is never dropped. A
select(or anomit: { notes: false }) that names it fails withValidationErrorat its path when a returned row lacks the predicate. Every operand a call writes over it (where,orderBy,distinct, aggregates andgroupBy, unique lookups,connect, relation filters and relation order) reads it as absent (NULL) on those rows. - A key, a field of a unique constraint or of a unique index, or a foreign
key cannot be gated, and two extensions of one chain cannot
declare the same key on a model: both are refused when the extension is
applied. One entry holds one
factskey.
Keep deleted rows: keep
delete: { instead: keep(data) } turns every delete of the model (root,
bulk, nested, or a member a relation write removes) into an update with that
data. The row stays, with every link:
import { arg, args, deletes, extension, keep, now, oneOf, rule, unless } from "viborm";
const db = client.$extends(
extension(
"archiving",
args({ purge: oneOf(true).on(deletes).models(["project"]) }),
rule({
project: {
delete: {
instead: keep(unless(arg("purge"), true, { archivedAt: now, archivedBy: "system" })),
},
},
})
)
);
await db.project.delete({ where: { id } }); // archivedAt = the call's time
await db.project.delete({ where: { id }, purge: true }); // a physical delete
- The update is admitted like any update:
updatedAtis refreshed and field transforms run once per row. Handlers, errors and logs still see adelete, anddeletereturns the row after the update. Adefaultspart’supdatedata is written too. - Every row one call updates this way gets the same
now; separate calls get their own. - A delete takes only the rows the model’s rules show with every argument
that has a default read at that default, whatever the call’s arguments
say, so deleting a hidden row is
NotFoundError. A model kept this way with no filter has every row eligible: deleting it again writes a new time. - It is refused with
ForeignKeyErrorwhile a row the child model’s rules show at those defaults still references it through a foreign key that restricts deletes, as the database refuses a physical delete. keepwrites constants, andnowin one field at most.keep(unless(arg(x), test, data))keeps the row unless the test holds, andkeep(when(arg(x), test, data))only when it holds: the test is folded per call, and where the row is not kept the delete stays physical. The argument is accepted where its own declaration says: write.on(deletes).models([...])to accept it only on the deletes of the kept models, as above. Akeepis written in an inline entry, not alazyone. The official soft delete is built this way.
Confine the sets your predicates compute: confine
On PostgreSQL drivers and D1, a body your predicates repeat in one statement
is computed once, as a set over its model’s whole table, bounded only by what
the body states. “The grants that name the caller” reads every tenant’s
grants. confine: within(where) says, per model, what every row of such a
set holds, as a where of the model’s own columns (no relation). The word
brings the code that applies it, so a rule that confines nothing carries
none of it:
import { accepts, arg, args, extension, rule, within } from "viborm";
import { v } from "viborm/validation";
const db = client.$extends(
extension(
"grants",
args({ tenant: accepts(v.string()).required(["grant"]) }),
rule({ grant: { confine: within({ tenantId: arg("tenant") }) } })
)
);
- It applies to a set your own predicates compute over a whole table: a repeated body, and, on a driver that bounds the relations of a statement (PlanetScale’s Neki), a recursive filter computed as a set. A relation they read row by row is not confined: from a row you admit, it reaches rows of the same tenant already.
- It applies where a test reads the set positively:
someoris, outside aNOT, and not in what anone,everyorisNotranges over.confinecan only take rows away from what your predicates grant. - It holds whatever the call’s arguments, and states a promise: a row a set
would lose to it
must be one your predicates never need.
permissions’tenantstates its tenant here.
defaults: what holds when the caller says nothing
defaults({ [model]: { orderBy?, create?, update?, fields? } }) declares what
a call gets when it does not say otherwise. The caller can always override it:
import { accepts, arg, args, defaults, extension, now, omitted, writes } from "viborm";
import { v } from "viborm/validation";
const db = client.$extends(
extension(
"house-style",
args({ actor: accepts(v.string()).on(writes).required(["post"]) }),
defaults({
card: { orderBy: [{ columnId: "asc" }, { rank: "asc" }] },
post: {
create: { createdBy: arg("actor") },
update: { updatedBy: arg("actor"), editedAt: now },
},
user: { fields: { passwordHash: omitted } },
})
)
);
await db.post.create({ data: { title }, actor: "ann" }); // createdBy: "ann"
await db.post.update({ where: { id }, data: { title }, actor: "bob" }); // updatedBy: "bob"
await db.user.findMany(); // no passwordHash
defaults brings no filter code and no argument admission of its own (the
args part brings that). When a rule part is on the same chain, it reads
what defaults set as well.
Default order: orderBy
- It applies to a root
findManyandfindFirst(a negativetakereads from its end), a to-many relation read at any depth (include,select, recursive), and the window of a pagedcountoraggregate(take,skip,cursor), so the rows a page counts are the rows it reads. Acursorpages through it. - An explicit
orderByreplaces it, whole;orderBy: []reads in key order. Without this extension, a relation read withoutorderBy,take,skip,cursorordistinctcomes back in no particular order.findUnique,groupByand unpaged aggregates are not ordered by it. - The model’s key always ends the order, so equal values read in a stable order.
- Each term names one scalar field,
"asc"or"desc": not a relation, a list, JSON, a vector or a point. The model must have a primary or unique key.$extends()refuses anything else with aClientInitializationError. - A later extension’s order for a model replaces an earlier one’s. A cached read is keyed on the statement it sends, so two clients that order a model differently never share a cached entry.
The official ordering extension declares its lists’ order this way.
Default data: create, update
A value is a constant, arg(name, path?) for the value the call passed, now
for the call’s one instant, or, for update, one of the field’s update
operators such as { increment: 1 }. The argument may be this extension’s or
one an earlier extension declares, so an audit stamp can take another
extension’s actor.
- Every create and update writes the fields: root and nested, one row or
many,
upserteither way. A delete a rule keeps (keep) is an update, so it writes theupdatefields too. Aconnectorsetthat only moves a foreign key writes nothing, as it does not refreshupdatedAteither. A delete that stays physical writes nothing. Raw SQL is not touched. - A field is written only when the caller left it out. A call that writes one
of these fields itself keeps its own value, at the root and in every nested
create or update. A field written as
undefinedcounts as left out. Writing the field through a relation counts as writing it: when the field is the relation’s foreign key (tenantIdfortenant), a call that writes that relation (connect,create,connectOrCreate, even a nestedupdateof the tenant) decides the key, and the default steps back. So a defaulttenantIdis a stamp, not write authorization: a caller who writestenantId, or connects a tenant, by hand writes into that tenant, on a create and on an update. A kept delete has no data from the caller, so itsupdatefields are always written. - A field your schema requires may be left out of a create when a default
writes it on that call: the call’s data is checked against the schema with
that field counted as given, at the root and in every nested create. A
required foreign key such as
tenantIdcounts as given for its relation too. When the call does not pass the argument the field names, nothing writes it, so leaving it out is refused as missing when the call runs; make the argument required on that model (.required(["post"])) so the call must pass it. - On the extended client, each field a default writes on create is optional in that model’s create data, in the call’s own data and in every create it nests through a relation, and it keeps its own type when you write it. The relation that holds it may be written too. An update’s fields are optional already and keep their types.
- What the types cannot see: model names built at runtime (a plain
string[]) narrow nothing, so a required field cannot be left out in your editor; and a create nested through a relation with variants is not rebuilt, so there a required field is still asked for. The types find a nested create’s model by its fields, not by its name, so a model without defaults whose fields and relations are the same as a model with them is treated like it in a nested create: the editor lets a required field be left out there, and the call is refused as missing when it runs. - When two extensions write the same field of a model, the one applied later wins, on every call, and a value the caller writes wins over both. Each extension writes its other fields. A field whose argument the call did not pass is not written: when the later of two extensions names an argument there, a call without it writes neither extension’s value.
A filter on a version and a default that moves it on make an optimistic lock. The recipes give it in full, with tenancy and audit stamping.
Default omission: omitted
fields: { passwordHash: omitted } leaves the field out of every result of
the client by default, root results and nested relation payloads alike. A
query brings it back with omit: { passwordHash: false } or a select that
names it. Two parts that omit fields of one model add up, in one extension or
in two. A default does not change a bulk operation from { count } to
returned rows. The official defaultOmit() is this
word in an extension named viborm.defaultOmit, so one chain applies it
once; further omissions go in your own extensions’ defaults.
Write values the statement computes
Three values, exported from viborm, go where a field’s value goes. Each is
typed as the field it is written to. They are open to any caller, not only to
extensions.
| Value | Where | What it writes |
|---|---|---|
computed(compute) |
update and updateMany data, defaults data |
A value computed when the statement is written: a plain value, or an SQL expression the statement evaluates |
stored() |
update and updateMany data |
Nothing: the field stays as stored, and no generated value (updatedAt()) fills it |
joined(source) |
updateMany data |
Each row’s own value, read from a derived table the UPDATE joins |
import { computed, sql, stored } from "viborm";
await client.counter.update({
where: { id },
data: {
hits: computed<number>(({ sql: q }) => [
sql`(SELECT MAX(${q.column("hits", "m")}) + 1 FROM ${q.table("m")})`,
]),
touchedAt: stored(),
},
});
compute(context, indexes) answers one value per row that holds it.
context gives the model’s name, the field, the statement’s rows
(context.rows, with indexes naming those that hold the value), the
dialect, and read(statement) where the write can read first in its own
unit (absent in a batch). context.sql spells the model as the client’s
statements do. The same object is db.<model>.$sql:
| Member | Result |
|---|---|
table(alias?) |
The model’s table, in its namespace |
column(field, alias?) |
A field’s column |
value(field, value) |
A value bound as that field is written and compared |
name(...path) |
A quoted identifier: name("r", "k") is "r"."k" |
visible(alias, { update?, where? }) |
A condition: the rows the call may see under alias; with update, those it may update by writing those fields |
visible() is settled by the model operation the fragment is handed to, so a
subquery you write reads the rows the call may read. A raw query does not
settle it: use $rows there.
joined({ join, value, rows }) takes the SQL form and the list form of the
same values. join(sql, target) returns the derived table and the condition
that matches it to the row written; value(sql) is the SET expression. A
database that joins no derived table (SurrealDB) calls rows(sql, read)
instead: a list of { where, value }, one per row, written only while the
row still holds the where values. An extension that supports SurrealDB
writes its own SurrealQL there, as it writes its own SQL per dialect.
A create’s own data does not take these values yet: use a defaults value.
methods: client and model methods
methods(factory) adds client methods: the factory returns $-prefixed
functions. modelMethods(factory) adds model methods: the factory returns,
under a model’s name, that model’s methods. Each brings only its own code, so
an extension of client methods carries nothing of model methods, and the
reverse:
import type { DelegateOperationResult, PendingOperation } from "viborm";
import { extension, methods, modelMethods } from "viborm";
type Archive = {
archive<Self, const A extends { where: { id: string } }>(
this: Self,
args: A
): PendingOperation<DelegateOperationResult<Self, "update", A>>;
};
// A model method is called with `this` set to the delegate it is called on.
// The cast reads that delegate's `update` without the client's types.
const archive: Archive["archive"] = function (args) {
const delegate = this as { update(args: object): PendingOperation<never> };
return delegate.update({ ...args, data: { archived: true } });
};
const db = client.$extends(
extension(
"post-tools",
methods((scope) => ({ $postCount: () => scope.post.count() })),
modelMethods(() => ({ post: { archive } }))
)
);
await db.$postCount();
await db.post.archive({ where: { id } });
- A key a factory may not return is refused when the extension is applied:
a model’s name in
methods, anything but a model inmodelMethods. - The factory receives the client scope of the current view. Use it, not a root client captured in a closure, so the methods also work inside callback and nested transactions; capturing an unrelated root client deliberately escapes that transaction scope.
- A model method is called with
thisset to the delegate it is called on. Typed with athisparameter andDelegateOperationResult, its result is what that delegate’s operation returns on the client it is called on, after every extension applied later, computed fields included. Called off its delegate (const { archive } = db.post), its result isunknown. - The client
$extends()returns runs each factory then, once, so a faulty factory fails there. Every other view (an interactive transaction’stx, a client$bindreturns) runs it once, when what it returns is first read. - Client method names start with
$. A contributed method cannot replace a core method, a model name,then, or a method from an earlier extension. The whole extension application fails if any name collides; TypeScript does not flag a replaced model method in your editor. - A method that binds an argument belongs to the extension that declares it
(
$bindtakes no other’s), so putargsand thatmethodspart in one extension.
A factory that takes scope reads the client’s types at this step: it is a
result consumer, and TypeScript refuses a later rule that hides rows or a
later omission on the same chain (compose). A factory
that takes nothing, and types its model methods through this as above, may
be followed by anything. The official soft delete, ordering and permissions
are written this way, so each is one step, applied in any order.
A method that passes an argument another extension declares (archived: "only") goes in an extension applied after it: its this delegate and its
scope then carry that argument.
fields: computed fields
fields adds fields that are computed from the row, as Prisma’s result
extensions do. Each field names the columns it reads in needs and computes
its value in compute:
import { extension, fields } from "viborm";
const db = client.$extends(
extension(
"names",
fields({
user: {
fullName: {
needs: { firstName: true, lastName: true },
compute: (user) => `${user.firstName} ${user.lastName}`,
},
},
})
)
);
const users = await db.user.findMany();
// { id, firstName, lastName, email, fullName }[]
const one = await db.user.findUnique({
where: { id },
select: { fullName: true },
});
// { fullName: string } | null
- Every row of the model. Reads, the writes that return rows (
create,update,upsert,delete, andcreateMany/updateMany/deleteManywith aselectoromit), relation rows reached throughincludeor a nestedselect, a recursive projection at every level,$transactionarrays and callbacks, and$withCache()reads all carry the field.count,aggregate,groupByandexistdo not. - Selected and omitted by name. With a
select, the field is returned only when theselectnames it; without one, always. A query-levelomitsubtracts from either, as it does for columns:select: { fullName: true, firstName: true }, omit: { firstName: true }returns{ fullName }, the omitted column still read for the field. needsare read, then removed. The columns a field needs are read even when the call does not select them, and are not in the result unless the call selects them. A column the client omits by default (omitted) is read for the field the same way.computeis given exactly itsneeds, typed from the model: reading another column is a compile error.- Computed lazily, once. Each field is an enumerable getter, as in
Prisma:
computeruns the first time the field is read (by your code, a spread,JSON.stringifyorstructuredClone), from the values the call read, and its value is kept. Changing the row’s columns afterwards, even inside a JSON, date or list value, does not change it (such a value a field needs is copied when the row is returned); assigning the field replaces it. Acomputethat throws throws where the field is read: the operation, and a write it made, still succeed. - A field may replace a column. A field named like a scalar of the model
(
email: { needs: { email: true }, compute: (u) => u.email.toLowerCase() }) is returned instead of it. Filters, ordering and aggregates still use the column. - Extensions compose. A later extension’s field may need an earlier
extension’s field, even one of the same name, and is computed after it.
$allModelsdeclares a field on every model; a model’s own field of the same name replaces it there.
The database never sees a computed field, so where, orderBy, distinct,
groupBy and aggregates cannot name it (a ValidationError, as for any
unknown field). The part is checked when it is applied: a need that is not a
readable scalar or an earlier computed field of the model, a field named like
a relation, or an unknown model is refused. Each row is copied before its
fields are attached, so cached and shared rows are never changed.
Differences from Prisma, and what is not typed yet:
- The rows of a polymorphic (variant) relation do not carry computed fields.
- At runtime a nested
selectoromitmay name a computed field (include: { author: { select: { fullName: true } } }); the types accept it only on the operation’s ownselectandomitfor now.$withCache()delegates andExtendedOperationResultare typed without the computed fields, which their rows carry at runtime. So is a relation row whose model shares its scalar and relation names with another model of the schema, since the types cannot tell the two apart: its added fields are left out, and a field that replaces a column is typed as the column or any of those models’ computed value.
A client without a fields part plans and copies nothing.
The life of a call
Calling a model method creates a lazy operation. Its parts start only when that operation is awaited or admitted to an array transaction:
unit `operation` begins [unit]
extension arguments taken out of the arguments, validated [args]
first moments, in chain order [call]
default omission [defaults: omitted]
computed fields planned [fields]
validation and preparation
second moments, nested, the first applied outermost [around]
{ inner: true } parts, closest to the core
planning and compilation
for each logical statement
rewrites, in chain order [unit, rewrites]
rendering, parameter snapshot, connection
unit `statement` begins, one per physical send [unit]
driver
result read
computed fields attached (computed when first read)
unit `operation` ends
- Rules (
rule) and defaults (defaults) are not a moment: the engine applies them everywhere a model appears in the query. settledfunctions run when the write is durable, before the call’s promise resolves: at once after the call’s own commit, after the outermost commit inside a transaction. All of them run, in chain order; the first fault rejects the call.- In
$transaction([...]), abatchunit surrounds the members. VibORM waits until each member’soperationunit has started its work before any first moment, and every member finishes its first moments and reachesrun()in its second before any driver work.
Compose extensions
Apply extensions in the order they should wrap one another:
const db = client
.$extends(boundedReads)
.$extends(timing)
.$extends(postTools);
First moments run in application order; second moments are nested in that
order, the first applied outermost; rewrites receive the previous rewrite’s
statement in that order; settled functions run in that order. There are no
priorities, global registrations, or extension removal. Build the desired
immutable client once and pass that client to the code that should use it.
Every extension’s rules, defaults and omissions apply to every call, methods’
calls included, whatever the order of the chain: a method runs through the
whole chain of the client it is called on. Only types can fall behind. A
part typed against the client it extends is a result consumer: a methods
factory that takes scope, or an around that names one model and one
operation. A later rule that hides rows can make a to-one relation it reads
null, and a later omission can drop a field it reads, so TypeScript refuses
those after a consumer; the runtime does not. Put rules and omissions first,
or type model methods through this.
Transaction clients inherit contributed methods but do not expose
$extends(). Derive the client before entering the callback. Every member of
an array transaction must also come from the same derived client scope (a
client $bind returns shares its client’s); do not mix base and
sibling-client operations.
Extensions written apart: parts<Of>()
An extension written inside $extends(...) is typed from the client it is
applied to. One written apart and exported, which names models, binds its
vocabulary to a schema or a client type first:
import { accepts, arg, args, defaults, parts, rule } from "viborm";
import { v } from "viborm/validation";
import type { schema } from "./schema";
const forSchema = parts<typeof schema>();
export const tenancy = forSchema.extension(
"tenancy",
args({ tenant: accepts(v.string()).required(["post"]) }),
rule({ post: { read: { where: { tenantId: arg("tenant") } } } }),
defaults({ post: { create: { tenantId: arg("tenant") } } })
);
const db = client.$extends(tenancy);
- Only
extensionis bound: the parts inside it read the target from it. - Bound to a schema,
parts<typeof schema>(), the extension applies to any client of that schema, and loses two things: it cannot name an argument an earlier extension of the chain declares, and a typedaround’srun()reads every to-one relation as| null. - Bound to a client type,
parts<typeof client>(), it loses nothing, and applies only to that client. - An extension that names no model (a generic
around, amethodspart with client methods only) needs no binding. - An extension meant for any client (a recipe that takes model names) is
written with plain
extension(...)and words held apart from the rule (const tenant = arg("tenant")): model names, fields and arguments are then checked by$extends()when it is applied. The recipes are written this way.
Name the complete client type
Use ExtendedClient when the base client, the extensions, and the final
composition live in different modules but the application needs one shared
client type:
import type { ExtendedClient } from "viborm";
export const applicationExtensions = [boundedReads, timing, postTools] as const;
export type ApplicationClient = ExtendedClient<
typeof client,
typeof applicationExtensions
>;
The tuple is the real application order. Keep it as const, then build the
runtime client in the same order wherever it belongs:
export const db: ApplicationClient = client
.$extends(applicationExtensions[0])
.$extends(applicationExtensions[1])
.$extends(applicationExtensions[2]);
ExtendedClient is type-only: it does not apply extensions or create a second
runtime chain. It also accepts an already extended client as its first
argument, so separately composed sections can name the remaining type
incrementally. The same tuple in another order names another client. A tuple
that is not a tuple (readonly Extension[]) and a statically invalid order
resolve to never, matching $extends(). Name collisions remain runtime
checks and fail when the extension is applied.
Before publishing an extension
- Give it one stable, unique name.
- Use the narrowest part:
callbeforearound,defaultsbeforerule,wherefilters beforeonly,checkandgate. - Put
argsbefore the parts that read its arguments, and rules before a typedaround. - Write it inside
$extends(...), or bind it withparts<Of>()when it is written apart and names models. - Keep first moments synchronous and return only a shallow patch.
- Call
run()exactly once unless intentionally short-circuiting a non-array model read, oragain(run)allows another. - Call
watchandsettledin the first moment. - Contain a
unithandler’s own faults: what it throws fails the call. Callnext()exactly once. - Treat a rewriting
unitas trusted SQL code. - Use the supplied scope in a
methodsfactory, and type model methods throughthiswhen later extensions may hide rows or omit fields. - Keep rules for visibility, never for authorization by themselves: take a tenant or an owner from your server, not from the caller.
- Test direct, callback-transaction, and array-transaction execution when the extension participates in those modes.
See the extension overview for the lifecycle and the official extensions for production cache, instrumentation, default omission, soft delete and authorization. Moving an extension written for the earlier contract: Migrating an extension.