turbine-orm 0.7.0 → 0.8.0

package/dist/schema-builder.d.ts

@@ -56,17 +56,50 @@ export interface ColumnConfig {
     maxLength: number | null;
 }
 export interface TableDef {
-    /** Table name (set during defineSchema) */
+    /**
+     * DDL-facing table name (snake_case). This is the name used when generating
+     * `CREATE TABLE` and other DDL statements. Set automatically during
+     * `defineSchema()` by converting the JS-facing accessor key from camelCase
+     * to snake_case (e.g. `postTags` → `post_tags`).
+     */
     name: string;
+    /**
+     * JS-facing accessor name (camelCase). This is the original key the user
+     * supplied to `defineSchema({ ... })` and is used as the property name on
+     * the generated `TurbineClient` (e.g. `db.postTags`). For schemas that
+     * already use snake_case keys, this matches `name`.
+     */
+    accessor: string;
     /** Column definitions keyed by camelCase field name */
     columns: Record<string, ColumnConfig>;
+    /**
+     * Optional composite primary key. When present, takes precedence over any
+     * column-level `primaryKey: true` flags. Column names listed here are the
+     * camelCase JS-facing field names — they will be converted to snake_case
+     * when emitted as a `PRIMARY KEY (...)` table constraint.
+     */
+    primaryKey?: readonly string[];
+}
+/**
+ * User-facing input shape for a single table when using the object format.
+ * The optional `primaryKey` field declares a composite primary key.
+ */
+export interface TableInput {
+    /** Optional composite primary key (camelCase field names) */
+    primaryKey?: readonly string[];
+    /** Column definitions keyed by camelCase field name */
+    [columnName: string]: ColumnDef | readonly string[] | undefined;
 }
 export interface SchemaDef {
-    /** All tables keyed by table name */
+    /**
+     * All tables keyed by their JS-facing accessor name (camelCase, exactly as
+     * the user wrote them in `defineSchema({ ... })`). The DDL-facing snake_case
+     * name is available as `tables[key].name`.
+     */
     tables: Record<string, TableDef>;
 }
 /** Input format: table name -> column defs (object format) or TableDef (legacy builder) */
-type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef>;
+type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableInput>;
 /**
  * Define the full database schema using plain objects.
  *

package/dist/schema-builder.js

@@ -81,23 +81,74 @@ function isTableDef(v) {
  */
 export function defineSchema(input) {
     const tables = {};
-    for (const [tableName, value] of Object.entries(input)) {
+    for (const [accessor, value] of Object.entries(input)) {
+        // The user-facing key is the camelCase JS accessor; the DDL-facing
+        // table name is its snake_case form (e.g. `postTags` → `post_tags`).
+        const dbName = camelToSnakeLocal(accessor);
         if (isTableDef(value)) {
             // Legacy format: defineSchema({ users: table({ ... }) })
-            value.name = tableName;
-            tables[tableName] = value;
+            // Stamp both the DDL name and the JS accessor.
+            value.name = dbName;
+            value.accessor = accessor;
+            tables[accessor] = value;
         }
         else {
             // Object format: defineSchema({ users: { id: { type: 'serial' }, ... } })
+            const raw = value;
             const columns = {};
-            for (const [fieldName, def] of Object.entries(value)) {
+            let pk;
+            for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'primaryKey') {
+                    // Top-level composite primary key declaration
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": top-level "primaryKey" must be an array of column names (string[])`);
+                        }
+                        pk = def;
+                    }
+                    continue;
+                }
+                // Anything else is a ColumnDef
                 columns[fieldName] = resolveColumn(def);
             }
-            tables[tableName] = { name: tableName, columns };
+            // Validate composite PK references real columns and clear column-level PKs
+            // for those columns so we don't double-emit `PRIMARY KEY` clauses.
+            // Composite PK members are implicitly NOT NULL — preserve that even
+            // when the user clears the column-level `primaryKey: true` flag.
+            if (pk && pk.length > 0) {
+                for (const colName of pk) {
+                    if (!(colName in columns)) {
+                        throw new Error(`Table "${accessor}": composite primaryKey references unknown column "${colName}". ` +
+                            `Known columns: ${Object.keys(columns).join(', ') || '(none)'}`);
+                    }
+                    // A composite PK at the table level supersedes any column-level
+                    // `primaryKey: true` flag — silently clear it so DDL emission
+                    // produces a single, valid table-level PRIMARY KEY constraint.
+                    // Force NOT NULL since PK columns can never be nullable.
+                    const c = columns[colName];
+                    if (c) {
+                        c.isPrimaryKey = false;
+                        c.isNotNull = true;
+                    }
+                }
+            }
+            tables[accessor] = {
+                name: dbName,
+                accessor,
+                columns,
+                ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
+            };
         }
     }
     return { tables };
 }
