turbine-orm 0.18.0 → 0.19.1

package/dist/cli/studio.d.ts

@@ -2,15 +2,20 @@
  * turbine-orm CLI — Studio
  *
  * A local, read-only web UI for browsing databases, exploring relations,
- * and running SELECT queries. Pure Node (built-in `http` module), no
- * runtime dependencies beyond `pg`, bound to 127.0.0.1 only.
+ * and composing queries visually. ORM-native since v0.19: there is no
+ * raw-SQL input surface — the Query tab builds `findMany` args that are
+ * validated against introspected metadata and compiled by QueryInterface
+ * (`/api/builder`). Pure Node (built-in `http` module), no runtime
+ * dependencies beyond `pg`, bound to 127.0.0.1 only.
  *
  * Security model:
  *   • Bind 127.0.0.1 only (never 0.0.0.0 — no LAN exposure)
  *   • Random auth token generated per process, required in Cookie header
- *   • SELECT/WITH-only guard on the query endpoint
+ *   • No SQL input surface at all — every identifier in a builder request is
+ *     validated against the introspected schema; all values are $N params
  *   • Every query runs in a READ ONLY transaction (belt-and-suspenders)
- *   • 30s statement timeout
+ *   • 30s statement timeout via parameterized set_config()
+ *   • Per-session rate limiting, CSP + security headers, cross-origin refusal
  *
  * Not implemented (deliberately): row editing, DDL, destructive operations.
  * Studio is for inspection. Use the CLI, migrate, or raw SQL for writes.

package/dist/cli/studio.js

@@ -2,15 +2,20 @@
  * turbine-orm CLI — Studio
  *
  * A local, read-only web UI for browsing databases, exploring relations,
- * and running SELECT queries. Pure Node (built-in `http` module), no
- * runtime dependencies beyond `pg`, bound to 127.0.0.1 only.
+ * and composing queries visually. ORM-native since v0.19: there is no
+ * raw-SQL input surface — the Query tab builds `findMany` args that are
+ * validated against introspected metadata and compiled by QueryInterface
+ * (`/api/builder`). Pure Node (built-in `http` module), no runtime
+ * dependencies beyond `pg`, bound to 127.0.0.1 only.
  *
  * Security model:
  *   • Bind 127.0.0.1 only (never 0.0.0.0 — no LAN exposure)
  *   • Random auth token generated per process, required in Cookie header
- *   • SELECT/WITH-only guard on the query endpoint
+ *   • No SQL input surface at all — every identifier in a builder request is
+ *     validated against the introspected schema; all values are $N params
  *   • Every query runs in a READ ONLY transaction (belt-and-suspenders)
- *   • 30s statement timeout
+ *   • 30s statement timeout via parameterized set_config()
+ *   • Per-session rate limiting, CSP + security headers, cross-origin refusal
  *
  * Not implemented (deliberately): row editing, DDL, destructive operations.
  * Studio is for inspection. Use the CLI, migrate, or raw SQL for writes.
@@ -140,6 +145,13 @@ async function handleRequest(req, res, ctx) {
         sendHtml(res, 200, STUDIO_HTML);
         return;
     }
+    // Favicon — answered before the auth gate so the browser's automatic request
+    // doesn't 401/404 on every load. No icon body needed (204).
+    if (pathname === '/favicon.ico') {
+        res.writeHead(204, { 'Content-Length': '0' });
+        res.end();
+        return;
+    }
     // API routes — all require auth.
     if (!isAuthorized(req, ctx.authToken)) {
         sendJson(res, 401, { error: 'unauthorized — use the URL printed in the terminal' });
@@ -160,9 +172,6 @@ async function handleRequest(req, res, ctx) {
         const rawName = decodeURIComponent(pathname.slice('/api/tables/'.length));
         return apiTableRows(res, ctx, rawName, url.searchParams);
     }
-    if (pathname === '/api/query' && req.method === 'POST') {
-        return apiQuery(req, res, ctx);
-    }
     if (pathname === '/api/builder' && req.method === 'POST') {
         return apiBuilder(req, res, ctx);
     }
@@ -222,6 +231,15 @@ function constantTimeEqual(a, b) {
     }
     return result === 0;
 }
+/**
+ * Build a helpful "unknown table" error that lists the available tables so the
+ * caller can spot a typo or schema mismatch immediately.
+ */
+function unknownTableMessage(name, ctx) {
+    const available = Object.keys(ctx.metadata.tables);
+    const list = available.length ? available.join(', ') : '(none)';
+    return `[turbine] Unknown table "${name}" in schema "${ctx.options.schema}". Available: ${list}`;
+}
 // ---------------------------------------------------------------------------
 // API: /api/schema
 // ---------------------------------------------------------------------------
