turbine-orm 0.28.3 → 0.30.0

package/dist/introspect.js

@@ -44,6 +44,7 @@ const SQL_COLUMNS = `
     table_name,
     column_name,
     udt_name,
+    udt_schema,
     data_type,
     is_nullable,
     column_default,
@@ -146,6 +147,7 @@ const SQL_MATVIEW_COLUMNS = `
     c.relname AS table_name,
     a.attname AS column_name,
     t.typname AS udt_name,
+    tn.nspname AS udt_schema,
     CASE WHEN t.typcategory = 'A' THEN 'ARRAY' ELSE 'base' END AS data_type,
     CASE WHEN a.attnotnull THEN 'NO' ELSE 'YES' END AS is_nullable,
     NULL AS column_default,
@@ -158,6 +160,7 @@ const SQL_MATVIEW_COLUMNS = `
   JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
   JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
   JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
+  JOIN pg_catalog.pg_namespace tn ON tn.oid = t.typnamespace
   WHERE n.nspname = $1
     AND c.relkind = 'm'
     AND a.attnum > 0
@@ -288,6 +291,14 @@ export async function introspectPostgresCatalog(options) {
                 arrayType,
                 pgArrayType: arrayType,
                 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
+                // 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'
+                    ? { pgTypeSchema: row.udt_schema }
+                    : {}),
             };
             if (!columnsByTable.has(tableName))
                 columnsByTable.set(tableName, []);
@@ -359,6 +370,9 @@ export async function introspectPostgresCatalog(options) {
                 enums[row.typname] = [];
             enums[row.typname].push(row.enumlabel);
         }
+        // ----- Build foreign key map -----
+        // Group FK rows by constraint_name to correctly handle multi-column composite FKs.
+        // Each constraint becomes one FKEntry with arrays of columns.
         const fkGroups = new Map();
         for (const row of fkResult.rows) {
             if (!tableSet.has(row.source_table) || !tableSet.has(row.target_table))
@@ -379,65 +393,21 @@ export async function introspectPostgresCatalog(options) {
         }
         const foreignKeys = Array.from(fkGroups.values());
         // ----- Build relations from foreign keys -----
-        // Count FKs per (source, target) pair for disambiguation
-        const fkCounts = new Map();
-        for (const fk of foreignKeys) {
-            const key = `${fk.sourceTable}→${fk.targetTable}`;
-            fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-        }
-        const relationsByTable = new Map();
-        for (const fk of foreignKeys) {
-            const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
-            const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
-            // For single-column FKs, keep string form for backwards compatibility.
-            // For multi-column (composite) FKs, use array form.
-            const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-            const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-            // --- belongsTo on the source (child) table ---
-            // e.g. posts.user_id → users.id creates posts.user (belongsTo)
-            // For composite FKs with disambiguation, use the constraint name
-            const belongsToName = needsDisambiguation
-                ? fk.sourceColumns.length === 1
-                    ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-                    : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
-                : singularize(snakeToCamel(fk.targetTable));
-            // Referential actions (omit the 'no action' default to keep metadata lean).
-            const actions = fkActions.get(fk.constraintName);
-            const actionFields = {};
-            if (actions?.onDelete && actions.onDelete !== 'no action')
-                actionFields.onDelete = actions.onDelete;
-            if (actions?.onUpdate && actions.onUpdate !== 'no action')
-                actionFields.onUpdate = actions.onUpdate;
-            if (!relationsByTable.has(fk.sourceTable))
-                relationsByTable.set(fk.sourceTable, {});
-            relationsByTable.get(fk.sourceTable)[belongsToName] = {
-                type: 'belongsTo',
-                name: belongsToName,
-                from: fk.sourceTable,
-                to: fk.targetTable,
-                foreignKey,
-                referenceKey,
-                ...actionFields,
-            };
-            // --- hasMany on the target (parent) table ---
-            // e.g. posts.user_id → users.id creates users.posts (hasMany)
-            const hasManyName = needsDisambiguation
-                ? fk.sourceColumns.length === 1
-                    ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-                    : snakeToCamel(`${fk.sourceTable}_by_${fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '')}`)
-                : snakeToCamel(fk.sourceTable);
-            if (!relationsByTable.has(fk.targetTable))
-                relationsByTable.set(fk.targetTable, {});
-            relationsByTable.get(fk.targetTable)[hasManyName] = {
-                type: 'hasMany',
-                name: hasManyName,
-                from: fk.targetTable,
-                to: fk.sourceTable,
-                foreignKey,
-                referenceKey,
-                ...actionFields,
-            };
+        // Delegated to the pure, unit-testable builder. Relation names are derived
+        // 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).
+        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
+            // 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)));
         }
+        const relationsByTable = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable);
         // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
         //
         // Auto-detecting m2m is a footgun: any table with two FKs *looks* like a
@@ -457,68 +427,9 @@ export async function introspectPostgresCatalog(options) {
         // 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
-        // never removes or renames anything. If the chosen relation name already
-        // exists on the source table (e.g. another relation grabbed it), we SKIP to
-        // stay additive.
-        for (const tableName of tableNames) {
-            const pk = pkByTable.get(tableName) ?? [];
-            if (pk.length !== 2)
-                continue;
-            // FKs whose source is this table.
-            const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-            if (tableFks.length !== 2)
-                continue;
-            // Both FKs must be single-column.
-            if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-                continue;
-            const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-            const pkSet = new Set(pk);
-            // Both FK columns must be the PK columns (and vice-versa).
-            if (!fkCols.every((c) => pkSet.has(c)))
-                continue;
-            if (new Set(fkCols).size !== 2)
-                continue;
-            // Two DISTINCT target tables.
-            const [fkA, fkB] = tableFks;
-            if (fkA.targetTable === fkB.targetTable)
-                continue;
-            // No payload columns: J's columns are exactly the two FK/PK columns.
-            const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-            if (jCols.length !== 2)
-                continue;
-            // For each direction, the m2m `referenceKey` is the *targeted* table's
-            // referenced column(s); the junction's sourceKey is the FK column pointing
-            // to that table; the targetKey is the FK column pointing to the OTHER table.
-            const addM2M = (self, other) => {
-                const sourceTbl = self.targetTable; // A
-                const targetTbl = other.targetTable; // B
-                const relName = snakeToCamel(targetTbl); // plural table name → e.g. "tags"
-                if (!relationsByTable.has(sourceTbl))
-                    relationsByTable.set(sourceTbl, {});
-                const existing = relationsByTable.get(sourceTbl);
-                // Additive-only: never clobber an existing relation name.
-                if (existing[relName])
-                    return;
-                existing[relName] = {
-                    type: 'manyToMany',
-                    name: relName,
-                    from: sourceTbl,
-                    to: targetTbl,
-                    // referenceKey = A's referenced column(s) that J's sourceKey points at.
-                    referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                    // foreignKey is unused for m2m correlation but kept for shape parity
-                    // (mirrors the source-side reference for back-compat consumers).
-                    foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                    through: {
-                        table: tableName,
-                        sourceKey: self.sourceColumns[0], // J col → A
-                        targetKey: other.sourceColumns[0], // J col → B
-                    },
-                };
-            };
-            addM2M(fkA, fkB); // A → B
-            addM2M(fkB, fkA); // B → A
-        }
+        // never removes or renames anything. Naming/collision handling lives in the
+        // shared addAutoManyToManyRelations helper.
+        addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable);
         // ----- Assemble TableMetadata for each table -----
         const tables = {};
         for (const tableName of tableNames) {
@@ -594,3 +505,317 @@ export function stripCheckWrapper(def) {
     }
     return s;
 }
+/**
+ * Derive a belongsTo relation name from its FK column. Strips a trailing
+ * `_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
+ * alongside the relation. A column literally named `id` (nothing left after
+ * stripping) keeps its own name.
+ */
+export function relationNameFromColumn(column) {
+    let base = column;
+    if (/_id$/i.test(base))
+        base = base.slice(0, -3);
+    else if (/[a-z0-9]Id$/.test(base))
+        base = base.slice(0, -2);
+    if (base.length === 0)
+        base = column;
+    return snakeToCamel(base);
+}
+/** Uppercase the first character (camelCase → PascalCase join helper). */
+function upperFirst(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+ * True for the tsType forms a json/jsonb column maps to (`unknown`, nullable
+ * `unknown | null`). A relation shadowing such a column is a HISTORICAL shadow
+ * that worked at runtime and compiled (`unknown` absorbs the relation
+ * payload), so the legacy-first naming keeps it instead of renaming.
+ */
+export function isUnknownTsType(tsType) {
+    return tsType === 'unknown' || tsType === 'unknown | null';
+}
+/**
+ * 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
+ * colliding name would otherwise shadow a column field and generate types
+ * that fail `tsc --strict` (TS2430/TS2322).
+ */
+function resolveRelationNameCollision(candidate, taken, table, source) {
+    if (!taken.has(candidate))
+        return candidate;
+    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.`);
+    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
+ * runtime must never change out from under a regenerating app):
+ *
+ *   1. First compute the historical derivation exactly as it shipped before
+ *      the collision guard existed: belongsTo strips a case-SENSITIVE `_id`
+ *      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
+ *      (`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
+ *      `unknown` (json/jsonb), keep it anyway with a warning: the shadow is
+ *      historical, ran fine at runtime, and compiled (`unknown` absorbs the
+ *      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`
+ *      case-insensitive strip of {@link relationNameFromColumn} plus the
+ *      `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
+ *   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).
+ */
+export function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable) {
+    // Count FKs per (source, target) pair for disambiguation.
+    const fkCounts = new Map();
+    for (const fk of foreignKeys) {
+        const key = `${fk.sourceTable}→${fk.targetTable}`;
+        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
+    }
+    const relationsByTable = new Map();
+    // Names already taken per table: seeded with the scalar column fields so a
+    // relation can never shadow a column; relation names are added as assigned.
+    const takenByTable = new Map();
+    const takenFor = (table) => {
+        let taken = takenByTable.get(table);
+        if (!taken) {
+            taken = new Set(columnFieldsByTable.get(table) ?? []);
+            takenByTable.set(table, taken);
+        }
+        return taken;
+    };
+    // 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();
+    const assignedFor = (table) => {
+        let assigned = assignedByTable.get(table);
+        if (!assigned) {
+            assigned = new Set();
+            assignedByTable.set(table, assigned);
+        }
+        return assigned;
+    };
+    /** 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 —
+        // 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 ` +
+                `the generated types. Rename the column to expose it.`);
+            return legacy;
+        }
+        if (modern !== null && modern !== legacy && !taken.has(modern))
+            return modern;
+        return resolveRelationNameCollision(modern ?? legacy, taken, table, source);
+    };
+    for (const fk of foreignKeys) {
+        const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
+        const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
+        const singleColumn = fk.sourceColumns.length === 1;
+        // For single-column FKs, keep string form for backwards compatibility.
+        // 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
+        // constraint name (with the usual fk_/-_fkey affixes stripped).
+        const constraintBase = fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '');
+        // --- belongsTo on the source (child) table ---
+        // e.g. posts.user_id → users.id creates posts.user (belongsTo)
+        const legacyBelongsTo = needsDisambiguation
+            ? singleColumn
+                ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
+                : snakeToCamel(constraintBase)
+            : singularize(snakeToCamel(fk.targetTable));
+        const modernBelongsTo = needsDisambiguation && singleColumn ? relationNameFromColumn(fk.sourceColumns[0]) : null;
+        const belongsToName = resolveName(legacyBelongsTo, modernBelongsTo, fk.sourceTable, `FK ${fk.constraintName}`);
+        takenFor(fk.sourceTable).add(belongsToName);
+        assignedFor(fk.sourceTable).add(belongsToName);
+        // Referential actions (omit the 'no action' default to keep metadata lean).
+        const actions = fkActions?.get(fk.constraintName);
+        const actionFields = {};
+        if (actions?.onDelete && actions.onDelete !== 'no action')
+            actionFields.onDelete = actions.onDelete;
+        if (actions?.onUpdate && actions.onUpdate !== 'no action')
+            actionFields.onUpdate = actions.onUpdate;
+        if (!relationsByTable.has(fk.sourceTable))
+            relationsByTable.set(fk.sourceTable, {});
+        relationsByTable.get(fk.sourceTable)[belongsToName] = {
+            type: 'belongsTo',
+            name: belongsToName,
+            from: fk.sourceTable,
+            to: fk.targetTable,
+            foreignKey,
+            referenceKey,
+            ...actionFields,
+        };
+        // --- hasMany on the target (parent) table ---
+        // e.g. posts.user_id → users.id creates users.posts (hasMany)
+        const legacyHasMany = needsDisambiguation
+            ? singleColumn
+                ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
+                : snakeToCamel(`${fk.sourceTable}_by_${constraintBase}`)
+            : snakeToCamel(fk.sourceTable);
+        const modernHasMany = needsDisambiguation
+            ? singleColumn
+                ? `${snakeToCamel(fk.sourceTable)}By${upperFirst(relationNameFromColumn(fk.sourceColumns[0]))}`
+                : `${snakeToCamel(fk.sourceTable)}By${upperFirst(snakeToCamel(constraintBase))}`
+            : null;
+        const hasManyName = resolveName(legacyHasMany, modernHasMany, fk.targetTable, `FK ${fk.constraintName}`);
+        takenFor(fk.targetTable).add(hasManyName);
+        assignedFor(fk.targetTable).add(hasManyName);
+        if (!relationsByTable.has(fk.targetTable))
+            relationsByTable.set(fk.targetTable, {});
+        relationsByTable.get(fk.targetTable)[hasManyName] = {
+            type: 'hasMany',
+            name: hasManyName,
+            from: fk.targetTable,
+            to: fk.sourceTable,
+            foreignKey,
+            referenceKey,
+            ...actionFields,
+        };
+    }
+    return relationsByTable;
+}
+/**
+ * Conservative auto-`manyToMany` detection over pure junction tables, shared
+ * by the Postgres introspector, the engine introspectors (SQLite / MySQL /
+ * MSSQL), the MCP server, and `schemaDefToMetadata()` so all surfaces derive
+ * IDENTICAL relation names for the same logical schema.
+ *
+ * A table J is a PURE junction only when ALL of these hold:
+ *   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.
+ *   4. The two FKs target two DISTINCT tables (A and B).
+ *   5. J has no payload columns beyond the two FK/PK columns.
+ *
+ * For such a J linking A and B this ADDS a `manyToMany` on A → B and B → A
+ * routed `through` J. It never removes or renames an existing relation:
+ *   - an already-assigned relation with the same name → SKIP (additive-only,
+ *     unchanged historical behavior);
+ *   - a shadowed json/jsonb (`unknown`-typed) column → keep the historical
+ *     name + warn (it worked at runtime and compiled);
+ *   - a shadowed concrete-typed column → deterministic `Rel` suffix + warn
+ *     instead of silently dropping the relation.
+ */
+export function addAutoManyToManyRelations(tableNames, foreignKeys, pkByTable, columnNamesByTable, relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable) {
+    for (const tableName of tableNames) {
+        const pk = pkByTable.get(tableName) ?? [];
+        if (pk.length !== 2)
+            continue;
+        // FKs whose source is this table — both must be single-column.
+        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
+        if (tableFks.length !== 2)
+            continue;
+        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
+            continue;
+        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
+        const pkSet = new Set(pk);
+        // Both FK columns must be the PK columns (and vice-versa).
+        if (!fkCols.every((c) => pkSet.has(c)))
+            continue;
+        if (new Set(fkCols).size !== 2)
+            continue;
+        // Two DISTINCT target tables.
+        const [fkA, fkB] = tableFks;
+        if (fkA.targetTable === fkB.targetTable)
+            continue;
+        // No payload columns: J's columns are exactly the two FK/PK columns.
+        const jCols = columnNamesByTable.get(tableName) ?? [];
+        if (jCols.length !== 2)
+            continue;
+        // For each direction, the m2m `referenceKey` is the *targeted* table's
+        // referenced column(s); the junction's sourceKey is the FK column pointing
+        // to that table; the targetKey is the FK column pointing to the OTHER table.
+        const addM2M = (self, other) => {
+            const sourceTbl = self.targetTable; // A
+            const targetTbl = other.targetTable; // B
+            let relName = snakeToCamel(targetTbl); // plural table name → e.g. "tags"
+            if (!relationsByTable.has(sourceTbl))
+                relationsByTable.set(sourceTbl, {});
+            const existing = relationsByTable.get(sourceTbl);
+            // Additive-only: never clobber an existing relation name.
+            if (existing[relName])
+                return;
+            const columnFields = columnFieldsByTable?.get(sourceTbl);
+            if (columnFields?.has(relName)) {
+                if (unknownTypedFieldsByTable?.get(sourceTbl)?.has(relName)) {
+                    // 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; ` +
+                        `the relation is omitted from the generated types.`);
+                }
+                else {
+                    const taken = new Set([...columnFields, ...Object.keys(existing)]);
+                    relName = resolveRelationNameCollision(relName, taken, sourceTbl, `junction ${tableName}`);
+                }
+            }
+            existing[relName] = {
+                type: 'manyToMany',
+                name: relName,
+                from: sourceTbl,
+                to: targetTbl,
+                // referenceKey = A's referenced column(s) that J's sourceKey points at.
+                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
+                // foreignKey is unused for m2m correlation but kept for shape parity
+                // (mirrors the source-side reference for back-compat consumers).
+                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
+                through: {
+                    table: tableName,
+                    sourceKey: self.sourceColumns[0], // J col → A
+                    targetKey: other.sourceColumns[0], // J col → B
+                },
+            };
+        };
+        addM2M(fkA, fkB); // A → B
+        addM2M(fkB, fkA); // B → A
+    }
+}
+/**
+ * One-stop relation derivation for the engine introspectors (SQLite / MySQL /
+ * 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
+ * relation names for the same logical schema (the engines previously carried
+ * stale copies of a retired naming scheme).
+ */
+export function deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable) {
+    const tableSet = new Set(tableNames);
+    const fks = foreignKeys.filter((fk) => tableSet.has(fk.sourceTable) && tableSet.has(fk.targetTable));
+    const columnFieldsByTable = new Map();
+    const unknownTypedFieldsByTable = new Map();
+    for (const [tbl, cols] of columnsByTable) {
+        columnFieldsByTable.set(tbl, new Set(cols.map((c) => c.field)));
+        unknownTypedFieldsByTable.set(tbl, new Set(cols.filter((c) => isUnknownTsType(c.tsType)).map((c) => c.field)));
+    }
+    const relationsByTable = buildRelationsFromForeignKeys(fks, columnFieldsByTable, undefined, unknownTypedFieldsByTable);
+    addAutoManyToManyRelations(tableNames, fks, pkByTable, new Map(Array.from(columnsByTable, ([tbl, cols]) => [tbl, cols.map((c) => c.name)])), relationsByTable, columnFieldsByTable, unknownTypedFieldsByTable);
+    return relationsByTable;
+}