+/**
+ * Local copy of camelToSnake to avoid a circular import dependency at the
+ * top of the file. Mirrors the implementation in `./schema.ts`.
+ */
+function camelToSnakeLocal(s) {
+    return s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
 // ---------------------------------------------------------------------------
 // Legacy compat — ColumnBuilder still works for existing code
 // ---------------------------------------------------------------------------
@@ -223,7 +274,7 @@ export function table(columns) {
     for (const [fieldName, builder] of Object.entries(columns)) {
         built[fieldName] = builder.build();
     }
-    return { name: '', columns: built };
+    return { name: '', accessor: '', columns: built };
 }
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/schema-sql.js

@@ -20,10 +20,11 @@ export function schemaToSQL(schema) {
     const statements = [];
     // Topologically sort tables by their foreign key references
     const sorted = topologicalSort(schema);
+    const resolveRef = makeRefResolver(schema);
     // Generate CREATE TABLE statements
     for (const tableName of sorted) {
         const table = schema.tables[tableName];
-        statements.push(generateCreateTable(table));
+        statements.push(generateCreateTable(table, resolveRef));
     }
     // Generate CREATE INDEX for foreign key columns
     for (const tableName of sorted) {
@@ -33,12 +34,51 @@ export function schemaToSQL(schema) {
     }
     return statements;
 }
+/**
+ * Build a function that resolves a raw `references: 'foo.id'` target name
+ * to the snake_case DDL table name. Accepts both the JS-facing camelCase
+ * accessor name and the snake_case DDL name; passes through unknown names
+ * unchanged so existing call sites continue to work.
+ */
+function makeRefResolver(schema) {
+    const lookup = buildTableLookup(schema);
+    return (rawName) => {
+        const key = lookup[rawName];
+        if (key) {
+            const def = schema.tables[key];
+            if (def?.name)
+                return def.name;
+        }
+        return rawName;
+    };
+}
+/**
+ * Build a lookup index from both DDL names (snake_case) and JS accessor
+ * names (camelCase) to table keys, so `references: 'post_tags.id'` and
+ * `references: 'postTags.id'` both resolve to the same TableDef.
+ */
+function buildTableLookup(schema) {
+    const lookup = {};
+    for (const [key, def] of Object.entries(schema.tables)) {
+        lookup[key] = key;
+        if (def.name && def.name !== key)
+            lookup[def.name] = key;
+        if (def.accessor && def.accessor !== key)
+            lookup[def.accessor] = key;
+    }
+    return lookup;
+}
 /**
  * Topologically sort tables so that referenced tables come before referencing ones.
+ * Returns the table keys (the same keys used in `schema.tables`). The keys are
+ * the JS-facing accessor names; consumers should still call `table.name` to get
+ * the snake_case DDL name when emitting SQL.
+ *
  * Falls back to input order for tables with no dependency ordering.
  */
 function topologicalSort(schema) {
     const tableNames = Object.keys(schema.tables);
+    const lookup = buildTableLookup(schema);
     const resolved = new Set();
     const result = [];
     const visiting = new Set();
@@ -55,9 +95,10 @@ function topologicalSort(schema) {
             // Visit all tables this table references
             for (const col of Object.values(table.columns)) {
                 if (col.referencesTarget) {
-                    const refTable = col.referencesTarget.split('.')[0];
-                    if (refTable !== name && schema.tables[refTable]) {
-                        visit(refTable);
+                    const refRaw = col.referencesTarget.split('.')[0];
+                    const refKey = lookup[refRaw];
+                    if (refKey && refKey !== name) {
+                        visit(refKey);
                     }
                 }
             }
@@ -73,12 +114,28 @@ function topologicalSort(schema) {
 }
 /**
  * Generate a CREATE TABLE statement for a single table definition.
+ *
+ * If `table.primaryKey` is set (composite primary key), emits a table-level
+ * `PRIMARY KEY ("col1", "col2", ...)` constraint instead of column-level
+ * `PRIMARY KEY` clauses on each member column. The composite PK column
+ * names are camelCase JS field names; they are converted to snake_case
+ * here.
+ *
+ * `resolveRef` (when supplied) maps raw `references: 'foo.id'` table names
+ * to their snake_case DDL form, so users can write either camelCase JS
+ * accessor names or snake_case DDL names.
  */
-function generateCreateTable(table) {
+function generateCreateTable(table, resolveRef) {
     const tableName = table.name;
     const columnDefs = [];
+    const compositePk = table.primaryKey && table.primaryKey.length > 0 ? table.primaryKey : null;
     for (const [fieldName, config] of Object.entries(table.columns)) {
-        columnDefs.push(generateColumnDef(fieldName, config));
+        columnDefs.push(generateColumnDef(fieldName, config, resolveRef));
+    }
+    // Append a table-level PRIMARY KEY constraint when a composite PK is set.
+    if (compositePk) {
+        const cols = compositePk.map((c) => quoteIdent(camelToSnake(c))).join(', ');
+        columnDefs.push(`PRIMARY KEY (${cols})`);
     }
     const body = columnDefs.map((d) => `    ${d}`).join(',\n');
     return `CREATE TABLE ${quoteIdent(tableName)} (\n${body}\n);`;
@@ -86,7 +143,7 @@ function generateCreateTable(table) {
 /**
  * Generate a single column definition line (e.g. "id BIGSERIAL PRIMARY KEY").
  */
-function generateColumnDef(fieldName, config) {
+function generateColumnDef(fieldName, config, resolveRef) {
     const snakeName = camelToSnake(fieldName);
     const parts = [quoteIdent(snakeName)];
     // Type
@@ -120,11 +177,14 @@ function generateColumnDef(fieldName, config) {
         const sqlDefault = normalizeDefault(config.defaultValue);
         parts.push(`DEFAULT ${sqlDefault}`);
     }
-    // REFERENCES
+    // REFERENCES — resolve the raw table name through the optional resolver so
+    // both camelCase accessor names and snake_case DDL names work.
     if (config.referencesTarget) {
         const refParts = config.referencesTarget.split('.');
         if (refParts.length === 2) {
-            parts.push(`REFERENCES ${quoteIdent(refParts[0])}(${quoteIdent(refParts[1])})`);
+            const rawTable = refParts[0];
+            const refTable = resolveRef ? resolveRef(rawTable) : rawTable;
+            parts.push(`REFERENCES ${quoteIdent(refTable)}(${quoteIdent(refParts[1])})`);
         }
     }
     return parts.join(' ');
@@ -231,33 +291,39 @@ export async function schemaDiff(schema, connectionString) {
                 dbUniques[row.table_name] = {};
             dbUniques[row.table_name][row.column_name] = row.constraint_name;
         }
-        const schemaTableNames = new Set(Object.keys(schema.tables));
+        // Build a set of DDL-facing snake_case table names that the schema defines.
+        const schemaDdlNames = new Set();
+        for (const def of Object.values(schema.tables))
+            schemaDdlNames.add(def.name);
         const result = { create: [], alter: [], drop: [], statements: [], reverseStatements: [] };
+        const resolveRef = makeRefResolver(schema);
         // Tables to create (in schema but not in DB)
         const sorted = topologicalSort(schema);
-        for (const tableName of sorted) {
-            if (!existingTables.has(tableName)) {
-                const tableDef = schema.tables[tableName];
+        for (const tableKey of sorted) {
+            const tableDef = schema.tables[tableKey];
+            const ddlName = tableDef.name;
+            if (!existingTables.has(ddlName)) {
                 result.create.push(tableDef);
-                result.statements.push(generateCreateTable(tableDef));
+                result.statements.push(generateCreateTable(tableDef, resolveRef));
                 const fkIndexes = generateForeignKeyIndexes(tableDef);
                 result.statements.push(...fkIndexes);
                 // Reverse: DROP TABLE (with indexes — they drop automatically)
-                result.reverseStatements.unshift(`DROP TABLE IF EXISTS ${quoteIdent(tableName)} CASCADE;`);
+                result.reverseStatements.unshift(`DROP TABLE IF EXISTS ${quoteIdent(ddlName)} CASCADE;`);
             }
         }
         // Tables to drop (in DB but not in schema)
         for (const existingTable of existingTables) {
-            if (!schemaTableNames.has(existingTable)) {
+            if (!schemaDdlNames.has(existingTable)) {
                 result.drop.push(existingTable);
                 // We don't auto-generate DROP statements for safety
             }
         }
         // Tables to alter (exist in both)
-        for (const tableName of sorted) {
+        for (const tableKey of sorted) {
+            const tableDef = schema.tables[tableKey];
+            const tableName = tableDef.name;
             if (!existingTables.has(tableName))
                 continue;
-            const tableDef = schema.tables[tableName];
             const dbCols = dbColumns[tableName] ?? {};
             const tableUniques = dbUniques[tableName] ?? {};
             const alterDef = { table: tableName, columns: [] };
@@ -266,7 +332,7 @@ export async function schemaDiff(schema, connectionString) {
                 const dbCol = dbCols[snakeName];
                 if (!dbCol) {
                     // Column exists in schema but not in DB — ADD COLUMN
-                    const colDef = generateColumnDef(fieldName, config);
+                    const colDef = generateColumnDef(fieldName, config, resolveRef);
                     const sql = `ALTER TABLE ${quoteIdent(tableName)} ADD COLUMN ${colDef};`;
                     const reverseSql = `ALTER TABLE ${quoteIdent(tableName)} DROP COLUMN ${quoteIdent(snakeName)};`;
                     alterDef.columns.push({ column: snakeName, action: 'add', sql, reverseSql });

package/dist/serverless.d.ts

@@ -35,12 +35,12 @@
  * // app/api/users/route.ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
- * import { schema } from '@/generated/turbine/metadata';
+ * import { SCHEMA } from '../../generated/turbine/metadata';
  *
  * export const runtime = 'edge';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
- * const db = turbineHttp(pool, schema);
+ * const db = turbineHttp(pool, SCHEMA);
  *
  * export async function GET() {
  *   const users = await db.table('users').findMany({ limit: 10 });
@@ -52,12 +52,12 @@
  *
  * ```ts
  * import { TurbineClient } from 'turbine-orm';
- * import { schema } from './generated/turbine/metadata.js';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
  *
  * const db = new TurbineClient({
  *   connectionString: process.env.SUPABASE_DB_URL,
  *   ssl: { rejectUnauthorized: false },
- * }, schema);
+ * }, SCHEMA);
  * ```
  *
  * ## Example — Cloudflare Workers
@@ -66,11 +66,12 @@
  * // Use the Neon HTTP driver which works in Workers runtime
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { SCHEMA } from './generated/turbine/metadata';
  *
  * export default {
  *   async fetch(req: Request, env: Env) {
  *     const pool = new Pool({ connectionString: env.DATABASE_URL });
- *     const db = turbineHttp(pool, schema);
+ *     const db = turbineHttp(pool, SCHEMA);
  *     const users = await db.table('users').findMany({ limit: 10 });
  *     return Response.json(users);
  *   }
@@ -102,10 +103,10 @@ export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'def
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
- * import { schema } from './generated/turbine/metadata.js';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
- * const db = turbineHttp(pool, schema);
+ * const db = turbineHttp(pool, SCHEMA);
  *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```

package/dist/serverless.js

@@ -35,12 +35,12 @@
  * // app/api/users/route.ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
- * import { schema } from '@/generated/turbine/metadata';
+ * import { SCHEMA } from '../../generated/turbine/metadata';
  *
  * export const runtime = 'edge';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
- * const db = turbineHttp(pool, schema);
+ * const db = turbineHttp(pool, SCHEMA);
  *
  * export async function GET() {
  *   const users = await db.table('users').findMany({ limit: 10 });
@@ -52,12 +52,12 @@
  *
  * ```ts
  * import { TurbineClient } from 'turbine-orm';
- * import { schema } from './generated/turbine/metadata.js';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
  *
  * const db = new TurbineClient({
  *   connectionString: process.env.SUPABASE_DB_URL,
  *   ssl: { rejectUnauthorized: false },
- * }, schema);
+ * }, SCHEMA);
  * ```
  *
  * ## Example — Cloudflare Workers
@@ -66,11 +66,12 @@
  * // Use the Neon HTTP driver which works in Workers runtime
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { SCHEMA } from './generated/turbine/metadata';
  *
  * export default {
  *   async fetch(req: Request, env: Env) {
  *     const pool = new Pool({ connectionString: env.DATABASE_URL });
- *     const db = turbineHttp(pool, schema);
+ *     const db = turbineHttp(pool, SCHEMA);
  *     const users = await db.table('users').findMany({ limit: 10 });
  *     return Response.json(users);
  *   }
@@ -94,10 +95,10 @@ import { TurbineClient } from './client.js';
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
- * import { schema } from './generated/turbine/metadata.js';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
- * const db = turbineHttp(pool, schema);
+ * const db = turbineHttp(pool, SCHEMA);
  *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.7.0",
+  "version": "0.8.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": {
@@ -43,8 +43,8 @@
     "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",
-    "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",
+    "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",
+    "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",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",