turbine-orm 0.23.2 → 0.25.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/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/cjs/serverless.js

@@ -89,12 +89,29 @@ const client_js_1 = require("./client.js");
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -102,10 +119,25 @@ const client_js_1 = require("./client.js");
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
 function turbineHttp(pool, schema, options = {}) {
+    // The generated subclass only layers `declare readonly` accessor typings
+    // over the base client; the base constructor materializes those same
+    // accessors at runtime (Object.defineProperty per schema table). So the
+    // returned instance genuinely has TClient's shape — the assertion is safe.
     return new client_js_1.TurbineClient({ pool, ...options }, schema);
 }

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.

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
 // ---------------------------------------------------------------------------

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 = {

package/dist/schema-builder.d.ts

@@ -24,7 +24,7 @@
  */
 import type { SchemaMetadata } from './schema.js';
 /** Shorthand type names that map to Postgres column types */
-export type ColumnTypeName = 'serial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'date' | 'json' | 'uuid' | 'real' | 'double' | 'numeric' | 'bytea';
+export type ColumnTypeName = 'serial' | 'bigserial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'timestamptz' | 'date' | 'json' | 'jsonb' | 'uuid' | 'real' | 'double' | 'numeric' | 'bytea';
 /** Column definition as a plain object. This is what users write. */
 export interface ColumnDef {
     /** Column type (required) */
@@ -45,7 +45,7 @@ export interface ColumnDef {
     maxLength?: number;
 }
 /** Postgres-level column type (uppercase, as used in DDL) */
-export type ColumnType = 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR';
+export type ColumnType = 'SERIAL' | 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR';
 export interface ColumnConfig {
     type: ColumnType;
     isPrimaryKey: boolean;
@@ -164,6 +164,7 @@ export declare class ColumnBuilder {
     private _config;
     constructor();
     serial(): this;
+    bigserial(): this;
     bigint(): this;
     integer(): this;
     smallint(): this;
@@ -171,8 +172,10 @@ export declare class ColumnBuilder {
     varchar(length: number): this;
     boolean(): this;
     timestamp(): this;
+    timestamptz(): this;
     date(): this;
     json(): this;
+    jsonb(): this;
     uuid(): this;
     real(): this;
     doublePrecision(): this;
@@ -188,7 +191,7 @@ export declare class ColumnBuilder {
 }
 /** @deprecated Use defineSchema() with plain objects instead */
 type ColumnProxy = {
-    [K in 'serial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'boolean' | 'timestamp' | 'date' | 'json' | 'uuid' | 'real' | 'doublePrecision' | 'numeric' | 'bytea']: () => ColumnBuilder;
+    [K in 'serial' | 'bigserial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'boolean' | 'timestamp' | 'timestamptz' | 'date' | 'json' | 'jsonb' | 'uuid' | 'real' | 'doublePrecision' | 'numeric' | 'bytea']: () => ColumnBuilder;
 } & {
     varchar: (length: number) => ColumnBuilder;
 };

package/dist/schema-builder.js

@@ -24,16 +24,28 @@
  */
 /** 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',
@@ -178,6 +190,11 @@ export 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;
     }
@@ -210,6 +227,10 @@ export class ColumnBuilder {
         this._config.type = 'TIMESTAMPTZ';
         return this;
     }
+    timestamptz() {
+        this._config.type = 'TIMESTAMPTZ';
+        return this;
+    }
     date() {
         this._config.type = 'DATE';
         return this;
@@ -218,6 +239,10 @@ export class ColumnBuilder {
         this._config.type = 'JSONB';
         return this;
     }
+    jsonb() {
+        this._config.type = 'JSONB';
+        return this;
+    }
     uuid() {
         this._config.type = 'UUID';
         return this;
@@ -269,14 +294,17 @@ export class 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/schema-sql.js

@@ -7,6 +7,15 @@
 import pg from 'pg';
 import { postgresDialect } from './dialect.js';
 import { camelToSnake } from './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
 // ---------------------------------------------------------------------------
@@ -154,7 +163,7 @@ function generateColumnDef(fieldName, config, resolveRef, dialect = postgresDial
     //   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
@@ -343,9 +352,13 @@ export 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};`;
@@ -355,7 +368,7 @@ export 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;`;
@@ -372,7 +385,7 @@ export 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;
@@ -451,6 +464,7 @@ export async function schemaDiff(schema, connectionString) {
  */
 function schemaTypeToUdt(config) {
     const map = {
+        SERIAL: 'int4',
         BIGSERIAL: 'int8',
         BIGINT: 'int8',
         INTEGER: 'int4',

package/dist/serverless.d.ts

@@ -94,12 +94,29 @@ export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'def
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -107,8 +124,19 @@ export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'def
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
-export declare function turbineHttp(pool: PgCompatPool, schema: SchemaMetadata, options?: TurbineHttpOptions): TurbineClient;
+export declare function turbineHttp<TClient extends TurbineClient = TurbineClient>(pool: PgCompatPool, schema: SchemaMetadata, options?: TurbineHttpOptions): TClient;

package/dist/serverless.js

@@ -86,12 +86,29 @@ import { TurbineClient } from './client.js';
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -99,10 +116,25 @@ import { TurbineClient } from './client.js';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
 export function turbineHttp(pool, schema, options = {}) {
+    // The generated subclass only layers `declare readonly` accessor typings
+    // over the base client; the base constructor materializes those same
+    // accessors at runtime (Object.defineProperty per schema table). So the
+    // returned instance genuinely has TClient's shape — the assertion is safe.
     return new TurbineClient({ pool, ...options }, schema);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.23.2",
+  "version": "0.25.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {