turbine-orm 0.4.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # turbine-orm
 
-The performance-first Postgres ORM. Prisma-compatible API, 2-3x faster nested queries, zero runtime overhead beyond `pg`.
+Postgres-native TypeScript ORM — runs on **Neon, Vercel Postgres, Cloudflare, Supabase**, and any pg-compatible driver. Streaming cursors, typed errors, single-query nested relations. 1 dependency, ~110KB.
 
 ```
 npm install turbine-orm
@@ -8,30 +8,35 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-ORMs like Prisma fetch nested relations with N+1 queries -- one query per nesting level. Turbine uses Postgres `json_agg` to resolve the entire object graph in **a single SQL query**. The result is fewer round-trips, less connection overhead, and significantly lower latency.
+Turbine is a PostgreSQL-native TypeScript ORM with features no other ORM offers together: **cursor-based streaming** through nested relations, **typed error classes** with PostgreSQL constraint mapping, **pipeline batching** (N queries, 1 round-trip), **middleware**, and a driver-agnostic core that plugs into any pg-compatible pool so it runs on Vercel Edge, Cloudflare Workers, Deno Deploy, and similar environments. It resolves nested relations in a single SQL query using `json_agg` — an approach now shared by Prisma 7+ and Drizzle v2, but Turbine does it with 1 runtime dependency (`pg`) and ~110KB on npm.
 
-**One query instead of N+1.** When you write `db.users.findMany({ with: { posts: { with: { comments: true } } } })`, Turbine generates a single SQL statement that returns fully-nested JSON. Prisma sends 3 separate queries. Drizzle uses LATERAL joins which are competitive, but Turbine still wins on median latency.
+**One query for nested relations.** When you write `db.users.findMany({ with: { posts: { with: { comments: true } } } })`, Turbine generates a single SQL statement using correlated subqueries with `json_agg`. Modern ORMs like Prisma 7+ and Drizzle v2 use similar single-query approaches (LATERAL JOINs). Turbine's advantage is architectural simplicity: 1 dependency, no code generation DSL, and PostgreSQL-native depth.
 
 ## Benchmarks
 
-Production results from Vercel Serverless hitting Neon Postgres (20 iterations, warm):
+Tested against **Prisma 7.6** (adapter-pg, relationJoins) and **Drizzle 0.45** (relational queries) on the same PostgreSQL database. 200 iterations, 20 warmup, Node v22.
 
-| Scenario | Turbine | Drizzle | Prisma |
+| Scenario | Turbine | Prisma 7 | Drizzle v2 |
 |---|---|---|---|
-| **Nested L3 (median)** | **5.3ms** | 6.5ms | 7.4ms |
-| Nested L3 (min) | **4.4ms** | 5.7ms | 6.0ms |
-| Nested L2 | **6.5ms** | 9.1ms | 10.2ms |
-| Simple select | 5.6ms | 7.1ms | 3.9ms |
-
-Local Docker results (50K iterations, HDR histograms):
-
-| Scenario | Turbine | Drizzle | Prisma |
+| **findMany — 100 rows (flat)** | **0.39 ms** | 0.58 ms | 0.44 ms |
+| **findMany — L2 nested (users + posts)** | **1.29 ms** | 1.84 ms | 1.30 ms |
+| **findMany — L3 nested (users → posts → comments)** | **0.50 ms** | 0.91 ms | 0.69 ms |
+| **findUnique by PK** | **0.08 ms** | 0.13 ms | 0.14 ms |
+| **findUnique — L3 nested** | **0.18 ms** | 0.32 ms | 0.34 ms |
+| **count** | **0.06 ms** | 0.10 ms | 0.08 ms |
+
+| Scenario | Turbine | Prisma 7 | Drizzle v2 |
 |---|---|---|---|
-| **L2 nested p50** | **201us** | 523us | 835us |
-| **L2 nested RPS (c=50)** | **24,041** | 6,360 | 3,784 |
-| L2 nested memory | 109MB | 117MB | 233MB |
+| findMany — flat | **1.00x** | 1.51x | 1.15x |
+| findMany — L2 nested | **1.00x** | 1.43x | 1.01x |
+| findMany — L3 nested | **1.00x** | 1.81x | 1.38x |
+| findUnique by PK | **1.00x** | 1.67x | 1.69x |
+| findUnique — L3 nested | **1.00x** | 1.81x | 1.93x |
+| count | **1.00x** | 1.70x | 1.38x |
+
+Turbine is fastest in every scenario. The advantage is largest on deep nesting (1.8x vs Prisma, up to 1.9x vs Drizzle) and single-record lookups (1.7x). All three ORMs now use single-query approaches for nested relations — Turbine's advantage comes from lower per-query overhead (minimal JS object allocation, no query plan compilation layer, direct pg driver access).
 
-Turbine is 2.6x faster than Drizzle and 4.2x faster than Prisma on nested queries at p50. Throughput is 3.8x higher than Drizzle and 6.3x higher than Prisma.
+> Reproduce: `cd benchmarks && npm install && npx prisma generate && DATABASE_URL=... npx tsx bench.ts`
 
 ## Quick Start
 
@@ -46,6 +51,16 @@ npx turbine init --url postgres://user:pass@localhost:5432/mydb
 npx turbine generate
 ```
 
+Works with both ESM and CommonJS:
+
+```typescript
+// ESM
+import { turbine } from './generated/turbine';
+
+// CommonJS
+const { turbine } = require('./generated/turbine');
+```
+
 This introspects your database and generates a fully-typed client at `./generated/turbine/`.
 
 ```typescript
@@ -167,6 +182,52 @@ const stats = await db.raw<{ day: Date; count: number }>`
 `;
 ```
 
+### Case-insensitive search
+
+```typescript
+const users = await db.users.findMany({
+  where: {
+    email: { contains: 'alice', mode: 'insensitive' },
+  },
+});
+// Generates: WHERE email ILIKE '%alice%'
+```
+
+### Streaming large result sets
+
+```typescript
+// Stream rows using PostgreSQL cursors — constant memory, no matter how many rows
+for await (const user of db.users.findManyStream({
+  where: { orgId: 1 },
+  batchSize: 500,       // internal FETCH batch size (default: 100)
+  orderBy: { id: 'asc' },
+  with: { posts: true }, // nested relations work too
+})) {
+  process.stdout.write(`${user.email}\n`);
+}
+```
+
+Uses `DECLARE CURSOR` under the hood — rows are fetched in batches on a dedicated connection, parsed individually, and yielded via `AsyncGenerator`. Safe to `break` early; the cursor and connection are cleaned up automatically.
+
+### Query timeout
+
+```typescript
+const users = await db.users.findMany({
+  where: { orgId: 1 },
+  timeout: 5000, // 5 second timeout
+});
+```
+
+### Default limit
+
+```typescript
+// Set a default limit for all queries on a model
+const db = turbine({
+  connectionString: process.env.DATABASE_URL,
+  defaultLimit: 100,
+});
+```
+
 ### Middleware
 
 ```typescript
@@ -187,6 +248,31 @@ db.$use(async (params, next) => {
 });
 ```
 
