turbine-orm 0.50.0 → 0.51.0

package/dist/introspect.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Schema introspection
+ * turbine-orm, Schema introspection
  *
  * Connects to a live Postgres database, reads information_schema + pg_catalog,
  * and produces a SchemaMetadata object describing every table, column, relation,
@@ -65,6 +65,15 @@ export interface IntrospectOptions {
     include?: string[];
     /** Tables to exclude (default: none). Applied after include. */
     exclude?: string[];
+    /**
+     * Rename derived relations, as `{ table: { derivedName: desiredName } }`.
+     *
+     * Relation names are composed by introspection (the database does not name
+     * relationships), so a port from another ORM that named them differently has
+     * to touch every call site. Declaring the mapping here makes it mechanical.
+     * A typo is an error, not a silent no-op: see {@link applyRelationRenames}.
+     */
+    relationNames?: Record<string, Record<string, string>>;
     /**
      * Also introspect **views** and **materialized views** as read-only
      * {@link TableMetadata} entries (`isView: true`). Off by default. Write
@@ -102,6 +111,23 @@ export interface IntrospectOptions {
  * SQL. PostgreSQL is driven by {@link introspectPostgresCatalog}.
  */
 export declare function introspect(options: IntrospectOptions): Promise<SchemaMetadata>;
+/**
+ * Rename introspected relations, per table, from the name turbine derived to
+ * the name the caller wants.
+ *
+ * Relation names are DERIVED, not declared: the database has no name for a
+ * foreign key's relationship, so introspection composes one, and two foreign
+ * keys pointing at the same table produce composed names (`msgsBySender`,
+ * `msgsByRecipient`) that nobody would predict. A codebase migrating from
+ * another ORM already has names for these, chosen by different rules, so every
+ * call site has to be hand-edited. This map turns that into a mechanical
+ * mapping done once in the config.
+ *
+ * Renames are validated rather than best-effort: an unknown table or an
+ * unknown source relation is an ERROR, because silently ignoring a typo here
+ * means the call sites it was supposed to fix break at runtime instead.
+ */
+export declare function applyRelationRenames(schema: SchemaMetadata, renames: Record<string, Record<string, string>>): SchemaMetadata;
 /**
  * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
  * produces {@link SchemaMetadata}. This is the implementation wrapped by
@@ -148,7 +174,7 @@ export interface ForeignKeyEntry {
 }
 /**
  * Derive a belongsTo relation name from its FK column. Strips a trailing
- * `_id` (snake_case) or `Id` (camelCase column names — common in Prisma-ported
+ * `_id` (snake_case) or `Id` (camelCase column names, common in Prisma-ported
  * schemas where columns are quoted camelCase identifiers), then camelCases:
  * `current_version_id` and `currentVersionId` both yield `currentVersion`.
  * Stripping is what keeps the scalar FK field (`currentVersionId`) targetable
@@ -189,7 +215,7 @@ export declare function parsePlainUniqueIndexColumns(indexdef: string): string[]
 export declare function detectUniqueForeignKeySets(pkByTable: Map<string, string[]>, uniqueByTable: Map<string, string[][]>, indexesByTable: Map<string, IndexMetadata[]>): Map<string, string[][]>;
 /**
  * Build the belongsTo/hasMany relation maps for every table from its foreign
- * keys. Naming rules (LEGACY-FIRST — a relation name that previously worked at
+ * keys. Naming rules (LEGACY-FIRST, a relation name that previously worked at
  * runtime must never change out from under a regenerating app):
  *
  *   1. First compute the historical derivation exactly as it shipped before
@@ -197,7 +223,7 @@ export declare function detectUniqueForeignKeySets(pkByTable: Map<string, string
  *      suffix (`snakeToCamel(col.replace(/_id$/, ''))` when several FKs point
  *      at the same target, else the singularized target table), and hasMany is
  *      `snakeToCamel(`${source}_by_${strippedColumn}`)` (else the source
- *      table). If that legacy name is free, KEEP IT — even when it looks odd
+ *      table). If that legacy name is free, KEEP IT, even when it looks odd
  *      (`blogPostsByAuthorId`, `postsBy_Author`): those names were collision-
  *      free and worked, so regenerating must not rename them.
  *   2. If the legacy name collides ONLY with a scalar column whose tsType is
@@ -206,17 +232,17 @@ export declare function detectUniqueForeignKeySets(pkByTable: Map<string, string
  *      relation payload; generate.ts's typeSafeRelations omits the relation
  *      from the type layer).
  *   3. On a genuine collision (concrete-typed column shadow, or a previously
- *      assigned relation), fall back to the modern derivation — the `_id`/`Id`
+ *      assigned relation), fall back to the modern derivation, the `_id`/`Id`
  *      case-insensitive strip of {@link relationNameFromColumn} plus the
- *      `By`-composed reverse name — which fixes the camelCase-FK shadowing
+ *      `By`-composed reverse name, which fixes the camelCase-FK shadowing
  *      shapes that were actually BROKEN before (relation name === scalar FK
  *      field → unusable types).
  *   4. Last resort: deterministic `Rel`/`Rel2` suffix + warning.
  *
- * @param columnFieldsByTable camelCase column *fields* per table — used to
+ * @param columnFieldsByTable camelCase column *fields* per table, used to
  *   guarantee relations never shadow concrete-typed scalar columns.
  * @param unknownTypedFieldsByTable subset of the column fields whose tsType is
- *   `unknown` (json/jsonb) — legacy shadows of these are preserved (rule 2).
+ *   `unknown` (json/jsonb), legacy shadows of these are preserved (rule 2).
  * @param uniqueSetsByTable when provided (F2), the child-table column sets that
  *   guarantee at-most-one row (PK + unique constraints + plain unique indexes,
  *   from {@link detectUniqueForeignKeySets}). A reverse relation whose FK column
@@ -262,7 +288,7 @@ export declare function addAutoManyToManyRelations(tableNames: Iterable<string>,
  * MSSQL): filters the FK list to the introspected table set, seeds the
  * taken-name / json-shadow maps from the engine's column metadata, and runs
  * the SAME `buildRelationsFromForeignKeys` + `addAutoManyToManyRelations`
- * pipeline as the Postgres introspector — so every engine derives identical
+ * pipeline as the Postgres introspector, so every engine derives identical
  * relation names for the same logical schema (the engines previously carried
  * stale copies of a retired naming scheme).
  */

package/dist/introspect.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Schema introspection
+ * turbine-orm, Schema introspection
  *
  * Connects to a live Postgres database, reads information_schema + pg_catalog,
  * and produces a SchemaMetadata object describing every table, column, relation,
@@ -9,6 +9,7 @@
  */
 import pg from 'pg';
 import { postgresDialect } from './dialect.js';
+import { ValidationError } from './errors.js';
 import { isDateType, pgTypeToTs, singularize, snakeToCamel, } from './schema.js';
 /**
  * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
@@ -125,21 +126,21 @@ const SQL_CHECKS = `
   WHERE con.contype = 'c'
     AND n.nspname = $1
 `;
-// Views (relkind 'v') — column metadata comes free from information_schema.columns.
+// Views (relkind 'v'), column metadata comes free from information_schema.columns.
 const SQL_VIEWS = `
   SELECT table_name
   FROM information_schema.views
   WHERE table_schema = $1
   ORDER BY table_name
 `;
-// Materialized views (relkind 'm') — NOT in information_schema; read from pg_catalog.
+// Materialized views (relkind 'm'), NOT in information_schema; read from pg_catalog.
 const SQL_MATVIEWS = `
   SELECT matviewname AS table_name
   FROM pg_matviews
   WHERE schemaname = $1
   ORDER BY matviewname
 `;
-// Materialized-view columns — information_schema.columns omits matviews, so pull
+// Materialized-view columns, information_schema.columns omits matviews, so pull
 // them from pg_attribute. Aliased to mirror SQL_COLUMNS so the same row-mapping
 // applies (array types surface as data_type 'ARRAY' + a '_'-prefixed udt_name).
 const SQL_MATVIEW_COLUMNS = `
@@ -241,11 +242,60 @@ export function defaultExcludedTablesPresent(names, options = {}) {
 export async function introspect(options) {
     const dialect = options.dialect ?? postgresDialect;
     const introspector = dialect.introspector;
-    if (introspector) {
-        return introspector.introspect(options);
+    const schema = introspector
+        ? await introspector.introspect(options)
+        : // Dialects without an introspector fall back to the Postgres catalog reader.
+            await introspectPostgresCatalog(options);
+    // Applied here rather than inside each introspector so every engine gets it.
+    return options.relationNames ? applyRelationRenames(schema, options.relationNames) : schema;
+}
+/**
+ * Rename introspected relations, per table, from the name turbine derived to
+ * the name the caller wants.
+ *
+ * Relation names are DERIVED, not declared: the database has no name for a
+ * foreign key's relationship, so introspection composes one, and two foreign
+ * keys pointing at the same table produce composed names (`msgsBySender`,
+ * `msgsByRecipient`) that nobody would predict. A codebase migrating from
+ * another ORM already has names for these, chosen by different rules, so every
+ * call site has to be hand-edited. This map turns that into a mechanical
+ * mapping done once in the config.
+ *
+ * Renames are validated rather than best-effort: an unknown table or an
+ * unknown source relation is an ERROR, because silently ignoring a typo here
+ * means the call sites it was supposed to fix break at runtime instead.
+ */
+export function applyRelationRenames(schema, renames) {
+    const tables = { ...schema.tables };
+    for (const [table, mapping] of Object.entries(renames)) {
+        const meta = tables[table];
+        if (!meta) {
+            throw new ValidationError(`[turbine] relationNames: unknown table "${table}". Known tables: ${Object.keys(tables).join(', ')}.`);
+        }
+        const relations = { ...meta.relations };
+        const columnFields = new Set(Object.values(meta.columnMap));
+        for (const [from, to] of Object.entries(mapping)) {
+            if (!Object.hasOwn(relations, from)) {
+                throw new ValidationError(`[turbine] relationNames: table "${table}" has no relation "${from}". ` +
+                    `Derived relations: ${Object.keys(relations).join(', ') || '(none)'}.`);
+            }
+            if (from === to)
+                continue;
+            if (Object.hasOwn(relations, to)) {
+                throw new ValidationError(`[turbine] relationNames: cannot rename "${table}.${from}" to "${to}", that relation already exists.`);
+            }
+            if (columnFields.has(to)) {
+                throw new ValidationError(`[turbine] relationNames: cannot rename "${table}.${from}" to "${to}", a column on "${table}" ` +
+                    `already uses that field name, and a relation must never shadow a column.`);
+            }
+            const def = relations[from];
+            delete relations[from];
+            // `RelationDef.name` is the relation's own identity, so it moves with it.
+            relations[to] = { ...def, name: to };
+        }
+        tables[table] = { ...meta, relations };
     }
-    // Dialects without an introspector fall back to the Postgres catalog reader.
-    return introspectPostgresCatalog(options);
+    return { ...schema, tables };
 }
 /**
  * PostgreSQL catalog introspector: reads information_schema + pg_catalog and
@@ -339,7 +389,7 @@ export async function introspectPostgresCatalog(options) {
                 // (gen_random_uuid(), now()), which Turbine must still synthesize.
                 isGenerated: (typeof row.column_default === 'string' && row.column_default.includes('nextval(')) ||
                     row.is_identity === 'YES',
-                // GENERATED ALWAYS AS (expr) STORED — computed by the database, never
+                // GENERATED ALWAYS AS (expr) STORED, computed by the database, never
                 // writable. Distinct from isGenerated (serial/identity, which a client
                 // MAY override). is_generated is 'ALWAYS' for STORED columns, else 'NEVER'.
                 isGeneratedStored: row.is_generated === 'ALWAYS',
@@ -350,7 +400,7 @@ export async function introspectPostgresCatalog(options) {
                 maxLength: row.character_maximum_length ?? undefined,
                 // Record the type's schema ONLY when it lives outside the introspected
                 // schema (and isn't a pg_catalog builtin). A same-named enum in another
-                // schema must NOT get this schema's `::"enum"` cast — search_path would
+                // schema must NOT get this schema's `::"enum"` cast, search_path would
                 // resolve the cast to the wrong type (see enumTypeForColumn). Omitting
                 // it for the common case keeps generated metadata byte-identical.
                 ...(typeof row.udt_schema === 'string' && row.udt_schema !== schema && row.udt_schema !== 'pg_catalog'
@@ -454,13 +504,13 @@ export async function introspectPostgresCatalog(options) {
         // per-FK-column when several FKs point at the same target, and every name
         // is collision-checked against the table's scalar column fields so a
         // relation can never shadow a column (which generated unsound types and
-        // made both surfaces unusable — dogfood T-4).
+        // made both surfaces unusable, dogfood T-4).
         const columnFieldsByTable = new Map();
         const unknownTypedFieldsByTable = new Map();
         for (const [tbl, cols] of columnsByTable) {
             columnFieldsByTable.set(tbl, new Set(cols.map((c) => c.field)));
             // Enum-typed columns also report tsType 'unknown' here, but generate.ts
-            // gives them a concrete union type — a shadow of one was type-broken on
+            // gives them a concrete union type, a shadow of one was type-broken on
             // main, so only genuine json/jsonb columns qualify as historical shadows.
             unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType) && !Object.hasOwn(enums, c.pgType)).map((c) => c.field)));
         }
@@ -482,14 +532,14 @@ export async function introspectPostgresCatalog(options) {
         //   1. J's primary key is exactly two columns.
         //   2. J has exactly two FKs, each single-column.
         //   3. Each FK's source column is one of J's two PK columns (the PK *is* the
-        //      two FK columns — no surrogate PK, no extra identity).
+        //      two FK columns, no surrogate PK, no extra identity).
         //   4. The two FKs target two DISTINCT tables (A and B).
         //   5. J has no columns beyond those two FK/PK columns (no payload columns
         //      like `grade` or `created_at`).
         //
         // For such a J linking A and B we ADD a `manyToMany` relation on A → B and
         // symmetrically on B → A, both routed `through` J. The existing belongsTo /
-        // hasMany relations derived from J's FKs are left untouched — this block
+        // hasMany relations derived from J's FKs are left untouched, this block
         // never removes or renames anything. Naming/collision handling lives in the
         // shared addAutoManyToManyRelations helper.
         //
@@ -624,7 +674,7 @@ export function stripCheckWrapper(def) {
 }
 /**
  * Derive a belongsTo relation name from its FK column. Strips a trailing
- * `_id` (snake_case) or `Id` (camelCase column names — common in Prisma-ported
+ * `_id` (snake_case) or `Id` (camelCase column names, common in Prisma-ported
  * schemas where columns are quoted camelCase identifiers), then camelCases:
  * `current_version_id` and `currentVersionId` both yield `currentVersion`.
  * Stripping is what keeps the scalar FK field (`currentVersionId`) targetable
@@ -743,7 +793,7 @@ export function detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTa
 /**
  * Resolve a derived relation name against the names already taken on the
  * table (scalar column fields + previously assigned relations). On collision,
- * applies a deterministic `Rel` / `Rel2` / `Rel3`… suffix and warns — a
+ * applies a deterministic `Rel` / `Rel2` / `Rel3`… suffix and warns, a
  * colliding name would otherwise shadow a column field and generate types
  * that fail `tsc --strict` (TS2430/TS2322).
  */
@@ -753,12 +803,12 @@ function resolveRelationNameCollision(candidate, taken, table, source) {
     let name = `${candidate}Rel`;
     for (let i = 2; taken.has(name); i++)
         name = `${candidate}Rel${i}`;
-    console.warn(`[turbine] Relation name "${candidate}" on table "${table}" (from ${source}) collides with an existing column or relation — using "${name}" instead.`);
+    console.warn(`[turbine] Relation name "${candidate}" on table "${table}" (from ${source}) collides with an existing column or relation, using "${name}" instead.`);
     return name;
 }
 /**
  * Build the belongsTo/hasMany relation maps for every table from its foreign
- * keys. Naming rules (LEGACY-FIRST — a relation name that previously worked at
+ * keys. Naming rules (LEGACY-FIRST, a relation name that previously worked at
  * runtime must never change out from under a regenerating app):
  *
  *   1. First compute the historical derivation exactly as it shipped before
@@ -766,7 +816,7 @@ function resolveRelationNameCollision(candidate, taken, table, source) {
  *      suffix (`snakeToCamel(col.replace(/_id$/, ''))` when several FKs point
  *      at the same target, else the singularized target table), and hasMany is
  *      `snakeToCamel(`${source}_by_${strippedColumn}`)` (else the source
- *      table). If that legacy name is free, KEEP IT — even when it looks odd
+ *      table). If that legacy name is free, KEEP IT, even when it looks odd
  *      (`blogPostsByAuthorId`, `postsBy_Author`): those names were collision-
  *      free and worked, so regenerating must not rename them.
  *   2. If the legacy name collides ONLY with a scalar column whose tsType is
@@ -775,17 +825,17 @@ function resolveRelationNameCollision(candidate, taken, table, source) {
  *      relation payload; generate.ts's typeSafeRelations omits the relation
  *      from the type layer).
  *   3. On a genuine collision (concrete-typed column shadow, or a previously
- *      assigned relation), fall back to the modern derivation — the `_id`/`Id`
+ *      assigned relation), fall back to the modern derivation, the `_id`/`Id`
  *      case-insensitive strip of {@link relationNameFromColumn} plus the
- *      `By`-composed reverse name — which fixes the camelCase-FK shadowing
+ *      `By`-composed reverse name, which fixes the camelCase-FK shadowing
  *      shapes that were actually BROKEN before (relation name === scalar FK
  *      field → unusable types).
  *   4. Last resort: deterministic `Rel`/`Rel2` suffix + warning.
  *
- * @param columnFieldsByTable camelCase column *fields* per table — used to
+ * @param columnFieldsByTable camelCase column *fields* per table, used to
  *   guarantee relations never shadow concrete-typed scalar columns.
  * @param unknownTypedFieldsByTable subset of the column fields whose tsType is
- *   `unknown` (json/jsonb) — legacy shadows of these are preserved (rule 2).
+ *   `unknown` (json/jsonb), legacy shadows of these are preserved (rule 2).
  * @param uniqueSetsByTable when provided (F2), the child-table column sets that
  *   guarantee at-most-one row (PK + unique constraints + plain unique indexes,
  *   from {@link detectUniqueForeignKeySets}). A reverse relation whose FK column
@@ -814,7 +864,7 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
         }
         return taken;
     };
-    // Relation names actually assigned so far (as opposed to column fields) —
+    // Relation names actually assigned so far (as opposed to column fields) -
     // needed to tell "collides only with a column" apart from "collides with an
     // already-assigned relation" for the legacy-shadow-preserving rule.
     const assignedByTable = new Map();
@@ -826,17 +876,17 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
         }
         return assigned;
     };
-    /** Legacy-first name resolution — see the naming rules in the JSDoc above. */
+    /** Legacy-first name resolution, see the naming rules in the JSDoc above. */
     const resolveName = (legacy, modern, table, source) => {
         const taken = takenFor(table);
         if (!taken.has(legacy))
             return legacy;
         // Historical json/jsonb shadow: previously worked at runtime AND compiled
-        // (tsType `unknown` absorbs the relation payload). Keep the name, warn —
+        // (tsType `unknown` absorbs the relation payload). Keep the name, warn -
         // typeSafeRelations() keeps the generated type layer sound.
         if (!assignedFor(table).has(legacy) && unknownTypedFieldsByTable?.get(table)?.has(legacy)) {
             console.warn(`[turbine] Relation "${legacy}" on table "${table}" (from ${source}) shadows the json/jsonb column ` +
-                `"${legacy}" — keeping the historical name for runtime compatibility; the relation is omitted from ` +
+                `"${legacy}", keeping the historical name for runtime compatibility; the relation is omitted from ` +
                 `the generated types. Rename the column to expose it.`);
             return legacy;
         }
@@ -852,7 +902,7 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
         // For multi-column (composite) FKs, use array form.
         const foreignKey = singleColumn ? fk.sourceColumns[0] : fk.sourceColumns;
         const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        // Composite FKs have no single column to derive from — fall back to the
+        // Composite FKs have no single column to derive from, fall back to the
         // constraint name (with the usual fk_/-_fkey affixes stripped).
         const constraintBase = fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '');
         // --- belongsTo on the source (child) table ---
@@ -956,7 +1006,7 @@ export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable,
  */
 export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, columnNamesByTable, relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable, uniqueIndexColsByTable) {
     for (const tableName of tableNames) {
-        // FKs whose source is this table — both must be single-column.
+        // FKs whose source is this table, both must be single-column.
         const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
         if (tableFks.length !== 2)
             continue;
@@ -1008,9 +1058,9 @@ export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, c
             const columnFields = columnFieldsByTable?.get(sourceTbl);
             if (columnFields?.has(relName)) {
                 if (unknownTypedFieldsByTable?.get(sourceTbl)?.has(relName)) {
-                    // Historical json/jsonb shadow — worked at runtime, compiled fine.
+                    // Historical json/jsonb shadow, worked at runtime, compiled fine.
                     console.warn(`[turbine] Relation "${relName}" on table "${sourceTbl}" (junction ${tableName}) shadows the ` +
-                        `json/jsonb column "${relName}" — keeping the historical name for runtime compatibility; ` +
+                        `json/jsonb column "${relName}", keeping the historical name for runtime compatibility; ` +
                         `the relation is omitted from the generated types.`);
                 }
                 else {
@@ -1044,7 +1094,7 @@ export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, c
  * MSSQL): filters the FK list to the introspected table set, seeds the
  * taken-name / json-shadow maps from the engine's column metadata, and runs
  * the SAME `buildRelationsFromForeignKeys` + `addAutoManyToManyRelations`
- * pipeline as the Postgres introspector — so every engine derives identical
+ * pipeline as the Postgres introspector, so every engine derives identical
  * relation names for the same logical schema (the engines previously carried
  * stale copies of a retired naming scheme).
  */

package/dist/mssql.d.ts

@@ -1,8 +1,8 @@
 /**
- * turbine-orm/mssql — Microsoft SQL Server engine (driver-injected, optional peer)
+ * turbine-orm/mssql, Microsoft SQL Server engine (driver-injected, optional peer)
  *
  * Binds Turbine to SQL Server 2016+ via the `mssql` driver (which wraps
- * `tedious`). `mssql` is **not** a root dependency — it is an **optional peer**:
+ * `tedious`). `mssql` is **not** a root dependency, it is an **optional peer**:
  * `npm i turbine-orm` pulls nothing extra, and only consumers who
  * `import 'turbine-orm/mssql'` install `mssql` themselves. The factory loads it
  * through a dynamic `import('mssql')` so importing this module never crashes when
@@ -33,14 +33,14 @@
  *     real JSON instead of being escaped as a string. `INCLUDE_NULL_VALUES`
  *     keeps NULL columns present (matching PostgreSQL `json_build_object`).
  *  3. **No `LIMIT`.** Paging is `ORDER BY … OFFSET n ROWS FETCH NEXT m ROWS ONLY`,
- *     which requires an ORDER BY — a stable `ORDER BY (SELECT NULL)` is injected
+ *     which requires an ORDER BY, a stable `ORDER BY (SELECT NULL)` is injected
  *     when the query has none (`Dialect.buildLimitOffset`).
  *
  * ## Named `@pN` placeholders (no positional `?`)
  *
  * `mssqlDialect.paramPlaceholder = (i) => '@p' + i`. The driver shim binds via
  * `request.input('p' + i, value)`, so binding is by NAME and independent of where
- * each placeholder lands in the SQL text — exactly the guarantee PostgreSQL's
+ * each placeholder lands in the SQL text, exactly the guarantee PostgreSQL's
  * numbered `$N` gives. (SQL Server is naturally named-param friendly, sidestepping
  * the positional-`?` mis-bind bug the SQLite/MySQL phases hit.)
  *
@@ -48,12 +48,12 @@
  *
  * - **Single query nested relations preserved** via `FOR JSON PATH` (SQL Server
  *   2016+). Ordered/limited to-many uses `ORDER BY … OFFSET/FETCH` inside the FOR
- *   JSON subquery (no inner-subquery rewrite needed — FOR JSON aggregates AFTER
+ *   JSON subquery (no inner-subquery rewrite needed, FOR JSON aggregates AFTER
  *   the row selection).
  * - **Result strategy `'output'`:** create/update/delete/upsert return their rows
  *   from the same statement. `createMany` returns the inserted rows via
  *   `OUTPUT INSERTED.*` on the multi-row VALUES insert (≤ 1000 rows / 2100 params
- *   per statement — exceeding either throws a clear `ValidationError`; chunk
+ *   per statement, exceeding either throws a clear `ValidationError`; chunk
  *   yourself or use single `create`s).
  * - **MERGE concurrency caveat:** `MERGE` is the upsert primitive; under high
  *   concurrency a `MERGE` can still race (it is NOT a substitute for a unique
@@ -62,20 +62,20 @@
  *   loser of a race.
  * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
  *   LISTEN/NOTIFY (`$listen`/`$notify`), RLS `sessionContext` (sp_set_session_context
- *   exists but is connection-scoped, not transaction-local, so it is not wired —
+ *   exists but is connection-scoped, not transaction-local, so it is not wired -
  *   throws rather than silently leaking context across pooled connections).
  * - **Advisory-lock migration locking** is available in principle via
  *   `sp_getapplock`/`sp_releaseapplock` (`supportsAdvisoryLock = true`); the
  *   migrate CLI is still PostgreSQL-only, so this flag documents intent for a
  *   future adapter.
- * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — deterministic
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)`, deterministic
  *   regardless of the column's collation (note this can defeat an index unless a
  *   computed/persisted `LOWER()` index exists).
  * - **bignum:** the shim applies the same safe-int policy Turbine uses for Postgres
  *   `int8` (number when it fits in 2^53, decimal string otherwise) WITHOUT mutating
  *   any global driver state. `DECIMAL`/`NUMERIC`/`MONEY` come back as strings;
  *   `BIT` binds/returns booleans.
- * - **`DISTINCT ON`** is PostgreSQL-only and is not translated — avoid `distinct`
+ * - **`DISTINCT ON`** is PostgreSQL-only and is not translated, avoid `distinct`
  *   on SQL Server.
  *
  * ## Example
@@ -146,7 +146,7 @@ type QueryArg = string | {
  * physical connection.
  */
 export declare class MssqlPool implements PgCompatPool {
-    /** The underlying `mssql` ConnectionPool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    /** The underlying `mssql` ConnectionPool, exposed as an escape hatch (seed / DDL / advanced ops). */
     readonly pool: MssqlConnectionPool;
     private readonly sqlNS;
     private closed;
@@ -215,7 +215,7 @@ export interface TurbineMssqlOptions extends Pick<TurbineConfig, 'logging' | 'de
  * Pass one of:
  *  - a connection string (`'mssql://sa:pass@host:1433/db'`),
  *  - an `mssql` config object (`{ server, user, password, database, options }`),
- *  - an existing `MssqlPool` (injection — you own its lifecycle, `disconnect()` is
+ *  - an existing `MssqlPool` (injection, you own its lifecycle, `disconnect()` is
  *    a no-op).
  *
  * When Turbine builds the pool (string/config), it probes