turbine-orm 0.8.0 → 0.9.1

package/README.md

@@ -8,7 +8,7 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-Turbine is a PostgreSQL-native TypeScript ORM with features no other ORM offers together: **deep typed `with` inference** (`users[0].posts[0].comments[0].author` autocompletes after one `findMany`), **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.
+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.
 
 **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.
 
@@ -34,7 +34,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 **inferred `with` result types** — `users[0].posts[0].comments[0].author.name` autocompletes from a single `findMany` with no manual assertion.
+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`
@@ -381,6 +381,7 @@ Commands:
   migrate status               Show applied/pending migrations
   seed                         Run seed file
   status                       Show database schema summary
+  studio                       Launch local read-only Studio web UI
 
 Options:
   --url, -u <url>       Postgres connection string
@@ -436,6 +437,32 @@ npx turbine migrate down
 npx turbine migrate status
 ```
 
+## Studio
+
+The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, no way around the transaction guard.
+
+```bash
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine studio
+# With flags
+npx turbine studio --port 5173 --host 127.0.0.1 --no-open
+```
+
+**Features**
+
+- **Data / Schema / SQL / Builder tabs.** Browse rows, inspect tables and relations, run ad-hoc `SELECT`s, or compose queries visually with a live TypeScript preview.
+- **Saved queries.** Named SQL snippets persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
+- **Cmd+K command palette.** Jump to any table, tab, or saved query in one keystroke.
+- **Full-text search across rows.** The Data tab supports substring search across every text column of the current table.
+- **Visual query composer.** The Builder tab lets you click together `where` / `orderBy` / `with` / `limit` clauses and renders the matching `db.table.findMany(...)` TypeScript in real time — copy it into your codebase.
+
+**Security posture (read-only by design)**
+
+- **Loopback by default** (`127.0.0.1`) with a loud warning if you bind to a non-loopback address.
+- **Per-process auth token** — 24 random bytes of hex, stored in a `SameSite=Strict` `HttpOnly` cookie.
+- **Every query runs inside `BEGIN READ ONLY` + `SET LOCAL statement_timeout = '30s'`.** Writes are physically impossible at the transaction level.
+- **SELECT/WITH-only SQL parser** strips comments and rejects non-trailing semicolons, blocking statement-stacking attacks.
+- **Security headers on every response** — `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`.
+
 ## 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.
@@ -533,9 +560,9 @@ 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 `with` clause is fully type-inferred end-to-end — `users[0].posts[0].comments[0].author.name` autocompletes from a single `findMany` call, with no manual type assertions.
+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. One runtime dependency (`pg`), no DSL compiler, no driver adapter shim for edge, and deep `with` type inference without verbose helper types.
+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.
 
 ## Type Mapping
 
@@ -573,7 +600,6 @@ Turbine is focused and opinionated. Here's what it doesn't do:
 - **PostgreSQL only.** No MySQL, SQLite, or MSSQL. By design — going deep on one database enables the performance advantage and the edge-runtime story.
 - **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.** Nested results are materialized server-side in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause — or stream the parents with `findManyStream` and resolve children per-row.
-- **No admin UI.** Turbine Studio is planned but not yet available.
 
 ## Examples
 

package/dist/cjs/cli/index.js

@@ -13,7 +13,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
- *   turbine studio                — Launch web UI (coming soon)
+ *   turbine studio                — Launch local read-only web UI
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -63,6 +63,7 @@ const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
 const loader_js_1 = require("./loader.js");
 const migrate_js_1 = require("./migrate.js");
+const studio_js_1 = require("./studio.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -129,6 +130,17 @@ function parseArgs() {
             case '-h':
                 result.help = true;
                 break;
+            case '--port':
+                result.port = next ? Number.parseInt(next, 10) : undefined;
+                i++;
+                break;
+            case '--host':
+                result.host = next;
+                i++;
+                break;
+            case '--no-open':
+                result.noOpen = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -925,19 +937,71 @@ async function cmdStatus(_args, config) {
     }
 }
 // ---------------------------------------------------------------------------
-// Command: studio (scaffold)
+// Command: studio — local read-only web UI
 // ---------------------------------------------------------------------------
