turbine-orm 0.19.0 → 0.19.1

package/dist/cli/loader.js

@@ -8,9 +8,18 @@
  *
  * Strategy:
  *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
- *      probe whether `tsx/esm` is resolvable from the user's CWD.
- *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
- *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *      probe whether `tsx` is resolvable from the user's CWD.
+ *   2. Prefer tsx's supported programmatic API, `tsx/esm/api`'s `register()`.
+ *      Calling Node's `module.register('tsx/esm', ...)` directly throws
+ *      "tsx must be loaded with --import instead of --loader" on every Node
+ *      version that has `module.register()` (>= 20.6) — tsx's hook file
+ *      guards against being loaded that way. The `tsx/esm/api` entry point
+ *      is the documented path and works everywhere `module.register()` does.
+ *   3. Fall back to `module.register('tsx/esm', ...)` only for very old tsx
+ *      versions (< 4.0) that predate `tsx/esm/api`.
+ *   4. If tsx isn't installed, or registration genuinely fails, surface an
+ *      actionable error — including the REAL underlying error message, never
+ *      a misdiagnosed "tsx is not installed".
  *
  * `tsx` is intentionally NOT a runtime dependency — many projects already
  * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
@@ -50,6 +59,14 @@ export function canResolveTsx(resolver) {
     }
 }
 let tsLoaderState = null;
+let tsLoaderError = null;
+/**
+ * The underlying error message from the last failed registration attempt,
+ * or null. Lets the CLI report the REAL cause instead of guessing.
+ */
+export function getTsLoaderError() {
+    return tsLoaderError;
+}
 /**
  * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
  * work. Safe to call multiple times — internal flag prevents double registration.
@@ -57,17 +74,51 @@ let tsLoaderState = null;
  * Returns:
  *   - 'registered'  loader was successfully registered this call
  *   - 'already'     a loader was previously registered (idempotent)
- *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6) and tsx has
+ *                   no programmatic API to fall back to
  *   - 'missing'     `tsx` is not installed in the user's project
+ *   - 'failed'      tsx IS installed but registration threw — see
+ *                   {@link getTsLoaderError} for the underlying message
  */
 export async function registerTsLoader() {
     if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
         return 'already';
     }
+    const userRequire = createRequire(`${process.cwd()}/`);
+    // Preferred: tsx's supported programmatic API (tsx >= 4.0).
+    let apiPath = null;
+    try {
+        apiPath = userRequire.resolve('tsx/esm/api');
+    }
+    catch {
+        apiPath = null;
+    }
+    if (apiPath) {
+        try {
+            const api = (await import(pathToFileURL(apiPath).href));
+            if (typeof api.register !== 'function') {
+                throw new Error(`tsx/esm/api resolved at ${apiPath} but exports no register() function`);
+            }
+            api.register();
+            tsLoaderState = 'registered';
+            tsLoaderError = null;
+            return 'registered';
+        }
+        catch (err) {
+            tsLoaderState = 'failed';
+            tsLoaderError = err instanceof Error ? err.message : String(err);
+            return 'failed';
+        }
+    }
+    // tsx/esm/api not resolvable — is tsx installed at all?
     if (!canResolveTsx()) {
         tsLoaderState = 'missing';
         return 'missing';
     }
+    // Legacy fallback for tsx < 4.0 (no tsx/esm/api): Node's module.register.
+    // On tsx >= 4.19 this path throws ("tsx must be loaded with --import
+    // instead of --loader") — but those versions all ship tsx/esm/api, so we
+    // only land here for genuinely old installs.
     try {
         const mod = await import('node:module');
         const register = mod.register;
@@ -77,15 +128,18 @@ export async function registerTsLoader() {
         }
         register('tsx/esm', pathToFileURL(`${process.cwd()}/`));
         tsLoaderState = 'registered';
+        tsLoaderError = null;
         return 'registered';
     }
-    catch {
-        tsLoaderState = 'missing';
-        return 'missing';
+    catch (err) {
+        tsLoaderState = 'failed';
+        tsLoaderError = err instanceof Error ? err.message : String(err);
+        return 'failed';
     }
 }
 /** Reset the loader state — used by unit tests only. */
 export function _resetTsLoaderStateForTests() {
     tsLoaderState = null;
+    tsLoaderError = null;
 }
 //# sourceMappingURL=loader.js.map

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.
@@ -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 {

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.