turbine-orm 0.9.0 → 0.9.2

package/README.md

@@ -1,6 +1,6 @@
 # turbine-orm
 
-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.
+Postgres ORM built for the edge. One runtime dependency. Built-in read-only Studio. Code-first and DB-first schema workflows in the same CLI. Runs on **Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase**, and any pg-compatible driver.
 
 ```
 npm install turbine-orm
@@ -8,9 +8,14 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-Turbine is a PostgreSQL-native TypeScript ORM built around features no other ORM bundles together: a **read-only, DBA-approvable Studio web UI** (the only one in the TS ORM ecosystem — `BEGIN READ ONLY` + statement-stacking guard + loopback-only + 24-byte auth token), **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. 1 runtime dependency (`pg`), ~110KB on npm.
+The elevator pitch: **a Prisma-like DX without Prisma's engine, a Drizzle-class runtime footprint, and the only built-in read-only Studio in the TS ORM ecosystem.** Four things bundled together that no other ORM bundles:
 
-**One round-trip for nested relations.** `db.users.findMany({ with: { posts: { with: { comments: true } } } })` resolves the entire object graph in a single database round-trip, regardless of nesting depth. Prisma 7+ and Drizzle v2 also do single-query nested loads — Turbine's advantage is architectural simplicity: 1 dependency, no code generation DSL, no query plan compiler.
+1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no code-generation DSL. ~110 KB on npm. 5 KB on the edge entry.
+2. **First-class edge support.** `turbineHttp(pool, schema)` — one import swap — and the full API runs on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No extra adapter package, no WASM bundle.
+3. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound, token-authed web UI with `BEGIN READ ONLY` + statement-stacking guard. DBA-approvable. No separate install.
+4. **Code-first and DB-first in the same CLI.** `defineSchema()` in TypeScript *or* `npx turbine pull` against a live database — same generated client, same migrations runner. Prisma forces the DSL; Drizzle is code-only.
+
+Plus the architectural bits you'd expect: pipeline batching (N queries in one round-trip via the pg extended-query protocol), `json_agg`-based nested relation loading (same technique Drizzle and Prisma 7 use — no N+1), deep `with` type inference, streaming cursors, typed error hierarchy with `isRetryable` discriminants, middleware.
 
 ## Benchmarks
 
@@ -34,7 +39,7 @@ Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizz
 - **Streaming 50K rows.** Turbine's optimized streaming (speculative first fetch + batch size 1000) matches Prisma at ~3.1–3.2 s. Drizzle's keyset pagination is 1.49× slower at 4.6 s. Turbine's cursor still gives you correctness on any `orderBy` and clean early-`break` semantics.
 - **Pipeline batching** puts 5 independent queries through a single round-trip using the Postgres extended-query pipeline protocol — all three ORMs are tied here since each runs 5 queries sequentially in a transaction.
 
-Beyond the numbers, Turbine's real strengths are: **one runtime dependency** (`pg`, ~110 KB), a **single import swap** for edge runtimes (`turbine-orm/serverless`), **typed Postgres errors** with a `readonly isRetryable` const for retry loops, and the **read-only Studio** web UI that ships in the CLI — the only one in the TS ORM ecosystem that physically cannot mutate your database. Deep type inference through `with` clauses is runtime-correct today (the relations are nested for you in a single round-trip) and lands at the type level in v1.0 — see the tracking issue for progress.
+Beyond the numbers, Turbine's real strengths are: **one runtime dependency** (`pg`, ~110 KB), a **single import swap** for edge runtimes (`turbine-orm/serverless`), **typed Postgres errors** with a `readonly isRetryable` const for retry loops, and the **read-only Studio** web UI that ships in the CLI — the only one in the TS ORM ecosystem that physically cannot mutate your database. And deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes — no manual assertion, no `*With*` helper interfaces.
 
 > Full analysis with p50/p95/p99 and methodology notes: [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md).
 > Reproduce: `cd benchmarks && npm install && npx prisma generate && DATABASE_URL=... npx tsx bench.ts`
@@ -560,7 +565,7 @@ Priority order: CLI flags > environment variables (`DATABASE_URL`) > config file
 
 ## How It Works
 
-Turbine resolves the entire object graph in a single database round-trip, regardless of nesting depth. The runtime nests relations for you via `json_agg` — one round-trip, no N+1, no client-side stitching. Deep `with` type inference at the TypeScript level (so `users[0].posts[0].comments[0].author.name` autocompletes without a manual assertion) is the last piece landing in v1.0; today, the generated `*With*` helper interfaces let you annotate the return type when you need the nested shape to narrow.
+Turbine resolves the entire object graph in a single database round-trip, regardless of nesting depth. The runtime nests relations for you via `json_agg` — one round-trip, no N+1, no client-side stitching. And the `with` clause is fully type-inferred: the generator emits branded `*Relations` interfaces with `RelationDescriptor` phantom fields, and a recursive `WithResult<T, R, W>` conditional type walks an arbitrarily-deep `with` literal to produce the exact nested return shape. Write `db.users.findMany({ with: { posts: { with: { comments: { with: { author: true } } } } } })` and `users[0].posts[0].comments[0].author.name` autocompletes — no manual assertion, no `*With*` helper annotation.
 
 Prisma 7+ and Drizzle v2 also do single-query nested loads. Turbine's advantage isn't query latency (see [Benchmarks](#benchmarks) — all three are within noise over a real pooled database); it's architectural simplicity plus the read-only Studio. One runtime dependency (`pg`), no DSL compiler, no driver adapter shim for edge, and the only TS ORM Studio your DBA will approve.
 

package/dist/cjs/cli/migrate.js

@@ -33,12 +33,12 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
 const errors_js_1 = require("../errors.js");
-const query_js_1 = require("../query.js");
+const index_js_1 = require("../query/index.js");
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
 const TRACKING_TABLE = '_turbine_migrations';
-const QUOTED_TRACKING_TABLE = (0, query_js_1.quoteIdent)(TRACKING_TABLE);
+const QUOTED_TRACKING_TABLE = (0, index_js_1.quoteIdent)(TRACKING_TABLE);
 const CREATE_TRACKING_TABLE = `
   CREATE TABLE IF NOT EXISTS ${QUOTED_TRACKING_TABLE} (
     id SERIAL PRIMARY KEY,

package/dist/cjs/cli/studio.js

@@ -38,7 +38,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
 const introspect_js_1 = require("../introspect.js");
-const query_js_1 = require("../query.js");
+const index_js_1 = require("../query/index.js");
 const studio_ui_generated_js_1 = require("./studio-ui.generated.js");
 // ---------------------------------------------------------------------------
 // Main entry point
@@ -259,10 +259,10 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     if (orderByRaw) {
         const col = resolveColumnName(table, orderByRaw);
         if (col)
-            orderByClause = `ORDER BY ${(0, query_js_1.quoteIdent)(col)} ${dir}`;
+            orderByClause = `ORDER BY ${(0, index_js_1.quoteIdent)(col)} ${dir}`;
     }
     if (!orderByClause && table.primaryKey.length > 0 && table.primaryKey[0]) {
-        orderByClause = `ORDER BY ${(0, query_js_1.quoteIdent)(table.primaryKey[0])} ${dir}`;
+        orderByClause = `ORDER BY ${(0, index_js_1.quoteIdent)(table.primaryKey[0])} ${dir}`;
     }
     // Full-text-ish search: ILIKE across text/varchar columns. The value is
     // parameterized so injection is impossible. Each query gets its own
@@ -276,7 +276,7 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     let mainWhere = '';
     if (hasSearch && pattern !== null) {
         mainValues.push(pattern);
-        const conds = textColumns.map((c) => `${(0, query_js_1.quoteIdent)(c)} ILIKE $3`);
+        const conds = textColumns.map((c) => `${(0, index_js_1.quoteIdent)(c)} ILIKE $3`);
         mainWhere = `WHERE (${conds.join(' OR ')})`;
     }
     // Count query: $1 = pattern (if search)
@@ -284,10 +284,10 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     let countWhere = '';
     if (hasSearch && pattern !== null) {
         countValues.push(pattern);
-        const conds = textColumns.map((c) => `${(0, query_js_1.quoteIdent)(c)} ILIKE $1`);
+        const conds = textColumns.map((c) => `${(0, index_js_1.quoteIdent)(c)} ILIKE $1`);
         countWhere = `WHERE (${conds.join(' OR ')})`;
     }
-    const qualifiedTable = `${(0, query_js_1.quoteIdent)(ctx.options.schema)}.${(0, query_js_1.quoteIdent)(table.name)}`;
+    const qualifiedTable = `${(0, index_js_1.quoteIdent)(ctx.options.schema)}.${(0, index_js_1.quoteIdent)(table.name)}`;
     const sql = `SELECT * FROM ${qualifiedTable} ${mainWhere} ${orderByClause} LIMIT $1 OFFSET $2`;
     const countSql = `SELECT COUNT(*)::text AS count FROM ${qualifiedTable} ${countWhere}`;
     const client = await ctx.pool.connect();
@@ -397,7 +397,7 @@ async function apiBuilder(req, res, ctx) {
     }
     let deferred;
     try {
-        const qi = new query_js_1.QueryInterface(ctx.pool, tableName, ctx.metadata, [], {
+        const qi = new index_js_1.QueryInterface(ctx.pool, tableName, ctx.metadata, [], {
             warnOnUnlimited: false,
             sqlCache: false,
             preparedStatements: false,

package/dist/cjs/client.js

@@ -30,7 +30,7 @@ exports.TurbineClient = exports.TransactionClient = void 0;
 const pg_1 = __importDefault(require("pg"));
 const errors_js_1 = require("./errors.js");
 const pipeline_js_1 = require("./pipeline.js");
-const query_js_1 = require("./query.js");
+const index_js_1 = require("./query/index.js");
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
     ReadUncommitted: 'READ UNCOMMITTED',
@@ -79,7 +79,7 @@ class TransactionClient {
             // Create a QueryInterface that uses the transaction client as its "pool"
             // We use a proxy pool that routes queries through the transaction client
             const txPool = this.createTxPool();
-            qi = new query_js_1.QueryInterface(txPool, name, this.schema, this.middlewares, this.queryOptions);
+            qi = new index_js_1.QueryInterface(txPool, name, this.schema, this.middlewares, this.queryOptions);
             this.tableCache.set(name, qi);
         }
         return qi;
@@ -306,7 +306,7 @@ class TurbineClient {
     table(name) {
         let qi = this.tableCache.get(name);
         if (!qi) {
-            qi = new query_js_1.QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
+            qi = new index_js_1.QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
             this.tableCache.set(name, qi);
         }
         return qi;

package/dist/cjs/index.js

@@ -71,8 +71,8 @@ var pipeline_js_1 = require("./pipeline.js");
 Object.defineProperty(exports, "executePipeline", { enumerable: true, get: function () { return pipeline_js_1.executePipeline; } });
 Object.defineProperty(exports, "pipelineSupported", { enumerable: true, get: function () { return pipeline_js_1.pipelineSupported; } });
 // Query builder
-var query_js_1 = require("./query.js");
-Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return query_js_1.QueryInterface; } });
+var index_js_1 = require("./query/index.js");
+Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_1.QueryInterface; } });
 // Schema utilities
 var schema_js_1 = require("./schema.js");
 Object.defineProperty(exports, "camelToSnake", { enumerable: true, get: function () { return schema_js_1.camelToSnake; } });