turbine-orm 0.28.0 → 0.28.2

package/dist/cjs/query/deferred.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * turbine-orm — Deferred query + QueryInterface option types
+ *
+ * Split from builder.ts so the class file focuses on SQL assembly / execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/query/filters.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * turbine-orm — Where-filter type guards and shape helpers
+ *
+ * Pure detection / fingerprint utilities used by the query builder's WHERE
+ * compiler. Kept out of builder.ts so the class file stays about SQL assembly
+ * and execution rather than filter-shape bookkeeping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_DISTANCE_COMPARATORS = exports.VECTOR_METRIC_OPERATORS = exports.TEXT_SEARCH_KEYS = exports.ARRAY_UNIQUE_KEYS = exports.ARRAY_OPERATOR_KEYS = exports.JSONB_UNIQUE_KEYS = exports.JSONB_OPERATOR_KEYS = exports.UPDATE_OPERATOR_KEYS = void 0;
+exports.isWhereOperator = isWhereOperator;
+exports.isUnmatchedPlainObject = isUnmatchedPlainObject;
+exports.fingerprintOperatorShape = fingerprintOperatorShape;
+exports.assertBindableEqualsOperand = assertBindableEqualsOperand;
+exports.sortedKeys = sortedKeys;
+exports.sortedEntries = sortedEntries;
+exports.isJsonFilter = isJsonFilter;
+exports.findJsonUniqueKey = findJsonUniqueKey;
+exports.isArrayFilter = isArrayFilter;
+exports.findArrayUniqueKey = findArrayUniqueKey;
+exports.isTextSearchFilter = isTextSearchFilter;
+exports.validateTextSearchConfig = validateTextSearchConfig;
+exports.isVectorFilter = isVectorFilter;
+exports.isVectorOrderBy = isVectorOrderBy;
+exports.isOrderBySpec = isOrderBySpec;
+exports.normalizeOrderBy = normalizeOrderBy;
+const errors_js_1 = require("../errors.js");
+const utils_js_1 = require("./utils.js");
+// ---------------------------------------------------------------------------
+// Where-operator detection
+// ---------------------------------------------------------------------------
+/** Check if a value is a where operator object (has at least one known operator key) */
+function isWhereOperator(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k) => utils_js_1.OPERATOR_KEYS.has(k));
+}
+/**
+ * True for a *plain object literal* that reached an equality fallthrough
+ * without matching any known filter shape — the misspelled-operator case.
+ * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
+ * bind values and return false, as do arrays and Dates.
+ */
+function isUnmatchedPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
+ * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
+ * param pushed), so null-ness is part of the shape — without it a cache entry
+ * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ */
+function fingerprintOperatorShape(value) {
+    const obj = value;
+    const opKeys = Object.keys(obj)
+        .filter((k) => k !== 'mode')
+        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .sort();
+    const modeStr = value.mode === 'insensitive' ? ':i' : '';
+    return `op(${opKeys.join(',')}${modeStr})`;
+}
+/**
+ * Guard for the value of an `equals` operator reaching the plain-equality
+ * operator path. A plain object literal can only legitimately be an equality
+ * value on a json/jsonb column — and those route to the JSONB filter branch
+ * BEFORE the operator branch, so any plain object that reaches here is a
+ * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
+ * SQL-build path and the cache-hit param-collect path so a warmed cache can
+ * never skip the check.
+ */
+function assertBindableEqualsOperand(value, column) {
+    if (!isUnmatchedPlainObject(value))
+        return;
+    throw new errors_js_1.ValidationError(`[turbine] Plain-object value for operator 'equals' on ${column}: ` +
+        `objects are only valid 'equals' values on JSON (json/jsonb) columns, ` +
+        `where 'equals' is the JSONB containment filter.`);
+}
+/**
+ * Object keys in sorted order, mirroring the canonical order used by every
+ * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
+ * enumerate object keys in this exact order: fingerprints sort keys, so two
+ * where clauses with the same fields in different insertion order share one
+ * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
+ * Array order (OR/AND members) is positional and is never sorted.
+ */
+function sortedKeys(obj) {
+    return Object.keys(obj).sort();
+}
+/** {@link sortedKeys}, but yielding `[key, value]` pairs. */
+function sortedEntries(obj) {
+    return Object.entries(obj).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+// ---------------------------------------------------------------------------
+// Atomic-update / JSONB / Array / text-search / vector key sets
+// ---------------------------------------------------------------------------
+/** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
+exports.UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
+/** Known JSONB operator keys */
+exports.JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * appear in any other where-filter shape, so the presence of one of these is
+ * an unambiguous signal that the user meant a JSON filter. Used by the
+ * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
+ * `WhereOperator` for LIKE) is not misclassified. Note `equals` is NOT in this
+ * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
+ * so it must fall through instead of throwing.
+ */
+exports.JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey']);
+/** Check if a value is a JSONB filter object */
+function isJsonFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.some((k) => exports.JSONB_OPERATOR_KEYS.has(k));
+}
+/**
+ * Returns the first JSON-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findJsonUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (exports.JSONB_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
+/** Known Array operator keys */
+exports.ARRAY_OPERATOR_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/**
+ * Array operator keys that are *unique* to {@link ArrayFilter}. None of the
+ * array operators currently overlap with `WhereOperator` or `JsonFilter`, so
+ * this set equals {@link ARRAY_OPERATOR_KEYS}; it is kept as a separate
+ * constant so a future overlap (e.g. a `contains` for arrays) is easy to
+ * carve out.
+ */
+exports.ARRAY_UNIQUE_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/** Check if a value is an Array filter object */
+function isArrayFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.some((k) => exports.ARRAY_OPERATOR_KEYS.has(k));
+}
+/**
+ * Returns the first array-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findArrayUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (exports.ARRAY_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
+/** Known text search operator keys */
+exports.TEXT_SEARCH_KEYS = new Set(['search', 'config']);
+/** Check if a value is a TextSearchFilter object */
+function isTextSearchFilter(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    // Must have 'search' key and only known text search keys
+    return keys.includes('search') && keys.every((k) => exports.TEXT_SEARCH_KEYS.has(k));
+}
+/**
+ * Validate a text search config name. Only alphanumeric characters and
+ * underscores are allowed to prevent SQL injection via the config parameter.
+ */
+function validateTextSearchConfig(config) {
+    return /^[a-zA-Z0-9_]+$/.test(config);
+}
+/**
+ * pgvector distance metric → operator allow-list. This is the ONLY mapping
+ * from a user-supplied metric token to a SQL operator; any token not present
+ * here is rejected, so a user value can never become an arbitrary operator.
+ *
+ *  - `l2`     → `<->` (Euclidean / L2 distance)
+ *  - `cosine` → `<=>` (cosine distance)
+ *  - `ip`     → `<#>` (negative inner product)
+ */
+exports.VECTOR_METRIC_OPERATORS = {
+    l2: '<->',
+    cosine: '<=>',
+    ip: '<#>',
+};
+/** Comparison keys allowed on a {@link VectorDistanceFilter}. */
+exports.VECTOR_DISTANCE_COMPARATORS = {
+    lt: '<',
+    lte: '<=',
+    gt: '>',
+    gte: '>=',
+};
+/** Check if a value is a vector distance WHERE filter: `{ distance: { to, metric } }` */
+function isVectorFilter(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Date) {
+        return false;
+    }
+    const dist = value.distance;
+    return (typeof dist === 'object' &&
+        dist !== null &&
+        !Array.isArray(dist) &&
+        'to' in dist &&
+        'metric' in dist);
+}
+/** Check if an orderBy value is a vector KNN ordering: `{ distance: { to, metric } }` */
+function isVectorOrderBy(value) {
+    return isVectorFilter(value);
+}
+/** Check if an orderBy value is an explicit `{ sort, nulls? }` spec. */
+function isOrderBySpec(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
+}
+/**
+ * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
+ * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile
+ * path (findMany, groupBy, relation inner subqueries).
+ */
+function normalizeOrderBy(value) {
+    if (isOrderBySpec(value)) {
+        return { dir: value.sort.toLowerCase() === 'desc' ? 'DESC' : 'ASC', nulls: value.nulls };
+    }
+    return { dir: String(value).toLowerCase() === 'desc' ? 'DESC' : 'ASC' };
+}

