turbine-orm 0.5.0 → 0.7.1

package/dist/schema-builder.d.ts

@@ -1,5 +1,5 @@
 /**
- * @batadata/turbine — Schema Builder
+ * turbine-orm — Schema Builder
  *
  * TypeScript-first schema definition API. Define your database schema
  * as plain objects — no method chaining, no DSL. Fully type-checked,
@@ -7,7 +7,7 @@
  *
  * @example
  * ```ts
- * import { defineSchema } from '@batadata/turbine';
+ * import { defineSchema } from 'turbine-orm';
  *
  * export default defineSchema({
  *   users: {
@@ -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

@@ -1,5 +1,5 @@
 /**
- * @batadata/turbine — Schema Builder
+ * turbine-orm — Schema Builder
  *
  * TypeScript-first schema definition API. Define your database schema
  * as plain objects — no method chaining, no DSL. Fully type-checked,
@@ -7,7 +7,7 @@
  *
  * @example
  * ```ts
- * import { defineSchema } from '@batadata/turbine';
+ * import { defineSchema } from 'turbine-orm';
  *
  * export default defineSchema({
  *   users: {
@@ -22,7 +22,6 @@
  * });
  * ```
  */
-import { camelToSnake } from './schema.js';
 /** Maps shorthand names to actual Postgres type strings */
 const TYPE_MAP = {
     serial: 'BIGSERIAL',
@@ -43,6 +42,9 @@ const TYPE_MAP = {
 };
 /** Convert a user-facing ColumnDef to the internal ColumnConfig */
 function resolveColumn(def) {
+    if (!(def.type in TYPE_MAP)) {
+        throw new Error(`Invalid column type "${def.type}". Valid types: ${Object.keys(TYPE_MAP).join(', ')}`);
+    }
     return {
         type: TYPE_MAP[def.type],
         isPrimaryKey: def.primaryKey ?? false,
@@ -79,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
 // ---------------------------------------------------------------------------
@@ -113,28 +166,94 @@ export class ColumnBuilder {
             maxLength: null,
         };
     }
-    serial() { this._config.type = 'BIGSERIAL'; return this; }
-    bigint() { this._config.type = 'BIGINT'; return this; }
-    integer() { this._config.type = 'INTEGER'; return this; }
-    smallint() { this._config.type = 'SMALLINT'; return this; }
-    text() { this._config.type = 'TEXT'; return this; }
-    varchar(length) { this._config.type = 'VARCHAR'; this._config.maxLength = length; return this; }
-    boolean() { this._config.type = 'BOOLEAN'; return this; }
-    timestamp() { this._config.type = 'TIMESTAMPTZ'; return this; }
-    date() { this._config.type = 'DATE'; return this; }
-    json() { this._config.type = 'JSONB'; return this; }
-    uuid() { this._config.type = 'UUID'; return this; }
-    real() { this._config.type = 'REAL'; return this; }
-    doublePrecision() { this._config.type = 'DOUBLE PRECISION'; return this; }
-    numeric() { this._config.type = 'NUMERIC'; return this; }
-    bytea() { this._config.type = 'BYTEA'; return this; }
-    primaryKey() { this._config.isPrimaryKey = true; return this; }
-    notNull() { this._config.isNotNull = true; return this; }
-    nullable() { this._config.isNullable = true; return this; }
-    unique() { this._config.isUnique = true; return this; }
-    default(val) { this._config.defaultValue = val; return this; }
-    references(target) { this._config.referencesTarget = target; return this; }
-    build() { return { ...this._config }; }
+    serial() {
+        this._config.type = 'BIGSERIAL';
+        return this;
+    }
+    bigint() {
+        this._config.type = 'BIGINT';
+        return this;
+    }
+    integer() {
+        this._config.type = 'INTEGER';
+        return this;
+    }
+    smallint() {
+        this._config.type = 'SMALLINT';
+        return this;
+    }
+    text() {
+        this._config.type = 'TEXT';
+        return this;
+    }
+    varchar(length) {
+        this._config.type = 'VARCHAR';
+        this._config.maxLength = length;
+        return this;
+    }
+    boolean() {
+        this._config.type = 'BOOLEAN';
+        return this;
+    }
+    timestamp() {
+        this._config.type = 'TIMESTAMPTZ';
+        return this;
+    }
+    date() {
+        this._config.type = 'DATE';
+        return this;
+    }
+    json() {
+        this._config.type = 'JSONB';
+        return this;
+    }
+    uuid() {
+        this._config.type = 'UUID';
+        return this;
+    }
+    real() {
+        this._config.type = 'REAL';
+        return this;
+    }
+    doublePrecision() {
+        this._config.type = 'DOUBLE PRECISION';
+        return this;
+    }
+    numeric() {
+        this._config.type = 'NUMERIC';
+        return this;
+    }
+    bytea() {
+        this._config.type = 'BYTEA';
+        return this;
+    }
+    primaryKey() {
+        this._config.isPrimaryKey = true;
+        return this;
+    }
+    notNull() {
+        this._config.isNotNull = true;
+        return this;
+    }
+    nullable() {
+        this._config.isNullable = true;
+        return this;
+    }
+    unique() {
+        this._config.isUnique = true;
+        return this;
+    }
+    default(val) {
+        this._config.defaultValue = val;
+        return this;
+    }
+    references(target) {
+        this._config.referencesTarget = target;
+        return this;
+    }
+    build() {
+        return { ...this._config };
+    }
 }
 /** @deprecated Use defineSchema() with plain objects instead */
 export const column = new Proxy({}, {
@@ -155,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.d.ts

@@ -1,5 +1,5 @@
 /**
- * @batadata/turbine — Schema SQL Generator
+ * turbine-orm — Schema SQL Generator
  *
  * Converts a SchemaDef (from defineSchema) into executable DDL statements.
  * Also provides diff and push commands for syncing schema to a live database.
@@ -16,9 +16,11 @@ export interface AlterColumnDef {
     /** Column name in snake_case */
     column: string;
     /** What changed */
-    action: 'add' | 'drop' | 'alter_type' | 'set_not_null' | 'drop_not_null' | 'set_default' | 'drop_default';
+    action: 'add' | 'drop' | 'alter_type' | 'set_not_null' | 'drop_not_null' | 'set_default' | 'drop_default' | 'add_unique' | 'drop_unique';
     /** SQL fragment for the alteration */
     sql: string;
+    /** SQL to reverse this change (for DOWN migrations) */
+    reverseSql: string;
 }
 export interface AlterDef {
     /** Table name */
@@ -33,8 +35,10 @@ export interface DiffResult {
     alter: AlterDef[];
     /** Table names that exist in DB but not in schema — would need DROP TABLE */
     drop: string[];
-    /** SQL statements to execute the diff */
+    /** SQL statements to execute the diff (UP direction) */
     statements: string[];
+    /** SQL statements to reverse the diff (DOWN direction, for migrations) */
+    reverseStatements: string[];
 }
 /**
  * Compare a SchemaDef against a live Postgres database and return the diff.