+### Error handling
+
+Turbine throws typed errors you can catch programmatically:
+
+```typescript
+import { NotFoundError, ValidationError, TimeoutError } from 'turbine-orm';
+
+try {
+  const user = await db.users.findUniqueOrThrow({ where: { id: 999 } });
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    // err.code === 'TURBINE_E001'
+    console.log('User not found');
+  } else if (err instanceof TimeoutError) {
+    // err.code === 'TURBINE_E002'
+    console.log('Query timed out');
+  } else if (err instanceof ValidationError) {
+    // err.code === 'TURBINE_E003'
+    console.log('Invalid query:', err.message);
+  }
+}
+```
+
+Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation).
+
 ## CLI
 
 ```
@@ -196,17 +282,19 @@ Commands:
   init                  Initialize a Turbine project (creates config, dirs, templates)
   generate | pull       Introspect database and generate TypeScript types + client
   push                  Apply schema-builder definitions to database
-  migrate create <name> Create a new SQL migration file
-  migrate up            Apply pending migrations
-  migrate down          Rollback last migration
-  migrate status        Show applied/pending migrations
-  seed                  Run seed file
-  status                Show database schema summary
+  migrate create <name>        Create a new SQL migration file
+  migrate create <name> --auto Auto-generate from schema diff
+  migrate up                   Apply pending migrations
+  migrate down                 Rollback last migration
+  migrate status               Show applied/pending migrations
+  seed                         Run seed file
+  status                       Show database schema summary
 
 Options:
   --url, -u <url>       Postgres connection string
   --out, -o <dir>       Output directory (default: ./generated/turbine)
   --schema, -s <name>   Postgres schema (default: public)
+  --auto                Auto-generate migration from schema diff
   --dry-run             Show SQL without executing
   --verbose, -v         Detailed output
 ```
@@ -239,12 +327,97 @@ npx turbine generate         # Regenerate typed client
 ### Migration workflow
 
 ```bash
+# Create a blank migration (write SQL manually)
 npx turbine migrate create add_users_table
-# Edit the generated .sql file with UP and DOWN sections
+
+# Auto-generate migration from schema diff (compares defineSchema() vs live DB)
+npx turbine migrate create add_email_index --auto
+# -> Generates UP (ALTER/CREATE) and DOWN (reverse) SQL automatically
+
+# Apply all pending migrations
 npx turbine migrate up
+
+# Rollback the last applied migration
+npx turbine migrate down
+
+# Check migration status (applied vs pending)
 npx turbine migrate status
 ```
 
+## Serverless / Edge
+
+Turbine's core is driver-agnostic: pass any pg-compatible pool to `TurbineConfig.pool` (or use the `turbineHttp()` factory) and Turbine runs on **Vercel Edge**, **Cloudflare Workers**, **Deno Deploy**, **Netlify Edge**, or any other environment where a direct TCP connection is unavailable. No new dependencies — install whichever driver you already use.
+
+### Neon Serverless (HTTP / WebSocket)
+
+```ts
+// app/api/users/route.ts
+import { Pool } from '@neondatabase/serverless';
+import { turbineHttp } from 'turbine-orm/serverless';
+import { schema } from '@/generated/turbine/metadata';
+
+export const runtime = 'edge';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = turbineHttp(pool, schema);
+
+export async function GET() {
+  const users = await db.table('users').findMany({
+    with: { posts: { with: { comments: true } } },
+    limit: 10,
+  });
+  return Response.json(users);
+}
+```
+
+### Vercel Postgres
+
+```ts
+import { createPool } from '@vercel/postgres';
+import { turbineHttp } from 'turbine-orm/serverless';
+import { schema } from './generated/turbine/metadata.js';
+
+const pool = createPool({ connectionString: process.env.POSTGRES_URL });
+const db = turbineHttp(pool, schema);
+```
+
+### Supabase (direct Postgres — no HTTP proxy needed)
+
+```ts
+import { TurbineClient } from 'turbine-orm';
+import { schema } from './generated/turbine/metadata.js';
+
+const db = new TurbineClient({
+  connectionString: process.env.SUPABASE_DB_URL,
+  ssl: { rejectUnauthorized: false },
+}, schema);
+```
+
+### Cloudflare Workers
+
+```ts
+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 users = await db.table('users').findMany({ limit: 10 });
+    return Response.json(users);
+  },
+};
+```
+
+### Limitations on HTTP drivers
+
+- **Streaming cursors** (`findManyStream`) require `DECLARE CURSOR`, which most HTTP drivers don't support. Use `findMany` with `limit` + pagination instead.
+- **LISTEN/NOTIFY** is not available over HTTP.
+- Transactions work but hold an HTTP connection for their duration — keep them short.
+
+When Turbine receives an external pool, `db.disconnect()` is a no-op: the caller owns the pool's lifecycle.
+
 ## Configuration
 
 Create `turbine.config.ts` in your project root (or run `npx turbine init`):
