---
title: Create an extension
description: Build a typed extension from the narrowest parts that do the job
icon: puzzle
---

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:

```ts
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 put `args(...)` before the `rule` or the `call` that 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](#extensions-written-apart-partsof).

### 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.

{/* Measured with `node scripts/extension-bytes.mjs` (the `pg-one-*`
fixtures of scripts/bundle-fixtures, and the official extensions' fixtures),
last on f34031a03; rerun it and update these figures when the code of
src/extensions changes. */}

| 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()`](/docs/extensions/omit) | 5.7 kB | 2.2 kB |
| [`on()`](/docs/extensions/on) | 9.7 kB | 3.9 kB |
| [`instrumentation()`](/docs/extensions/instrumentation) | 14.8 kB | 5.4 kB |
| [`softDelete()`](/docs/extensions/soft-delete) | 20.6 kB | 8.1 kB |
| [`cache()`](/docs/extensions/cache) | 26.9 kB | 10.1 kB |
| [`ordering()`](/docs/extensions/ordering) | 26.9 kB | 11.0 kB |
| [`permissions()`](/docs/extensions/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.

:::tip
Use the official [`instrumentation()`](/docs/extensions/instrumentation)
extension for production tracing and structured logging. The example above is
deliberately small so the call protocol is visible.
:::

## 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**:

```ts
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.set` refuses 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 a `QueryError`. VibORM keeps the caller's
  exact result shape. A raw query's arguments cannot be patched: `c.set` is
  refused there too.
- The read-only contract is shallow. Nested caller values are borrowed, so
  build a patch instead of mutating `c.args` or 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 what
  `around` is for.
- What the handler throws refuses the call: a VibORM error as it is, any
  other error as the cause of a `QueryError` that 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`](/docs/extensions/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`](#defaults-what-holds-when-the-caller-says-nothing) or
[`defaultOmit()`](/docs/extensions/omit), 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`](/docs/extensions/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:

```ts
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**, unless [`again(run)`](#make-a-failed-call-again-again)
  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 an `Error` is
  the cause of a `QueryError` naming 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 what `run()`
  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
  reaches `run()` in its second before any driver work. A refusal, a second
  `run()`, 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:

```ts
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: `kind` is `"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 own
  `RETURNING` where 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 (`nested` is `true`), in write
  order. `kind` is 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.
- `watch` and `settled` work in the first moment of a model call, in a `call`
  or an `around` whose target is a set of writes: `target(writes)`,
  `target(deletes)`, or `target("order", writes)`. The set brings what tells
  them, so a part that never watches carries none of it. Anywhere else they
  are refused with a `TypeError`, never ignored (a raw query's `settled` in
  an `around` with no target excepted, [below](#act-after-the-commit-settled)):
  `target("order", "update")` names an operation, not a set, and brings
  nothing that watches.
- A call that fails calls neither `rows` nor `settled`, with one exception:
  a write whose statement failed after it was sent may have committed, so
  `settled` is told (`certainty: "may-have-committed"`) and `rows` is not.
  Several extensions can watch; each is told in the order the extensions
  were applied.
  [`viborm/on`](/docs/extensions/on) is 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 `Error` included, is the cause of a `QueryError`.
  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 `around` with no target, `settled` also hears `$executeRaw` and
  `$executeRawUnsafe`, which may have written anything.
- `settled(scope, fn)` in a [method](#methods-client-and-model-methods) runs
  `fn` at 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 `settled` registers 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 imports `settled` carries 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:

```ts
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:

```ts
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](/docs/extensions/cache) does:

```ts
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, and `run()` 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)` is `undefined` for 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 as `run`
  does and keeps those rows; `snapshot()` gives them as JSON data (a value
  JSON cannot carry, such as a bigint, a `Date` or bytes, written as a
  tagged array), and throws a `TypeError` when the last `run()` 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 when `stored` is 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: `codec`
  refuses it with an `UnsupportedOperationError`.
- `database(x)`, on a first moment's `c`, a `run` or a method's scope, gives
  the database's `dialect` and SQL `namespace` (a PostgreSQL schema, a MySQL
  database; `undefined` where the dialect qualifies nothing) and the
  `driverName` (`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_VERSION` is the version of the `viborm` package: 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.

```ts
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 when `next()` is
  called, and VibORM awaits the handler's promise. Its end has `status`,
  `duration`, `certainty` where there is a commit, and `recovered`. 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](#present-a-failure-disclosed)) |
| `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 `statement` unit is one physical send: a native batch is one, and
  `statements(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)`, not `sql(u)`: `sql` is 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:

```ts
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 `Sql` value. 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 `$queryRawUnsafe` and `$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:

```ts
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:

```ts
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)` runs `fn` as a unit
  under every `unit` part of the chain `origin` belongs to: `origin` is a
  call's `c` or `run`, a unit a `unit()` received, one `work` made, or a
  method's scope (whose unit is an execution of its own, with its own
  correlation). When no part listens, `fn` runs alone. `note`, given, is the
  unit's first fact, noted before any handler sees it. The official
  [instrumentation](/docs/extensions/instrumentation#present-your-own-units)
  traces and logs a unit from what is noted on it.
- `note(target, fact)` attaches a fact to a unit still running: `target` is a
  unit, or a call's `run`, which notes on the call's `operation` unit. It
  returns `false` when there is no such unit or it has ended.
- `notes(u)` reads a unit's facts, in order, typically after `next()`.

`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](/docs/extensions/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`:

```ts
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`, the `meta` keys VibORM knows,
  and its causes, as VibORM recorded them when it built the error. Of any
  other `Error`: the name `"Error"`, the message `"Error details redacted"`,
  and those of its own `code`, `errno`, `sqlState`, `status`, `statusCode`
  that have the shape of a code (`ECONNRESET`, a SQLSTATE, an HTTP status).
- **Removed.** The stack, always, and every other property. A cause's
  message, `detail` and `hint` (a provider's words), unless the
  application's `disclosure` allowed `providerDetails`; then they are kept,
  with the credentials in URLs, `password=…`, `token=…`, `secret=…` and
  `Bearer …` redacted. A `callsite`, unless the application allowed
  `callsite`. The statement text in `meta`, unless `sql`; the parameter
  values in `meta`, unless `parameters`. What the application's `disclosure`
  hid was never put in the error, so `sql` and `parameters` can 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`) gives `Error: 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. `cause` and `originalCause` are 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.

```ts
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
  `TypeError` that says to write `accepts(schema)`). A list held in a
  variable keeps its literal values only with `as 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 `ValidationError` at the argument's
  path. A schema that throws, is asynchronous or cannot be read is a
  `QueryError`; a VibORM error it throws passes through unchanged.
- A required argument left out is a `ValidationError` at its path, before
  anything runs. `.required([...models])` asks for it on those models only;
  every other model still accepts it where `.on` places it.
- A `bound` argument 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](#bind-arguments-to-a-client-bind)). 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 `args` part 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](/docs/extensions/cache) declares its mutation `cache`
  option 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:

```ts
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 of `db` and 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 `$as` again
  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 with `bound(schema)` (another extension's,
  or one of its own `oneOf` or `accepts` arguments) is a
  `ClientInitializationError`.
- `$bind` returns `unknown`: the method that returns the bound client types
  it with a `this` parameter, so each client sees itself. Declare the methods
  apart from the returned object, as above: written inline, the factory's own
  type makes that `this` `void`.
- 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.

```ts
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 `where` and `data`. `$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`/`is` and `recurse`
  included. A `recurse` must write its `depth` (`false` for the whole closure,
  or a number); `true` and `{}` are refused.
- A model without an entry reads as before. A key an entry leaves out adds no
  restriction: an entry with only `read.where` lets 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) }`.
- `rule` also 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 inside `AND`, `OR` and
  `NOT`, and inside `exists`. Your editor types the field and its operators;
  deeper (a relation's own `where`), `$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 with `IS 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's `related`
  rows and never this one's.
- `row("orgId", 1)` reads the column of the row one relation body above (an
  `exists` body 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 a `recurse` relation 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:

```ts
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
```

- `root` filters the rows the call itself selects; `related` filters rows
  reached through a relation. Each takes a `where` or a list of them, which
  conjoin.
- `when` and `unless` are folded per call: a test that does not hold removes
  its filter for that call, and calls that pass the same `oneOf` value 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 not `create` or `createMany`. 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 `oneOf` or `accepts`, 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 a `recurse` over 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 a `read.where`, `root`, `related` or 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`, `InferDatabase` and `renderOperationResultType` describe
  the schema alone: on such a client they type a to-one relation as present
  where it can read `null`. `ExtendedOperationResult` types the client's own
  results, and so does a typed `around`'s `run()`, which also reads the
  rules of the parts before it in its own extension. A rule placed **after**
  an `around` in 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](#compose-extensions)).
- 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 (as
  [`viborm/permissions`](/docs/extensions/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:

```ts expect-error
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.where` is conjoined with every write key: a write never takes a row
  its call cannot see.
- `only` is 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 its `data` writes, that field's `update.fields` entry, which
  replaces `update.where` for that field, else `update.where`, all of them
  at once. An update that writes a field a `keep`
  manages (by hand or through a restore) also takes `delete.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`, `defaults` data) never change
  which key judges: `data: {}` on a row they touch is judged at `update`, 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: `update` and `delete`
  are `NotFoundError`, and `updateMany` and `deleteMany` count only the
  others. A `connect`, `set` or `disconnect` naming a linked row the call may
  not write is `NestedWriteError`. `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):

```ts
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:

```ts expect-error with=sharing
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.where` says which rows an update may take;
  `update.check` says what the row it leaves must hold. To keep an updated
  row inside what its call could have written, write `update.check` with 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 at `update.check` where the update
  writes a field the predicate reads, and at each written field's `check`:
  an update that writes nothing the predicate reads cannot move the row out
  of it, and its statement carries no judgement.
- `acyclic` is judged with the rows a write produces, so it needs a `check`
  on the same model (`create.check`, `update.check` or a field's `check`):
  without one, `$extends()` refuses it.
- `acyclic` may 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 write `NestedWriteError`, before any constraint, so a unique key
  or a missing target never answers first. `createMany` and `updateMany`
  refuse 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 `createMany` or `updateMany` never 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`/`unshift` or an exact decimal's `multiply`/`divide` is 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 a
  `create.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:

```ts with=sharing
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 beside
  `read.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 `select` holding only
  `$access: false` is empty and refused (`ValidationError`), the key comes
  back where the `select` wrote it, and no `data` may write it.
- A gated field is present where its predicate holds and absent elsewhere; the
  row is never dropped. A `select` (or an `omit: { notes: false }`) that names
  it fails with `ValidationError` at its path when a returned row lacks the
  predicate. Every operand a call writes over it (`where`, `orderBy`,
  `distinct`, aggregates and `groupBy`, 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 `facts` key.

### 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:

```ts
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: `updatedAt` is refreshed and field
  transforms run once per row. Handlers, errors and logs still see a `delete`,
  and `delete` returns the row after the update. A `defaults` part's `update`
  data 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 `ForeignKeyError` while 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.
- `keep` writes constants, and `now` in one field at most.
  `keep(unless(arg(x), test, data))` keeps the row unless the test holds, and
  `keep(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. A `keep` is written in an inline entry, not a `lazy`
  one. The official [soft delete](/docs/extensions/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:

```ts
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: `some` or `is`, outside
  a `NOT`, and not in what a `none`, `every` or `isNot` ranges over.
  `confine` can 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`' `tenant` states 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:

```ts
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 `findMany` and `findFirst` (a negative `take` reads
  from its end), a to-many relation read at any depth (`include`, `select`,
  recursive), and the window of a paged `count` or `aggregate` (`take`,
  `skip`, `cursor`), so the rows a page counts are the rows it reads. A
  `cursor` pages through it.
- An explicit `orderBy` replaces it, whole; `orderBy: []` reads in key order.
  Without this extension, a relation read without `orderBy`, `take`, `skip`,
  `cursor` or `distinct` comes back in no particular order.
  `findUnique`, `groupBy` and 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 a `ClientInitializationError`.
- 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](/docs/extensions/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, `upsert` either way. A delete a rule keeps (`keep`) is an update, so it
  writes the `update` fields too. A `connect` or `set` that only moves a
  foreign key writes nothing, as it does not refresh `updatedAt` either. 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 `undefined` counts as left out.
  Writing the field through a relation counts as writing it: when the field is
  the relation's foreign key (`tenantId` for `tenant`), a call that writes
  that relation (`connect`, `create`, `connectOrCreate`, even a nested `update`
  of the tenant) decides the key, and the default steps back. So a default
  `tenantId` is a stamp, not write authorization: a caller who writes
  `tenantId`, 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 its
  `update` fields 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 `tenantId` counts 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](/docs/extensions/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()`](/docs/extensions/omit) 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 |

```ts
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`](/docs/client/raw-sql) 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:

```ts
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 in `modelMethods`.
- 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 `this` set to the delegate it is called on.
  Typed with a `this` parameter and `DelegateOperationResult`, 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 is `unknown`.
- The client `$extends()` returns runs each factory then, once, so a faulty
  factory fails there. Every other view (an interactive transaction's `tx`, a
  client `$bind` returns) 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
  (`$bind` takes no other's), so put `args` and that `methods` part 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](#compose-extensions)). 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`:

```ts
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`, and `createMany` / `updateMany` / `deleteMany`
  with a `select` or `omit`), relation rows reached through `include` or a
  nested `select`, a recursive projection at every level, `$transaction`
  arrays and callbacks, and `$withCache()` reads all carry the field.
  `count`, `aggregate`, `groupBy` and `exist` do not.
- **Selected and omitted by name.** With a `select`, the field is returned
  only when the `select` names it; without one, always. A query-level `omit`
  subtracts 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.
- **`needs` are 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. `compute` is given exactly its `needs`, typed
  from the model: reading another column is a compile error.
- **Computed lazily, once.** Each field is an enumerable getter, as in
  Prisma: `compute` runs the first time the field is read (by your code, a
  spread, `JSON.stringify` or `structuredClone`), 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. A `compute` that 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.
  `$allModels` declares 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 `select` or `omit` may name a computed field
  (`include: { author: { select: { fullName: true } } }`); the types accept
  it only on the operation's own `select` and `omit` for now. `$withCache()`
  delegates and `ExtendedOperationResult` are 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:

```text
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.
- `settled` functions 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([...])`, a `batch` unit surrounds the members. VibORM waits
  until each member's `operation` unit has started its work before any first
  moment, and every member finishes its first moments and reaches `run()` in
  its second before any driver work.

## Compose extensions

Apply extensions in the order they should wrap one another:

```ts with=compose
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:

```ts
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 `extension` is 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 typed `around`'s `run()`
  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`, a `methods`
  part 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](/docs/extensions/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:

```ts with=compose
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:

```ts with=compose,application
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: `call` before `around`, `defaults` before `rule`,
  `where` filters before `only`, `check` and `gate`.
- Put `args` before the parts that read its arguments, and rules before a
  typed `around`.
- Write it inside `$extends(...)`, or bind it with `parts<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, or `again(run)` allows another.
- Call `watch` and `settled` in the first moment.
- Contain a `unit` handler's own faults: what it throws fails the call. Call
  `next()` exactly once.
- Treat a rewriting `unit` as trusted SQL code.
- Use the supplied scope in a `methods` factory, and type model methods
  through `this` when 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](/docs/extensions) for the lifecycle and the
[official extensions](/docs/extensions#official-extensions) for production
cache, instrumentation, default omission, soft delete and
[authorization](/docs/extensions/permissions). Moving an extension written
for the earlier contract: [Migrating an extension](/docs/extensions/migrating).
