turbine-orm 0.40.1 → 0.41.0

package/dist/cjs/introspect.js

@@ -12,12 +12,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXCLUDED_TABLES = void 0;
 exports.pgConfActionToReferential = pgConfActionToReferential;
+exports.applyTableFilters = applyTableFilters;
+exports.defaultExcludedTablesPresent = defaultExcludedTablesPresent;
 exports.introspect = introspect;
 exports.introspectPostgresCatalog = introspectPostgresCatalog;
 exports.stripCheckWrapper = stripCheckWrapper;
 exports.relationNameFromColumn = relationNameFromColumn;
 exports.isUnknownTsType = isUnknownTsType;
+exports.parsePlainUniqueIndexColumns = parsePlainUniqueIndexColumns;
+exports.detectUniqueForeignKeySets = detectUniqueForeignKeySets;
 exports.buildRelationsFromForeignKeys = buildRelationsFromForeignKeys;
 exports.addAutoManyToManyRelations = addAutoManyToManyRelations;
 exports.deriveEngineRelations = deriveEngineRelations;
@@ -190,6 +195,61 @@ const SQL_ENUMS = `
   ORDER BY t.typname, e.enumsortorder
 `;
 // ---------------------------------------------------------------------------
+// Default table exclusions (F12)
+// ---------------------------------------------------------------------------
+/**
+ * Migration-bookkeeping tables that introspection drops by default: Turbine's
+ * own `_turbine_migrations` / `_turbine_metrics` and Prisma's
+ * `_prisma_migrations`. These are almost never meant to be surfaced as typed
+ * accessors, and a fresh migrate-from-Prisma introspection would otherwise emit
+ * a `PrismaMigrations` entity plus stray FK-derived relations on neighbours.
+ *
+ * A table named here is dropped UNLESS it is explicitly listed in
+ * `options.include` (`include` is the escape hatch, no separate flag), and
+ * naming a default-excluded table restores its old generated output byte for
+ * byte. The list is deliberately tight (exactly these three); leading-
+ * underscore tables are legitimate user tables and are never blanket-excluded.
+ */
+exports.DEFAULT_EXCLUDED_TABLES = ['_turbine_migrations', '_prisma_migrations', '_turbine_metrics'];
+/**
+ * The single authority for turning a raw list of candidate table names into the
+ * introspected set, shared by the Postgres catalog reader and every engine
+ * introspector (SQLite / MySQL / MSSQL / PowDB) so all surfaces agree.
+ *
+ * Order of operations:
+ *   1. `include` filter: when non-empty, keep only the named tables.
+ *   2. user `exclude`: drop anything the caller listed.
+ *   3. {@link DEFAULT_EXCLUDED_TABLES}: drop migration bookkeeping tables,
+ *      EXCEPT any that the caller explicitly named in `include` (the escape
+ *      hatch that restores the pre-0.41 output for those tables).
+ */
+function applyTableFilters(names, options = {}) {
+    let result = names;
+    const includeSet = options.include?.length ? new Set(options.include) : null;
+    if (includeSet) {
+        result = result.filter((t) => includeSet.has(t));
+    }
+    if (options.exclude?.length) {
+        const excludeSet = new Set(options.exclude);
+        result = result.filter((t) => !excludeSet.has(t));
+    }
+    // Default exclusions never override an explicit include.
+    const defaults = new Set(exports.DEFAULT_EXCLUDED_TABLES);
+    result = result.filter((t) => !defaults.has(t) || (includeSet?.has(t) ?? false));
+    return result;
+}
+/**
+ * The subset of {@link DEFAULT_EXCLUDED_TABLES} that were present in `names` but
+ * dropped by {@link applyTableFilters} (i.e. not re-added via `include`). Pure
+ * helper so the CLI can report "skipped internal table X" without re-deriving
+ * the filtering rule.
+ */
+function defaultExcludedTablesPresent(names, options = {}) {
+    const includeSet = options.include?.length ? new Set(options.include) : null;
+    const present = new Set(names);
+    return exports.DEFAULT_EXCLUDED_TABLES.filter((t) => present.has(t) && !(includeSet?.has(t) ?? false));
+}
+// ---------------------------------------------------------------------------
 // Main introspection function
 // ---------------------------------------------------------------------------
 /**
@@ -257,16 +317,18 @@ async function introspectPostgresCatalog(options) {
                 onUpdate: pgConfActionToReferential(row.confupdtype),
             });
         }
-        // Filter tables by include/exclude. Views/matviews join the base tables as
-        // candidates so include/exclude apply uniformly.
-        let tableNames = [...tablesResult.rows.map((r) => r.table_name), ...viewNameSet];
-        if (options.include?.length) {
-            const includeSet = new Set(options.include);
-            tableNames = tableNames.filter((t) => includeSet.has(t));
-        }
-        if (options.exclude?.length) {
-            const excludeSet = new Set(options.exclude);
-            tableNames = tableNames.filter((t) => !excludeSet.has(t));
+        // Filter tables by include/exclude + default bookkeeping-table exclusions
+        // (F12). Views/matviews join the base tables as candidates so the filters
+        // apply uniformly.
+        const candidateTables = [
+            ...tablesResult.rows.map((r) => r.table_name),
+            ...viewNameSet,
+        ];
+        const tableNames = applyTableFilters(candidateTables, options);
+        if (options.onDefaultTableExclusion) {
+            const skipped = defaultExcludedTablesPresent(candidateTables, options);
+            if (skipped.length > 0)
+                options.onDefaultTableExclusion(skipped);
         }
         const tableSet = new Set(tableNames);
         // ----- Group columns by table -----
@@ -421,7 +483,13 @@ async function introspectPostgresCatalog(options) {
             // 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);
+        // F2: unless the caller opts out, detect child FK column sets that a unique
+        // constraint / plain unique index exactly covers, so the reverse relation is
+        // emitted as a one-to-one (`hasOne`) instead of `hasMany`.
+        const uniqueSetsByTable = options.legacyToManyUniques
+            ? undefined
+            : detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTable);
+        const relationsByTable = buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable, uniqueSetsByTable);
         // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
         //
         // Auto-detecting m2m is a footgun: any table with two FKs *looks* like a
@@ -551,6 +619,92 @@ function upperFirst(s) {
 function isUnknownTsType(tsType) {
     return tsType === 'unknown' || tsType === 'unknown | null';
 }
+// ---------------------------------------------------------------------------
+// Unique-foreign-key detection for one-to-one relations (F2)
+// ---------------------------------------------------------------------------
+/** True when two column lists cover the same set (order-insensitive, no dupes). */
+function columnSetsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const bs = new Set(b);
+    return a.every((c) => bs.has(c));
+}
+/**
+ * Parse the column list of a PLAIN unique index from its `pg_indexes.indexdef`,
+ * returning `null` for anything that does NOT guarantee at-most-one child row:
+ *
+ *   - a PARTIAL index (has a `WHERE` clause): only unique within the predicate;
+ *   - an EXPRESSION index (`lower(email)`, `(a || b)`): the uniqueness is on the
+ *     expression, not the raw FK column set.
+ *
+ * Anchors on the `USING <method> (` clause the same way
+ * {@link describeIndexDefMismatch} does, so a partial index's `WHERE (...)`
+ * parentheses are never mistaken for the column list. Every column token must be
+ * a bare or double-quoted identifier; anything else (a function call, an
+ * operator expression) fails the check and yields `null`.
+ */
+function parsePlainUniqueIndexColumns(indexdef) {
+    // Partial index: uniqueness is scoped to the WHERE predicate.
+    if (/\bWHERE\b/i.test(indexdef))
+        return null;
+    const paren = indexdef.match(/USING\s+\w+\s*\(([^)]*)\)/i);
+    if (!paren)
+        return null;
+    const tokens = paren[1].split(',').map((c) => c
+        .trim()
+        .replace(/\s+(ASC|DESC|NULLS\s+(FIRST|LAST))\b/gi, '')
+        .trim());
+    const columns = [];
+    for (const token of tokens) {
+        if (token.length === 0)
+            return null;
+        if (/^"(?:[^"]|"")*"$/.test(token)) {
+            // Quoted identifier: unquote and unescape doubled quotes.
+            columns.push(token.slice(1, -1).replace(/""/g, '"'));
+        }
+        else if (/^[A-Za-z_][A-Za-z0-9_$]*$/.test(token)) {
+            columns.push(token);
+        }
+        else {
+            // Expression column (function call, operator, cast, and the like): never a plain FK.
+            return null;
+        }
+    }
+    return columns.length > 0 ? columns : null;
+}
+/**
+ * Assemble, per table, every column set that EXACTLY guarantees at-most-one row:
+ * the primary key, every UNIQUE constraint, and every PLAIN (non-partial,
+ * non-expression) UNIQUE index. Consumed by
+ * {@link buildRelationsFromForeignKeys} to flip a child relation whose FK column
+ * set matches one of these sets from `hasMany` to `hasOne` (F2, Prisma
+ * one-to-one parity).
+ */
+function detectUniqueForeignKeySets(pkByTable, uniqueByTable, indexesByTable) {
+    const result = new Map();
+    const add = (table, cols) => {
+        if (cols.length === 0)
+            return;
+        if (!result.has(table))
+            result.set(table, []);
+        result.get(table).push(cols);
+    };
+    for (const [table, pk] of pkByTable)
+        add(table, pk);
+    for (const [table, sets] of uniqueByTable)
+        for (const cols of sets)
+            add(table, cols);
+    for (const [table, indexes] of indexesByTable) {
+        for (const idx of indexes) {
+            if (!idx.unique)
+                continue;
+            const cols = parsePlainUniqueIndexColumns(idx.definition);
+            if (cols)
+                add(table, cols);
+        }
+    }
+    return result;
+}
 /**
  * Resolve a derived relation name against the names already taken on the
  * table (scalar column fields + previously assigned relations). On collision,
@@ -597,8 +751,16 @@ function resolveRelationNameCollision(candidate, taken, table, source) {
  *   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).
+ * @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
+ *   set EXACTLY matches one of the child's unique sets is emitted as `hasOne`
+ *   (to-one) instead of `hasMany`, and named with the SINGULAR of the child
+ *   table (falling back to the legacy plural name on collision). Omit it (the
+ *   engine introspectors and `defineSchema` path do) to keep every reverse
+ *   relation `hasMany`.
  */
