@jarenjs/db 0.56.0 → 0.67.0

package/schemas/jaren-replication.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-replication",
+  "title": "Portable logical replication transaction",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$replication",
+    "replica",
+    "seq",
+    "frontier",
+    "model",
+    "operations"
+  ],
+  "properties": {
+    "$replication": {
+      "const": "0.1"
+    },
+    "replica": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "frontier": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128
+      },
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 9007199254740991
+      }
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "table",
+          "key",
+          "before",
+          "after"
+        ],
+        "properties": {
+          "table": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+          },
+          "key": {
+            "type": "string"
+          },
+          "before": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "after": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/src/algebra.js

@@ -27,7 +27,23 @@ export const PLAN_VERSION = 2;
  *   schema-declared type or `'unknown'`; `column` is the generated
  *   column name when the collection indexes this path.
  *
- * @typedef {{ lit: unknown } | { ext: string }} PlanOperand
+ * @typedef {{ lit: unknown } | { ext: string } | { seek: string }} PlanOperand
+ *   A SEEK operand names one of the plan's own seeks: a scalar the
+ *   database itself supplies before the statement runs (`PlanSeek`).
+ *
+ * @typedef {{ name: string, kind: 'number' | 'text', ref: PlanRef,
+ *   bound: { op: 'le' | 'ge', lit: number | string },
+ *   inner: 'max' | 'min', outer: 'min' | 'max',
+ *   group: PlanRef | null, keys: (string | number)[] | null }} PlanSeek
+ *   One anchor the plan asks the database for before it binds. An
+ *   as-of batch cannot bound its far side by arithmetic on the probes:
+ *   the row that answers the EARLIEST probe may lie arbitrarily far
+ *   before it. The tight bound is the data's own — per group, the last
+ *   instant at or before that probe — and the least of those over the
+ *   groups is a scalar every group's answer is at or above. It is one
+ *   aggregate read through the same declared index, and it binds
+ *   through a TYPED slot: its type is the instant column's declared
+ *   type, so the comparison needs no bind-time type branch.
  *
  * @typedef {(
  *   { p: 'and' | 'or', items: PlanPredicate[] } |
@@ -42,7 +58,11 @@ export const PLAN_VERSION = 2;
  *   { p: 'bboxOverlap', columns: { w: string, s: string, e: string,
  *     n: string }, probe: { box: number[] } | { ext: string } } |
  *   { p: 'cellIn', column: string, cells: string[] } |
- *   { p: 'cellPrefix', column: string, prefix: string }
+ *   { p: 'cellPrefix', column: string, prefix: string } |
+ *   { p: 'interval', columns: { start: string, end: string },
+ *     probe: { from: number, to: number } } |
+ *   { p: 'colCmp', op: 'eq' | 'lt' | 'le' | 'gt' | 'ge',
+ *     column: string, operand: { lit: unknown } | { seek: string } }
  * )} PlanPredicate
  *   The last three are the SPATIAL forms: predicates over the derived
  *   index columns a model declares, which a spatial conjunct either
@@ -56,8 +76,62 @@ export const PLAN_VERSION = 2;
  *   box or no cell answers FALSE rather than SQL's NULL and negation
  *   still composes classically.
  *