package/dist/errors.js

@@ -24,11 +24,25 @@ export const TurbineErrorCode = {
     EXCLUSION_VIOLATION: 'TURBINE_E016',
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
 };
+/**
+ * Prefix a human message with its stable error code so logs are greppable
+ * without requiring structured field access. Idempotent if the message already
+ * starts with `[TURBINE_E0NN]`.
+ */
+function formatErrorMessage(code, message) {
+    const tag = `[${code}]`;
+    if (message.startsWith(tag))
+        return message;
+    // Empty message → just the code (defensive; callers always pass text today).
+    if (!message)
+        return tag;
+    return `${tag} ${message}`;
+}
 /** Base error class for all Turbine errors */
 export class TurbineError extends Error {
     code;
     constructor(code, message, options) {
-        super(message, options);
+        super(formatErrorMessage(code, message), options);
         this.name = 'TurbineError';
         this.code = code;
     }

package/dist/powdb.d.ts

@@ -9,7 +9,7 @@
  * seam. The four SQL engines are untouched.
  *
  * PowDB realities shape the design (all verified firsthand against a live
- * `powdb-server` / the embedded addon, see `docs/strategy/powdb-parity-matrix.md`):
+ * `powdb-server` / the embedded addon, see `docs/internal/strategy/powdb-parity-matrix.md`):
  *   - **`RETURNING` (since 0.7.0)** — `create/createMany/update/delete` append the
  *     trailing `returning` keyword (`RETURNING *`, all columns) and read the
  *     affected rows back in one round-trip. `upsert` is the lone exception (its

package/dist/powdb.js

@@ -9,7 +9,7 @@
  * seam. The four SQL engines are untouched.
  *
  * PowDB realities shape the design (all verified firsthand against a live
- * `powdb-server` / the embedded addon, see `docs/strategy/powdb-parity-matrix.md`):
+ * `powdb-server` / the embedded addon, see `docs/internal/strategy/powdb-parity-matrix.md`):
  *   - **`RETURNING` (since 0.7.0)** — `create/createMany/update/delete` append the
  *     trailing `returning` keyword (`RETURNING *`, all columns) and read the
  *     affected rows back in one round-trip. `upsert` is the lone exception (its

package/dist/powql.d.ts

@@ -10,7 +10,7 @@
  * it separate also means the four SQL engines are untouched.
  *
  * Behavioural deltas from the SQL path, all driven by PowDB's wire reality (see
- * `docs/strategy/powdb-parity-matrix.md`, every row verified against a live
+ * `docs/internal/strategy/powdb-parity-matrix.md`, every row verified against a live
  * server):
  *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
  *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows

package/dist/powql.js

@@ -10,7 +10,7 @@
  * it separate also means the four SQL engines are untouched.
  *
  * Behavioural deltas from the SQL path, all driven by PowDB's wire reality (see
- * `docs/strategy/powdb-parity-matrix.md`, every row verified against a live
+ * `docs/internal/strategy/powdb-parity-matrix.md`, every row verified against a live
  * server):
  *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
  *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows

package/dist/query/builder.d.ts

@@ -11,129 +11,10 @@
  * metadata — nothing is hardcoded.
  */
 import type pg from 'pg';
-import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByArgs, QueryResult, RelationLoadStrategy, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
-/**
- * Runs a SQL statement and resolves its raw result. Passed to a
- * {@link DeferredQuery.reselect} plan so it can run the write and the follow-up
- * SELECT through the same timeout/instrumentation path as the primary query.
- */
-export type ReselectExecutor = (sql: string, params: unknown[], preparedName?: string) => Promise<pg.QueryResult>;
-export interface DeferredQuery<T> {
-    /** SQL text with $1, $2 placeholders */
-    sql: string;
-    /** Bound parameter values */
-    params: unknown[];
-    /** How to transform the raw pg.QueryResult into the final value */
-    transform: (result: pg.QueryResult) => T;
-    /** Tag for debugging / logging */
-    tag: string;
-    /** Prepared statement name (t_<16hex>). Set when SQL cache is enabled. */
-    preparedName?: string;
-    /**
-     * Execution plan for dialects whose {@link Dialect.resultStrategy} is
-     * `'reselect'` (no RETURNING — e.g. MySQL). Owns the statement ordering: it
-     * runs the write and the follow-up row-fetching SELECT(s) via `exec`, and
-     * resolves the result whose rows {@link DeferredQuery.transform} consumes.
-     * Absent for `'returning'`/`'output'` dialects (the statement returns its own
-     * rows), so the PostgreSQL path never allocates or consults it.
-     */
-    reselect?: (exec: ReselectExecutor) => Promise<pg.QueryResult>;
-}
-/** Middleware function type — imported from client to avoid circular deps */
-export type MiddlewareFn = (params: {
-    model: string;
-    action: string;
-    args: Record<string, unknown>;
-}, next: (params: {
-    model: string;
-    action: string;
-    args: Record<string, unknown>;
-}) => Promise<unknown>) => Promise<unknown>;
-/** Emitted after every query execution (success or failure). */
-export interface QueryEvent {
-    sql: string;
-    params: unknown[];
-    duration: number;
-    model: string;
-    action: string;
-    rows: number;
-    timestamp: Date;
-    error?: Error;
-}
-export type QueryEventListener = (event: QueryEvent) => void;
-/** Options passed from TurbineClient to QueryInterface */
-export interface QueryInterfaceOptions {
-    /** Default LIMIT applied to findMany() when no limit is specified */
-    defaultLimit?: number;
-    /**
-     * Log a one-time warning when {@link QueryInterface.findMany} is called
-     * without a `limit`. Defaults to `true` so that accidental unbounded
-     * queries are surfaced loudly during development. Pass `false` to silence
-     * the warning entirely (e.g. for CLI tooling that intentionally streams
-     * full tables).
-     */
-    warnOnUnlimited?: boolean;
-    /**
-     * Enable prepared statements. When true, queries are submitted with a
-     * `{ name, text, values }` object to the pg driver, which caches the
-     * parse+plan on the server per connection.
-     *
-     * Default: `true` for Turbine-owned pools, `false` for external pools
-     * (serverless drivers may not support named statements).
-     */
-    preparedStatements?: boolean;
-    /**
-     * Enable the SQL template cache. When true, repeated queries with the
-     * same shape (same keys, operators, relations — different values) reuse
-     * cached SQL text instead of rebuilding from scratch.
-     *
-     * Default: `true`. Set to `false` as a nuclear kill switch.
-     */
-    sqlCache?: boolean;
-    /** SQL dialect implementation. Defaults to PostgreSQL. */
-    dialect?: Dialect;
-    /**
-     * Interpret offset-less timestamp strings (Postgres `timestamp` without
-     * time zone, and the JSON emitted by nested-relation subqueries) as UTC.
-     * This is the Prisma/Rails/Django convention and makes results independent
-     * of the server's local time zone. Default: `true`. Set `false` to restore
-     * the pre-0.26 behavior (JS local-time interpretation).
-     */
-    utcTimestamps?: boolean;
-    /**
-     * Client-level default relation-loading strategy for `with` clauses. Per-query
-     * `relationLoadStrategy` args override this; both default to `'join'`.
-     */
-    relationLoadStrategy?: RelationLoadStrategy;
-    /**
-     * How nested-relation subqueries encode each row's JSON: `'object'` (default,
-     * `json_build_object`) or `'positional'` (`json_build_array`, key-less — see
-     * {@link Dialect.buildJsonArray}). Positional is Postgres-only in v1; a
-     * `with` clause on any other dialect throws `UnsupportedFeatureError` (E017).
-     */
-    jsonEncoding?: 'object' | 'positional';
-    /**
-     * Automatic WHERE filters keyed by table accessor, AND-merged into every
-     * query on that table and every relation subquery targeting it (soft-delete /
-     * multi-tenancy). Function values are evaluated at query-build time. See
-     * {@link GlobalFilters}.
-     */
-    globalFilters?: GlobalFilters;
-    /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
-    _txScoped?: boolean;
-    /** @internal Callback from TurbineClient for query event emission. */
-    _onQuery?: (event: QueryEvent) => void;
-    /**
-     * @internal Factory that builds the per-table query interface. Defaults to
-     * `new QueryInterface` (the SQL path). Non-SQL backends (PowDB) supply a
-     * factory returning a structurally-compatible interface that generates their
-     * own query language instead of SQL. The SQL dialects never set this, so their
-     * `table()` behavior is byte-identical.
-     */
-    queryInterfaceFactory?: (pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares: MiddlewareFn[], options: QueryInterfaceOptions) => QueryInterface<object>;
-}
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './deferred.js';
+import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
     private readonly table;