turbine-orm 0.18.0 → 0.19.0

package/dist/cli/studio.js

@@ -140,6 +140,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 +167,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 +226,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 +267,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 +283,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 +378,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 +385,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;
@@ -475,7 +442,9 @@ 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.
+        const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
+        return { version: 1, queries };
     }
     catch {
         return { version: 1, queries: [] };
@@ -498,27 +467,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 +485,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/query/builder.js

@@ -1687,12 +1687,24 @@ export class QueryInterface {
      */
     resolveColumns(select, omit) {
         if (select) {
+            // An array here means a caller wrote `select: ['id', 'name']` (Drizzle/SQL
+            // style) instead of the object shape. Object.entries() would iterate the
+            // numeric indices and throw a cryptic `Unknown field "0"` — catch it early
+            // with an actionable message.
+            if (Array.isArray(select)) {
+                throw new ValidationError(`[turbine] "select" must be an object mapping field names to true ` +
+                    `(e.g. { id: true, name: true }), not an array.`);
+            }
             // Only include columns where value is true
             return Object.entries(select)
                 .filter(([, v]) => v)
                 .map(([k]) => this.toColumn(k));
         }
         if (omit) {
+            if (Array.isArray(omit)) {
+                throw new ValidationError(`[turbine] "omit" must be an object mapping field names to true ` +
+                    `(e.g. { createdAt: true }), not an array.`);
+            }
             // Include all columns except those where value is true
             const omitCols = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
@@ -2271,8 +2283,10 @@ export class QueryInterface {
                 params.push(v);
             }
         }
-        // limit param
-        if (spec.limit) {
+        // limit param — only hasMany parameterizes its limit (mirrors
+        // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
+        // pushing one here would orphan a param and desync the collect path.
+        if (relDef.type === 'hasMany' && spec.limit) {
             params.push(Number(spec.limit));
         }
         // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
@@ -2480,6 +2494,25 @@ export class QueryInterface {
                 andClauses.push(...opClauses);
                 continue;
             }
+            // Strict validation: a plain (non-array, non-Date) object on a non-JSON
+            // column matched no known filter shape — almost always a misspelled
+            // operator (`startWith` for `startsWith`) or a stray nested object.
+            // Silently treating it as `col = $1` returns wrong rows with no error, so
+            // throw with the offending keys and the supported operator list. JSON/JSONB
+            // columns legitimately accept object values for equality, so they fall
+            // through unchanged.
+            if (typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+                const colType = this.getColumnPgType(rawColumn);
+                if (colType !== 'json' && colType !== 'jsonb') {
+                    const badKeys = Object.keys(value);
+                    throw new ValidationError(badKeys.length === 0
+                        ? `[turbine] Empty filter object on "${rawColumn}" for table "${this.table}". ` +
+                            `Provide a value or an operator like { gt: 1 }.`
+                        : `[turbine] Unknown operator${badKeys.length > 1 ? 's' : ''} ` +
+                            `${badKeys.map((k) => `"${k}"`).join(', ')} on "${rawColumn}" for table "${this.table}". ` +
+                            `Supported operators: ${[...OPERATOR_KEYS].join(', ')}.`);
+                }
+            }
             // Plain equality
             params.push(value);
             andClauses.push(`${column} = ${this.p(params.length)}`);
@@ -2663,7 +2696,8 @@ export class QueryInterface {
         return Object.entries(orderBy)
             .map(([key, dir]) => {
             if (meta && !(key in meta.columnMap)) {
-                throw new ValidationError(`Unknown column "${key}" in orderBy for table "${this.table}"`);
+                throw new ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${this.table}". ` +
+                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
             }
             // Vector KNN ordering: { distance: { to, metric, direction? } }
             if (isVectorOrderBy(dir)) {
@@ -3092,9 +3126,13 @@ export class QueryInterface {
                 whereClause += ` AND ${alias}.${this.q(col)} = ${this.p(params.length)}`;
             }
         }
-        // LIMIT
+        // LIMIT — only meaningful for hasMany. A belongsTo / hasOne subquery returns
+        // a single row (literal `LIMIT 1` below), so a `spec.limit` here must NOT push
+        // a parameter: doing so orphans an untyped `$N` that the SQL never references,
+        // which Postgres rejects with "could not determine data type of parameter $N"
+        // (and shifts every later placeholder by one). To-one relations ignore limit.
         let limitClause = '';
-        if (spec !== true && spec.limit) {
+        if (relDef.type === 'hasMany' && spec !== true && spec.limit) {
             params.push(Number(spec.limit));
             limitClause = ` LIMIT ${this.p(params.length)}`;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.18.0",
+  "version": "0.19.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": {