+ *   `colCmp` is the same idea one comparison wide: a bound over a
+ *   DECLARED column, with no `json_type` beside it. The planner builds
+ *   it only where the comparison NARROWS and something else decides —
+ *   the temporal refinements, whose residual re-runs the caller's own
+ *   operator — because without the guard the column's own type rules
+ *   decide a cross-type row rather than the engine's. Narrowing is what
+ *   makes that safe: SQL's ordering keeps a row the guard would have
+ *   dropped, never the other way about, and the kernel then answers for
+ *   it. In exchange the statement stops reading the document once per
+ *   row to discriminate a member the model already declared.
+ *
+ *   `interval` is the temporal one and carries no guard for the same
+ *   kind of reason: the planner admits it only over a member the schema
+ *   types as an object of two REQUIRED numeric bounds, so a stored
+ *   bound that is absent or textual is a row the collection cannot
+ *   hold. It is true where the row's half-open span meets the probe's
+ *   — and ALSO where the row's own span is empty or reversed, which is
+ *   not an overlap but a row §8.16 RAISES on: a pre-filter narrows, and
+ *   a narrowing that swallowed an error would answer where the engine
+ *   does not.
+ *
+ * @typedef {(
+ *   { p: 'leaf', index: number } |
+ *   { p: 'key', index: number } |
+ *   { p: 'agg', index: number } |
+ *   { p: 'lit', value: unknown } |
+ *   { p: 'object', members: { name: string, node: PlanProjectionNode }[] } |
+ *   { p: 'array', items: PlanProjectionNode[] }
+ * )} PlanProjectionNode
+ *   The shape one projected row answers, rebuilt by the decoder from
+ *   the LEAVES the statement fetched — never by parsing a JSON text the
+ *   database assembled, which could not tell an absent member from a
+ *   present `null`. `leaf` indexes the plan's `leaves`, one entry per
+ *   DISTINCT member path (a path used twice is fetched once); `lit` is a
+ *   value from the caller's document, present in every row even when it
+ *   is `null`, where a leaf that finds nothing is omitted from its
+ *   object and skipped in its array — the engine's own rule.
+ *
  * @typedef {{ ref: PlanRef, desc: boolean, emptyGreatest: boolean }} PlanOrderTerm
  *
