turbine-orm 0.9.2 → 0.10.0

package/dist/index.js

@@ -32,6 +32,7 @@
  * await db.disconnect();
  * ```
  */
+export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
 // Error types
@@ -45,7 +46,7 @@ export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder
 export { QueryInterface, } from './query/index.js';
 // Schema utilities
-export { camelToSnake, isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
+export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 // Schema builder — define schemas in TypeScript
 export { ColumnBuilder, column, defineSchema, 
 // Legacy compat (deprecated — use object format with defineSchema)

package/dist/introspect.js

@@ -66,13 +66,16 @@ const SQL_FOREIGN_KEYS = `
 const SQL_UNIQUE_CONSTRAINTS = `
   SELECT
     tc.table_name,
-    kcu.column_name
+    tc.constraint_name,
+    kcu.column_name,
+    kcu.ordinal_position
   FROM information_schema.table_constraints tc
   JOIN information_schema.key_column_usage kcu
     ON tc.constraint_name = kcu.constraint_name
     AND tc.table_schema = kcu.table_schema
   WHERE tc.constraint_type = 'UNIQUE'
     AND tc.table_schema = $1
+  ORDER BY tc.table_name, tc.constraint_name, kcu.ordinal_position
 `;
 const SQL_INDEXES = `
   SELECT tablename, indexname, indexdef
@@ -153,14 +156,22 @@ export async function introspect(options) {
             pkByTable.get(row.table_name).push(row.column_name);
         }
         // ----- Group unique constraints by table -----
+        // Group rows by (table_name, constraint_name) to correctly handle multi-column unique constraints
         const uniqueByTable = new Map();
+        const uniqueConstraintGroups = new Map();
         for (const row of uniqueResult.rows) {
             if (!tableSet.has(row.table_name))
                 continue;
-            if (!uniqueByTable.has(row.table_name))
-                uniqueByTable.set(row.table_name, []);
-            // Each unique constraint may be multi-column; for simplicity, treat as single-col here
-            uniqueByTable.get(row.table_name).push([row.column_name]);
+            const key = `${row.table_name}::${row.constraint_name}`;
+            if (!uniqueConstraintGroups.has(key)) {
+                uniqueConstraintGroups.set(key, { table: row.table_name, columns: [] });
+            }
+            uniqueConstraintGroups.get(key).columns.push(row.column_name);
+        }
+        for (const { table, columns } of uniqueConstraintGroups.values()) {
+            if (!uniqueByTable.has(table))
+                uniqueByTable.set(table, []);
+            uniqueByTable.get(table).push(columns);
         }
         // ----- Group indexes by table -----
         const indexesByTable = new Map();
@@ -187,17 +198,25 @@ export async function introspect(options) {
                 enums[row.typname] = [];
             enums[row.typname].push(row.enumlabel);
         }
-        const foreignKeys = [];
+        const fkGroups = new Map();
         for (const row of fkResult.rows) {
             if (!tableSet.has(row.source_table) || !tableSet.has(row.target_table))
                 continue;
-            foreignKeys.push({
-                sourceTable: row.source_table,
-                sourceColumn: row.source_column,
-                targetTable: row.target_table,
-                targetColumn: row.target_column,
-            });
+            const key = row.constraint_name;
+            if (!fkGroups.has(key)) {
+                fkGroups.set(key, {
+                    sourceTable: row.source_table,
+                    sourceColumns: [],
+                    targetTable: row.target_table,
+                    targetColumns: [],
+                    constraintName: key,
+                });
+            }
+            const entry = fkGroups.get(key);
+            entry.sourceColumns.push(row.source_column);
+            entry.targetColumns.push(row.target_column);
         }
+        const foreignKeys = Array.from(fkGroups.values());
         // ----- Build relations from foreign keys -----
         // Count FKs per (source, target) pair for disambiguation
         const fkCounts = new Map();
@@ -209,10 +228,17 @@ export async function introspect(options) {
         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
-                ? snakeToCamel(fk.sourceColumn.replace(/_id$/, ''))
+                ? fk.sourceColumns.length === 1
+                    ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
+                    : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
                 : singularize(snakeToCamel(fk.targetTable));
             if (!relationsByTable.has(fk.sourceTable))
                 relationsByTable.set(fk.sourceTable, {});
@@ -221,13 +247,15 @@ export async function introspect(options) {
                 name: belongsToName,
                 from: fk.sourceTable,
                 to: fk.targetTable,
-                foreignKey: fk.sourceColumn,
-                referenceKey: fk.targetColumn,
+                foreignKey,
+                referenceKey,
             };
             // --- hasMany on the target (parent) table ---
             // e.g. posts.user_id → users.id creates users.posts (hasMany)
             const hasManyName = needsDisambiguation
-                ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumn.replace(/_id$/, '')}`)
+                ? 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, {});
@@ -236,8 +264,8 @@ export async function introspect(options) {
                 name: hasManyName,
                 from: fk.targetTable,
                 to: fk.sourceTable,
-                foreignKey: fk.sourceColumn,
-                referenceKey: fk.targetColumn,
+                foreignKey,
+                referenceKey,
             };
         }
         // ----- Assemble TableMetadata for each table -----