-async function cmdStudio(_args, _config) {
+async function cmdStudio(args, config) {
     (0, ui_js_1.banner)();
+    const url = requireUrl(config);
+    const port = args.port ?? 4983;
+    const host = args.host ?? '127.0.0.1';
+    const openBrowser = !args.noOpen;
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        console.log((0, ui_js_1.red)(`✗ invalid port: ${args.port}`));
+        process.exit(1);
+    }
+    // Refuse to bind anything other than loopback unless explicitly overridden.
+    // This is deliberate: Studio has no real authentication beyond a random
+    // session token, so exposing it on a LAN interface is foot-gun territory.
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+        console.log((0, ui_js_1.warn)(`Studio is binding to ${(0, ui_js_1.yellow)(host)} — this is NOT loopback. ` +
+            `Anyone on your network who can reach this port + guess the session token can read your database.`));
+    }
+    const spinner = new ui_js_1.Spinner('Introspecting database').start();
+    let studio;
+    try {
+        studio = await (0, studio_js_1.startStudio)({
+            url,
+            schema: config.schema,
+            port,
+            host,
+            openBrowser,
+            include: config.include.length ? config.include : undefined,
+            exclude: config.exclude.length ? config.exclude : undefined,
+        });
+        spinner.succeed(`Studio is running`);
+    }
+    catch (err) {
+        spinner.fail(`Failed to start Studio: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    (0, ui_js_1.newline)();
     console.log((0, ui_js_1.box)([
-        `${(0, ui_js_1.bold)('Turbine Studio')} ${(0, ui_js_1.dim)('— coming soon')}`,
+        `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)('— local read-only UI')}`,
         '',
-        'A local web UI for browsing your database,',
-        'exploring relations, and managing data.',
+        `  ${(0, ui_js_1.cyan)('URL:')}    ${(0, ui_js_1.bold)(studio.url)}`,
+        `  ${(0, ui_js_1.cyan)('Schema:')} ${config.schema}`,
+        `  ${(0, ui_js_1.cyan)('DB:')}     ${(0, ui_js_1.redactUrl)(url)}`,
         '',
-        `Follow ${(0, ui_js_1.cyan)('@turbineorm')} for updates.`,
-    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio')), padding: 2 }));
+        (0, ui_js_1.dim)('Open the URL above in your browser. It includes a one-time session'),
+        (0, ui_js_1.dim)('token that gets set as an HttpOnly cookie on first load.'),
+        (0, ui_js_1.dim)('Press Ctrl+C to stop.'),
+    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio')), padding: 1 }));
     (0, ui_js_1.newline)();
+    // Wait forever until SIGINT/SIGTERM, then dispose cleanly.
+    await new Promise((resolve) => {
+        const shutdown = async () => {
+            console.log((0, ui_js_1.dim)('\n  shutting down…'));
+            try {
+                await studio.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve();
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
 }
 // ---------------------------------------------------------------------------
 // Subcommand help
@@ -1086,7 +1150,7 @@ function showHelp() {
     console.log(`      ${(0, ui_js_1.dim)('status')}           Show applied/pending migrations`);
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}     Show schema summary`);
-    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch web UI (coming soon)`);
+    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}      Postgres connection string`);
@@ -1098,6 +1162,11 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}        Show detailed output`);
     console.log(`    ${(0, ui_js_1.cyan)('--force, -f')}          Overwrite existing files`);
     (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Studio options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}           HTTP port ${(0, ui_js_1.dim)('(default: 4983)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}        Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-open')}            Don't auto-open the browser`);
