@bakery-framework/orm 2.0.0-alpha.9 → 2.0.0-rc.1

package/src/adapters/mysql.ts

@@ -13,11 +13,11 @@ export class MySQLAdapter extends SQLAdapter {
         ? connectionTarget.toString().replace(/^(mysqli?s?:\/\/)/, 'mysql://')
         : undefined
     super('mysql', undefined, target)
-    // `isOpenConnection`, not `instanceof SQL` — see the helper for why the
+    // `isOpenConnection`, not `instanceof SQL`. See the helper for why the
     // latter throws rather than answering.
     //
     // Pool options apply only when this opens its own connection. A handle
-    // handed in is already someone else's pool — notably a transaction's, where
+    // handed in is already someone else's pool: notably a transaction's, where
     // re-sizing anything would be meaningless.
     this.sql = isOpenConnection(connectionTarget)
       ? (connectionTarget as SQL)
@@ -40,7 +40,7 @@ export class MySQLAdapter extends SQLAdapter {
         // `affectedRows` first, and the order is the whole fix.
         //
         // Bun's MySQL driver sets `count` to **0** for every write and puts the
-        // real number in `affectedRows` — the reverse of SQLite, where `count`
+        // real number in `affectedRows`: the reverse of SQLite, where `count`
         // is authoritative and `affectedRows` is null. Reading `count` first
         // through a `??` chain therefore never fell through: zero is not
         // nullish, so it was taken and returned. Every insert, update and
@@ -251,7 +251,7 @@ export class MySQLAdapter extends SQLAdapter {
   /**
    * MySQL binds a view's tables at query time, not at `CREATE VIEW`, so a table
    * can be dropped and rebuilt underneath a view that names it. SQLite and
-   * Postgres both refuse — see the base declaration for the two messages.
+   * Postgres both refuse. See the base declaration for the two messages.
    */
   override get viewsBlockTableRebuild(): boolean {
     return false
@@ -270,7 +270,9 @@ export class MySQLAdapter extends SQLAdapter {
     return new MySQLAdapter(sql as SQL)
   }
 
-  async getSchema(): Promise<SQLAdapter.TableDetails[]> {
+  async getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]> {
     const res = (await this.query(
       'SELECT table_name AS name' +
         ' FROM information_schema.tables' +
@@ -280,7 +282,11 @@ export class MySQLAdapter extends SQLAdapter {
     const tablesWithDetails: SQLAdapter.TableDetails[] = []
     for (const t of res) {
       const [countRes, cols, idxs] = (await Promise.all([
-        this.query(`SELECT COUNT(*) as count FROM ${this.quote(t.name)}`).get(),
+        options?.rowCounts
+          ? this.query(
+              `SELECT COUNT(*) as count FROM ${this.quote(t.name)}`,
+            ).get()
+          : null,
         this.query(
           'SELECT column_name AS name, data_type AS type,' +
             ' is_nullable AS is_nullable, column_key AS column_key' +
@@ -293,13 +299,13 @@ export class MySQLAdapter extends SQLAdapter {
             ' FROM information_schema.statistics' +
             ' WHERE table_name = ? AND table_schema = DATABASE()',
         ).all(t.name),
-      ])) as [SQLAdapter.CountRow, any[], any[]]
+      ])) as [SQLAdapter.CountRow | null, any[], any[]]
       const uniqueIdxs = Array.from(
         new Map(idxs.map(i => [i.name, i.non_unique === 0])).entries(),
       ).map(([name, unique]) => ({ name, unique }))
       tablesWithDetails.push({
         name: t.name,
-        rowCount: countRes?.count || 0,
+        rowCount: options?.rowCounts ? countRes?.count || 0 : null,
         columns: cols.map(c => ({
           name: c.name,
           type: c.type,
@@ -326,10 +332,15 @@ export class MySQLAdapter extends SQLAdapter {
       new Set(cols.map(c => c.name)),
     )
     const tName = this.quote(tableName)
-    const countRes = (await this.query(
-      `SELECT COUNT(*) as count FROM ${tName}${whereSql}`,
-    ).get(...whereParams)) as SQLAdapter.CountRow
-    const totalRows = countRes?.count || 0
+    // See `TableDataOptions.knownTotal`: the count is almost the whole cost
+    // of a page, and a caller that has already counted can say so.
+    const reuse = SQLAdapter.usableTotal(options.knownTotal)
+    const countRes = reuse
+      ? null
+      : ((await this.query(
+          `SELECT COUNT(*) as count FROM ${tName}${whereSql}`,
+        ).get(...whereParams)) as SQLAdapter.CountRow)
+    const totalRows = reuse ? options.knownTotal! : countRes?.count || 0
     const rows = await this.query(
       `SELECT * FROM ${tName}${whereSql}${orderSql} LIMIT ? OFFSET ?`,
     ).all(
@@ -352,7 +363,7 @@ export class MySQLAdapter extends SQLAdapter {
    *
    * This deliberately does *not* go through `getSchema()`. That lists every
    * table in the database and then issues `COUNT(*)` plus two
-   * information_schema queries per table — so deleting one row from a
+   * information_schema queries per table, so deleting one row from a
    * twenty-table schema ran sixty-one statements, twenty of them full row
    * counts, to learn one column name. The pk is one lookup against the same
    * `column_key = 'PRI'` that getSchema itself derived the flag from, in the
@@ -400,8 +411,8 @@ export class MySQLAdapter extends SQLAdapter {
    * Every information_schema column is aliased to its own lowercase name, and
    * the aliases are load-bearing despite looking redundant.
    *
-   * MySQL 8 returns information_schema field names **uppercase** — a bare
-   * `SELECT table_name` yields a row keyed `TABLE_NAME` — while an alias is
+   * MySQL 8 returns information_schema field names **uppercase** (a bare
+   * `SELECT table_name` yields a row keyed `TABLE_NAME`), while an alias is
    * returned exactly as written. Without them `t.table_name` is `undefined`
    * and this method throws `undefined is not an object` inside `Case.camel`,
    * which takes `db:sync` against MySQL down entirely. Postgres was never
@@ -505,6 +516,7 @@ export class MySQLAdapter extends SQLAdapter {
           type: info.non_unique === 0 ? 'unique' : 'index',
           table: Case.camel(info.table),
           cols: info.cols.map(Case.camel),
+          rawCols: info.cols,
         },
       ]),
     )
@@ -512,7 +524,7 @@ export class MySQLAdapter extends SQLAdapter {
   // Match pattern only. MySQL re-renders an expression default before storing
   // it in information_schema (`unix_timestamp()`, case and parens not
   // guaranteed), and isDateNowDefault() strips parens and uppercases before
-  // comparing — so the bare prefix is the right entry here. It is *not*
+  // comparing, so the bare prefix is the right entry here. It is *not*
   // emittable SQL; see below.
   override readonly dateNowDefaults: string[] = ['UNIX_TIMESTAMP']
 
@@ -539,7 +551,7 @@ export class MySQLAdapter extends SQLAdapter {
       ),
     }
     // `column_type` ('varchar(64)'), not `data_type` ('varchar'), so the guard
-    // sees the same string a human would read — and so TEXT, whose
+    // sees the same string a human would read, and so TEXT, whose
     // character_maximum_length MySQL reports as 65535, is excluded.
     const length = this.sizedTextLength(
       String(col.column_type || col.data_type || ''),

package/src/adapters/observe.ts

@@ -6,7 +6,7 @@ import type { SQLAdapter } from './base'
  *
  * Deliberately **not** an emitter and **not** a listener array. This sits in
  * the hot path of every statement the ORM runs, so the cost of having the
- * feature at all has to be a single null read when nobody is watching — see
+ * feature at all has to be a single null read when nobody is watching. See
  * `observe()` below, which returns the driver's own value untouched in that
  * case. An emitter would allocate an event object and walk a list per query
  * whether or not anything subscribed.
@@ -22,12 +22,12 @@ import type { SQLAdapter } from './base'
 export type QueryMethod = 'all' | 'run' | 'get' | 'values' | 'iterate'
 
 export interface QueryEvent {
-  /** The statement as handed to the driver, before dialect normalisation. */
+  /** The statement as handed to the driver, before dialect normalization. */
   sql: string
   /** Wall-clock duration in milliseconds, fractional. */
   ms: number
   /**
-   * Rows the statement produced, or `null` when it cannot be known — a failed
+   * Rows the statement produced, or `null` when it cannot be known: a failed
    * statement, or a result shape the adapter does not describe as an array.
    * For `run` this is the *affected* row count, not a result set.
    */
@@ -47,7 +47,7 @@ export interface QueryEvent {
    * observer receives is one `logger.info` away from a log file, an analytics
    * table or a dashboard panel. Defaulting this on would turn "add a slow
    * query panel" into a credential leak that nobody reviewed. Callers that
-   * genuinely need bindings — a local query profiler, say — must ask, and are
+   * genuinely need bindings (a local query profiler, say) must ask, and are
    * then responsible for what they do with them.
    */
   params?: readonly unknown[]
@@ -73,7 +73,7 @@ let includeParams = false
  * call installed, so a test that forgets to restore cannot silently unhook a
  * later one.
  *
- * ```ts no-check — illustrative: the app decides where slow queries go
+ * ```ts no-check: illustrative: the app decides where slow queries go
  * import { setQueryObserver } from '@bakery-framework/orm'
  *
  * setQueryObserver(event => {
@@ -150,7 +150,7 @@ async function timed<R>(
         rows: null,
         driver,
         method,
-        // Normalised so `error` is a reliable "did this throw" signal: a driver
+        // Normalized so `error` is a reliable "did this throw" signal: a driver
         // that rejects with `undefined` would otherwise be indistinguishable
         // from success.
         error: error ?? new Error('query failed with no error value'),
@@ -165,8 +165,8 @@ async function timed<R>(
  * Wrap one executor entry point so it reports to the observer.
  *
  * The unobserved path is the `if` below and nothing else: no timer read, no
- * event object, and the underlying call's own return value — which for `all`
- * and `run` may legitimately be synchronous — passes straight through.
+ * event object, and the underlying call's own return value (which for `all`
+ * and `run` may legitimately be synchronous) passes straight through.
  */
 export function observe<R>(
   driver: SQLAdapter.Driver,
@@ -182,7 +182,7 @@ export function observe<R>(
 ): (sqlText: string, params?: unknown[]) => Promise<R> | R
 // Two overloads because the executor's five entry points are not one shape.
 // `get` and `values` are declared to return a promise unconditionally, while
-// `all` and `run` may legitimately be synchronous — and the implementation
+// `all` and `run` may legitimately be synchronous, and the implementation
 // signature, which has to admit both, cannot narrow to the former on its own.
 // Without the first overload `createExecutor` fails to satisfy `Executor`.
 export function observe<R>(
@@ -201,7 +201,7 @@ export function observe<R>(
  * `iterate` is a stream, so its duration means something different from the
  * other four, and the choice here is deliberate:
  *
- * - `ms` spans from the call to `iterate()` until iteration **ends** — the
+ * - `ms` spans from the call to `iterate()` until iteration **ends**: the
  *   generator is exhausted, throws, or the consumer breaks out of the loop.
  *   That includes whatever the consumer did between yields, so an `iterate`
  *   event is not comparable with an `all` event and must not be averaged into
@@ -254,7 +254,7 @@ export function observeIterate(
     // The source is created here rather than inside `drain`, and `started` with
     // it: an async generator body does not run until the first `next()`, so
     // both would otherwise be deferred to whenever the consumer got round to
-    // pulling — and the statement would be issued later than it is today.
+    // pulling, and the statement would be issued later than it is today.
     const started = performance.now()
     return drain(driver, iterate(sqlText, params), sqlText, params, started)
   }

package/src/adapters/pgsql.ts

@@ -22,11 +22,11 @@ export class PGAdapter extends SQLAdapter {
         ? connectionTarget.toString()
         : undefined
     super('postgres', undefined, target)
-    // `isOpenConnection`, not `instanceof SQL` — see the helper for why the
+    // `isOpenConnection`, not `instanceof SQL`. See the helper for why the
     // latter throws rather than answering.
     //
     // Pool options apply only when this opens its own connection. A handle
-    // handed in is already someone else's pool — notably a transaction's, where
+    // handed in is already someone else's pool: notably a transaction's, where
     // re-sizing anything would be meaningless.
     this.sql = isOpenConnection(connectionTarget)
       ? (connectionTarget as SQL)
@@ -57,16 +57,23 @@ export class PGAdapter extends SQLAdapter {
 
   private static handleSpecial(
     char: string,
-    nextChar: string | undefined,
+    // Underscored because it is deliberately unread: the branch that would
+    // have used it is the backslash branch, and the comment below is why
+    // there is not one. Kept in the signature so the shape matches
+    // `handleSpecial` in the other two adapters.
+    _nextChar: string | undefined,
     state: PGSQLParserState,
   ): string | null {
-    if (char === '\\') {
-      if ((state.inSingleQuote || state.inDoubleQuote) && nextChar) {
-        state.skipNext = true
-        return `\\${nextChar}`
-      }
-      return char
-    }
+    // No backslash branch, deliberately. Postgres with
+    // `standard_conforming_strings`: the server default since 9.1, and what
+    // every connection here runs under: treats a backslash inside a `'…'`
+    // literal as an ordinary character. This scanner used to apply MySQL's
+    // rule instead: `\` consumed the next character, so the `'` closing a
+    // `'\'` literal was eaten, the scanner stayed "inside" a literal the
+    // server had already closed, and every `?` after it was left unrewritten,
+    // which is how `ESCAPE '\'` produced a syntax error several tokens
+    // downstream. The server's parse is the only one that matters; the scanner
+    // now agrees with it by having no opinion about backslashes at all.
     if (char === '`') {
       return !state.inSingleQuote && !state.inDoubleQuote ? '"' : char
     }
@@ -89,7 +96,7 @@ export class PGAdapter extends SQLAdapter {
       skipNext: false,
       paramsLength: params.length,
     }
-    // `skipNext` is consumed in exactly one place — the `i++` below — and
+    // `skipNext` is consumed in exactly one place (the `i++` below), and
     // cleared there.
     //
     // It used to be consumed twice: a top-of-loop
@@ -100,9 +107,8 @@ export class PGAdapter extends SQLAdapter {
     // default containing an apostrophe silently lost the rest of its value, and
     // the same applied to a backslash escape. Values bind as parameters, so
     // this
-    // only ever reached literals the framework itself emits — DDL defaults —
-    // which is why it survived: `ddl.test.ts` asserts the SQL *before*
-    // normalisation, and no live server ran until now.
+    // only ever reached literals the framework itself emits (DDL defaults),     // which is why it survived: `ddl.test.ts` asserts the SQL *before*
+    // normalization, and no live server ran until now.
     for (let i = 0; i < sql.length; i++) {
       const char = sql[i]
       const nextChar = sql[i + 1]
@@ -142,15 +148,15 @@ export class PGAdapter extends SQLAdapter {
         PGAdapter.normalizePostgresSQL(sql, params),
         params,
       )) as any
-      // `count` is authoritative on Postgres for every command — it is the
-      // row count from the command tag — so it is read first and `rows.length`
+      // `count` is authoritative on Postgres for every command (it is the
+      // row count from the command tag), so it is read first and `rows.length`
       // is only a fallback.
       //
       // It used to be the other way round, behind an `Array.isArray` check
       // that was always true: Bun returns an *array* for a write too, just an
       // empty one, so the `count` branch was unreachable and `changes` was
       // `rows.length`. `UPDATE` and `DELETE` return no rows, so both reported
-      // 0. `INSERT` was right only by accident — the `RETURNING *` appended
+      // 0. `INSERT` was right only by accident: the `RETURNING *` appended
       // above happens to make `rows.length` the number inserted.
       const changes = Number(
         rows?.count ?? (Array.isArray(rows) ? rows.length : 0),
@@ -246,7 +252,9 @@ export class PGAdapter extends SQLAdapter {
     return new PGAdapter(sql as SQL)
   }
 
-  async getSchema(): Promise<SQLAdapter.TableDetails[]> {
+  async getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]> {
     const res = (await this.query(
       'SELECT table_name AS name, table_type AS type' +
         ' FROM information_schema.tables' +
@@ -261,7 +269,9 @@ export class PGAdapter extends SQLAdapter {
       res.map(async t => {
         const qName = this.quote(t.name)
         const [countRes, cols, pkCols, idxs] = (await Promise.all([
-          this.query(`SELECT COUNT(*)::int as count FROM ${qName}`).get(),
+          options?.rowCounts
+            ? this.query(`SELECT COUNT(*)::int as count FROM ${qName}`).get()
+            : null,
           this.query(
             'SELECT column_name AS name, data_type AS type,' +
               ' is_nullable AS is_nullable' +
@@ -271,8 +281,8 @@ export class PGAdapter extends SQLAdapter {
               ' ORDER BY ordinal_position',
           ).all(t.name),
           // `::regclass` casts a **string**, so the table name binds as a
-          // parameter. It used to interpolate `qName` — a double-quoted
-          // *identifier* — which Postgres reads as a column reference, so this
+          // parameter. It used to interpolate `qName` (a double-quoted
+          // *identifier*), which Postgres reads as a column reference, so this
           // threw `column "<table>" does not exist` for every table and took the
           // whole of `getSchema()` down with it on this dialect.
           //
@@ -292,10 +302,10 @@ export class PGAdapter extends SQLAdapter {
               " WHERE schemaname NOT IN ('pg_catalog', 'information_schema')" +
               ' AND tablename = ?',
           ).all(t.name),
-        ])) as [SQLAdapter.CountRow, any[], any[], any[]]
+        ])) as [SQLAdapter.CountRow | null, any[], any[], any[]]
         return {
           name: t.name,
-          rowCount: countRes?.count || 0,
+          rowCount: options?.rowCounts ? countRes?.count || 0 : null,
           columns: cols.map(c => ({
             name: c.name,
             type: c.type,
@@ -326,10 +336,15 @@ export class PGAdapter extends SQLAdapter {
       new Set(cols.map(c => c.name)),
     )
     const tName = this.quote(tableName)
-    const countRes = (await this.query(
-      `SELECT COUNT(*) as count FROM ${tName}${whereSql}`,
-    ).get(...whereParams)) as SQLAdapter.CountRow
-    const totalRows = countRes?.count || 0
+    // See `TableDataOptions.knownTotal`: the count is almost the whole cost
+    // of a page, and a caller that has already counted can say so.
+    const reuse = SQLAdapter.usableTotal(options.knownTotal)
+    const countRes = reuse
+      ? null
+      : ((await this.query(
+          `SELECT COUNT(*) as count FROM ${tName}${whereSql}`,
+        ).get(...whereParams)) as SQLAdapter.CountRow)
+    const totalRows = reuse ? options.knownTotal! : countRes?.count || 0
     const rows = (await this.query(
       `SELECT ctid::text AS rowid, * FROM ${tName}` +
         `${whereSql}${orderSql} LIMIT ? OFFSET ?`,
@@ -438,7 +453,7 @@ export class PGAdapter extends SQLAdapter {
       }
 
       // is_identity/identity_generation are selected because an identity column
-      // — what colDef() emits — carries a NULL column_default; only the legacy
+      // (what colDef() emits) carries a NULL column_default; only the legacy
       // serial style leaves a nextval(...) marker there.
       const cols = (await this.query(
         'SELECT column_name, data_type, is_nullable, column_default,' +
@@ -473,24 +488,24 @@ export class PGAdapter extends SQLAdapter {
       )
         continue
       const m = r.indexdef.match(/\(([^)]+)\)/)
+      const raw: string[] = m
+        ? m[1].split(',').map((c: string) => c.trim().replace(/"/g, ''))
+        : []
       dbIndexes[Case.camel(r.indexname)] = {
         type: /UNIQUE/i.test(r.indexdef) ? 'unique' : 'index',
         table: Case.camel(r.tablename),
-        cols: m
-          ? m[1]
-              .split(',')
-              .map((c: string) => Case.camel(c.trim().replace(/"/g, '')))
-          : [],
+        cols: raw.map(Case.camel),
+        rawCols: raw,
       }
     }
     return dbIndexes
   }
-  // Two patterns because Postgres does not store DDL text — it stores a parsed
+  // Two patterns because Postgres does not store DDL text: it stores a parsed
   // expression and re-renders it, and how it renders depends on the version.
   // PG 14+ reports `(EXTRACT(epoch FROM now()))::integer`; PG <= 13 parses
   // EXTRACT into `date_part('epoch'::text, now())`, which the EXTRACT pattern
   // does not match. Missing it means the column diffs dirty on every single
-  // sync — the same perpetual-rebuild failure the SQLite quote bug caused.
+  // sync: the same perpetual-rebuild failure the SQLite quote bug caused.
   override readonly dateNowDefaults: string[] = [
     'EXTRACT(EPOCH FROM',
     'DATE_PART',
@@ -506,7 +521,7 @@ export class PGAdapter extends SQLAdapter {
   // `gen_random_uuid()` is built in from Postgres 13; before that it lived in
   // the pgcrypto extension. Postgres reports it back as
   // `gen_random_uuid()`, so unlike the epoch expression the emitted form and
-  // the match pattern coincide — stated rather than assumed, because the two
+  // the match pattern coincide: stated rather than assumed, because the two
   // being equal here is a coincidence of this expression, not a rule.
   override readonly uuidDefaults: string[] = ['GEN_RANDOM_UUID']
   override readonly uuidExpression: string = 'gen_random_uuid()'
@@ -521,7 +536,7 @@ export class PGAdapter extends SQLAdapter {
       ),
     }
     // Postgres calls it 'character varying' and reports null for TEXT, so the
-    // guard has less to do here than on MySQL — but it is the same guard.
+    // guard has less to do here than on MySQL, but it is the same guard.
     const length = this.sizedTextLength(
       String(col.data_type || col.udt_name || ''),
       col.character_maximum_length,
@@ -542,11 +557,11 @@ export class PGAdapter extends SQLAdapter {
       // Postgres does not store the DDL text of a default; it re-renders the
       // parsed expression and appends the column's type. `''` comes back as
       // `''::character varying` and `'x'` as `'x'::text`, neither of which
-      // equals what the schema says — so the column diffs on every sync.
+      // equals what the schema says, so the column diffs on every sync.
       //
       // The cast is only stripped when it ends the string, which leaves
       // `nextval('seq'::regclass)` and the `%dateNow%` expressions alone: both
-      // end in `)`, and both are recognised elsewhere.
+      // end in `)`, and both are recognized elsewhere.
       if (typeof def === 'string') {
         const bare = def.replace(/::[\w ]+$/, '').trim()
         const quoted = /^'([\s\S]*)'$/.exec(bare)

package/src/adapters/registry.ts

@@ -6,11 +6,11 @@ import type { SQLAdapter } from './base'
  * add its own.
  *
  * A union type cannot be extended from outside the package, and widening it to
- * `string` would give up every place the compiler currently catches a typo — so
+ * `string` would give up every place the compiler currently catches a typo, so
  * this is an interface and a new name arrives by declaration merging, the same
  * mechanism `DBSchema` already uses for an app's tables:
  *
- * ```ts no-check — a third-party package's own declaration file
+ * ```ts no-check: a third-party package's own declaration file
  * declare module '@bakery-framework/orm/adapters' {
  *   interface DriverRegistry {
  *     mssql: true
@@ -18,7 +18,7 @@ import type { SQLAdapter } from './base'
  * }
  * ```
  *
- * `@bakery-framework/orm/adapters` — the public subpath — and not this file, which is
+ * `@bakery-framework/orm/adapters` (the public subpath), and not this file, which is
  * private and does not resolve from outside the package. The merge reaches
  * through the barrel's `export *`; aiming it at an unresolvable specifier
  * instead declares a second, unrelated interface and leaves every driver name
@@ -47,14 +47,14 @@ export interface AdapterSpec {
   /**
    * URL schemes this adapter answers to, without `://`.
    *
-   * Checked first and exactly — `mysql://…` reaches the adapter that listed
+   * Checked first and exactly: `mysql://…` reaches the adapter that listed
    * `mysql`, and nothing else is consulted. List every spelling you accept;
    * the built-in MySQL adapter lists four.
    */
   protocols?: readonly string[]
 
   /**
-   * Last resort, for a target no scheme matched — a bare file path, say.
+   * Last resort, for a target no scheme matched: a bare file path, say.
    *
    * Consulted in reverse registration order, so an adapter registered later can
    * claim a target one of the built-ins would otherwise have taken. Return
@@ -66,7 +66,7 @@ export interface AdapterSpec {
    * Open a connection. `target` is the raw `DB_URL`, or `undefined` when none
    * was set and this adapter is the default.
    *
-   * Async so the implementation can `await import()` its own driver module —
+   * Async so the implementation can `await import()` its own driver module,
    * which is how the three built-ins stay lazy: registering all of them costs
    * three object literals, and only the one that wins is ever loaded.
    */
@@ -77,7 +77,7 @@ export interface AdapterSpec {
 }
 
 /**
- * What to fall back to when the target names no adapter — split in two because
+ * What to fall back to when the target names no adapter: split in two because
  * the two cases have never had the same answer. See {@link resolveDriver}.
  */
 export interface DriverFallback {
@@ -96,8 +96,8 @@ export const DEFAULT_FALLBACK: DriverFallback = {
  * A stack per driver name, not one entry per name.
  *
  * Registering over an existing driver is temporary far more often than it is
- * permanent — a test swapping in a fake, an app overriding a built-in for one
- * environment — so "undo" has to give back exactly what was displaced. One
+ * permanent (a test swapping in a fake, an app overriding a built-in for one
+ * environment), so "undo" has to give back exactly what was displaced. One
  * entry per name cannot: release two registrations out of order and the second
  * disposer restores the first's spec, quietly leaving a stub adapter installed
  * for the rest of the process. A stack makes the order irrelevant, which is the
@@ -149,14 +149,14 @@ export function listAdapters(): AdapterSpec[] {
  * 1. **No target at all** → `fallback` (`sqlite`), so a fresh app with no
  *    `DB_URL` gets a file database rather than an error.
  * 2. **A URL scheme** that some adapter declared → that adapter, exactly.
- * 3. **`matches()`**, in reverse registration order — later registrations get
+ * 3. **`matches()`**, in reverse registration order: later registrations get
  *    first refusal, which is what makes overriding a built-in possible.
  * 4. **`fallback`** otherwise, which for a target that looked like a host is
- *    `postgres`. Long-standing behaviour, kept deliberately: a bare
+ *    `postgres`. Long-standing behavior, kept deliberately: a bare
  *    `db.internal:5432/app` has been read as Postgres since before the
  *    registry existed.
  *
- * Throws only if the resolved driver has no adapter registered — which means
+ * Throws only if the resolved driver has no adapter registered, which means
  * something registered a `protocols` entry and then unregistered itself, not
  * anything a user can reach by typing a URL.
  */
@@ -175,7 +175,7 @@ export function resolveAdapter(
   return spec
 }
 
-/** Step 1–4 of {@link resolveAdapter}, without the lookup. */
+/** Step 1 to 4 of {@link resolveAdapter}, without the lookup. */
 export function resolveDriver(
   target: string,
   fallback: DriverFallback = DEFAULT_FALLBACK,