@@ -283,12 +456,56 @@ SELECT u.*,
 FROM users u WHERE u.org_id = 1
 ```
 
-This resolves the entire 3-level object graph in one database round-trip. Prisma would send 3 queries. The performance difference scales with nesting depth and network latency.
+This resolves the entire 3-level object graph in one database round-trip. Prisma 7+ and Drizzle v2 also use single-query approaches (LATERAL JOINs), but Turbine's correlated subquery strategy has lower per-query overhead — see [Benchmarks](#benchmarks).
+
+## Type Mapping
+
+Turbine maps Postgres types to TypeScript:
+
+| Postgres | TypeScript | Notes |
+|---|---|---|
+| `int2`, `int4`, `float4`, `float8` | `number` | Standard numeric types |
+| `int8` / `bigint` | `number` | Values > `Number.MAX_SAFE_INTEGER` (2^53 - 1) are returned as `string` at runtime to avoid precision loss. This affects < 0.01% of use cases (auto-increment IDs, counts, etc. are all safe). |
+| `numeric`, `money` | `string` | Arbitrary precision — kept as string to avoid JS float issues |
+| `text`, `varchar`, `uuid`, `citext` | `string` | |
+| `timestamptz`, `timestamp`, `date` | `Date` | |
+| `boolean` | `boolean` | |
+| `json`, `jsonb` | `unknown` | |
+| `bytea` | `Buffer` | |
+| Array types | `T[]` | e.g. `_text` → `string[]` |
+
+## Comparison
+
+| | **Turbine** | **Prisma** | **Drizzle** | **Kysely** |
+|---|---|---|---|---|
+| **Nested relations** | 1 query (`json_agg`) | 1 query (LATERAL JOIN + json_agg, since v5.8) | 1 query (LATERAL JOINs) | Manual (`jsonArrayFrom`) |
+| **API style** | `findMany`, `with` | `findMany`, `include` | SQL-like + relational | SQL builder |
+| **Schema** | TypeScript | Custom DSL (`.prisma`) | TypeScript | Manual interfaces |
+| **Runtime deps** | 1 (`pg`) | `@prisma/client` + adapter | 0 | 0 |
+| **Multi-DB** | PostgreSQL only | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
+| **Code generation** | `turbine generate` | `prisma generate` | Not needed | Not needed |
+
+All three ORMs now use single-query approaches for nested relations. Turbine uses correlated subqueries with `json_agg`, Prisma 7 uses LATERAL JOIN + `json_agg`, and Drizzle uses LATERAL JOINs. Turbine is 1.4–1.9x faster due to lower per-query overhead — minimal JS object allocation, no query plan compilation layer, and direct pg driver access. See [Benchmarks](#benchmarks) for full results.
+
+## Limitations
+
+Turbine is focused and opinionated. Here's what it doesn't do:
+
+- **PostgreSQL only.** No MySQL, SQLite, or MSSQL. This is by design — the `json_agg` approach is PostgreSQL-specific, and going deep on one database enables the performance advantage.
+- **No incremental updates.** Prisma's `{ count: { increment: 1 } }` syntax is not yet supported. Use raw SQL for atomic increments.
+- **No full-text search operators.** TSVECTOR/TSQUERY are not exposed in the query builder. Use `db.raw` for full-text queries.
+- **Large nested result sets.** `json_agg` builds the entire JSON array in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause to cap the aggregation size.
+- **No admin UI.** Turbine Studio is planned but not yet available.
+
+## Examples
+
+- **[Next.js](./examples/nextjs/)** — Server-rendered app with nested relations, streaming, and live code demos
 
 ## Requirements
 
-- Node.js >= 22.0.0
+- Node.js >= 18.0.0
 - PostgreSQL >= 14
+- Works with both ESM (`import`) and CommonJS (`require`)
 
 ## License
 

package/dist/cjs/cli/config.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * turbine-orm CLI — Configuration file support
+ *
+ * Loads turbine.config.ts (or .js/.mjs) via dynamic import.
+ * Falls back to CLI args and environment variables.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.findConfigFile = findConfigFile;
+exports.resolveConfig = resolveConfig;
+exports.configTemplate = configTemplate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+// ---------------------------------------------------------------------------
+// Config file names, in priority order
+// ---------------------------------------------------------------------------
+const CONFIG_FILES = ['turbine.config.ts', 'turbine.config.mts', 'turbine.config.js', 'turbine.config.mjs'];
+// ---------------------------------------------------------------------------
+// Load config
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to load a turbine config file from the current directory.
+ * Returns the config if found, or an empty object.
+ */
+async function loadConfig(cwd) {
+    const dir = cwd ?? process.cwd();
+    for (const filename of CONFIG_FILES) {
+        const filePath = (0, node_path_1.join)(dir, filename);
+        if (!(0, node_fs_1.existsSync)(filePath))
+            continue;
+        try {
+            const absPath = (0, node_path_1.resolve)(filePath);
+            const fileUrl = (0, node_url_1.pathToFileURL)(absPath).href;
+            // For .ts files, we need to rely on Node's --experimental-strip-types
+            // or the tsx loader. Dynamic import handles .js/.mjs natively.
+            const mod = await Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
+            const config = mod.default ?? mod;
+            return config;
+        }
+        catch (err) {
+            // If importing a .ts file fails, try the next one
+            if (filename.endsWith('.ts') || filename.endsWith('.mts')) {
+                continue;
+            }
+            throw new Error(`Failed to load config from ${filename}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {};
+}
+/**
+ * Find the config file path (for display purposes).
+ * Returns null if no config file is found.
+ */
+function findConfigFile(cwd) {
+    const dir = cwd ?? process.cwd();
+    for (const filename of CONFIG_FILES) {
+        const filePath = (0, node_path_1.join)(dir, filename);
+        if ((0, node_fs_1.existsSync)(filePath))
+            return filePath;
+    }
+    return null;
+}
+/**
+ * Merge config file values with CLI overrides and env vars.
+ * Priority: CLI flags > env vars > config file > defaults.
+ */
+function resolveConfig(fileConfig, overrides) {
+    return {
+        url: overrides.url ?? process.env.DATABASE_URL ?? fileConfig.url ?? '',
+        out: overrides.out ?? fileConfig.out ?? './generated/turbine',
+        schema: overrides.schema ?? fileConfig.schema ?? 'public',
+        include: overrides.include ?? fileConfig.include ?? [],
+        exclude: overrides.exclude ?? fileConfig.exclude ?? [],
+        migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
+        seedFile: fileConfig.seedFile ?? './turbine/seed.ts',
+        schemaFile: fileConfig.schemaFile ?? './turbine/schema.ts',
+    };
+}
+// ---------------------------------------------------------------------------
+// Config file template (for `turbine init`)
+// ---------------------------------------------------------------------------
+function configTemplate(connectionString) {
+    const _url = connectionString ?? 'process.env.DATABASE_URL';
+    const urlLine = connectionString ? `  url: '${connectionString}',` : `  url: process.env.DATABASE_URL,`;
+    return `import type { TurbineCliConfig } from 'turbine-orm/cli';
+
+/**
+ * Turbine configuration
+ * @see https://turbineorm.dev
+ */
+const config: TurbineCliConfig = {
+  /** Postgres connection string */
+${urlLine}
+
+  /** Output directory for generated types + client */
+  out: './generated/turbine',
+
+  /** Postgres schema to introspect (default: public) */
+  schema: 'public',
+
+  /** Tables to exclude from generation */
+  // exclude: ['_migrations', '_sessions'],
+
+  /** Directory for SQL migration files */
+  migrationsDir: './turbine/migrations',
+
+  /** Path to seed file */
+  seedFile: './turbine/seed.ts',
+
+  /** Path to schema builder file (for turbine push) */
+  schemaFile: './turbine/schema.ts',
+};
+
+export default config;
+`;
+}