turbine-orm 0.7.0 → 0.8.0

package/dist/cjs/schema-builder.js

@@ -86,23 +86,74 @@ function isTableDef(v) {
  */
 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
 // ---------------------------------------------------------------------------
@@ -229,7 +280,7 @@ 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/cjs/schema-sql.js

@@ -29,10 +29,11 @@ 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) {
@@ -42,12 +43,51 @@ 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();
@@ -64,9 +104,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);
                     }
                 }
             }
@@ -82,12 +123,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) => (0, query_js_1.quoteIdent)((0, schema_js_1.camelToSnake)(c))).join(', ');
+        columnDefs.push(`PRIMARY KEY (${cols})`);
     }
     const body = columnDefs.map((d) => `    ${d}`).join(',\n');
     return `CREATE TABLE ${(0, query_js_1.quoteIdent)(tableName)} (\n${body}\n);`;
@@ -95,7 +152,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 = (0, schema_js_1.camelToSnake)(fieldName);
     const parts = [(0, query_js_1.quoteIdent)(snakeName)];
     // Type
@@ -129,11 +186,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 ${(0, query_js_1.quoteIdent)(refParts[0])}(${(0, query_js_1.quoteIdent)(refParts[1])})`);
+            const rawTable = refParts[0];
+            const refTable = resolveRef ? resolveRef(rawTable) : rawTable;
+            parts.push(`REFERENCES ${(0, query_js_1.quoteIdent)(refTable)}(${(0, query_js_1.quoteIdent)(refParts[1])})`);
         }
     }
     return parts.join(' ');
@@ -240,33 +300,39 @@ 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 ${(0, query_js_1.quoteIdent)(tableName)} CASCADE;`);
+                result.reverseStatements.unshift(`DROP TABLE IF EXISTS ${(0, query_js_1.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: [] };
@@ -275,7 +341,7 @@ 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 ${(0, query_js_1.quoteIdent)(tableName)} ADD COLUMN ${colDef};`;
                     const reverseSql = `ALTER TABLE ${(0, query_js_1.quoteIdent)(tableName)} DROP COLUMN ${(0, query_js_1.quoteIdent)(snakeName)};`;
                     alterDef.columns.push({ column: snakeName, action: 'add', sql, reverseSql });

package/dist/cjs/serverless.js

@@ -36,12 +36,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 });
@@ -53,12 +53,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
@@ -67,11 +67,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);
  *   }
@@ -97,10 +98,10 @@ const client_js_1 = require("./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/dist/cli/index.js

@@ -26,6 +26,7 @@ import { generate } from '../generate.js';
 import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfig, resolveConfig } from './config.js';
+import { needsTsLoader, registerTsLoader } from './loader.js';
 import { createMigration, listMigrationFiles, migrateDown, migrateStatus, migrateUp } from './migrate.js';
 import { banner, blue, bold, box, cyan, dim, divider, elapsed, error, table as formatTable, gray, green, header, info, label, magenta, newline, red, redactUrl, Spinner, success, symbols, warn, yellow, } from './ui.js';
 function parseArgs() {
@@ -78,6 +79,9 @@ function parseArgs() {
             case '--auto':
                 result.auto = true;
                 break;
+            case '--allow-drift':
+                result.allowDrift = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -100,6 +104,36 @@ function parseArgs() {
     return result;
 }
 // ---------------------------------------------------------------------------
+// TypeScript loader — user-facing error helper
+// ---------------------------------------------------------------------------
+/**
+ * Print a friendly error explaining how to install tsx, then exit.
+ * Called when we know we need to load a `.ts` file but the loader isn't available.
+ */
+function failMissingTsLoader(filePath, reason) {
+    newline();
+    error(`Cannot load TypeScript file: ${filePath}`);
+    newline();
+    if (reason === 'unsupported') {
+        console.log(`  ${dim('Your Node.js version does not support')} ${cyan('module.register()')}.`);
+        console.log(`  ${dim('Upgrade to Node.js')} ${cyan('20.6+')} ${dim('or use a')} ${cyan('.js')} ${dim('/')} ${cyan('.mjs')} ${dim('config file.')}`);
+    }
+    else {
+        console.log(`  ${dim('Loading .ts config / schema files requires')} ${cyan('tsx')} ${dim('to be installed.')}`);
+        newline();
+        console.log(`  ${dim('Install it as a dev dependency:')}`);
+        console.log(`    ${cyan('npm install --save-dev tsx')}`);
+        console.log(`    ${dim('or')}`);
+        console.log(`    ${cyan('pnpm add -D tsx')}`);
+        console.log(`    ${dim('or')}`);
+        console.log(`    ${cyan('yarn add -D tsx')}`);
+        newline();
+        console.log(`  ${dim('Alternatively, rename your file to')} ${cyan('.js')} ${dim('or')} ${cyan('.mjs')}.`);
+    }
+    newline();
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function requireUrl(config) {
@@ -122,6 +156,15 @@ async function loadSchemaFile(schemaFile) {
         console.log(`  ${dim('Create one with:')} ${cyan('turbine init')}`);
         process.exit(1);
     }
+    // If this is a TypeScript file, ensure the tsx ESM loader is registered
+    // before we attempt the dynamic import. Without this, Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    if (needsTsLoader(absPath)) {
+        const status = await registerTsLoader();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(schemaFile, status);
+        }
+    }
     try {
         const fileUrl = pathToFileURL(absPath).href;
         const mod = await import(fileUrl);
@@ -136,6 +179,11 @@ async function loadSchemaFile(schemaFile) {
         error(`Failed to load schema file: ${schemaFile}`);
         if (err instanceof Error) {
             console.log(`  ${dim(err.message)}`);
+            // If the error is the classic ERR_UNKNOWN_FILE_EXTENSION, give a hint.
+            if (err.message.includes('ERR_UNKNOWN_FILE_EXTENSION') || err.message.includes('Unknown file extension')) {
+                newline();
+                console.log(`  ${dim('Hint: install')} ${cyan('tsx')} ${dim('to load .ts files:')} ${cyan('npm install --save-dev tsx')}`);
+            }
         }
         process.exit(1);
     }
@@ -486,9 +534,10 @@ async function cmdMigrate(args, config) {
         console.log(`    ${cyan('status')}                Show migration status`);
         newline();
         console.log(`  ${bold('Options:')}`);
-        console.log(`    ${cyan('--auto')}         Auto-generate UP/DOWN SQL from schema diff`);
-        console.log(`    ${cyan('--step, -n')}     Number of migrations to apply/rollback`);
-        console.log(`    ${cyan('--dry-run')}      Show SQL without executing`);
+        console.log(`    ${cyan('--auto')}           Auto-generate UP/DOWN SQL from schema diff`);
+        console.log(`    ${cyan('--step, -n')}       Number of migrations to apply/rollback`);
+        console.log(`    ${cyan('--dry-run')}        Show SQL without executing`);
+        console.log(`    ${cyan('--allow-drift')}    Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
         newline();
         console.log(`  ${bold('Examples:')}`);
         console.log(`    ${dim('npx turbine migrate create add_users_table')}`);
@@ -604,9 +653,18 @@ async function cmdMigrateUp(args, config) {
         newline();
         return;
     }
+    // Big, loud warning when bypassing drift detection — this is a deliberately
+    // dangerous operation and the user should see it on every invocation.
+    if (args.allowDrift) {
+        warn('--allow-drift is set — checksum validation is DISABLED for this run.');
+        console.log(`  ${dim('Applied migrations may have been modified or deleted on disk.')}`);
+        console.log(`  ${dim('Proceed only if you are intentionally rewriting migration history.')}`);
+        newline();
+    }
     const spinner = new Spinner('Applying migrations').start();
     const result = await migrateUp(url, config.migrationsDir, {
         step: args.step,
+        allowDrift: args.allowDrift,
     });
     if (result.applied.length === 0 && result.errors.length === 0) {
         spinner.succeed('All migrations are up to date');
@@ -935,6 +993,7 @@ function showMigrateHelp() {
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
     console.log(`    ${cyan('--step, -n')} ${dim('<N>')}    Number of migrations to apply/rollback`);
     console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
     console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
     newline();
     console.log(`  ${bold('Examples:')}`);
@@ -1043,6 +1102,16 @@ async function main() {
         showVersion();
         return;
     }
+    // If the user has a TypeScript config file, register the tsx ESM loader
+    // before we attempt to import it. Otherwise Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    const configPath = findConfigFile();
+    if (needsTsLoader(configPath)) {
+        const status = await registerTsLoader();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
+        }
+    }
     // Load config file
     let fileConfig = {};
     try {

package/dist/cli/loader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * turbine-orm CLI — TypeScript loader registration
+ *
+ * The CLI loads user-supplied config and schema files via dynamic `import()`.
+ * Plain Node has no built-in `.ts` loader, so importing `turbine.config.ts`
+ * blows up with `ERR_UNKNOWN_FILE_EXTENSION` unless we register a TypeScript
+ * loader first.
+ *
+ * Strategy:
+ *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
+ *      probe whether `tsx/esm` is resolvable from the user's CWD.
+ *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
+ *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *
+ * `tsx` is intentionally NOT a runtime dependency — many projects already
+ * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
+ */
+/**
+ * Detect whether a config / schema file path needs the tsx ESM loader.
+ * Returns true for `.ts`, `.mts`, and `.cts` files; false for `.js`, `.mjs`,
+ * `.cjs`, `.json`, missing paths, or anything else.
+ */
+export declare function needsTsLoader(filePath: string | null | undefined): boolean;
+/**
+ * Probe whether `tsx/esm` is resolvable from the user's current working
+ * directory. Returns true if `tsx` is installed in the user's project.
+ *
+ * Accepts an injected `resolver` so unit tests don't need a real filesystem.
+ */
+export declare function canResolveTsx(resolver?: (id: string) => string): boolean;
+export type TsLoaderStatus = 'registered' | 'already' | 'unsupported' | 'missing';
+/**
+ * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
+ * work. Safe to call multiple times — internal flag prevents double registration.
+ *
+ * Returns:
+ *   - 'registered'  loader was successfully registered this call
+ *   - 'already'     a loader was previously registered (idempotent)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'missing'     `tsx` is not installed in the user's project
+ */
+export declare function registerTsLoader(): Promise<TsLoaderStatus>;
+/** Reset the loader state — used by unit tests only. */
+export declare function _resetTsLoaderStateForTests(): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/cli/loader.js

@@ -0,0 +1,91 @@
+/**
+ * turbine-orm CLI — TypeScript loader registration
+ *
+ * The CLI loads user-supplied config and schema files via dynamic `import()`.
+ * Plain Node has no built-in `.ts` loader, so importing `turbine.config.ts`
+ * blows up with `ERR_UNKNOWN_FILE_EXTENSION` unless we register a TypeScript
+ * loader first.
+ *
+ * Strategy:
+ *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
+ *      probe whether `tsx/esm` is resolvable from the user's CWD.
+ *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
+ *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *
+ * `tsx` is intentionally NOT a runtime dependency — many projects already
+ * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
+ */
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+/**
+ * Detect whether a config / schema file path needs the tsx ESM loader.
+ * Returns true for `.ts`, `.mts`, and `.cts` files; false for `.js`, `.mjs`,
+ * `.cjs`, `.json`, missing paths, or anything else.
+ */
+export function needsTsLoader(filePath) {
+    if (!filePath)
+        return false;
+    return /\.(ts|mts|cts)$/i.test(filePath);
+}
+/**
+ * Probe whether `tsx/esm` is resolvable from the user's current working
+ * directory. Returns true if `tsx` is installed in the user's project.
+ *
+ * Accepts an injected `resolver` so unit tests don't need a real filesystem.
+ */
+export function canResolveTsx(resolver) {
+    try {
+        if (resolver) {
+            resolver('tsx/esm');
+            return true;
+        }
+        // Probe relative to the user's CWD, not Turbine's install location.
+        // This way we honour whatever `tsx` version the user has pinned.
+        const userRequire = createRequire(`${process.cwd()}/`);
+        userRequire.resolve('tsx/esm');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let tsLoaderState = null;
+/**
+ * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
+ * work. Safe to call multiple times — internal flag prevents double registration.
+ *
+ * Returns:
+ *   - 'registered'  loader was successfully registered this call
+ *   - 'already'     a loader was previously registered (idempotent)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'missing'     `tsx` is not installed in the user's project
+ */
+export async function registerTsLoader() {
+    if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
+        return 'already';
+    }
+    if (!canResolveTsx()) {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+    try {
+        const mod = await import('node:module');
+        const register = mod.register;
+        if (typeof register !== 'function') {
+            tsLoaderState = 'unsupported';
+            return 'unsupported';
+        }
+        register('tsx/esm', pathToFileURL(`${process.cwd()}/`));
+        tsLoaderState = 'registered';
+        return 'registered';
+    }
+    catch {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+}
+/** Reset the loader state — used by unit tests only. */
+export function _resetTsLoaderStateForTests() {
+    tsLoaderState = null;
+}
+//# sourceMappingURL=loader.js.map

package/dist/cli/migrate.d.ts

@@ -85,11 +85,17 @@ export declare function createMigration(migrationsDir: string, name: string, aut
  * Features:
  * - Idempotent: running twice is safe (already-applied migrations are skipped)
  * - Advisory lock: prevents concurrent migration runs
- * - Checksum validation: detects modified migration files
+ * - Checksum validation: detects modified migration files (BLOCKING — use
+ *   `allowDrift: true` to bypass when intentionally rewriting history)
  * - Each migration runs in its own transaction
+ *
+ * Throws `MigrationError` if any applied migration has been modified or deleted
+ * on disk, listing the offending files. Pass `{ allowDrift: true }` to bypass
+ * this check (the CLI exposes this as `--allow-drift`).
  */
 export declare function migrateUp(connectionString: string, migrationsDir: string, options?: {
     step?: number;
+    allowDrift?: boolean /** @deprecated use allowDrift */;
     force?: boolean;
 }): Promise<{
     applied: MigrationFile[];