package/dist/mssql.js

@@ -92,7 +92,9 @@
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
 import { ConnectionError, RelationError, UnsupportedFeatureError, ValidationError } from './errors.js';
-import { camelToSnake, isDateType, normalizeKeyColumns, singularize, snakeToCamel, } from './schema.js';
+import { deriveEngineRelations } from './introspect.js';
+import importOptionalPeer from './optional-peer-import.cjs';
+import { camelToSnake, isDateType, normalizeKeyColumns, snakeToCamel, } from './schema.js';
 // ---------------------------------------------------------------------------
 // SQL Server / connection limits
 // ---------------------------------------------------------------------------
@@ -853,103 +855,15 @@ function buildForJsonManyToMany(dialect, ctx, h) {
 }
 const num = (v) => (typeof v === 'string' ? Number(v) : (v ?? 0));
 /**
- * Derive belongsTo + hasMany relations (and conservatively-detected manyToMany
- * junctions) from a flat foreign-key list. Mirrors the PostgreSQL / MySQL / SQLite
- * introspectors so the produced {@link SchemaMetadata} has an identical relation
- * shape across engines.
+ * Derive relations from the FK list via the SHARED introspection pipeline
+ * (`deriveEngineRelations` → `buildRelationsFromForeignKeys` +
+ * `addAutoManyToManyRelations` in introspect.ts), so this engine derives
+ * IDENTICAL relation names to `turbine generate` against Postgres for the
+ * same logical schema — legacy-first naming, per-column disambiguation, and
+ * collision resolution against scalar column fields included.
  */
 function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, columnsByTable) {
-    const tableSet = new Set(tableNames);
-    const fkCounts = new Map();
-    for (const fk of foreignKeys) {
-        const key = `${fk.sourceTable}->${fk.targetTable}`;
-        fkCounts.set(key, (fkCounts.get(key) ?? 0) + 1);
-    }
-    const relationsByTable = new Map();
-    for (const fk of foreignKeys) {
-        if (!tableSet.has(fk.targetTable))
-            continue;
-        const needsDisambiguation = (fkCounts.get(`${fk.sourceTable}->${fk.targetTable}`) ?? 0) > 1;
-        const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
-        const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
-        const belongsToName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
-            : singularize(snakeToCamel(fk.targetTable));
-        if (!relationsByTable.has(fk.sourceTable))
-            relationsByTable.set(fk.sourceTable, {});
-        relationsByTable.get(fk.sourceTable)[belongsToName] = {
-            type: 'belongsTo',
-            name: belongsToName,
-            from: fk.sourceTable,
-            to: fk.targetTable,
-            foreignKey,
-            referenceKey,
-        };
-        const hasManyName = needsDisambiguation && fk.sourceColumns.length === 1
-            ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
-            : snakeToCamel(fk.sourceTable);
-        if (!relationsByTable.has(fk.targetTable))
-            relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
-            from: fk.targetTable,
-            to: fk.sourceTable,
-            foreignKey,
-            referenceKey,
-        };
-    }
-    // Conservative many-to-many auto-detection (additive): a table J is a pure
-    // junction iff PK is exactly two columns, exactly two single-column FKs whose
-    // source columns ARE the PK, two distinct target tables, and no payload columns.
-    for (const tableName of tableNames) {
-        const pk = pkByTable.get(tableName) ?? [];
-        if (pk.length !== 2)
-            continue;
-        const tableFks = foreignKeys.filter((fk) => fk.sourceTable === tableName);
-        if (tableFks.length !== 2)
-            continue;
-        if (tableFks.some((fk) => fk.sourceColumns.length !== 1))
-            continue;
-        const fkCols = tableFks.map((fk) => fk.sourceColumns[0]);
-        const pkSet = new Set(pk);
-        if (!fkCols.every((c) => pkSet.has(c)))
-            continue;
-        if (new Set(fkCols).size !== 2)
-            continue;
-        const [fkA, fkB] = tableFks;
-        if (fkA.targetTable === fkB.targetTable)
-            continue;
-        const jCols = (columnsByTable.get(tableName) ?? []).map((c) => c.name);
-        if (jCols.length !== 2)
-            continue;
-        const addM2M = (self, other) => {
-            const sourceTbl = self.targetTable;
-            const targetTbl = other.targetTable;
-            const relName = snakeToCamel(targetTbl);
-            if (!relationsByTable.has(sourceTbl))
-                relationsByTable.set(sourceTbl, {});
-            const existing = relationsByTable.get(sourceTbl);
-            if (existing[relName])
-                return;
-            existing[relName] = {
-                type: 'manyToMany',
-                name: relName,
-                from: sourceTbl,
-                to: targetTbl,
-                referenceKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                foreignKey: self.targetColumns.length === 1 ? self.targetColumns[0] : self.targetColumns,
-                through: {
-                    table: tableName,
-                    sourceKey: self.sourceColumns[0],
-                    targetKey: other.sourceColumns[0],
-                },
-            };
-        };
-        addM2M(fkA, fkB);
-        addM2M(fkB, fkA);
-    }
-    return relationsByTable;
+    return deriveEngineRelations(tableNames, foreignKeys, pkByTable, columnsByTable);
 }
 /**
  * Introspect a SQL Server database into the same {@link SchemaMetadata} shape the
@@ -1196,11 +1110,12 @@ async function loadMssql() {
     let mod;
     try {
         // `mssql` ships no bundled type declarations (it needs @types/mssql, which
-        // Turbine deliberately does not depend on) — the structural MssqlModule above
-        // is our typed surface. Import through a widened specifier so tsc treats the
-        // typeless module as `any` instead of erroring (TS7016).
-        const specifier = 'mssql';
-        mod = (await import(specifier));
+        // Turbine deliberately does not depend on) — the structural MssqlModule
+        // above is our typed surface; the helper returns `unknown` so no TS7016.
+        // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
+        // import() even if a future mssql major goes ESM-only (the CommonJS pass
+        // transpiles a plain `import()` here into `require()`).
+        mod = (await importOptionalPeer('mssql'));
     }
     catch (err) {
         throw new ConnectionError("[turbine] turbine-orm/mssql requires the optional peer dependency 'mssql'. Install it: npm i mssql. " +