-function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable) {
+function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActions, unknownTypedFieldsByTable, uniqueSetsByTable) {
     // Count FKs per (source, target) pair for disambiguation.
     const fkCounts = new Map();
     for (const fk of foreignKeys) {
@@ -687,26 +849,41 @@ function buildRelationsFromForeignKeys(foreignKeys, columnFieldsByTable, fkActio
             referenceKey,
             ...actionFields,
         };
-        // --- hasMany on the target (parent) table ---
-        // e.g. posts.user_id → users.id creates users.posts (hasMany)
-        const legacyHasMany = needsDisambiguation
+        // --- reverse relation on the target (parent) table ---
+        // e.g. posts.user_id → users.id creates users.posts (hasMany), UNLESS the
+        // child's FK column set is exactly covered by a unique constraint / plain
+        // unique index (F2), then it is a one-to-one, emitted as `hasOne` and
+        // named with the SINGULAR of the child table.
+        const isUniqueFk = (uniqueSetsByTable?.get(fk.sourceTable) ?? []).some((set) => columnSetsEqual(set, fk.sourceColumns));
+        const disambSuffix = needsDisambiguation
+            ? singleColumn
+                ? `By${upperFirst(relationNameFromColumn(fk.sourceColumns[0]))}`
+                : `By${upperFirst((0, schema_js_1.snakeToCamel)(constraintBase))}`
+            : '';
+        const legacyReverse = needsDisambiguation
             ? singleColumn
                 ? (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
                 : (0, schema_js_1.snakeToCamel)(`${fk.sourceTable}_by_${constraintBase}`)
             : (0, schema_js_1.snakeToCamel)(fk.sourceTable);
-        const modernHasMany = needsDisambiguation
-            ? singleColumn
-                ? `${(0, schema_js_1.snakeToCamel)(fk.sourceTable)}By${upperFirst(relationNameFromColumn(fk.sourceColumns[0]))}`
-                : `${(0, schema_js_1.snakeToCamel)(fk.sourceTable)}By${upperFirst((0, schema_js_1.snakeToCamel)(constraintBase))}`
-            : null;
-        const hasManyName = resolveName(legacyHasMany, modernHasMany, fk.targetTable, `FK ${fk.constraintName}`);
-        takenFor(fk.targetTable).add(hasManyName);
-        assignedFor(fk.targetTable).add(hasManyName);
+        const modernReverse = needsDisambiguation ? `${(0, schema_js_1.snakeToCamel)(fk.sourceTable)}${disambSuffix}` : null;
+        let reverseName;
+        const reverseType = isUniqueFk ? 'hasOne' : 'hasMany';
+        if (isUniqueFk) {
+            // Prefer the singular child-table name; fall back to the legacy plural
+            // (which stays byte-stable for any app that was on the pre-flip shape).
+            const singularReverse = `${(0, schema_js_1.singularize)((0, schema_js_1.snakeToCamel)(fk.sourceTable))}${disambSuffix}`;
+            reverseName = resolveName(singularReverse, legacyReverse, fk.targetTable, `FK ${fk.constraintName}`);
+        }
+        else {
+            reverseName = resolveName(legacyReverse, modernReverse, fk.targetTable, `FK ${fk.constraintName}`);
+        }
+        takenFor(fk.targetTable).add(reverseName);
+        assignedFor(fk.targetTable).add(reverseName);
         if (!relationsByTable.has(fk.targetTable))
             relationsByTable.set(fk.targetTable, {});
-        relationsByTable.get(fk.targetTable)[hasManyName] = {
-            type: 'hasMany',
-            name: hasManyName,
+        relationsByTable.get(fk.targetTable)[reverseName] = {
+            type: reverseType,
+            name: reverseName,
             from: fk.targetTable,
             to: fk.sourceTable,
             foreignKey,

package/dist/cjs/mssql.js

@@ -560,7 +560,12 @@ exports.mssqlDialect = {
             .map((row) => `(${row.map(() => this.paramPlaceholder(++n)).join(', ')})`)
             .join(', ');
         const out = mssqlOutput(input.returning, 'INSERTED');
-        // skipDuplicates has no single-statement equivalent here; ignored (documented).
+        // SQL Server has no single-statement skip-duplicates form (no ON CONFLICT /
+        // INSERT IGNORE), so silently dropping the flag would let duplicate rows
+        // through against the caller's intent. Refuse loudly instead.
+        if (input.skipDuplicates) {
+            throw new errors_js_1.UnsupportedFeatureError('createMany({ skipDuplicates: true })', 'mssql', 'SQL Server has no ON CONFLICT DO NOTHING equivalent, pre-filter conflicting rows or use a MERGE.');
+        }
         return {
             sql: `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES ${placeholders}`,
             params: input.rowValues.flat(),
@@ -934,15 +939,9 @@ function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, colum
  */
 async function introspectMssqlWith(exec, schema = 'dbo', options = {}) {
     // ----- Tables -----
-    let tableNames = (await exec("SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = @p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    const candidateTables = (await exec("SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = @p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
+    // include / exclude + default bookkeeping-table exclusions (F12).
+    const tableNames = (0, introspect_js_1.applyTableFilters)(candidateTables, options);
     const tableSet = new Set(tableNames);
     // ----- Identity columns (mark hasDefault) -----
     const identityRows = await exec(`SELECT t.name AS TABLE_NAME, c.name AS COLUMN_NAME

package/dist/cjs/mysql.js

@@ -596,15 +596,9 @@ function buildRelationsFromForeignKeys(tableNames, foreignKeys, pkByTable, colum
  */
 async function introspectMysqlWith(exec, schema, options = {}) {
     // ----- Tables -----
-    let tableNames = (await exec("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = :p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    const candidateTables = (await exec("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = :p1 AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME", [schema])).map((r) => String(r.TABLE_NAME));
+    // include / exclude + default bookkeeping-table exclusions (F12).
+    const tableNames = (0, introspect_js_1.applyTableFilters)(candidateTables, options);
     const tableSet = new Set(tableNames);
     // ----- Columns -----
     const columnRows = (await exec(`SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY,

package/dist/cjs/powdb-introspect.js

@@ -57,6 +57,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.introspectPowdbDatabase = introspectPowdbDatabase;
 const errors_js_1 = require("./errors.js");
+const introspect_js_1 = require("./introspect.js");
 const powdb_js_1 = require("./powdb.js");
 const schema_js_1 = require("./schema.js");
 /** Coerce a wire cell to string (legacy wire cells are strings; native cells may be typed). */
@@ -110,24 +111,18 @@ async function introspectPowdbDatabase(exec, options = {}) {
     }
     // ----- Types (one row per table, columns `name`, `columns`) -----
     const schemaRows = (await exec('schema')).rows;
-    let tableNames = schemaRows.map((r) => asString(r.name)).filter((n) => n.length > 0);
+    const candidateTables = schemaRows.map((r) => asString(r.name)).filter((n) => n.length > 0);
     // A mis-shaped `exec` (e.g. the raw client's positional `string[][]` rows
     // passed straight through) yields rows whose `name` cell is `undefined`, so
     // every table filters out and the schema comes back silently empty. Refuse
     // that instead of losing data: real rows must carry a `name`.
-    if (schemaRows.length > 0 && tableNames.length === 0) {
+    if (schemaRows.length > 0 && candidateTables.length === 0) {
         throw new errors_js_1.ValidationError(`[turbine] PowDB introspection: the \`schema\` statement returned ${schemaRows.length} row(s) but none carried a ` +
             '`name` cell. The `exec` you supplied likely returns POSITIONAL rows (string[][]) rather than records keyed by ' +
             'column name; zip `columns` with each row (see introspectPowdbDatabase docs).');
     }
-    if (options.include?.length) {
-        const inc = new Set(options.include);
-        tableNames = tableNames.filter((t) => inc.has(t));
-    }
-    if (options.exclude?.length) {
-        const exc = new Set(options.exclude);
-        tableNames = tableNames.filter((t) => !exc.has(t));
-    }
+    // include / exclude + default bookkeeping-table exclusions (F12).
+    const tableNames = (0, introspect_js_1.applyTableFilters)(candidateTables, options);
     const tables = {};
     for (const tableName of tableNames) {
         // `describe` needs the table name in bare-identifier position → quote it so

package/dist/cjs/powql.js

@@ -74,6 +74,7 @@ const node_crypto_1 = require("node:crypto");
 const errors_js_1 = require("./errors.js");
 const nested_write_js_1 = require("./nested-write.js");
 const powdb_js_1 = require("./powdb.js");
+const compound_unique_js_1 = require("./query/compound-unique.js");
 const filters_js_1 = require("./query/filters.js");
 const utils_js_1 = require("./query/utils.js");
 const schema_js_1 = require("./schema.js");
@@ -1043,6 +1044,13 @@ class PowqlInterface {
             .filter((line) => line.length > 0);
     }
     async findUnique(args) {
+        // Prisma compound-unique selector → column conjunction (engine parity with
+        // the SQL findUnique family; pure metadata, so this is a one-line adoption).
+        if (args.where) {
+            const expanded = (0, compound_unique_js_1.expandCompoundUniqueWhere)(this.meta, args.where);
+            if (expanded !== args.where)
+                args = { ...args, where: expanded };
+        }
         return this.withMiddleware('findUnique', args, async () => {
             const { rows, native, nestedPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
@@ -1772,6 +1780,11 @@ class PowqlInterface {
     }
     async createMany(args) {
         return this.withMiddleware('createMany', args, async () => {
+            if (args.skipDuplicates) {
+                // PowQL's `insert … returning` has no conflict clause, so there is no
+                // faithful skip-duplicates form; refuse rather than silently insert.
+                throw new errors_js_1.UnsupportedFeatureError('createMany({ skipDuplicates: true })', 'powdb', 'PowQL insert has no ON CONFLICT DO NOTHING equivalent, filter duplicates before inserting.');
+            }
             const inputs = args.data.map((d) => this.applyPkDefault(d));
             if (!inputs.length)
                 return [];