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

package/src/adapters/sqlite.ts

@@ -1,10 +1,20 @@
 import path from 'node:path'
 import { Bakery } from '@bakery-framework/core/core/bakery'
+import { Logger, messageLogger } from '@bakery-framework/core/logger'
 import { Case, Try } from '@bakery-framework/core/utils'
 import { SQL } from 'bun'
 import type * as SyncTypes from '../sync/types'
 import { createExecutor, SQLAdapter } from './base'
 
+// Convention 4: logging is data, declared in a table rather than formatted at
+// the call site.
+const MESSAGES = messageLogger(new Logger('database'), {
+  JOURNAL_WAL_REFUSED:
+    'W SQLite refused WAL for %y{file}%* (answered %y{answer}%*): running the %y{mode}%* journal instead. Expected on a network path; on a local disk it costs every write.',
+  PRAGMA_FAILED:
+    'W A SQLite performance pragma was rejected: %r{error}%*. The database works; it is not tuned.',
+} as const)
+
 export class SQLiteAdapter extends SQLAdapter {
   // SQLite's standard identifier quote. The base class defaults to MySQL's
   // backtick, which SQLite only tolerates as a compatibility extension.
@@ -12,12 +22,26 @@ export class SQLiteAdapter extends SQLAdapter {
 
   protected readonly sql: SQL
 
+  /**
+   * Resolves when the performance pragmas have finished, or failed loudly.
+   *
+   * They are deliberately not awaited by every query the way `ready` is:
+   * tuning is not correctness, and making the first statement of every process
+   * wait on six round trips to gain nothing is the wrong trade. But `close()`
+   * has to wait, because a handle closed underneath an in-flight pragma
+   * rejects with `Connection closed`, and that is indistinguishable at the
+   * catch from a filesystem genuinely refusing one. A short-lived adapter (a
+   * test, a one-shot script) would otherwise warn on every close about a
+   * failure that never happened.
+   */
+  protected readonly tuned: Promise<unknown> = Promise.resolve()
+
   /**
    * Resolves once `foreign_keys` is on, and every query awaits it.
    *
    * SQLite defaults the pragma OFF and it is per-connection, so without this a
    * FOREIGN KEY is stored, reported by `PRAGMA foreign_key_list`, shown in the
-   * dashboard — and enforces nothing.
+   * dashboard, and enforces nothing.
    *
    * Deliberately *not* in the performance pragma chain above it. That chain is
    * fire-and-forget by design (its own comment calls the statements
@@ -124,7 +148,7 @@ export class SQLiteAdapter extends SQLAdapter {
       filename,
       typeof connectionTarget === 'string' ? connectionTarget : undefined,
     )
-    // `sql` is supplied when wrapping an existing connection — notably once per
+    // `sql` is supplied when wrapping an existing connection: notably once per
     // transaction. Setup below belongs only to a connection we open ourselves;
     // re-running it per transaction meant a mkdirSync plus six unawaited
     // PRAGMAs
@@ -143,7 +167,7 @@ export class SQLiteAdapter extends SQLAdapter {
       (filename === ':memory:'
         ? new SQL('sqlite://:memory:')
         : new SQL(filename, { adapter: 'sqlite' }))
-    // Every owned connection, `:memory:` included — the perf pragmas below
+    // Every owned connection, `:memory:` included, the perf pragmas below
     // skip in-memory databases, but correctness does not get to.
     this.ready = ownsConnection
       ? this.sql.unsafe('PRAGMA foreign_keys = ON;')
@@ -151,18 +175,105 @@ export class SQLiteAdapter extends SQLAdapter {
 
     if (ownsConnection && filename !== ':memory:') {
       const cacheSize = import.meta.env.THREAD_WORKER ? -1000 : -10000
-      const journalMode = process.platform === 'win32' ? 'DELETE' : 'WAL'
-      this.sql
-        .unsafe(`PRAGMA journal_mode = ${journalMode};`)
+      this.tuned = this.sql
+        .unsafe('PRAGMA journal_mode = WAL;')
+        .then((rows: unknown) => this.confirmWAL(rows, filename))
         .then(() => this.sql.unsafe('PRAGMA synchronous = NORMAL;'))
         .then(() => this.sql.unsafe('PRAGMA temp_store = memory;'))
         .then(() => this.sql.unsafe(`PRAGMA cache_size = ${cacheSize};`))
         .then(() => this.sql.unsafe('PRAGMA busy_timeout = 5000;'))
         .then(() => this.sql.unsafe('PRAGMA mmap_size = 0;'))
-        .catch(() => {})
+        // Not `catch(() => {})`. Every performance pragma failing silently is
+        // how a database ends up running at a fraction of its speed with
+        // nothing anywhere saying so, and convention 3 bans the bare form for
+        // exactly this. These are tuning, not correctness (`foreign_keys`
+        // above is awaited and is allowed to reject), so a failure is a
+        // warning rather than a throw.
+        .catch((error: Error) => {
+          MESSAGES.PRAGMA_FAILED({ error: error.message })
+        })
     }
   }
 
+  /**
+   * Waits for the pragma chain before closing the handle. See `tuned`.
+   */
+  override async close(): Promise<void> {
+    await Try.catch(this.tuned)
+    await super.close()
+  }
+
+  /**
+   * **WAL first, DELETE only where WAL is actually refused.**
+   *
+   * The journal mode used to be `platform === 'win32' ? 'DELETE' : 'WAL'`, a
+   * rule with no recorded reason. The hypothesis behind it was that a Windows
+   * network path cannot host WAL, which is true (WAL needs a shared `-shm`
+   * mapping that SMB and WebDAV do not provide), but the rule applied to every
+   * Windows install, local disks included, where WAL works.
+   *
+   * Measured on this machine, four interleaved rounds against a CPU-bound
+   * control that stayed flat at 29-34 ms:
+   *
+   *     single autocommit write    DELETE 3629 us    WAL 36 us      100x
+   *     100-row transaction        DELETE 3.91 ms    WAL 0.13 ms     29x
+   *
+   * An attempt and a check replaces the rule, which is what makes it safe to
+   * change without knowing why it was there. SQLite refuses WAL in two
+   * observable ways and both are handled: it returns the *unchanged* mode in
+   * the pragma's own result row (an in-memory database answers `memory`), or
+   * it throws. Both shapes were reproduced before this was written, so the
+   * fallback rests on a measurement rather than on the documentation.
+   *
+   * The same logic runs on the cache database in
+   * `@bakery-framework/core/cache/shared-db`. It is deliberately not shared:
+   * that site is synchronous `bun:sqlite` and this one is an async
+   * `Bun.SQL`, so the control flow has nothing in common and only the
+   * predicate would move: at the cost of a new published export subpath on a
+   * surface that was closed on purpose before 2.0.0.
+   */
+  private async confirmWAL(rows: unknown, filename: string): Promise<void> {
+    const first = Array.isArray(rows) ? rows[0] : undefined
+    const answer = String(
+      (first as { journal_mode?: unknown } | undefined)?.journal_mode ?? '',
+    )
+    if (answer.toLowerCase() === 'wal') return
+
+    const fell = await this.sql.unsafe('PRAGMA journal_mode = DELETE;')
+    const mode = Array.isArray(fell)
+      ? String((fell[0] as { journal_mode?: unknown })?.journal_mode ?? 'unknown')
+      : 'unknown'
+    MESSAGES.JOURNAL_WAL_REFUSED({
+      file: filename,
+      answer: answer || '(no row)',
+      mode,
+    })
+  }
+
+  /**
+   * `PRAGMA schema_version`, which is a counter SQLite bumps on every schema
+   * change and leaves alone for every row change.
+   *
+   * Measured on a 50-table database: the full introspection the explorer runs
+   * per write is **250 statements and 8.28 ms**, and this is **10.4 us** - 795x.
+   * The semantics were checked rather than taken from the documentation: the
+   * counter advances on `CREATE TABLE`, on `ALTER TABLE ... ADD COLUMN` and on
+   * `DROP TABLE`, and does not move for an `INSERT`.
+   *
+   * Prefixed with the driver and the file so two different SQLite databases
+   * cannot collide on the same small integer. A fresh database starts near
+   * zero, so "version 3" is a value many of them hold at once.
+   */
+  override async schemaFingerprint(): Promise<string | null> {
+    const row = (await this.query('PRAGMA schema_version').get()) as
+      | { schema_version?: number }
+      | null
+      | undefined
+    const version = row?.schema_version
+    if (typeof version !== 'number') return null
+    return `sqlite:${this.filename ?? ''}:${version}`
+  }
+
   private static resolveFilename(rawValue?: string | null): string {
     const envVal = process.env.DATABASE_URL || process.env.SQLITE_PATH
     // `Bakery.dataDir`, not a literal: the default database file has to follow
@@ -212,7 +323,7 @@ export class SQLiteAdapter extends SQLAdapter {
   )
 
   // `PRAGMA table_info('${table}')` interpolated the table name into a
-  // string literal — a second SQL writer on a public adapter method, outside
+  // string literal, a second SQL writer on a public adapter method, outside
   // the `qId`/`qRef`/`safeColumn` guards convention 8 makes the only ones.
   // The `pragma_table_info` table-valued function takes the same argument as a
   // bound parameter, so there is nothing left to quote; MySQL and Postgres
@@ -236,8 +347,7 @@ export class SQLiteAdapter extends SQLAdapter {
         bigint: 'BIGINT',
         json: 'JSON',
       }[d.type as string] || 'TEXT'
-    // SQLite has no VARCHAR of its own — every text column is TEXT affinity —
-    // but it stores the *declared* type verbatim and hands it back through
+    // SQLite has no VARCHAR of its own (every text column is TEXT affinity),     // but it stores the *declared* type verbatim and hands it back through
     // `pragma table_info`. Emitting the width is therefore free here and is
     // what lets one schema round-trip on all three dialects.
     let out =
@@ -282,7 +392,9 @@ export class SQLiteAdapter extends SQLAdapter {
     return new SQLiteAdapter(this.filename, sql as SQL)
   }
 
-  async getSchema(): Promise<SQLAdapter.TableDetails[]> {
+  async getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]> {
     const res = (await this.query(
       'SELECT name FROM sqlite_master' +
         " WHERE type='table' AND name NOT LIKE 'sqlite_%'",
@@ -292,30 +404,31 @@ export class SQLiteAdapter extends SQLAdapter {
     // 20-table schema cost 20 sequential round-trip waves. They share nothing,
     // so the whole fan-out is one wave now.
     //
-    // Worth knowing before this grows: the `COUNT(*)` is a full scan on this
-    // dialect and on Postgres, and it is paid on every caller of `getSchema()`
-    // even though only a schema *listing* displays the number. Making it
-    // optional means `rowCount` has to admit it can be absent, which is a type
-    // change across every consumer — recorded rather than done here.
+    // The `COUNT(*)` is a full scan on this dialect and on Postgres, so it is
+    // opt-in: only a schema *listing* displays the number, and `getSchema()`
+    // also sits on the explorer's write path, where a count nobody shows cost
+    // a scan of every table per write.
     return await Promise.all(
       res.map(async t => {
         const tableName = this.quote(t.name)
 
         const [countRes, cols, idxs] = (await Promise.all([
-          this.query(`SELECT COUNT(*) as count FROM ${tableName}`).get(),
+          options?.rowCounts
+            ? this.query(`SELECT COUNT(*) as count FROM ${tableName}`).get()
+            : null,
           this.query(`PRAGMA table_info(${tableName})`).all(),
           this.query(`PRAGMA index_list(${tableName})`).all(),
-        ])) as [SQLAdapter.CountRow, any[], any[]]
+        ])) as [SQLAdapter.CountRow | null, 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,
             notnull: c.notnull === 1,
             // `pk` is the column's **1-based position within the primary key**,
-            // not a boolean — `PRAGMA table_info` reports 0 for "not part of the
+            // not a boolean: `PRAGMA table_info` reports 0 for "not part of the
             // key", 1 for the first key column, 2 for the second. So `=== 1`
             // reported a composite `PRIMARY KEY (a, b)` as a single-column key on
             // `a`, silently, and only on SQLite: MySQL reads `column_key = 'PRI'`
@@ -348,17 +461,23 @@ export class SQLiteAdapter extends SQLAdapter {
 
     const { page, pageSize } = options
 
+    // See `TableDataOptions.knownTotal`: the count is 97% of a page's cost,
+    // and a caller that has already counted can say so.
+    const reuse = SQLAdapter.usableTotal(options.knownTotal)
+
     const [countRes, rows] = (await Promise.all([
-      this.query(`SELECT COUNT(*) as count FROM ${tname}${whereSql}`).get(
-        ...whereParams,
-      ),
+      reuse
+        ? Promise.resolve(null)
+        : this.query(`SELECT COUNT(*) as count FROM ${tname}${whereSql}`).get(
+            ...whereParams,
+          ),
       this.query(
         `SELECT rowid AS rowid, * FROM ${tname}` +
           `${whereSql}${orderSql} LIMIT ? OFFSET ?`,
       ).all(...whereParams, pageSize, (page - 1) * pageSize),
-    ])) as [SQLAdapter.CountRow, any[]]
+    ])) as [SQLAdapter.CountRow | null, any[]]
 
-    const totalRows = countRes?.count || 0
+    const totalRows = reuse ? options.knownTotal! : countRes?.count || 0
     return {
       rows,
       totalRows,
@@ -446,7 +565,7 @@ export class SQLiteAdapter extends SQLAdapter {
   }
 
   /**
-   * SQLite has `UNION ALL` but neither `INTERSECT ALL` nor `EXCEPT ALL` — the
+   * SQLite has `UNION ALL` but neither `INTERSECT ALL` nor `EXCEPT ALL`: the
    * `ALL` modifier is only accepted after `UNION`.
    */
   override get supportsSetOperationAll(): boolean {
@@ -466,9 +585,13 @@ export class SQLiteAdapter extends SQLAdapter {
       const tName = Case.camel(table.name)
       dbConstraints[tName] = {} as SyncTypes.TableConstraints
 
+      // Bound, not interpolated: the same conversion `hasCol` above
+      // records. This one survived it: `getConstraints` runs over every table
+      // the database reports, so a name carrying an apostrophe closed the
+      // literal and the rest of the statement went with it.
       const cols = (await this.query(
-        `PRAGMA table_info('${table.name}')`,
-      ).all()) as any[]
+        'SELECT * FROM pragma_table_info(?)',
+      ).all(table.name)) as any[]
 
       if (table.type === 'view') {
         const match = table.sql.match(/AS\s+(.*)/is)
@@ -505,18 +628,26 @@ export class SQLiteAdapter extends SQLAdapter {
     ).all()) as any[]
     return Object.fromEntries(
       await Promise.all(
-        indexes.map(async idx => [
-          Case.camel(idx.name),
-          {
-            type: idx.sql.toUpperCase().includes('UNIQUE') ? 'unique' : 'index',
-            table: Case.camel(idx.tbl_name),
-            cols: (
-              (await this.query(
-                `PRAGMA index_info('${idx.name}')`,
-              ).all()) as any[]
-            ).map(c => Case.camel(c.name)),
-          },
-        ]),
+        indexes.map(async idx => {
+          // Bound for the same reason as `getConstraints` above: an index
+          // name comes from `sqlite_master`, not from this codebase.
+          const raw = (
+            (await this.query('SELECT * FROM pragma_index_info(?)').all(
+              idx.name,
+            )) as any[]
+          ).map(c => String(c.name))
+          return [
+            Case.camel(idx.name),
+            {
+              type: idx.sql.toUpperCase().includes('UNIQUE')
+                ? 'unique'
+                : 'index',
+              table: Case.camel(idx.tbl_name),
+              cols: raw.map(Case.camel),
+              rawCols: raw,
+            },
+          ]
+        }),
       ),
     )
   }
@@ -536,7 +667,7 @@ export class SQLiteAdapter extends SQLAdapter {
   /**
    * SQLite has no UUID function, so the canonical 8-4-4-4-12 form is assembled
    * from `randomblob(16)`. Version and variant nibbles are **not** forced, so
-   * this is a random 128-bit value in UUID shape rather than a conforming v4 —
+   * this is a random 128-bit value in UUID shape rather than a conforming v4:
    * unique, but do not hand it to something that validates the version field.
    *
    * SQLite stores the default expression verbatim and hands it back the same
@@ -559,7 +690,7 @@ export class SQLiteAdapter extends SQLAdapter {
 
     // SQLite has no catalog column for width; it stores the *declared* type
     // verbatim and hands it back through `pragma table_info`, so the number is
-    // in the type string — 'VARCHAR(64)'. That is also why emitting the width
+    // in the type string, 'VARCHAR(64)'. That is also why emitting the width
     // is worth doing on a dialect with no real VARCHAR: it is what lets one
     // schema round-trip on all three.
     const declared = String(col.type || '')
@@ -587,7 +718,7 @@ export class SQLiteAdapter extends SQLAdapter {
   }
 
   // `protected override`, not `private`: narrowing a base member's visibility
-  // is TS2415, and it made SQLiteAdapter fail to satisfy SQLAdapter — so the
+  // is TS2415, and it made SQLiteAdapter fail to satisfy SQLAdapter, so the
   // one adapter with real test coverage did not typecheck against the contract
   // the two untested ones share.
   protected override parseDefault(def: any): any {
@@ -600,7 +731,7 @@ export class SQLiteAdapter extends SQLAdapter {
       // sqlite_master hands back the literal exactly as formatDefault wrote it,
       // so the quote it doubled per SQL rules is still doubled. Stripping the
       // delimiters without collapsing it leaves `it''s fine` where the schema
-      // says `it's fine` — drift diffColumnMismatch can never resolve, and a
+      // says `it's fine`: drift diffColumnMismatch can never resolve, and a
       // table rebuild on every db:sync as a result.
       return unquoted.replaceAll(quote + quote, quote)
     }

package/src/adapters.ts

@@ -6,7 +6,7 @@ import { registerAdapter, resolveAdapter } from './adapters/registry'
 /**
  * Does this target name a SQLite file rather than a server?
  *
- * Deliberately greedy — anything with a path separator lands here — because it
+ * Deliberately greedy (anything with a path separator lands here), because it
  * is consulted only *after* every registered scheme has had its say. Before
  * the registry that ordering was implicit and this heuristic ran second by
  * luck; now `protocols` is checked first by contract, so an adapter that
@@ -27,7 +27,7 @@ function isSQLite(val: string) {
 /**
  * The three built-in adapters, registered at module load.
  *
- * Registering is cheap — three object literals — because `open` is what pulls
+ * Registering is cheap (three object literals), because `open` is what pulls
  * the driver in. An app on SQLite never loads `mysql.ts` or `pgsql.ts`, which
  * was true of the `switch` this replaced and had to stay true of the registry.
  */
@@ -64,8 +64,8 @@ registerAdapter({
 export async function createDbAdapter() {
   const url = process.env.DB_URL || process.env.DATABASE_URL || ''
   const { poolOptionsFromEnv } = await import('./pool')
-  // Read once and handed to every adapter. SQLite ignores it — a single file
-  // handle has no pool to size — but the registry cannot know which does what,
+  // Read once and handed to every adapter. SQLite ignores it (a single file
+  // handle has no pool to size), but the registry cannot know which does what,
   // so the option goes to all of them and each takes what it needs.
   const pool = poolOptionsFromEnv()
   return await resolveAdapter(url).open(url || undefined, pool)

package/src/backup.ts

@@ -12,7 +12,7 @@ const MESSAGES = messageLogger(new Logger('db-backup'), {
 
 /**
  * Returns whether a backup file was actually written. Callers about to run a
- * destructive migration must check this — a thrown error, a `:memory:` database,
+ * destructive migration must check this: a thrown error, a `:memory:` database,
  * or a missing `pg_dump`/`mysqldump` all previously looked identical to success.
  */
 export async function backupDatabase(adapter?: any): Promise<boolean> {

package/src/connection.ts

@@ -8,7 +8,7 @@ let testDb: any = null
 
 /**
  * Test seam. Unit tests that only need a stub adapter should call this instead
- * of `mock.module('./connection', …)` — Bun's module mocks are process-global
+ * of `mock.module('./connection', …)`: Bun's module mocks are process-global
  * and are never restored, so one mocking test file silently breaks every later
  * test that needs a real connection.
  */

package/src/define.ts

@@ -8,15 +8,15 @@ import type {
  * Prototype: tables as values.
  *
  * Today a schema is one `constraints` object plus a hand-written `DBSchema`
- * type, and everything that references a table — indexes, foreign keys, query
- * columns — does so by string. Typos surface at sync time, or not at all.
+ * type, and everything that references a table (indexes, foreign keys, query
+ * columns) does so by string. Typos surface at sync time, or not at all.
  *
  * Here a table is a value carrying its own name and columns, so `indexes.ts`
  * and `foreign.ts` can import it, rename-symbol works across files, and an
  * identifier reaching SQL is one the framework constructed rather than one a
  * caller typed.
  *
- * The column descriptors are unchanged — the `Field` builders and the
+ * The column descriptors are unchanged: the `Field` builders and the
  * `ExtractTableTypes` mapping are reused as-is, so this is a restructuring of
  * how tables are *declared*, not of how their types are computed. That is what
  * keeps `DB.table('users')` autocompleting exactly as it does now: the derived
@@ -31,7 +31,7 @@ export type ColumnMap = Record<string, unknown>
  * from, and the columns themselves.
  *
  * **Was `TableDef`, and the rename is the point.** `schema-util.ts` exports a
- * `TableDef<T, N, O>` describing a *column* — and that is the one every
+ * `TableDef<T, N, O>` describing a *column*, and that is the one every
  * internal call site, every test and every schema file means. Both were public,
  * and the root barrel re-exported *this* one, so `import type { TableDef } from
  * '@bakery-framework/orm'` handed you a table where you asked for a column. Nothing
@@ -43,7 +43,7 @@ export interface TableRef<
   N extends string = string,
   C extends ColumnMap = ColumnMap,
 > {
-  /** The name columns qualify against — the alias, when aliased. */
+  /** The name columns qualify against: the alias, when aliased. */
   readonly __table: N
   /** The real table to read FROM. Differs from `__table` only for an alias. */
   readonly __source: string
@@ -52,7 +52,7 @@ export interface TableRef<
 
 /**
  * A reference to one column, carrying its table. This is the value that
- * replaces the `'users.id'` string — `qId` receives structured data rather
+ * replaces the `'users.id'` string: `qId` receives structured data rather
  * than text that has to be validated before it can be trusted.
  */
 export interface TableColumn<
@@ -84,7 +84,7 @@ export function table<N extends string, C extends ColumnMap>(
 }
 
 /**
- * Declare a view — a stored `SELECT` the database treats as a table.
+ * Declare a view: a stored `SELECT` the database treats as a table.
  *
  *     export const activeUsers = view(
  *       'active_users',
@@ -94,15 +94,15 @@ export function table<N extends string, C extends ColumnMap>(
  *
  * The columns are the shape the `SELECT` returns. They are declared rather than
  * inferred because nothing here parses SQL, and they are what gives the view a
- * row type — reading from it is typed exactly like reading a table.
+ * row type: reading from it is typed exactly like reading a table.
  *
  * **Writes are rejected at compile time.** `InferViews` collects these names and
  * `Mutation.Tables` excludes them, so `DB.Insert.into('active_users')` does not
  * typecheck. A view is a `SELECT`; the database would refuse the write anyway,
  * and refusing it earlier is strictly better.
  *
- * `db:sync` emits `CREATE VIEW`, diffs the body as normalised text, and drops
- * and recreates the view when it changes — views hold no data, so recreating is
+ * `db:sync` emits `CREATE VIEW`, diffs the body as normalized text, and drops
+ * and recreates the view when it changes: views hold no data, so recreating is
  * free and there is no migration to plan.
  *
  * Previously declarable only in the older `DBInfo` layout, or here by writing
@@ -122,7 +122,7 @@ export function view<N extends string, C extends ColumnMap>(
  *     export const activeUsers = view('active_users', users, 'SELECT * FROM users WHERE active = 1')
  *
  * The filtered-view case, which is the common one: the shape is the source
- * table's, so restating it is duplication that nothing checks — declare a
+ * table's, so restating it is duplication that nothing checks. Declare a
  * column the `SELECT` does not return and you find out at query time.
  *
  * The source is a **value**, not a type argument, and that is forced rather
@@ -130,7 +130,7 @@ export function view<N extends string, C extends ColumnMap>(
  * inferring the *remaining* type parameters as soon as one is supplied
  * explicitly, so `N` would fall back to `string` and the view's name would stop
  * being a literal. `__table` is what `InferConstraints` keys the schema map on,
- * so that name degrading takes `InferViews` with it — and since
+ * so that name degrading takes `InferViews` with it, and since
  * `Mutation.Tables` now excludes views, `Exclude<…, string>` is `never` and
  * *every* mutation stops compiling. Passing the table keeps both inferred.
  *
@@ -158,7 +158,7 @@ export function view<N extends string, C extends ColumnMap>(
  *
  * This is what `db:sync --choose=db` writes into `orm/views.ts`, and it is the
  * honest shape for a view: **a view has no column DDL.** `CREATE VIEW x AS
- * SELECT …` declares no types, and the sync engine only ever reads the body —
+ * SELECT …` declares no types, and the sync engine only ever reads the body.
  * `createView(name, sql)` takes nothing else, and the diff compares the two
  * bodies as text. So a view's columns exist purely to give it a row type, and
  * writing `Field.Varchar(64)` there would imply a width the database neither
@@ -166,12 +166,12 @@ export function view<N extends string, C extends ColumnMap>(
  *
  * **Both type arguments are given, and that is forced.** TypeScript stops
  * inferring the remaining type parameters as soon as one is supplied, so
- * `view<ActiveUsersView>(name, body)` would leave `N` as `string` — and `N` is
+ * `view<ActiveUsersView>(name, body)` would leave `N` as `string`, and `N` is
  * what `TablesOf` re-keys the schema map on, so the whole map collapses to an
  * index signature and every mutation stops compiling. Naming both keeps it a
  * literal. In generated code the repetition costs nothing.
  *
- * Column references still work — `activeUsers.id` — even though the keys are
+ * Column references still work: `activeUsers.id`: even though the keys are
  * known only to the type. See the implementation.
  */
 export function view<N extends string, T>(
@@ -203,8 +203,8 @@ export function view(
 /**
  * A row interface, as the descriptor map `ExtractTableTypes` reads.
  *
- * One `{ type: T[K] }` per property — which is all a descriptor needs now that
- * `type` carries the row type — plus the `_view` marker that makes
+ * One `{ type: T[K] }` per property (which is all a descriptor needs now that
+ * `type` carries the row type) plus the `_view` marker that makes
  * `ExtractViews` classify it as a view.
  */
 type ViewColumns<T> = { [K in keyof T]-?: { type: T[K] } } & { _view: string }
@@ -255,7 +255,7 @@ function viewImpl<N extends string, C extends ColumnMap>(
   // It has to be in `__columns`'s *declared type* too, not only at runtime:
   // `ExtractViews` is what `InferViews` reads and what `Mutation.Tables`
   // excludes, so erasing `_view` from the type left writes to a view
-  // compiling — the exact thing declaring one is supposed to prevent.
+  // compiling: the exact thing declaring one is supposed to prevent.
   // `ExtractTableTypes` filters the key out of the row type separately.
   return Object.assign(table(name, columns), {
     __columns: { _view: body, ...columns },
@@ -308,7 +308,7 @@ export type InferConstraints<M> = {
     : never
 }
 
-/** Row types — the derived replacement for a hand-written `DBSchema`. */
+/** Row types: the derived replacement for a hand-written `DBSchema`. */
 export type InferSchema<M> = {
   [N in keyof InferConstraints<M>]: ExtractTableTypes<InferConstraints<M>, N>
 }
@@ -332,7 +332,7 @@ export function collectConstraints(module: Record<string, unknown>) {
 
     // Skip aliases. An alias is a query-time view of an existing table, and
     // collecting one would tell the sync engine to CREATE a table named after
-    // it — so `alias(users, 'author')` would try to build an `author` table.
+    // it, so `alias(users, 'author')` would try to build an `author` table.
     if (def.__source !== def.__table) continue
 
     constraints[def.__table] = def.__columns
@@ -347,8 +347,8 @@ export function collectConstraints(module: Record<string, unknown>) {
  *     export type ActiveUsersView = RowOf<typeof activeUsers>
  *     //     ^ { id: number; name: string }
  *
- * TypeScript cannot mint a *named* interface from a value — a name has to be
- * written somewhere — so this is the one line that does it, and it stays
+ * TypeScript cannot mint a *named* interface from a value (a name has to be
+ * written somewhere), so this is the one line that does it, and it stays
  * correct when the declaration changes because it is derived rather than
  * copied. A hand-written `interface ActiveUsersView` would be a second source
  * of truth that nothing checks against the first.