@@ -254,7 +272,9 @@ async function apiSchema(res, ctx) {
      WHERE n.nspname = $1 AND c.relkind = 'r'`, [ctx.options.schema]);
     const counts = new Map();
     for (const row of countsResult.rows) {
-        counts.set(row.relname, Number(row.reltuples));
+        // pg_class.reltuples is -1 on PG14+ until a table is ANALYZEd; clamp so the
+        // sidebar never shows a negative estimate.
+        counts.set(row.relname, Math.max(0, Number(row.reltuples)));
     }
     sendJson(res, 200, {
         schema: ctx.options.schema,
@@ -268,7 +288,7 @@ async function apiSchema(res, ctx) {
 export async function apiTableRows(res, ctx, rawTableName, params) {
     const table = ctx.metadata.tables[rawTableName];
     if (!table) {
-        sendJson(res, 404, { error: `unknown table: ${rawTableName}` });
+        sendJson(res, 404, { error: unknownTableMessage(rawTableName, ctx) });
         return;
     }
     const limit = clampInt(params.get('limit'), 50, 1, 500);
@@ -363,54 +383,6 @@ export function escapeLikePattern(s) {
     return s.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
 }
 // ---------------------------------------------------------------------------
-// API: /api/query — read-only SELECT/WITH runner
-// ---------------------------------------------------------------------------
-async function apiQuery(req, res, ctx) {
-    const body = await readJsonBody(req);
-    const rawSql = typeof body?.sql === 'string' ? body.sql.trim() : '';
-    if (!rawSql) {
-        sendJson(res, 400, { error: 'missing sql' });
-        return;
-    }
-    if (rawSql.length > 10_000) {
-        sendJson(res, 400, { error: 'query too long — maximum 10,000 characters allowed' });
-        return;
-    }
-    if (!isReadOnlyStatement(rawSql)) {
-        sendJson(res, 400, {
-            error: 'only SELECT / WITH statements are allowed in Studio — use the CLI for writes',
-        });
-        return;
-    }
-    const client = await ctx.pool.connect();
-    try {
-        await client.query('BEGIN READ ONLY');
-        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
-        const started = Date.now();
-        const result = await client.query(rawSql);
-        const elapsedMs = Date.now() - started;
-        await client.query('COMMIT');
-        sendJson(res, 200, {
-            columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
-            rows: result.rows.map((r) => serializeRow(r)),
-            rowCount: result.rowCount ?? result.rows.length,
-            elapsedMs,
-        });
-    }
-    catch (err) {
-        try {
-            await client.query('ROLLBACK');
-        }
-        catch {
-            /* ignore */
-        }
-        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
-    }
-    finally {
-        client.release();
-    }
-}
-// ---------------------------------------------------------------------------
 // API: /api/builder — Turbine ORM findMany spec runner
 // ---------------------------------------------------------------------------
 export async function apiBuilder(req, res, ctx) {
@@ -418,7 +390,7 @@ export async function apiBuilder(req, res, ctx) {
     const tableName = typeof body?.table === 'string' ? body.table : '';
     const args = (body?.args ?? {});
     if (!tableName || !ctx.metadata.tables[tableName]) {
-        sendJson(res, 400, { error: `unknown table: ${tableName}` });
+        sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
     }
     let deferred;
@@ -438,6 +410,11 @@ export async function apiBuilder(req, res, ctx) {
     try {
         await client.query('BEGIN READ ONLY');
         await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+        // QueryInterface emits unqualified table identifiers, which resolve via
+        // the connection's search_path. Pin it to the configured --schema so the
+        // Query tab reads the same schema as the Data tab (set_config is
+        // transaction-local and fully parameterized).
+        await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
         const started = Date.now();
         const result = await client.query(deferred.sql, deferred.params);
         const elapsedMs = Date.now() - started;
@@ -466,6 +443,8 @@ export async function apiBuilder(req, res, ctx) {
 function savedQueriesPath(ctx) {
     return pathResolve(ctx.stateDir, 'studio-queries.json');
 }
+/** One-shot flag so the legacy saved-query notice isn't logged on every request. */
+let legacyDropNoticeShown = false;
 function loadSavedQueries(ctx) {
     const file = savedQueriesPath(ctx);
     if (!existsSync(file))
@@ -475,7 +454,17 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        return { version: 1, queries: parsed.queries };
+        // Drop any legacy raw-SQL entries — Studio is builder-only now. Tell the
+        // user instead of silently discarding their saved work (the file on disk
+        // is only rewritten when a new query is saved, so this is recoverable).
+        const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
+        const dropped = parsed.queries.length - queries.length;
+        if (dropped > 0 && !legacyDropNoticeShown) {
+            legacyDropNoticeShown = true;
+            console.warn(`[turbine studio] Ignoring ${dropped} legacy raw-SQL saved quer${dropped === 1 ? 'y' : 'ies'} in ${file} — ` +
+                'Studio is builder-only since v0.19. The entries remain in the file until a new query is saved.');
+        }
+        return { version: 1, queries };
     }
     catch {
         return { version: 1, queries: [] };
@@ -498,27 +487,17 @@ export async function apiCreateSavedQuery(req, res, ctx) {
     const body = await readJsonBody(req);
     const table = typeof body?.table === 'string' ? body.table : '';
     const name = typeof body?.name === 'string' ? body.name.trim() : '';
-    const kind = body?.kind === 'builder' ? 'builder' : body?.kind === 'sql' ? 'sql' : null;
     if (!table || !ctx.metadata.tables[table]) {
-        sendJson(res, 400, { error: `unknown table: ${table}` });
+        sendJson(res, 400, { error: unknownTableMessage(table, ctx) });
         return;
     }
     if (!name) {
         sendJson(res, 400, { error: 'name is required' });
         return;
     }
-    if (!kind) {
-        sendJson(res, 400, { error: 'kind must be "sql" or "builder"' });
-        return;
-    }
-    const sql = kind === 'sql' && typeof body?.sql === 'string' ? body.sql : undefined;
-    const args = kind === 'builder' ? body?.args : undefined;
-    if (kind === 'sql' && !sql) {
-        sendJson(res, 400, { error: 'sql is required for kind=sql' });
-        return;
-    }
-    if (kind === 'sql' && sql && !isReadOnlyStatement(sql)) {
-        sendJson(res, 400, { error: 'saved sql must be SELECT/WITH only' });
+    // Studio only persists visual-builder queries (no raw SQL surface).
+    if (body?.kind !== 'builder') {
+        sendJson(res, 400, { error: 'kind must be "builder"' });
         return;
     }
     const data = loadSavedQueries(ctx);
@@ -526,9 +505,8 @@ export async function apiCreateSavedQuery(req, res, ctx) {
         id: randomUUID(),
         table,
         name,
-        kind,
-        sql,
-        args,
+        kind: 'builder',
+        args: body?.args,
         createdAt: new Date().toISOString(),
     };
     data.queries.push(entry);

package/dist/client.js

@@ -202,6 +202,14 @@ export class TurbineClient {
     /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
     constructor(config = {}, schema) {
+        // Constructing without schema metadata previously crashed deep in the
+        // constructor with an opaque "Cannot read properties of undefined
+        // (reading 'tables')". Fail fast with an actionable message instead.
+        if (!schema || typeof schema !== 'object' || !schema.tables) {
+            throw new ValidationError('[turbine] TurbineClient requires schema metadata as its second argument. ' +
+                'Run `npx turbine generate` and use the generated client (`turbine()` from your output dir), ' +
+                'or pass the generated `schemaMetadata` object: new TurbineClient(config, schemaMetadata).');
+        }
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/query/builder.d.ts

@@ -402,6 +402,41 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Uses the target table's column mapping to resolve field names.
      */
     private buildSubWhereForRelation;
+    /**
+     * Resolve a column's Postgres type from an arbitrary table's metadata
+     * (relation targets, not just `this.table`).
+     */
+    private pgTypeForColumn;
+    /**
+     * Equality-fallthrough guard shared by every SQL-build path AND every
+     * cache-hit param-collect path. A plain object literal that matched no known
+     * filter shape on a non-JSON column is almost always a misspelled operator
+     * (`startWith` for `startsWith`); binding it as `col = $1` silently returns
+     * wrong rows. Class instances (Buffer for bytea, Decimal wrappers, ...) are
+     * legitimate bind values and pass through, as do objects on json/jsonb
+     * columns (object equality).
+     */
+    private assertBindableEqualityValue;
+    /**
+     * Build the user-supplied `where` filter of a relation `with` clause against
+     * the relation's table alias. Supports the same scalar surface as the
+     * top-level WHERE builder — equality, IS NULL, operator objects (incl.
+     * `mode: 'insensitive'`), and OR/AND/NOT combinators. Unknown operator
+     * objects throw via {@link assertBindableEqualityValue}.
+     *
+     * Param push order MUST mirror {@link collectAliasWhereParams} exactly, or
+     * cache hits and pipeline batching will desync.
+     */
+    private buildAliasWhere;
+    /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
+    private collectAliasWhereParams;
+    /**
+     * Value-invariant, shape-aware fingerprint for a relation `with` clause's
+     * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
+     * can emit — equality vs null vs operator sets vs combinators — or two
+     * differently-shaped wheres would share one cached SQL string.
+     */
+    private fingerprintAliasWhere;
     /**
      * Build SQL clauses for a single operator object on a column.
      * Each operator key becomes its own clause, all ANDed together.