turbine-orm 0.23.1 → 0.24.0

package/README.md

@@ -51,8 +51,9 @@ Performance is at parity with Prisma and Drizzle — the real reasons to choose
 ## Quick Start
 
 ```bash
-# 1. Install
+# 1. Install (the CLI also needs tsx to load .ts config/schema files)
 npm install turbine-orm
+npm install --save-dev tsx
 
 # 2. Initialize project
 npx turbine init --url postgres://user:pass@localhost:5432/mydb
@@ -61,6 +62,8 @@ npx turbine init --url postgres://user:pass@localhost:5432/mydb
 npx turbine generate
 ```
 
+> **CLI prerequisites.** The `turbine` CLI loads your `turbine.config.ts` / `turbine/schema.ts` directly, so a fresh project needs (1) `tsx` installed — otherwise `.ts` config loading fails with *"Loading .ts config / schema files requires tsx to be installed"* — and (2) `"type": "module"` in `package.json`, since Turbine is ESM. Without it you'll hit `Error [ERR_REQUIRE_ESM]: Cannot require() ES Module`. `create-next-app` sets neither by default. See [USING-TURBINE-ORM.md §0](docs/USING-TURBINE-ORM.md) for details.
+
 Works with both ESM and CommonJS:
 
 ```typescript

package/dist/adapters/cockroachdb.d.ts

@@ -37,4 +37,3 @@
  */
 import type { DatabaseAdapter } from './index.js';
 export declare const cockroachdb: DatabaseAdapter;
-//# sourceMappingURL=cockroachdb.d.ts.map

package/dist/adapters/cockroachdb.js

@@ -166,4 +166,3 @@ export const cockroachdb = {
         return { sql: `SELECT set_config('transaction_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };
-//# sourceMappingURL=cockroachdb.js.map

package/dist/adapters/index.d.ts

@@ -108,4 +108,3 @@ export declare const alloydb: DatabaseAdapter;
 export declare const timescale: DatabaseAdapter;
 export { cockroachdb } from './cockroachdb.js';
 export { yugabytedb } from './yugabytedb.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.js

@@ -83,4 +83,3 @@ export const timescale = {
 // ---------------------------------------------------------------------------
 export { cockroachdb } from './cockroachdb.js';
 export { yugabytedb } from './yugabytedb.js';
-//# sourceMappingURL=index.js.map

package/dist/adapters/yugabytedb.d.ts

@@ -49,4 +49,3 @@
  */
 import type { DatabaseAdapter } from './index.js';
 export declare const yugabytedb: DatabaseAdapter;
-//# sourceMappingURL=yugabytedb.d.ts.map

package/dist/adapters/yugabytedb.js

@@ -155,4 +155,3 @@ export const yugabytedb = {
         return { sql: `SELECT set_config('statement_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };
-//# sourceMappingURL=yugabytedb.js.map

package/dist/cjs/cli/config.js

@@ -39,6 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikeSchemaFilePath = looksLikeSchemaFilePath;
 exports.loadConfig = loadConfig;
 exports.findConfigFile = findConfigFile;
 exports.resolveConfig = resolveConfig;
@@ -46,6 +47,19 @@ exports.configTemplate = configTemplate;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
+/**
+ * Heuristic: does a configured `schema` value actually look like a schema FILE
+ * path rather than a Postgres schema name? `schema` is the Postgres namespace
+ * to introspect (default `public`); the schema-builder file goes in `schemaFile`.
+ * A value containing a path separator or a JS/TS extension is almost certainly a
+ * mis-set `schemaFile` — introspecting `WHERE table_schema = './turbine/schema.ts'`
+ * silently matches zero tables. Used by `turbine generate` to fail loudly.
+ */
+function looksLikeSchemaFilePath(schema) {
+    if (!schema)
+        return false;
+    return schema.includes('/') || schema.includes('\\') || /\.(ts|mts|cts|js|mjs|cjs|json)$/i.test(schema);
+}
 // ---------------------------------------------------------------------------
 // Config file names, in priority order
 // ---------------------------------------------------------------------------

package/dist/cjs/cli/index.js

@@ -120,6 +120,9 @@ function parseArgs() {
             case '--allow-drift':
                 result.allowDrift = true;
                 break;
+            case '--allow-empty':
+                result.allowEmpty = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -242,10 +245,28 @@ async function loadSchemaFile(schemaFile) {
                 (0, ui_js_1.newline)();
                 console.log(`  ${(0, ui_js_1.dim)('Hint: install')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to load .ts files:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
             }
+            printCjsHintIfApplicable(err);
         }
         process.exit(1);
     }
 }
+/**
+ * When a config/schema import blows up with the CommonJS-vs-ESM interop error
+ * (`Cannot require() ES Module` / `ERR_REQUIRE_ESM`), the root cause is almost
+ * always a project whose `package.json` lacks `"type": "module"`: tsx transpiles
+ * the `.ts` file to CJS and then can't `require()` Turbine's ESM build. Point the
+ * user at the one-line fix instead of leaving them with a raw Node stack trace.
+ */
+function printCjsHintIfApplicable(err) {
+    const msg = err.message;
+    if (msg.includes('ERR_REQUIRE_ESM') ||
+        msg.includes('require() of ES Module') ||
+        msg.includes('Cannot require() ES Module')) {
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Hint: add')} ${(0, ui_js_1.cyan)('"type": "module"')} ${(0, ui_js_1.dim)('to your')} ${(0, ui_js_1.cyan)('package.json')}${(0, ui_js_1.dim)('.')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Turbine is an ESM package; without it, Node/tsx tries to')} ${(0, ui_js_1.cyan)('require()')} ${(0, ui_js_1.dim)('it and fails.')}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Command: init
 // ---------------------------------------------------------------------------
@@ -443,6 +464,24 @@ async function cmdGenerate(args, config) {
     (0, ui_js_1.banner)();
     const url = requireUrl(config);
     const startTime = performance.now();
+    // Guard: `schema` is the Postgres NAMESPACE to introspect (default `public`),
+    // NOT the path to your schema-builder file — that goes in `schemaFile`. If the
+    // configured `schema` looks like a file path, introspection would silently
+    // match zero tables and emit an empty client. Fail loudly instead.
+    if (!args.allowEmpty && (0, config_js_1.looksLikeSchemaFilePath)(config.schema)) {
+        (0, ui_js_1.error)(`The "schema" option looks like a file path: ${(0, ui_js_1.cyan)(config.schema)}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('"schema" is the Postgres schema NAME to introspect')} ${(0, ui_js_1.dim)('(default:')} ${(0, ui_js_1.cyan)('public')}${(0, ui_js_1.dim)(').')}`);
+        console.log(`  ${(0, ui_js_1.dim)('The path to your defineSchema() file belongs in')} ${(0, ui_js_1.cyan)('schemaFile')}${(0, ui_js_1.dim)('.')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Fix your')} ${(0, ui_js_1.cyan)('turbine.config.ts')}${(0, ui_js_1.dim)(':')}`);
+        console.log(`    ${(0, ui_js_1.green)('schema:')} ${(0, ui_js_1.cyan)("'public'")}${(0, ui_js_1.dim)(",       // or omit — introspects the 'public' schema")}`);
+        console.log(`    ${(0, ui_js_1.green)('schemaFile:')} ${(0, ui_js_1.cyan)(`'${config.schema}'`)}${(0, ui_js_1.dim)(', // your defineSchema() file (used by `turbine push`)')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Re-run with')} ${(0, ui_js_1.cyan)('--allow-empty')} ${(0, ui_js_1.dim)('to introspect this literal schema name anyway.')}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
     (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
     (0, ui_js_1.label)('Schema', config.schema);
     (0, ui_js_1.label)('Output', config.out);
@@ -459,6 +498,24 @@ async function cmdGenerate(args, config) {
     const totalColumns = Object.values(schema.tables).reduce((sum, t) => sum + t.columns.length, 0);
     const totalRelations = Object.values(schema.tables).reduce((sum, t) => sum + Object.keys(t.relations).length, 0);
     spinner.succeed(`Found ${(0, ui_js_1.bold)(String(tableNames.length))} tables, ${(0, ui_js_1.bold)(String(totalColumns))} columns, ${(0, ui_js_1.bold)(String(totalRelations))} relations`);
+    // Guard: zero tables means the generated client would be empty. That is almost
+    // always a misconfiguration (wrong `schema`, an include/exclude that filtered
+    // everything, or a database with no tables yet) rather than intent. Fail loudly
+    // instead of silently emitting an empty typed client.
+    if (tableNames.length === 0 && !args.allowEmpty) {
+        (0, ui_js_1.newline)();
+        (0, ui_js_1.error)(`Introspection matched 0 tables in schema ${(0, ui_js_1.cyan)(config.schema)} — refusing to generate an empty client.`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Common causes:')}`);
+        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('schema')} ${(0, ui_js_1.dim)('points at the wrong Postgres namespace')} ${(0, ui_js_1.dim)('(it is the schema NAME, default')} ${(0, ui_js_1.cyan)('public')}${(0, ui_js_1.dim)(').')}`);
+        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.dim)('You meant to set')} ${(0, ui_js_1.cyan)('schemaFile')} ${(0, ui_js_1.dim)('(your defineSchema() file), not')} ${(0, ui_js_1.cyan)('schema')}${(0, ui_js_1.dim)('.')}`);
+        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('include')}/${(0, ui_js_1.cyan)('exclude')} ${(0, ui_js_1.dim)('filtered out every table.')}`);
+        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.dim)('The database has no tables yet — run')} ${(0, ui_js_1.cyan)('turbine push')} ${(0, ui_js_1.dim)('or a migration first.')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('If an empty client is genuinely what you want, re-run with')} ${(0, ui_js_1.cyan)('--allow-empty')}${(0, ui_js_1.dim)('.')}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
     // Print table summary
     if (args.verbose) {
         (0, ui_js_1.newline)();
@@ -1134,6 +1191,7 @@ function showGenerateHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--schema, -s')} ${(0, ui_js_1.dim)('<name>')}   Postgres schema ${(0, ui_js_1.dim)('(default: public)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--include')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to include`);
     console.log(`    ${(0, ui_js_1.cyan)('--exclude')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to exclude`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-empty')}         Generate even when introspection matches 0 tables`);
     (0, ui_js_1.newline)();
 }
 function showPushHelp() {
@@ -1342,6 +1400,8 @@ async function main() {
     catch (err) {
         if (args.command !== 'init') {
             (0, ui_js_1.warn)(`Could not load config: ${err instanceof Error ? err.message : String(err)}`);
+            if (err instanceof Error)
+                printCjsHintIfApplicable(err);
         }
     }
     const overrides = {

package/dist/cjs/schema-builder.js

@@ -30,16 +30,28 @@ exports.table = table;
 exports.applyManyToManyRelations = applyManyToManyRelations;
 /** Maps shorthand names to actual Postgres type strings */
 const TYPE_MAP = {
-    serial: 'BIGSERIAL',
+    // `serial` maps to SERIAL (int4). Its values fit in a JS `number` and pg
+    // returns them as numbers — so the generated `number` type is accurate.
+    // For 64-bit auto-increment keys use `bigserial` (int8), noting that values
+    // above Number.MAX_SAFE_INTEGER read back as string. (Changed in 0.24.0;
+    // `serial` previously emitted BIGSERIAL.)
+    serial: 'SERIAL',
+    bigserial: 'BIGSERIAL',
     bigint: 'BIGINT',
     integer: 'INTEGER',
     smallint: 'SMALLINT',
     text: 'TEXT',
     varchar: 'VARCHAR',
     boolean: 'BOOLEAN',
+    // `timestamp` is an honest alias for TIMESTAMPTZ (timezone-aware) — Turbine
+    // has always emitted TIMESTAMPTZ for it. `timestamptz` is the explicit spelling.
     timestamp: 'TIMESTAMPTZ',
+    timestamptz: 'TIMESTAMPTZ',
     date: 'DATE',
+    // `json` is an alias for JSONB (Turbine has always emitted JSONB). `jsonb`
+    // is the explicit spelling.
     json: 'JSONB',
+    jsonb: 'JSONB',
     uuid: 'UUID',
     real: 'REAL',
     double: 'DOUBLE PRECISION',
@@ -184,6 +196,11 @@ class ColumnBuilder {
         };
     }
     serial() {
+        // See TYPE_MAP: `serial` is SERIAL (int4) as of 0.24.0. Use bigserial() for 64-bit.
+        this._config.type = 'SERIAL';
+        return this;
+    }
+    bigserial() {
         this._config.type = 'BIGSERIAL';
         return this;
     }
@@ -216,6 +233,10 @@ class ColumnBuilder {
         this._config.type = 'TIMESTAMPTZ';
         return this;
     }
+    timestamptz() {
+        this._config.type = 'TIMESTAMPTZ';
+        return this;
+    }
     date() {
         this._config.type = 'DATE';
         return this;
@@ -224,6 +245,10 @@ class ColumnBuilder {
         this._config.type = 'JSONB';
         return this;
     }
+    jsonb() {
+        this._config.type = 'JSONB';
+        return this;
+    }
     uuid() {
         this._config.type = 'UUID';
         return this;
@@ -276,14 +301,17 @@ exports.ColumnBuilder = ColumnBuilder;
 /** Type guard: is `prop` a known nullary ColumnBuilder type method? */
 function isNullaryColumnType(prop) {
     return (prop === 'serial' ||
+        prop === 'bigserial' ||
         prop === 'bigint' ||
         prop === 'integer' ||
         prop === 'smallint' ||
         prop === 'text' ||
         prop === 'boolean' ||
         prop === 'timestamp' ||
+        prop === 'timestamptz' ||
         prop === 'date' ||
         prop === 'json' ||
+        prop === 'jsonb' ||
         prop === 'uuid' ||
         prop === 'real' ||
         prop === 'doublePrecision' ||

package/dist/cjs/schema-sql.js

@@ -16,6 +16,15 @@ exports.schemaToSQLString = schemaToSQLString;
 const pg_1 = __importDefault(require("pg"));
 const dialect_js_1 = require("./dialect.js");
 const schema_js_1 = require("./schema.js");
+/**
+ * Whether a resolved column type is an auto-increment pseudo-type (SERIAL /
+ * BIGSERIAL). These carry an implicit sequence default and NOT NULL, and their
+ * underlying integer width (int4 vs int8) is never auto-migrated by diff — a
+ * width change on a live PK is destructive and must be done by hand.
+ */
+function isSerialType(type) {
+    return type === 'SERIAL' || type === 'BIGSERIAL';
+}
 // ---------------------------------------------------------------------------
 // SQL Generation — SchemaDef → CREATE TABLE statements
 // ---------------------------------------------------------------------------
@@ -163,7 +172,7 @@ function generateColumnDef(fieldName, config, resolveRef, dialect = dialect_js_1
     //   2. Is a serial (BIGSERIAL implies NOT NULL), OR
     //   3. Has a primary key (PKs are NOT NULL)
     // A column is left nullable if .nullable() was called.
-    const isSerial = config.type === 'BIGSERIAL';
+    const isSerial = isSerialType(config.type);
     const implicitNotNull = isSerial || config.isPrimaryKey;
     const notNull = config.isNotNull && !implicitNotNull;
     // DEFAULT
@@ -352,9 +361,13 @@ async function schemaDiff(schema, connectionString) {
                     result.reverseStatements.unshift(reverseSql);
                     continue;
                 }
-                // Check type mismatch
+                // Check type mismatch. Serial/bigserial columns are exempt: their
+                // underlying int4/int8 width must never be auto-altered on a live table
+                // (a downcast on a PK loses data / breaks the sequence). This also
+                // preserves back-compat for DBs whose `serial` columns were created as
+                // BIGSERIAL (int8) before 0.24.0 — `push` won't try to shrink them.
                 const expectedUdt = schemaTypeToUdt(config);
-                if (expectedUdt && dbCol.udtName !== expectedUdt) {
+                if (expectedUdt && !isSerialType(config.type) && dbCol.udtName !== expectedUdt) {
                     const sqlType = config.type === 'VARCHAR' && config.maxLength ? `VARCHAR(${config.maxLength})` : config.type;
                     const oldSqlType = udtToSqlType(dbCol.udtName, dbCol.maxLength);
                     const sql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${sqlType} USING ${dialect.quoteIdentifier(snakeName)}::${sqlType};`;
@@ -364,7 +377,7 @@ async function schemaDiff(schema, connectionString) {
                     result.reverseStatements.unshift(reverseSql);
                 }
                 // Check NOT NULL mismatch
-                const shouldBeNotNull = config.isNotNull || config.isPrimaryKey || config.type === 'BIGSERIAL';
+                const shouldBeNotNull = config.isNotNull || config.isPrimaryKey || isSerialType(config.type);
                 const isCurrentlyNullable = dbCol.isNullable;
                 if (shouldBeNotNull && isCurrentlyNullable && !config.isNullable) {
                     const sql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} SET NOT NULL;`;
@@ -381,7 +394,7 @@ async function schemaDiff(schema, connectionString) {
                     result.reverseStatements.unshift(reverseSql);
                 }
                 // Check DEFAULT value mismatch
-                const isSerial = config.type === 'BIGSERIAL';
+                const isSerial = isSerialType(config.type);
                 if (!isSerial) {
                     const schemaDefault = config.defaultValue ? normalizeDefault(config.defaultValue) : null;
                     const dbDefault = dbCol.columnDefault;
@@ -460,6 +473,7 @@ async function schemaDiff(schema, connectionString) {
  */
 function schemaTypeToUdt(config) {
     const map = {
+        SERIAL: 'int4',
         BIGSERIAL: 'int8',
         BIGINT: 'int8',
         INTEGER: 'int4',

package/dist/cli/config.d.ts

@@ -33,6 +33,20 @@ export interface TurbineCliConfig {
      */
     adapter?: import('../adapters/index.js').DatabaseAdapter;
 }
+/**
+ * Alias for {@link TurbineCliConfig}. Some docs and examples import the config
+ * type as `TurbineConfig`; both names refer to the same shape.
+ */
+export type TurbineConfig = TurbineCliConfig;
+/**
+ * Heuristic: does a configured `schema` value actually look like a schema FILE
+ * path rather than a Postgres schema name? `schema` is the Postgres namespace
+ * to introspect (default `public`); the schema-builder file goes in `schemaFile`.
+ * A value containing a path separator or a JS/TS extension is almost certainly a
+ * mis-set `schemaFile` — introspecting `WHERE table_schema = './turbine/schema.ts'`
+ * silently matches zero tables. Used by `turbine generate` to fail loudly.
+ */
+export declare function looksLikeSchemaFilePath(schema: string): boolean;
 /**
  * Attempt to load a turbine config file from the current directory.
  * Returns the config if found, or an empty object.
@@ -66,4 +80,3 @@ export interface CliOverrides {
  */
 export declare function resolveConfig(fileConfig: TurbineCliConfig, overrides: CliOverrides): ResolvedConfig;
 export declare function configTemplate(connectionString?: string): string;
-//# sourceMappingURL=config.d.ts.map

package/dist/cli/config.js

@@ -7,6 +7,19 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+/**
+ * Heuristic: does a configured `schema` value actually look like a schema FILE
+ * path rather than a Postgres schema name? `schema` is the Postgres namespace
+ * to introspect (default `public`); the schema-builder file goes in `schemaFile`.
+ * A value containing a path separator or a JS/TS extension is almost certainly a
+ * mis-set `schemaFile` — introspecting `WHERE table_schema = './turbine/schema.ts'`
+ * silently matches zero tables. Used by `turbine generate` to fail loudly.
+ */
+export function looksLikeSchemaFilePath(schema) {
+    if (!schema)
+        return false;
+    return schema.includes('/') || schema.includes('\\') || /\.(ts|mts|cts|js|mjs|cjs|json)$/i.test(schema);
+}
 // ---------------------------------------------------------------------------
 // Config file names, in priority order
 // ---------------------------------------------------------------------------
@@ -110,4 +123,3 @@ ${urlLine}
 export default config;
 `;
 }
-//# sourceMappingURL=config.js.map

package/dist/cli/index.d.ts

@@ -21,4 +21,3 @@
  *   npx turbine migrate create add_users_table
  */
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -26,7 +26,7 @@ import { pathToFileURL } from 'node:url';
 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 { configTemplate, findConfigFile, loadConfig, looksLikeSchemaFilePath, resolveConfig } from './config.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { createMigration, listMigrationFiles, migrateDown, migrateStatus, migrateUp } from './migrate.js';
 import { startObserve } from './observe.js';
@@ -85,6 +85,9 @@ function parseArgs() {
             case '--allow-drift':
                 result.allowDrift = true;
                 break;
+            case '--allow-empty':
+                result.allowEmpty = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -207,10 +210,28 @@ async function loadSchemaFile(schemaFile) {
                 newline();
                 console.log(`  ${dim('Hint: install')} ${cyan('tsx')} ${dim('to load .ts files:')} ${cyan('npm install --save-dev tsx')}`);
             }
+            printCjsHintIfApplicable(err);
         }
         process.exit(1);
     }
 }
+/**
+ * When a config/schema import blows up with the CommonJS-vs-ESM interop error
+ * (`Cannot require() ES Module` / `ERR_REQUIRE_ESM`), the root cause is almost
+ * always a project whose `package.json` lacks `"type": "module"`: tsx transpiles
+ * the `.ts` file to CJS and then can't `require()` Turbine's ESM build. Point the
+ * user at the one-line fix instead of leaving them with a raw Node stack trace.
+ */
+function printCjsHintIfApplicable(err) {
+    const msg = err.message;
+    if (msg.includes('ERR_REQUIRE_ESM') ||
+        msg.includes('require() of ES Module') ||
+        msg.includes('Cannot require() ES Module')) {
+        newline();
+        console.log(`  ${dim('Hint: add')} ${cyan('"type": "module"')} ${dim('to your')} ${cyan('package.json')}${dim('.')}`);
+        console.log(`  ${dim('Turbine is an ESM package; without it, Node/tsx tries to')} ${cyan('require()')} ${dim('it and fails.')}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Command: init
 // ---------------------------------------------------------------------------
@@ -408,6 +429,24 @@ async function cmdGenerate(args, config) {
     banner();
     const url = requireUrl(config);
     const startTime = performance.now();
+    // Guard: `schema` is the Postgres NAMESPACE to introspect (default `public`),
+    // NOT the path to your schema-builder file — that goes in `schemaFile`. If the
+    // configured `schema` looks like a file path, introspection would silently
+    // match zero tables and emit an empty client. Fail loudly instead.
+    if (!args.allowEmpty && looksLikeSchemaFilePath(config.schema)) {
+        error(`The "schema" option looks like a file path: ${cyan(config.schema)}`);
+        newline();
+        console.log(`  ${dim('"schema" is the Postgres schema NAME to introspect')} ${dim('(default:')} ${cyan('public')}${dim(').')}`);
+        console.log(`  ${dim('The path to your defineSchema() file belongs in')} ${cyan('schemaFile')}${dim('.')}`);
+        newline();
+        console.log(`  ${dim('Fix your')} ${cyan('turbine.config.ts')}${dim(':')}`);
+        console.log(`    ${green('schema:')} ${cyan("'public'")}${dim(",       // or omit — introspects the 'public' schema")}`);
+        console.log(`    ${green('schemaFile:')} ${cyan(`'${config.schema}'`)}${dim(', // your defineSchema() file (used by `turbine push`)')}`);
+        newline();
+        console.log(`  ${dim('Re-run with')} ${cyan('--allow-empty')} ${dim('to introspect this literal schema name anyway.')}`);
+        newline();
+        process.exit(1);
+    }
     label('Database', redactUrl(url));
     label('Schema', config.schema);
     label('Output', config.out);
@@ -424,6 +463,24 @@ async function cmdGenerate(args, config) {
     const totalColumns = Object.values(schema.tables).reduce((sum, t) => sum + t.columns.length, 0);
     const totalRelations = Object.values(schema.tables).reduce((sum, t) => sum + Object.keys(t.relations).length, 0);
     spinner.succeed(`Found ${bold(String(tableNames.length))} tables, ${bold(String(totalColumns))} columns, ${bold(String(totalRelations))} relations`);
+    // Guard: zero tables means the generated client would be empty. That is almost
+    // always a misconfiguration (wrong `schema`, an include/exclude that filtered
+    // everything, or a database with no tables yet) rather than intent. Fail loudly
+    // instead of silently emitting an empty typed client.
+    if (tableNames.length === 0 && !args.allowEmpty) {
+        newline();
+        error(`Introspection matched 0 tables in schema ${cyan(config.schema)} — refusing to generate an empty client.`);
+        newline();
+        console.log(`  ${dim('Common causes:')}`);
+        console.log(`    ${dim('•')} ${cyan('schema')} ${dim('points at the wrong Postgres namespace')} ${dim('(it is the schema NAME, default')} ${cyan('public')}${dim(').')}`);
+        console.log(`    ${dim('•')} ${dim('You meant to set')} ${cyan('schemaFile')} ${dim('(your defineSchema() file), not')} ${cyan('schema')}${dim('.')}`);
+        console.log(`    ${dim('•')} ${cyan('include')}/${cyan('exclude')} ${dim('filtered out every table.')}`);
+        console.log(`    ${dim('•')} ${dim('The database has no tables yet — run')} ${cyan('turbine push')} ${dim('or a migration first.')}`);
+        newline();
+        console.log(`  ${dim('If an empty client is genuinely what you want, re-run with')} ${cyan('--allow-empty')}${dim('.')}`);
+        newline();
+        process.exit(1);
+    }
     // Print table summary
     if (args.verbose) {
         newline();
@@ -1099,6 +1156,7 @@ function showGenerateHelp() {
     console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}   Postgres schema ${dim('(default: public)')}`);
     console.log(`    ${cyan('--include')} ${dim('<tables>')}    Comma-separated tables to include`);
     console.log(`    ${cyan('--exclude')} ${dim('<tables>')}    Comma-separated tables to exclude`);
+    console.log(`    ${cyan('--allow-empty')}         Generate even when introspection matches 0 tables`);
     newline();
 }
 function showPushHelp() {
@@ -1307,6 +1365,8 @@ async function main() {
     catch (err) {
         if (args.command !== 'init') {
             warn(`Could not load config: ${err instanceof Error ? err.message : String(err)}`);
+            if (err instanceof Error)
+                printCjsHintIfApplicable(err);
         }
     }
     const overrides = {
@@ -1398,4 +1458,3 @@ async function main() {
     }
 }
 main();
-//# sourceMappingURL=index.js.map

package/dist/cli/loader.d.ts

@@ -59,4 +59,3 @@ export declare function getTsLoaderError(): string | null;
 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

@@ -142,4 +142,3 @@ export function _resetTsLoaderStateForTests() {
     tsLoaderState = null;
     tsLoaderError = null;
 }
-//# sourceMappingURL=loader.js.map

package/dist/cli/migrate.d.ts

@@ -150,4 +150,3 @@ export declare function migrateDown(connectionString: string, migrationsDir: str
 export declare function migrateStatus(connectionString: string, migrationsDir: string, options?: {
     dialect?: Dialect;
 }): Promise<MigrationStatus[]>;
-//# sourceMappingURL=migrate.d.ts.map

package/dist/cli/migrate.js

@@ -491,4 +491,3 @@ export async function migrateStatus(connectionString, migrationsDir, options) {
         await client.end();
     }
 }
-//# sourceMappingURL=migrate.js.map

package/dist/cli/observe-ui.d.ts

@@ -1,2 +1 @@
 export declare const OBSERVE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n  <meta name=\"color-scheme\" content=\"dark\" />\n  <title>Turbine Observe</title>\n  <style>\n    :root {\n      --bg: #0a0a0b;\n      --bg-elev: #111113;\n      --bg-hover: #1a1a1d;\n      --border: #26262b;\n      --text: #e6e6ea;\n      --text-dim: #8a8a93;\n      --accent: #60a5fa;\n      --green: #4ade80;\n      --red: #f87171;\n      --orange: #fb923c;\n      --purple: #a78bfa;\n      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n      --sans: system-ui, -apple-system, sans-serif;\n      --radius: 6px;\n    }\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }\n    h1 { font-size: 20px; margin-bottom: 4px; }\n    .subtitle { color: var(--text-dim); margin-bottom: 24px; }\n    .controls { display: flex; gap: 8px; margin-bottom: 24px; }\n    .controls button {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;\n    }\n    .controls button.active { border-color: var(--accent); color: var(--accent); }\n    .card {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      padding: 16px; margin-bottom: 16px;\n    }\n    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }\n    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }\n    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }\n    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }\n    .num { text-align: right; }\n    .error-rate { color: var(--red); }\n    .low-error { color: var(--green); }\n    svg { width: 100%; height: 200px; }\n    .chart-line { fill: none; stroke-width: 1.5; }\n    .line-avg { stroke: var(--accent); }\n    .line-p95 { stroke: var(--orange); }\n    .line-p99 { stroke: var(--red); }\n    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }\n    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }\n    .legend .l-avg::before { background: var(--accent); }\n    .legend .l-p95::before { background: var(--orange); }\n    .legend .l-p99::before { background: var(--red); }\n    .empty { color: var(--text-dim); text-align: center; padding: 40px; }\n  </style>\n</head>\n<body>\n  <h1>Turbine Observe</h1>\n  <p class=\"subtitle\">Query performance metrics</p>\n  <div class=\"controls\">\n    <button data-range=\"1h\" class=\"active\">1h</button>\n    <button data-range=\"6h\">6h</button>\n    <button data-range=\"24h\">24h</button>\n    <button data-range=\"7d\">7d</button>\n  </div>\n  <div class=\"card\" id=\"latency-card\">\n    <h2>Latency over time</h2>\n    <div id=\"chart\"></div>\n    <div class=\"legend\">\n      <span class=\"l-avg\">avg</span>\n      <span class=\"l-p95\">p95</span>\n      <span class=\"l-p99\">p99</span>\n    </div>\n  </div>\n  <div class=\"card\" id=\"models-card\">\n    <h2>Top models</h2>\n    <div id=\"models-table\"></div>\n  </div>\n  <div class=\"card\" id=\"errors-card\">\n    <h2>Error rates</h2>\n    <div id=\"errors-table\"></div>\n  </div>\n  <script>\n    let currentRange = '1h';\n    const token = document.cookie.match(/turbine_observe_token=([a-f0-9]+)/)?.[1] || '';\n    const headers = { 'x-turbine-token': token };\n\n    document.querySelector('.controls').addEventListener('click', e => {\n      if (e.target.tagName !== 'BUTTON') return;\n      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));\n      e.target.classList.add('active');\n      currentRange = e.target.dataset.range;\n      refresh();\n    });\n\n    async function fetchJson(path) {\n      const res = await fetch(path, { headers });\n      if (!res.ok) return null;\n      return res.json();\n    }\n\n    function buildSvgPath(points, width, height, maxY) {\n      if (points.length === 0) return '';\n      const xStep = width / Math.max(points.length - 1, 1);\n      return points.map((y, i) => {\n        const px = i * xStep;\n        const py = height - (y / maxY) * height;\n        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);\n      }).join(' ');\n    }\n\n    function renderChart(data) {\n      const el = document.getElementById('chart');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      const width = 800; const height = 180;\n      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);\n      const maxY = Math.max(...allVals, 1) * 1.1;\n      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);\n      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);\n      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);\n      el.innerHTML = '<svg viewBox=\"0 0 ' + width + ' ' + height + '\" preserveAspectRatio=\"none\">'\n        + '<path class=\"chart-line line-avg\" d=\"' + avgPath + '\"/>'\n        + '<path class=\"chart-line line-p95\" d=\"' + p95Path + '\"/>'\n        + '<path class=\"chart-line line-p99\" d=\"' + p99Path + '\"/>'\n        + '</svg>';\n    }\n\n    function escapeHtml(s) {\n      if (s == null) return '';\n      return String(s)\n        .replace(/&/g, '&amp;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;')\n        .replace(/\"/g, '&quot;')\n        .replace(/'/g, '&#39;');\n    }\n\n    function renderModels(data) {\n      const el = document.getElementById('models-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Count</th><th class=\"num\">Avg (ms)</th><th class=\"num\">P95 (ms)</th><th class=\"num\">P99 (ms)</th></tr></thead><tbody>';\n      for (const row of data) {\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + row.count + '</td>'\n          + '<td class=\"num\">' + row.avg_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p95_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p99_ms.toFixed(1) + '</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    function renderErrors(data) {\n      const el = document.getElementById('errors-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No errors</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Total</th><th class=\"num\">Errors</th><th class=\"num\">Rate</th></tr></thead><tbody>';\n      for (const row of data) {\n        const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';\n        const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + row.count + '</td>'\n          + '<td class=\"num\">' + row.error_count + '</td>'\n          + '<td class=\"num ' + cls + '\">' + rate + '%</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    async function refresh() {\n      const [latency, models] = await Promise.all([\n        fetchJson('/api/latency?range=' + currentRange),\n        fetchJson('/api/models?range=' + currentRange),\n      ]);\n      renderChart(latency);\n      renderModels(models);\n      // Derive errors from models data\n      const withErrors = (models || []).filter(m => m.error_count > 0);\n      renderErrors(withErrors);\n    }\n\n    refresh();\n    setInterval(refresh, 60000);\n  </script>\n</body>\n</html>";
-//# sourceMappingURL=observe-ui.d.ts.map

package/dist/cli/observe-ui.js

@@ -187,4 +187,3 @@ export const OBSERVE_HTML = `<!doctype html>
   </script>
 </body>
 </html>`;
-//# sourceMappingURL=observe-ui.js.map

package/dist/cli/observe.d.ts

@@ -17,4 +17,3 @@ export interface ObserveServerHandle {
     url: string;
 }
 export declare function startObserve(options: ObserveOptions): Promise<ObserveServerHandle>;
-//# sourceMappingURL=observe.d.ts.map

package/dist/cli/observe.js

@@ -233,4 +233,3 @@ function openUrl(url) {
         // Best effort
     }
 }
-//# sourceMappingURL=observe.js.map

package/dist/cli/studio-ui.generated.d.ts

@@ -1,2 +1 @@
 export declare const STUDIO_HTML: string;
-//# sourceMappingURL=studio-ui.generated.d.ts.map