+ * @typedef {{ keys: { as: string, ref: PlanRef }[],
+ *   aggregates: { as: string, fn: 'rows' | 'sum' | 'avg' | 'min' | 'max',
+ *     ref: PlanRef | null, empty: 'zero' | 'omit' | 'null' }[],
+ *   tree: PlanProjectionNode,
+ *   order: 'first-seen' | { index: number, desc: boolean, nullsFirst: boolean }[]
+ * }} PlanGroup
+ *   The GENERAL `GROUP BY`: one key per declared grouping name, the
+ *   closed aggregate set over the group's rows, and the projection tree
+ *   the decoder rebuilds each group's answer from — where a `key` node
+ *   reads a key's value beside its JSON type (an absent key is a group
+ *   whose member is omitted, which SQL's `NULL` alone could not say) and
+ *   an `agg` node reads one aggregate under its `empty` rule. `order` is
+ *   `'first-seen'`, the engine's own order of first appearance, or the
+ *   group-key ordering an `$orderby` declared. A plan carrying a group
+ *   carries no `bucket`, no `aggregate` and no `rank`.
+ *
  * @typedef {{ ref: PlanRef, every: number, origin: number, as: string,
  *   order: 'asc' | 'desc' | 'first-seen',
  *   aggregates: { fn: 'rows' | 'sum' | 'avg' | 'min' | 'max',
@@ -73,13 +147,18 @@ export const PLAN_VERSION = 2;
  *   which is the engine's own "order of first appearance" (§6.5).
  *   A plan carrying a bucket carries no `aggregate` and no `rank`.
  *
- * @typedef {{ column: string, dims: number,
+ * @typedef {{ alternatives: { column: string, dims: number }[],
  *   probe: { lit: number[] } | { ext: string },
  *   offset: number, limit: number, margin: number }} PlanRank
- *   The k-nearest stage: the packed vector column the ranking reads,
- *   its declared width, the probe (a plan-time literal vector, or the
- *   external that carries one at call time), the window the ENGINE
- *   will apply, and the inclusive score margin of the candidate cut.
+ *   The k-nearest stage: every packed vector column declared over the
+ *   subject with its width — ONE for a literal probe, whose width is
+ *   known at plan time, and one per declared width for an external
+ *   probe, whose width the BIND names — the probe (a plan-time literal
+ *   vector, or the external that carries one at call time), the window
+ *   the ENGINE will apply, and the inclusive score margin of the
+ *   candidate cut. A plan with several alternatives emits one statement
+ *   per width and binds exactly one: a `CASE` across the columns would
+ *   read every one of them per row.
  *   The column cuts — every row whose column score is within `margin`
  *   of the `offset + limit`-th best is a candidate — and the engine
  *   decides: the original document, its whole ordering and window
@@ -96,10 +175,23 @@ export const PLAN_VERSION = 2;
  *   window: { offset: number, limit: number | null } | null,
  *   rank: PlanRank | null,
  *   bucket: PlanBucket | null,
+ *   group: PlanGroup | null,
+ *   seeks: PlanSeek[],
  *   aggregate: { fn: 'count' | 'sum' | 'avg' | 'min' | 'max',
- *     ref: PlanRef | null } | null,
- *   project: 'document',
+ *     ref: PlanRef | null }
+ *     | { fn: 'registered', ref: PlanRef, operator: string, sql: string }
+ *     | null,
+ *   project: 'document' | { path: PlanRef }
+ *     | { tree: PlanProjectionNode, leaves: PlanRef[] },
  * }} Plan
+ *   `project` is what each row answers: the whole document, or ONE
+ *   member path — its value as JSON text beside its JSON type, so the
+ *   reader tells a present `null` from an absent member and a boolean
+ *   from an integer exactly as the engine does. An aggregate whose `fn`
+ *   is `'registered'` is the Ring-3 one: `operator` is the registry name
+ *   the document used and `sql` the function the store registered for it
+ *   — a NAME, not a fragment of any query language, exactly as a `udf`
+ *   predicate carries one.
  */
 
 /**
@@ -117,11 +209,137 @@ export function selectPlan(collection) {
     window: null,
     rank: null,
     bucket: null,
+    group: null,
+    seeks: [],
     aggregate: null,
     project: 'document',
   };
 }
 
+/**
+ * @typedef {{ source: 'column' | 'document' | 'group' | 'identity',
+ *   binding: string | null, column: string | null,
+ *   path: (string | number)[] | null, desc: boolean,
+ *   nullsFirst: boolean | null, tieBreaker: boolean }} EffectiveOrderTerm
+ *   One term of the order a statement actually executes under. `source`
+ *   is closed: a mapped `column`, a `document` path the dialect
+ *   extracts, the `group` key of a bucketed plan, or the row `identity`
+ *   the emitters append so a sequence answers in insertion order. Only
+ *   a `column` term carries a column name, only a `document` term a
+ *   path, and the identity term carries neither — its value is the
+ *   row's, not the document's, which is why `nullsFirst` is `null`
+ *   there (a row identity is never absent). `tieBreaker` marks a term
+ *   the plan appended rather than one the caller declared.
+ */
+
+/**
+ * Whether an order term reads its value from a mapped column rather
+ * than the document. Two ref shapes reach here — a collection
+ * {@link PlanRef}, which has a column or does not, and an entity ref,
+ * which also carries a flavor: an `entity-epoch` column exists but
+ * orders by the document string (mixed stored precisions would sort
+ * the integer column differently), so a flavored ref answers by its
+ * flavor and only a plain one by its column.
+ * @param {any} ref
+ * @returns {boolean}
+ */
+export function ordersByColumn(ref) {
+  return ref.flavor === undefined ? ref.column !== null : ref.flavor === 'entity-column';
+}
+
+/**
+ * One declared order term as its effective form.
+ * @param {{ ref: any, desc: boolean, emptyGreatest: boolean }} term
+ * @param {string | null} [binding]
+ * @returns {EffectiveOrderTerm}
+ */
+function declaredTerm(term, binding = null) {
+  const byColumn = ordersByColumn(term.ref);
+  return {
+    // Jaren's default sorts an empty key least: NULLS FIRST ascending,
+    // NULLS LAST descending — and mirrored for `$empty: 'greatest'`
+    source: byColumn ? 'column' : 'document',
+    binding,
+    column: byColumn ? term.ref.column : null,
+    path: byColumn ? null : term.ref.segments.map((segment) =>
+      ('name' in segment ? segment.name : segment.index)),
+    desc: term.desc,
+    nullsFirst: term.emptyGreatest === term.desc,
+    tieBreaker: false,
+  };
+}
+
+/**
+ * The row-identity tie-breaker an emitter appends.
+ * @param {string | null} [binding]
+ * @param {boolean} [tieBreaker]
+ * @returns {EffectiveOrderTerm}
+ */
+function identityTerm(binding = null, tieBreaker = true) {
+  return { source: 'identity', binding, column: null, path: null,
+    desc: false, nullsFirst: null, tieBreaker };
+}
+
+/**
+ * The effective order a set of declared terms executes under: the
+ * terms themselves, then one row-identity tie-breaker per binding —
+ * the ordering the emitters append so a collection answers in its
+ * insertion order and a join in the engine's nested-loop order. Given
+ * `keyColumns`, the appended tie-breaker is the primary key instead
+ * (keyset mode: a continuation must resume from a value the row
+ * carries, which a row identity is not).
+ * @param {{ ref: any, desc: boolean, emptyGreatest: boolean,
+ *   binding?: string }[] | null} terms
+ * @param {{ bindings?: (string | null)[],
+ *   keyColumns?: readonly string[] }} [options]
+ * @returns {EffectiveOrderTerm[]}
+ */
+export function effectiveOrder(terms, options = undefined) {
+  const declared = (terms ?? []).map((term) =>
+    declaredTerm(term, term.binding ?? null));
+  const keyColumns = options?.keyColumns;
+  if (keyColumns !== undefined) {
+    for (const column of keyColumns) {
+      // a key column is NOT NULL, so its null placement is the ASC
+      // default, spelled rather than branched on
+      if (!declared.some((term) => term.source === 'column' && term.column === column)) {
+        declared.push({ source: 'column', binding: null, column,
+          desc: false, nullsFirst: true, path: null, tieBreaker: true });
+      }
+    }
+    return declared;
+  }
+  for (const binding of options?.bindings ?? [null]) declared.push(identityTerm(binding));
+  return declared;
+}
+
+/**
+ * The effective order of one plan — the same normalized order its
+ * emitter renders, never read back out of SQL. `null` is the honest
+ * answer for a statement that orders nothing: an aggregate answers one
+ * row, and a k-nearest fetch is deliberately unordered because the
+ * ENGINE ranks the candidates it returns.
+ * @param {any} plan - a select, entity-select or entity-join plan
+ * @returns {EffectiveOrderTerm[] | null}
+ */
+export function planOrder(plan) {
+  if (plan === null || plan === undefined) return null;
+  if (plan.alg === 'entity-select' || plan.alg === 'entity-join') {
+    if (plan.aggregate !== null) return null;
+    return effectiveOrder(plan.order, { bindings: plan.bindings.map((b) => b.name) });
+  }
+  if (plan.aggregate !== null || plan.rank !== null) return null;
+  if (plan.bucket !== null) {
+    // the bucket owns its own ordering: the group key, or — for the
+    // engine's order of first appearance — the group's earliest row
+    return [plan.bucket.order === 'first-seen'
+      ? identityTerm(null, false)
+      : { source: 'group', binding: null, column: plan.bucket.as, path: null,
+        desc: plan.bucket.order === 'desc', nullsFirst: false, tieBreaker: false }];
+  }
+  return effectiveOrder(plan.order);
+}
+
 /**
  * Conjoin a predicate onto a plan's filter.
  * @param {PlanPredicate | null} filter

package/src/backup.js

@@ -0,0 +1,161 @@
+//@ts-check
+/**
+ * @file Online backup with atomic publication. `backupTo(targetPath)`
+ * copies a live store through the driver's backup primitive and
+ * publishes the copy by rename, so the target path never holds a
+ * partial file: the copy is written to a temporary sibling in the same
+ * directory (one file system, so the rename is atomic), renamed onto
+ * the target only once the platform reported the copy complete, and
+ * deleted on every other outcome — a cancellation, a copy failure, a
+ * rename failure. An incomplete backup is never something a later
+ * process could mistake for a good one.
+ *
+ * The copy runs OFF the store gate: an online backup's whole point is
+ * that writers proceed. SQLite updates the copy in place when this
+ * connection writes during it and restarts the copy when another
+ * connection does; only the checkpoint that fixes the snapshot boundary
+ * takes the gate, exactly as the other maintenance operations do.
+ *
+ * Cancellation is honoured BETWEEN pages, at the granularity the
+ * platform reports progress (`rate` pages per step): the platform
+ * itself takes no signal, so the signal is checked in the progress
+ * callback and a throw there is what stops the pump. There is no
+ * progress event with a zero remainder — the platform's completion
+ * signal is the resolved copy, which answers the page total — so
+ * progress events are handed on verbatim and completion is the promise.
+ *
+ * This module imports no runtime builtin: the copy, the rename and the
+ * removal are the driver's primitives (`connection.backup`), present on
+ * the Node binding and declared absent elsewhere.
+ */
+
+import { DbRuntimeError, wrapDriverError } from './errors.js';
+import { chain, attempt, toPromise } from './driver.js';
+import { refuseCancelled } from './cancellation.js';
+
+/**
+ * The temporary sibling of a target path: same directory, a marker a
+ * sweep can recognise, and a suffix from the store's injected
+ * randomness.
+ * @param {string} targetPath
+ * @param {() => number} random
+ * @returns {string}
+ */
+export function temporaryPathFor(targetPath, random) {
+  const word = () => Math.floor(random() * 0x100000000).toString(16).padStart(8, '0');
+  return `${targetPath}.jaren-tmp-${word()}${word()}`;
+}
+
+/**
+ * Build `backupTo` over a connection.
+ * @param {{ connection: any, readOnly: boolean,
+ *   gated: (fn: () => any, what: string) => any,
+ *   checkpoint: (options?: { mode?: string }) => any,
+ *   random: () => number, now: () => number }} context - `checkpoint`
+ *   is the maintenance surface's own (ungated; the gate is taken here
+ *   around it); `now` is the clock a deadline is read against
+ * @returns {{ capability: boolean,
+ *   backupTo: (targetPath: string, options?: any) => any }}
+ */
+export function createBackup({ connection, readOnly, gated, checkpoint, random, now }) {
+  const capability = connection.capabilities.backup === true && connection.backup !== null;
+
+  /** The driver's own failure, classed and wrapped under the backup's
+   * lifecycle code; a coded error is the error. A file-system failure
+   * (a refused rename, a missing directory the platform reports as
+   * `unable to open`) rides the same wrap. */
+  const failed = (error) => wrapDriverError(error, { code: 'JD2078', reason: 'the backup failed', always: true });
+
+  /** @param {AbortSignal} signal */
+  const cancelled = (signal) => new DbRuntimeError('JD2079',
+    'the backup was cancelled between pages; the temporary file was removed and the '
+    + 'target path was not written', { cause: signal.reason });
+  /** The check before the copy starts and between its pages: an abort
+   * is the backup's own lifecycle code, a passed deadline the one
+   * deadline code, both with the file consequences named. */
+  const callable = (options, ran) => refuseCancelled(options, now,
+    { abortCode: 'JD2079', aborted: 'the copy started', passed: 'the next page', ran });
+
+  return {
+    capability,
+    /**
+     * @param {string} targetPath
+     * @param {{ rate?: number, onProgress?: (progress: { totalPages: number,
+     *   remainingPages: number }) => void, signal?: AbortSignal,
+     *   deadline?: number, checkpoint?: string | false }} [options]
+     * @returns {any} value-or-promise of `{ path, pages, checkpoint }`
+     */
+    backupTo(targetPath, options = undefined) {
+      if (typeof targetPath !== 'string' || targetPath.length === 0)
+        throw new TypeError('backupTo: targetPath is a non-empty string');
+      const rate = options?.rate;
+      if (rate !== undefined && (!Number.isSafeInteger(rate) || rate < 1))
+        throw new TypeError(`backupTo: rate is a positive integer (pages per step), got ${JSON.stringify(rate)}`);
+      const onProgress = options?.onProgress;
+      if (onProgress !== undefined && typeof onProgress !== 'function')
+        throw new TypeError('backupTo: onProgress is a function');
+      const signal = options?.signal;
+      if (!capability) {
+        throw new DbRuntimeError('JD2077',
+          "the maintenance operation 'backupTo' is unavailable on this store: the driver's binding "
+          + 'declares no backup primitive');
+      }
+      // the snapshot boundary: the checkpoint mode, `false` to skip it,
+      // and skipped by default on a read-only store, where a checkpoint
+      // is not an operation this store may run
+      const mode = options?.checkpoint === undefined
+        ? (readOnly ? false : 'passive')
+        : options.checkpoint;
+      if (mode !== false && (typeof mode !== 'string'))
+        throw new TypeError("backupTo: checkpoint is a wal_checkpoint mode or false");
+      callable(options, 'no file was written');
+
+      const boundary = mode === false
+        ? null
+        : gated(() => checkpoint({ mode }), 'a backup checkpoint');
+      return chain(boundary, (checkpointed) => {
+        callable(options, 'no file was written');
+        const tmpPath = temporaryPathFor(targetPath, random);
+        const files = connection.backup;
+        /** Remove the temporary file, then settle with `error`; a
+         * removal that itself fails rides along rather than replacing
+         * the reason the backup failed. */
+        const discard = (error) => chain(
+          attempt(() => files.remove(tmpPath), (removal) => {
+            error.cleanupError = removal;
+            return error;
+          }),
+          () => { throw error; });
+        let aborted = null;
+        const progress = (report) => {
+          if (signal?.aborted === true) {
+            aborted = cancelled(signal);
+            throw aborted;
+          }
+          // a passed deadline stops the pump between pages exactly as an
+          // abort does, under its own code
+          callable(options, 'the temporary file was removed and the target path was not written');
+          onProgress?.({ totalPages: report.totalPages, remainingPages: report.remainingPages });
+        };
+        let copying;
+        try {
+          copying = files.copy(tmpPath, rate === undefined ? { progress } : { rate, progress });
+        }
+        catch (error) {
+          return discard(aborted ?? failed(error));
+        }
+        // publication: the platform's resolved copy is its completion
+        // signal (it answers the page total); only then is the
+        // temporary file renamed onto the target. The file primitives
+        // are asynchronous on every host that has them, so this leg is
+        // a promise on purpose
+        const publish = (pages) => chain(
+          attempt(() => files.rename(tmpPath, targetPath), failed),
+          () => Object.freeze({ path: targetPath, pages: Number(pages), checkpoint: checkpointed ?? null }));
+        return toPromise(copying)
+          .then((pages) => toPromise(publish(pages)))
+          .catch((error) => discard(aborted ?? failed(error)));
+      });
+    },
+  };
+}

package/src/cancellation.js

@@ -0,0 +1,48 @@
+//@ts-check
+/**
+ * @file The ONE cancellation check every unit of work in this package
+ * runs before it starts: an aborted signal is a coded refusal naming
+ * what was cancelled, a deadline is validated and read against the
+ * clock the caller was given — the store's runtime record's, never the
+ * platform's — and a passed one is `JD2075`, the one deadline code,
+ * whatever the unit (a statement, a row, a step, a batch, a page).
+ *
+ * The check runs BETWEEN units, never inside one: the shipped SQLite
+ * drivers expose no interrupt, so a statement that has started runs to
+ * its end, and the capability report says so (`cancellation.midStatement`
+ * is `false`). Each caller names the abort code its lifecycle owns —
+ * `JD2072` for a query, `JD2080` for a migration, `JD2081` for a
+ * maintenance operation, `JD2079` for a backup — and the unit it was
+ * about to start, so the refusal says exactly where the work stopped.
+ */
+
+import { DbRuntimeError } from './errors.js';
+
+/**
+ * Refuse to start the next unit of work when the caller's signal has
+ * aborted or its deadline has passed.
+ * @param {{ signal?: AbortSignal, deadline?: number } | undefined} options
+ * @param {() => number} now - the clock the deadline is read against
+ * @param {{ abortCode: string, aborted: string, passed: string, ran?: string }} what -
+ *   the abort code this lifecycle owns, the unit an abort was caught
+ *   before ("the call was aborted before <aborted>"), the unit a passed
+ *   deadline was caught before ("the deadline passed before <passed>"),
+ *   and what has NOT happened as a result (default: "no statement was
+ *   issued")
+ */
+export function refuseCancelled(options, now, what) {
+  const ran = what.ran ?? 'no statement was issued';
+  const signal = options?.signal;
+  if (signal?.aborted === true) {
+    throw new DbRuntimeError(what.abortCode,
+      `the call was aborted before ${what.aborted}: ${ran}`, { cause: signal.reason });
+  }
+  const deadline = options?.deadline;
+  if (deadline === undefined) return;
+  if (typeof deadline !== 'number' || !Number.isFinite(deadline))
+    throw new TypeError('deadline is an epoch-millisecond number');
+  if (now() > deadline) {
+    throw new DbRuntimeError('JD2075',
+      `the deadline passed before ${what.passed} (${new Date(deadline).toISOString()}); ${ran}`);
+  }
+}