turbine-orm 0.19.0 → 0.19.2

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.
@@ -74,14 +79,4 @@ export declare function apiBuilder(req: IncomingMessage, res: ServerResponse, ct
 export declare function apiListSavedQueries(res: ServerResponse, ctx: StudioContext, params: URLSearchParams): void;
 export declare function apiCreateSavedQuery(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
 export declare function apiDeleteSavedQuery(res: ServerResponse, ctx: StudioContext, id: string): void;
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-export declare function isReadOnlyStatement(sql: string): boolean;
 //# sourceMappingURL=studio.d.ts.map

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.
@@ -405,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;
@@ -433,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))
@@ -442,8 +454,16 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        // Drop any legacy raw-SQL entries — Studio is builder-only now.
+        // 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 {
@@ -515,35 +535,6 @@ function clampInt(value, fallback, min, max) {
         return fallback;
     return Math.min(Math.max(n, min), max);
 }
-/**
- * Accept only SELECT or WITH (CTE) statements. Reject any statement that
- * contains a semicolon followed by non-whitespace (prevents statement
- * stacking), and require the first non-comment keyword to be SELECT or WITH.
- *
- * This is a first-line filter — the transaction's READ ONLY mode is the
- * second line of defense. Both must fail before a destructive statement
- * could run.
- */
-export function isReadOnlyStatement(sql) {
-    const stripped = stripSqlComments(sql).trim();
-    if (!stripped)
-        return false;
-    // Disallow statement stacking. A single trailing `;` is fine.
-    const withoutTrailingSemi = stripped.replace(/;+\s*$/, '');
-    if (withoutTrailingSemi.includes(';'))
-        return false;
-    const firstWord = withoutTrailingSemi.slice(0, 6).toUpperCase();
-    if (firstWord.startsWith('SELECT'))
-        return true;
-    if (firstWord.startsWith('WITH'))
-        return true;
-    return false;
-}
-function stripSqlComments(sql) {
-    // Strip -- line comments and /* block comments */. Not a full SQL parser,
-    // but sufficient to catch the common bypass attempts.
-    return sql.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
-}
 function serializeRow(row) {
     const out = {};
     for (const [k, v] of Object.entries(row)) {

package/dist/client.d.ts

@@ -255,12 +255,14 @@ export declare class TurbineClient {
     private readonly activeSubscriptions;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      *
      * @example
      * ```ts
@@ -272,16 +274,13 @@ export declare class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */

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).
@@ -315,12 +323,14 @@ export class TurbineClient {
     // Middleware — intercept all queries
     // -------------------------------------------------------------------------
     /**
-     * Register a middleware function that runs before/after every query.
+     * Register a middleware function that runs around every query.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      *
      * @example
      * ```ts
@@ -332,16 +342,13 @@ export class TurbineClient {
      *   return result;
      * });
      *
-     * // Soft-delete middleware
+     * // Result transformation middleware — redact a field on the way out
      * db.$use(async (params, next) => {
-     *   if (params.action === 'findMany' || params.action === 'findUnique') {
-     *     params.args.where = { ...params.args.where, deletedAt: null };
-     *   }
-     *   if (params.action === 'delete') {
-     *     params.action = 'update';
-     *     params.args = { where: params.args.where, data: { deletedAt: new Date() } };
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
      *   }
-     *   return next(params);
+     *   return result;
      * });
      * ```
      */

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 CreateDataInput, 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 NestedUpdateOpItem, type NestedUpsertOpItem, 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 UpdateDataInput, 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

@@ -168,10 +168,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
      *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
      */
     private executeWithMiddleware;
     findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
@@ -228,11 +230,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
     findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
     buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
-    create(args: CreateArgs<T>): Promise<T>;
+    create(args: CreateArgs<T, R>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
-    update(args: UpdateArgs<T>): Promise<T>;
+    update(args: UpdateArgs<T, R>): Promise<T>;
     buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
     private nestedCreate;
     private nestedUpdate;
@@ -402,6 +404,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.