+    (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Config file:')}`);
     console.log(`    ${(0, ui_js_1.dim)('Create')} ${(0, ui_js_1.cyan)('turbine.config.ts')} ${(0, ui_js_1.dim)('with')} ${(0, ui_js_1.cyan)('npx turbine init')}`);
     console.log(`    ${(0, ui_js_1.dim)('CLI flags override config file values.')}`);
@@ -1114,7 +1183,30 @@ function showHelp() {
 // Version
 // ---------------------------------------------------------------------------
 function showVersion() {
-    console.log(`turbine-orm v0.5.0`);
+    // Walk up from the running script to find the turbine-orm package.json.
+    // Using process.argv[1] instead of import.meta.url so the same code compiles
+    // cleanly for both the ESM and CJS builds.
+    try {
+        let dir = (0, node_path_1.dirname)(process.argv[1] ?? '');
+        for (let i = 0; i < 6; i++) {
+            const candidate = (0, node_path_1.resolve)(dir, 'package.json');
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                const pkg = JSON.parse((0, node_fs_1.readFileSync)(candidate, 'utf8'));
+                if (pkg.name === 'turbine-orm') {
+                    console.log(`turbine-orm v${pkg.version ?? '?'}`);
+                    return;
+                }
+            }
+            const parent = (0, node_path_1.dirname)(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        console.log(`turbine-orm`);
+    }
+    catch {
+        console.log(`turbine-orm`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Main

package/dist/cjs/cli/migrate.js

@@ -24,6 +24,7 @@ exports.listMigrationFiles = listMigrationFiles;
 exports.parseMigrationContent = parseMigrationContent;
 exports.parseMigrationSQL = parseMigrationSQL;
 exports.createMigration = createMigration;
+exports.deriveLockId = deriveLockId;
 exports.migrateUp = migrateUp;
 exports.migrateDown = migrateDown;
 exports.migrateStatus = migrateStatus;
@@ -218,16 +219,44 @@ ${autoContent.down}
 // ---------------------------------------------------------------------------
 // Advisory lock for concurrent migration safety
 // ---------------------------------------------------------------------------
-/** Fixed lock ID for Turbine migrations — prevents concurrent migrate runs */
-const MIGRATION_LOCK_ID = 8_347_291; // arbitrary but stable
-async function acquireLock(client) {
-    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [
-        MIGRATION_LOCK_ID,
-    ]);
-    return result.rows[0]?.pg_try_advisory_lock ?? false;
+/**
+ * Derive a Postgres advisory lock ID (positive int4) from the database name.
+ *
+ * Uses FNV-1a 32-bit hash — a well-known, stable, non-cryptographic hash with
+ * excellent distribution over short strings (database names are typically <64
+ * chars). Chosen over alternatives because it's:
+ *   - deterministic (same input → same output, across processes/machines)
+ *   - tiny (two lines, no allocations, no imports)
+ *   - well-distributed (low collision rate for typical DB-name distributions)
+ *
+ * The top bit is cleared so the result fits in a positive int4, which is the
+ * range `pg_advisory_lock` expects for the single-argument form. Two databases
+ * in the same Postgres cluster can now run `turbine migrate` concurrently
+ * without contending on a single hardcoded lock ID.
+ */
+function deriveLockId(databaseName) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < databaseName.length; i++) {
+        hash ^= databaseName.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 1; // positive int4 (top bit cleared)
+}
+/**
+ * Fetch the current database name from the connected client. Used to derive
+ * the advisory lock ID so concurrent migrations in sibling databases do not
+ * contend on one another.
+ */
+async function getCurrentDatabaseName(client) {
+    const result = await client.query(`SELECT current_database()`);
+    return result.rows[0]?.current_database ?? '';
+}
+async function acquireLock(client, lockId) {
+    const result = await client.query(`SELECT pg_try_advisory_lock($1) AS locked`, [lockId]);
+    return result.rows[0]?.locked ?? false;
 }
-async function releaseLock(client) {
-    await client.query(`SELECT pg_advisory_unlock($1)`, [MIGRATION_LOCK_ID]);
+async function releaseLock(client, lockId) {
+    await client.query(`SELECT pg_advisory_unlock($1)`, [lockId]);
 }
 /**
  * Validate that applied migration files have not been modified or deleted since they were run.
@@ -290,8 +319,12 @@ async function migrateUp(connectionString, migrationsDir, options) {
     // Treat `force` as an alias for `allowDrift` for backwards compatibility.
     const allowDrift = options?.allowDrift === true || options?.force === true;
     try {
+        // Derive an advisory lock ID per-database so concurrent migrations in
+        // sibling databases on the same Postgres cluster do not contend.
+        const dbName = await getCurrentDatabaseName(client);
+        const lockId = deriveLockId(dbName);
         // Acquire advisory lock to prevent concurrent migrations
-        const gotLock = await acquireLock(client);
+        const gotLock = await acquireLock(client, lockId);
         if (!gotLock) {
             throw new errors_js_1.MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
@@ -363,7 +396,7 @@ async function migrateUp(connectionString, migrationsDir, options) {
             return { applied: results, errors };
         }
         finally {
-            await releaseLock(client);
+            await releaseLock(client, lockId);
         }
     }
     finally {
@@ -382,7 +415,11 @@ async function migrateDown(connectionString, migrationsDir, options) {
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();
     try {
-        const gotLock = await acquireLock(client);
+        // Derive a per-database advisory lock ID so concurrent migrations in
+        // sibling databases on the same cluster do not contend.
+        const dbName = await getCurrentDatabaseName(client);
+        const lockId = deriveLockId(dbName);
+        const gotLock = await acquireLock(client, lockId);
         if (!gotLock) {
             throw new errors_js_1.MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
@@ -429,7 +466,7 @@ async function migrateDown(connectionString, migrationsDir, options) {
             return { rolledBack: results, errors };
         }
         finally {
-            await releaseLock(client);
+            await releaseLock(client, lockId);
         }
     }
     finally {