turbine-orm 0.16.0 → 0.18.0

package/dist/cjs/errors.js

@@ -211,7 +211,13 @@ class UniqueConstraintError extends TurbineError {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             const columnsPart = columns && columns.length > 0 ? ` (${columns.join(', ')})` : '';
             message = `[turbine] Unique constraint violation${constraintPart}${columnsPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -233,7 +239,13 @@ class ForeignKeyError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Foreign key constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -254,7 +266,13 @@ class NotNullViolationError extends TurbineError {
         if (!message) {
             const columnPart = column ? ` on column "${column}"` : '';
             message = `[turbine] NOT NULL constraint violation${columnPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -342,7 +360,13 @@ class CheckConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Check constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -362,7 +386,13 @@ class ExclusionConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Exclusion constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }

package/dist/cjs/generate.js

@@ -156,7 +156,8 @@ function generateTypes(schema) {
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                const cardinality = rel.type === 'hasMany' ? "'many'" : "'one'";
+                // manyToMany is a collection too → 'many' cardinality (same as hasMany).
+                const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
                 const targetRelations = tablesWithRelations.has(rel.to) ? `${targetType}Relations` : '{}';
                 lines.push(`  ${relName}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
             }
@@ -165,7 +166,7 @@ function generateTypes(schema) {
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                if (rel.type === 'hasMany') {
+                if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
                     lines.push(`export interface ${typeName}With${(0, schema_js_1.snakeToPascal)(relName)} extends ${typeName} {`);
                     lines.push(`  ${relName}: ${targetType}[];`);
@@ -332,7 +333,17 @@ function generateMetadata(schema) {
             const refLiteral = Array.isArray(rel.referenceKey)
                 ? `[${rel.referenceKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
                 : `'${escSQ(rel.referenceKey)}'`;
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral} },`);
+            // manyToMany relations carry a `through` junction descriptor — emit it so
+            // the runtime query builder can JOIN through the junction table.
+            let throughLiteral = '';
+            if (rel.through) {
+                const keyLiteral = (k) => Array.isArray(k) ? `[${k.map((c) => `'${escSQ(c)}'`).join(', ')}]` : `'${escSQ(k)}'`;
+                throughLiteral =
+                    `, through: { table: '${escSQ(rel.through.table)}', ` +
+                        `sourceKey: ${keyLiteral(rel.through.sourceKey)}, ` +
+                        `targetKey: ${keyLiteral(rel.through.targetKey)} }`;
+            }
+            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral}${throughLiteral} },`);
         }
         lines.push('      },');
         // indexes

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.table = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = void 0;
+exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.table = exports.defineSchema = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -90,6 +90,9 @@ Object.defineProperty(exports, "pipelineSupported", { enumerable: true, get: fun
 // Query builder
 var index_js_2 = require("./query/index.js");
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
+// Realtime — LISTEN/NOTIFY pub/sub
+var realtime_js_1 = require("./realtime.js");
+Object.defineProperty(exports, "validateChannel", { enumerable: true, get: function () { return realtime_js_1.validateChannel; } });
 // Schema utilities
 var schema_js_1 = require("./schema.js");
 Object.defineProperty(exports, "camelToSnake", { enumerable: true, get: function () { return schema_js_1.camelToSnake; } });
@@ -102,6 +105,7 @@ Object.defineProperty(exports, "snakeToCamel", { enumerable: true, get: function
 Object.defineProperty(exports, "snakeToPascal", { enumerable: true, get: function () { return schema_js_1.snakeToPascal; } });
 // Schema builder — define schemas in TypeScript
 var schema_builder_js_1 = require("./schema-builder.js");
+Object.defineProperty(exports, "applyManyToManyRelations", { enumerable: true, get: function () { return schema_builder_js_1.applyManyToManyRelations; } });
 Object.defineProperty(exports, "ColumnBuilder", { enumerable: true, get: function () { return schema_builder_js_1.ColumnBuilder; } });
 Object.defineProperty(exports, "column", { enumerable: true, get: function () { return schema_builder_js_1.column; } });
 Object.defineProperty(exports, "defineSchema", { enumerable: true, get: function () { return schema_builder_js_1.defineSchema; } });
@@ -116,3 +120,7 @@ Object.defineProperty(exports, "schemaToSQLString", { enumerable: true, get: fun
 // Serverless / edge factory
 var serverless_js_1 = require("./serverless.js");
 Object.defineProperty(exports, "turbineHttp", { enumerable: true, get: function () { return serverless_js_1.turbineHttp; } });
+// Typed raw SQL — Turbine's TypedSQL escape hatch
+var typed_sql_js_1 = require("./typed-sql.js");
+Object.defineProperty(exports, "buildTypedSql", { enumerable: true, get: function () { return typed_sql_js_1.buildTypedSql; } });
+Object.defineProperty(exports, "TypedSqlQuery", { enumerable: true, get: function () { return typed_sql_js_1.TypedSqlQuery; } });

package/dist/cjs/introspect.js

@@ -281,6 +281,87 @@ async function introspect(options) {
                 referenceKey,
             };
         }
+        // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
+        //
+        // Auto-detecting m2m is a footgun: any table with two FKs *looks* like a
+        // junction, but a `enrollments(student_id, course_id, grade, enrolled_at)`
+        // table is a first-class entity, not a join table. Prisma and Drizzle both
+        // require explicit m2m declaration for exactly this reason.
+        //
+        // We only treat a table J as a PURE junction 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 (the PK *is* the
+        //      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
+        // 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 = (0, schema_js_1.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
+        }
         // ----- Assemble TableMetadata for each table -----
         const tables = {};
         for (const tableName of tableNames) {

package/dist/cjs/nested-write.js

@@ -144,17 +144,29 @@ async function executeNestedCreate(ctx, tableName, data, depth = 0, path = []) {
         }
         validateOps(relName, ops, false);
     }
-    // Insert the parent row
-    const parentRow = (await ctx.tx.table(tableName).create({ data: scalars }));
-    // Process each relation
+    // belongsTo relations put the foreign key on the PARENT row, so they must be
+    // resolved BEFORE the parent is inserted — otherwise a NOT NULL FK column
+    // fails on the initial INSERT. We resolve each belongsTo op (create/connect/
+    // connectOrCreate) to its referenced row and fold the FK values into the
+    // parent's own INSERT.
+    const belongsToFks = {};
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (rel.type === 'belongsTo') {
+            Object.assign(belongsToFks, await resolveBelongsToForCreate(ctx, rel, ops, tableName, depth, path, relName));
+        }
+    }
+    // Insert the parent row (scalars + resolved belongsTo foreign keys)
+    const parentRow = (await ctx.tx.table(tableName).create({
+        data: { ...scalars, ...belongsToFks },
+    }));
+    // Process hasMany / hasOne relations — their FK lives on the CHILD, so they
+    // need the parent row to exist first.
     for (const [relName, ops] of Object.entries(relations)) {
         const rel = tableMeta.relations[relName];
         if (rel.type === 'hasMany' || rel.type === 'hasOne') {
             await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
         }
-        else if (rel.type === 'belongsTo') {
-            await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
-        }
     }
     // Build the `with` clause for the final read to return the full tree
     const withClause = {};
@@ -319,6 +331,58 @@ async function processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relNa
 // ---------------------------------------------------------------------------
 // belongsTo create operations
 // ---------------------------------------------------------------------------
+/**
+ * Resolve a belongsTo relation's create/connect/connectOrCreate op to the
+ * foreign-key value(s) that belong on the PARENT row, returning them keyed by
+ * the parent's own field names so they can be merged into the parent INSERT.
+ *
+ * Used by the create path only. (The update path uses processBelongsToCreate,
+ * which UPDATEs the FK after the parent already exists.)
+ */
+async function resolveBelongsToForCreate(ctx, rel, ops, parentTable, depth, path, relName) {
+    const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+    const refs = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    let relatedRow = null;
+    if (ops.create !== undefined) {
+        const items = toArray(ops.create);
+        if (items.length > 0) {
+            relatedRow = (await executeNestedCreate(ctx, rel.to, items[0], depth + 1, [...path, relName]));
+        }
+    }
+    else if (ops.connect !== undefined) {
+        const items = toArray(ops.connect);
+        if (items.length > 0) {
+            const target = items[0];
+            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: target }));
+            if (!relatedRow) {
+                throw new errors_js_1.ValidationError(`[turbine] connect on "${relName}": no ${rel.to} row found matching ${JSON.stringify(target)}.`);
+            }
+        }
+    }
+    else if (ops.connectOrCreate !== undefined) {
+        const items = toArray(ops.connectOrCreate);
+        if (items.length > 0) {
+            const op = items[0];
+            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: op.where }));
+            if (!relatedRow) {
+                // For belongsTo the FK lives on the parent, so the related row is
+                // created plainly (no FK injection) and we read its reference key.
+                relatedRow = (await ctx.tx.table(rel.to).create({ data: op.create }));
+            }
+        }
+    }
+    const fkScalars = {};
+    if (relatedRow) {
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+            fkScalars[fkField] = relatedRow[refField];
+        }
+    }
+    return fkScalars;
+}
 async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
     const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
     const refs = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);