package/dist/query/builder.js

@@ -12,7 +12,7 @@
  */
 import { CircularRelationError, NotFoundError, RelationError, TimeoutError, ValidationError, wrapPgError, } from '../errors.js';
 import { camelToSnake, snakeToCamel } from '../schema.js';
-import { escapeLike, escSingleQuote, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
+import { buildCorrelation, escapeLike, escSingleQuote, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 // ---------------------------------------------------------------------------
 // Internal detection helpers — used by QueryInterface
 // ---------------------------------------------------------------------------
@@ -96,6 +96,7 @@ function findArrayUniqueKey(value) {
     }
     return null;
 }
+// biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
 export class QueryInterface {
     pool;
     table;
@@ -258,6 +259,7 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     // findUnique
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
             const deferred = this.buildFindUnique(args);
@@ -265,6 +267,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUnique(args) {
         const columnsList = this.resolveColumns(args.select, args.omit);
         const whereObj = args.where;
@@ -360,6 +363,7 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     // findMany
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findMany(args) {
         this.maybeWarnUnlimited(args);
         // Dev-only: warn on deeply nested with clauses
@@ -417,6 +421,7 @@ export class QueryInterface {
         }
         return maxDepth;
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindMany(args) {
         const columnsList = this.resolveColumns(args?.select, args?.omit);
         const colKey = columnsList ? columnsList.join(',') : '*';
@@ -560,6 +565,7 @@ export class QueryInterface {
      * }
      * ```
      */
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async *findManyStream(args) {
         const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
         const hasRelations = !!args?.with;
@@ -616,6 +622,7 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirst — like findMany but returns a single row or null
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             const deferred = this.buildFindFirst(args);
@@ -623,6 +630,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindFirst(args) {
         // Reuse findMany's SQL builder but force LIMIT 1
         const findManyArgs = { ...args, limit: 1 };
@@ -640,6 +648,7 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirstOrThrow — like findFirst but throws if no record found
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
@@ -647,6 +656,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindFirstOrThrow(args) {
         const inner = this.buildFindFirst(args);
         return {
@@ -669,6 +679,7 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     // findUniqueOrThrow — like findUnique but throws if no record found
     // -------------------------------------------------------------------------
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
@@ -676,6 +687,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     buildFindUniqueOrThrow(args) {
         const inner = this.buildFindUnique(args);
         return {
@@ -2013,15 +2025,15 @@ export class QueryInterface {
         const qt = quoteIdent(targetTable);
         const qSelf = quoteIdent(this.table);
         const clauses = [];
-        // Correlation: link child table to parent table
+        // Correlation: link child table to parent table (supports composite FKs)
         let correlation;
         if (relDef.type === 'hasMany' || relDef.type === 'hasOne') {
             // parent.pk = child.fk
-            correlation = `${qt}.${quoteIdent(relDef.foreignKey)} = ${qSelf}.${quoteIdent(relDef.referenceKey)}`;
+            correlation = buildCorrelation(qt, relDef.foreignKey, qSelf, relDef.referenceKey);
         }
         else {
             // belongsTo: parent.fk = child.pk
-            correlation = `${qt}.${quoteIdent(relDef.referenceKey)} = ${qSelf}.${quoteIdent(relDef.foreignKey)}`;
+            correlation = buildCorrelation(qt, relDef.referenceKey, qSelf, relDef.foreignKey);
         }
         // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
         if (filterObj.some !== undefined) {
@@ -2064,6 +2076,10 @@ export class QueryInterface {
             if (value === undefined)
                 continue;
             const col = meta.columnMap[field] ?? camelToSnake(field);
+            if (!meta.allColumns.includes(col)) {
+                throw new ValidationError(`[turbine] Unknown field "${field}" in relation filter for table "${targetTable}". ` +
+                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
+            }
             const qCol = `${qt}.${quoteIdent(col)}`;
             if (value === null) {
                 conditions.push(`${qCol} IS NULL`);
@@ -2471,12 +2487,13 @@ export class QueryInterface {
         // Build WHERE — correlate to parent via parentRef (alias or table name).
         // For hasMany: target has FK, so alias.fk = parentRef.pk
         // For belongsTo: source has FK, so alias.pk = parentRef.fk (reversed)
+        // Supports composite foreign keys (string[]) via buildCorrelation.
         let whereClause;
         if (relDef.type === 'belongsTo' || relDef.type === 'hasOne') {
-            whereClause = `${alias}.${quoteIdent(relDef.referenceKey)} = ${qParent}.${quoteIdent(relDef.foreignKey)}`;
+            whereClause = buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey);
         }
         else {
-            whereClause = `${alias}.${quoteIdent(relDef.foreignKey)} = ${qParent}.${quoteIdent(relDef.referenceKey)}`;
+            whereClause = buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
         }
         // Additional filters — properly parameterized
         if (spec !== true && spec.where) {

package/dist/query/index.d.ts

@@ -7,7 +7,7 @@
  */
 export type { AggregateArgs, AggregateResult, ArrayFilter, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, JsonFilter, OrderDirection, RelationDescriptor, RelationFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { SqlCacheEntry } from './utils.js';
-export { escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
+export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 export type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './builder.js';
 export { QueryInterface } from './builder.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/query/index.js

@@ -5,6 +5,6 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export { escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
+export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 export { QueryInterface } from './builder.js';
 //# sourceMappingURL=index.js.map

package/dist/query/utils.d.ts

@@ -57,4 +57,12 @@ export declare function fnv1a64Hex(s: string): string;
 export declare function sqlToPreparedName(sql: string): string;
 /** Known operator keys — used to detect operator objects vs plain values */
 export declare const OPERATOR_KEYS: Set<string>;
+/**
+ * Build a correlation clause joining columns between two table references.
+ * Handles both single-column (string) and multi-column (string[]) foreign keys.
+ *
+ * For single-column: `"alias"."col" = "parent"."col"`
+ * For multi-column:  `"alias"."col_a" = "parent"."ref_a" AND "alias"."col_b" = "parent"."ref_b"`
+ */
+export declare function buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/query/utils.js

@@ -111,4 +111,21 @@ export const OPERATOR_KEYS = new Set([
     'endsWith',
     'mode',
 ]);
+// ---------------------------------------------------------------------------
+// Composite key correlation helper
+// ---------------------------------------------------------------------------
+/**
+ * Build a correlation clause joining columns between two table references.
+ * Handles both single-column (string) and multi-column (string[]) foreign keys.
+ *
+ * For single-column: `"alias"."col" = "parent"."col"`
+ * For multi-column:  `"alias"."col_a" = "parent"."ref_a" AND "alias"."col_b" = "parent"."ref_b"`
+ */
+export function buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
+    const leftCols = Array.isArray(leftColumns) ? leftColumns : [leftColumns];
+    const rightCols = Array.isArray(rightColumns) ? rightColumns : [rightColumns];
+    return leftCols
+        .map((col, i) => `${leftRef}.${quoteIdent(col)} = ${rightRef}.${quoteIdent(rightCols[i])}`)
+        .join(' AND ');
+}
 //# sourceMappingURL=utils.js.map

package/dist/schema.d.ts

@@ -62,11 +62,13 @@ export interface RelationDef {
     from: string;
     /** Target table */
     to: string;
-    /** FK column on the "many" / "child" side (snake_case) */
-    foreignKey: string;
-    /** Referenced column on the "one" / "parent" side (snake_case) */
-    referenceKey: string;
+    /** FK column(s) on the "many" / "child" side (snake_case). Array for composite FKs. */
+    foreignKey: string | string[];
+    /** Referenced column(s) on the "one" / "parent" side (snake_case). Array for composite FKs. */
+    referenceKey: string | string[];
 }
+/** Normalize foreignKey/referenceKey to always be an array for uniform processing */
+export declare function normalizeKeyColumns(key: string | string[]): string[];
 export interface IndexMetadata {
     name: string;
     columns: string[];

package/dist/schema.js

@@ -5,6 +5,13 @@
  * They're used by the query builder, code generator, and CLI.
  */
 // ---------------------------------------------------------------------------
+// Helpers for composite key handling
+// ---------------------------------------------------------------------------
+/** Normalize foreignKey/referenceKey to always be an array for uniform processing */
+export function normalizeKeyColumns(key) {
+    return Array.isArray(key) ? key : [key];
+}
+// ---------------------------------------------------------------------------
 // Type mapping: Postgres → TypeScript
 // ---------------------------------------------------------------------------
 const PG_TO_TS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. 1 dependency, ~110KB",
   "type": "module",
   "exports": {
@@ -18,6 +18,11 @@
       "import": "./dist/cli/config.js",
       "require": "./dist/cjs/cli/config.js",
       "types": "./dist/cli/config.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/adapters/index.js",
+      "require": "./dist/cjs/adapters/index.js",
+      "types": "./dist/adapters/index.d.ts"
     }
   },
   "main": "./dist/cjs/index.js",
@@ -44,7 +49,7 @@
     "status": "tsx src/cli/index.ts status",
     "examples": "tsx examples/examples.ts",
     "test": "tsx --test src/test/*.test.ts",
-    "test:unit": "tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts",
+    "test:unit": "tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts src/test/cockroachdb-adapter.test.ts src/test/yugabytedb-adapter.test.ts src/test/pg-compat.test.ts src/test/relation-filter-validation.test.ts src/test/client-coverage.test.ts src/test/schema-diff.test.ts src/test/composite-fk.test.ts",
     "test:coverage": "c8 tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",