turbine-orm 0.16.0 → 0.19.0

package/dist/generate.js

@@ -152,7 +152,8 @@ export 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}>;`);
             }
@@ -161,7 +162,7 @@ export 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${snakeToPascal(relName)} extends ${typeName} {`);
                     lines.push(`  ${relName}: ${targetType}[];`);
@@ -328,7 +329,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/index.d.ts

@@ -43,10 +43,12 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
-export { ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { applyManyToManyRelations, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type ManyToManyDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';
+export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -48,14 +48,18 @@ export { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './
 export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder
 export { QueryInterface, } from './query/index.js';
+// Realtime — LISTEN/NOTIFY pub/sub
+export { validateChannel } from './realtime.js';
 // Schema utilities
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
-export { ColumnBuilder, column, defineSchema, 
+export { applyManyToManyRelations, ColumnBuilder, column, defineSchema, 
 // Legacy compat (deprecated — use object format with defineSchema)
 table, } from './schema-builder.js';
 // Schema SQL — generate DDL, diff, and push
 export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
 // Serverless / edge factory
 export { turbineHttp } from './serverless.js';
+// Typed raw SQL — Turbine's TypedSQL escape hatch
+export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 //# sourceMappingURL=index.js.map

package/dist/introspect.js

@@ -275,6 +275,87 @@ export 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 = 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/nested-write.js

@@ -137,17 +137,29 @@ export 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 = {};
@@ -312,6 +324,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 = normalizeKeyColumns(rel.foreignKey);
+    const refs = 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 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 = normalizeKeyColumns(rel.foreignKey);
     const refs = normalizeKeyColumns(rel.referenceKey);

package/dist/query/builder.d.ts

@@ -114,6 +114,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly columnArrayTypeMap;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
+    /**
+     * Per-table memo of date columns keyed by their camelCase FIELD name.
+     * `meta.dateColumns` is keyed by raw snake_case column name, which matches
+     * top-level rows from pg. Nested relation rows arrive from json_build_object
+     * with camelCase keys, so they need this camelCase-keyed set to be coerced
+     * to Date as well (otherwise nested dates leak through as strings).
+     */
+    private readonly camelDateFieldCache;
     /** True when this QI runs inside an active transaction (set via _txScoped option). */
     private readonly txScoped;
     /** Original options reference — forwarded to child QIs in nested writes. */
@@ -251,6 +259,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Build the SQL fragments for a {@link HavingClause}.
+     *
+     * Each aggregate expression (`COUNT(*)`, `SUM("col")`, etc.) is constructed
+     * from a **schema-validated, quoted** column identifier — `this.toColumn()`
+     * throws {@link ValidationError} for unknown fields and `this.q()` quotes via
+     * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
+     * comparison value is pushed onto the shared `params` array and referenced by
+     * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
+     * interpolation of user values.
+     */
+    private buildHavingClauses;
+    /**
+     * Convert a single having filter into one or more parameterized SQL
+     * comparisons against the given aggregate expression. A bare number is
+     * shorthand for equality. Unknown operator keys throw {@link ValidationError}.
+     */
+    private buildHavingNumericClauses;
     aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
     buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
     /**
@@ -311,6 +337,19 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private collectJsonFilterParams;
     /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
     private collectArrayFilterParams;
+    /**
+     * Collect params for an orderBy clause. Only vector KNN ordering pushes a
+     * param (the `$n::vector` query vector); plain direction ordering is
+     * parameterless. Mirrors buildOrderBy's push order exactly so the cached-SQL
+     * param re-collection stays in lockstep.
+     */
+    private collectOrderByParams;
+    /**
+     * Collect params for a vector distance WHERE filter. Mirrors
+     * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
+     * the comparison threshold(s).
+     */
+    private collectVectorFilterParams;
     /**
      * Produce a fingerprint for a `with` clause tree. Recursion mirrors
      * buildSelectWithRelations / buildRelationSubquery.
@@ -368,9 +407,40 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Each operator key becomes its own clause, all ANDed together.
      */
     private buildOperatorClauses;
-    /** Build ORDER BY clause from an object */
+    /**
+     * Build ORDER BY clause from an object.
+     *
+     * Each value is either a plain direction (`'asc'`/`'desc'`) or — for pgvector
+     * columns — a `{ distance: { to, metric, direction? } }` KNN ordering object.
+     * Vector ordering binds the query vector as a `$n::vector` param, so a `params`
+     * array MUST be supplied when a vector ordering may be present (top-level
+     * findMany path). When `params` is omitted (groupBy / relation path) a vector
+     * ordering throws — KNN ordering is only supported at the top level.
+     */
     private buildOrderBy;
+    /**
+     * Resolve a {@link VectorMetric} to its pgvector distance operator from a
+     * fixed allow-list, validating the target column is actually a `vector`
+     * column. Throws {@link ValidationError} for an unknown metric or a
+     * non-vector column — a user-supplied string can never become a SQL operator.
+     */
+    private vectorOperator;
+    /**
+     * Validate and bind a query vector as a single `$n::vector` parameter.
+     * Every element must be a finite number (no NaN / Infinity / strings) so a
+     * malformed array can never produce a broken `::vector` literal, and the array
+     * is NEVER string-interpolated into the SQL text. Returns the `$n::vector`
+     * placeholder string.
+     */
+    private pushVectorParam;
     /** Parse a flat row: convert snake_case to camelCase + Date coercion */
+    /**
+     * Returns the set of camelCase field names for a table's date columns,
+     * derived once from `meta.dateColumns` (snake_case) via reverseColumnMap and
+     * memoized per table. Used so nested relation rows (camelCase keys) coerce
+     * dates the same way top-level rows do.
+     */
+    private getCamelDateFields;
     private parseRow;
     /** Parse a row that may contain JSON nested relation columns */
     private parseNestedRow;
@@ -509,6 +579,27 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *          evaluates to a JSON array (hasMany) or a JSON object (belongsTo/hasOne).
      */
     private buildRelationSubquery;
+    /**
+     * Build the json_agg subquery for a `manyToMany` relation, JOINing the target
+     * table through a junction (join) table.
+     *
+     * Shape (no LIMIT/ORDER):
+     * ```sql
+     * SELECT COALESCE(json_agg(json_build_object(...)), '[]'::json)
+     * FROM <target> <talias>
+     * JOIN <junction> <jalias> ON <jalias>.<targetKey> = <talias>.<targetPK>
+     * WHERE <jalias>.<sourceKey> = <parentRef>.<referenceKey>
+     * ```
+     *
+     * With LIMIT/ORDER, the rows are wrapped in an inner subquery so the LIMIT
+     * applies BEFORE aggregation (identical strategy to hasMany).
+     *
+     * Cardinality is always 'many' → empty-array fallback, never NULL.
+     *
+     * IMPORTANT: every `params.push` here MUST be mirrored, in the same order, in
+     * {@link collectRelationSubqueryParams} or pipeline batching will desync.
+     */
+    private buildManyToManySubquery;
     /**
      * Get the Postgres type for a column (e.g. 'jsonb', 'text', '_int4').
      * Used to detect JSONB/array columns for specialized operators.
@@ -530,6 +621,18 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Supports: has, hasEvery, hasSome, isEmpty.
      */
     private buildArrayFilterClauses;
+    /**
+     * Build SQL clauses for a pgvector distance WHERE filter:
+     *
+     *   `"embedding" <-> $1::vector < $2`
+     *
+     * The query vector is bound as a `$n::vector` param (never interpolated), the
+     * metric maps to an operator via a fixed allow-list, and each comparison
+     * threshold (`lt`/`lte`/`gt`/`gte`) is its own bound param. Emits one clause
+     * per supplied comparator (all ANDed). Param push order matches
+     * {@link collectVectorFilterParams}.
+     */
+    private buildVectorFilterClauses;
     /**
      * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
      * The config name is validated to prevent injection (only alphanumeric + underscore).