turbine-orm 0.27.0 → 0.28.0

package/dist/query/batched-loader.js

@@ -46,7 +46,7 @@
  *
  * @module
  */
-import { CircularRelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
+import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
@@ -114,6 +114,14 @@ export function neededParentKeyFields(parentMeta, withClause) {
     for (const [relName, spec] of Object.entries(withClause)) {
         if (!spec)
             continue;
+        // `_count` needs each counted relation's parent-side key to stitch counts.
+        if (relName === '_count') {
+            for (const rel of resolveCountRelations(parentMeta, spec)) {
+                for (const col of localKeyColumns(rel))
+                    fields.add(parentMeta.reverseColumnMap[col] ?? col);
+            }
+            continue;
+        }
         const rel = parentMeta.relations[relName];
         if (!rel)
             continue; // unknown relation — the join path throws; let the loader surface it
@@ -134,6 +142,37 @@ function localKeyColumns(rel) {
         return normalizeKeyColumns(rel.foreignKey);
     return normalizeKeyColumns(rel.referenceKey);
 }
+/**
+ * Resolve the set of to-many relations a `_count` spec selects. `true` counts
+ * every to-many relation (hasMany + manyToMany) of the table; the record form
+ * counts only the enabled names. Shared by the join builder and the batched
+ * loader so both count the exact same relations.
+ *
+ * Errors: E005 ({@link RelationError}) for an unknown relation name, E003
+ * ({@link ValidationError}) when a named relation is to-one.
+ */
+export function resolveCountRelations(parentMeta, countSpec) {
+    const isToMany = (r) => r.type === 'hasMany' || r.type === 'manyToMany';
+    if (countSpec === true) {
+        return Object.values(parentMeta.relations).filter(isToMany);
+    }
+    const out = [];
+    for (const [relName, enabled] of Object.entries(countSpec)) {
+        if (!enabled)
+            continue;
+        const rel = parentMeta.relations[relName];
+        if (!rel) {
+            throw new RelationError(`[turbine] Unknown relation "${relName}" in _count on table "${parentMeta.name}". ` +
+                `Available: ${Object.keys(parentMeta.relations).join(', ')}`);
+        }
+        if (!isToMany(rel)) {
+            throw new ValidationError(`[turbine] _count is only supported for to-many relations; "${relName}" on ` +
+                `"${parentMeta.name}" is a to-one relation.`);
+        }
+        out.push(rel);
+    }
+    return out;
+}
 /** Stringified stitch key — robust to number/uuid/bigint type drift across a join. */
 function keyOf(value) {
     return String(value);
@@ -155,6 +194,11 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
     for (const [relName, spec] of Object.entries(withClause)) {
         if (!spec)
             continue;
+        // Reserved `_count` key — one grouped COUNT(*) follow-up per counted relation.
+        if (relName === '_count') {
+            loads.push(loadCounts(ctx, parents, spec));
+            continue;
+        }
         const rel = ctx.parentMeta.relations[relName];
         if (!rel) {
             throw new ValidationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
@@ -209,6 +253,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
             select: proj.select,
             omit: proj.omit,
             orderBy: options.orderBy,
+            skipGlobalFilters: ctx.skipGlobalFilters,
         });
         const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
         return deferred.transform(result);
@@ -307,6 +352,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
             select: proj.select,
             omit: proj.omit,
             orderBy: options.orderBy,
+            skipGlobalFilters: ctx.skipGlobalFilters,
         });
         const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
         return deferred.transform(result);
@@ -341,6 +387,107 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     }
     stripFields(targetsInOrder, proj.strip);
 }
+/**
+ * Load correlated `_count` values for the counted relations. One grouped
+ * follow-up per relation (`SELECT key, COUNT(*) … WHERE key = ANY($1) GROUP BY
+ * key`), attached onto each parent's `_count` object (0 when a parent has no
+ * matching rows) — byte-identical to the join strategy's `_count` output.
+ */
+async function loadCounts(ctx, parents, countSpec) {
+    const rels = resolveCountRelations(ctx.parentMeta, countSpec);
+    // Initialise every parent's `_count` up-front so the concurrent per-relation
+    // loads below (each writing its own key) never race on the object creation.
+    for (const parent of parents) {
+        if (parent._count === undefined)
+            parent._count = {};
+    }
+    await Promise.all(rels.map((rel) => loadOneCount(ctx, parents, rel)));
+}
+/** One grouped COUNT(*) follow-up for a single to-many relation. */
+async function loadOneCount(ctx, parents, rel) {
+    let parentKeyCol;
+    let childTable;
+    let childKeyCol;
+    if (rel.type === 'manyToMany') {
+        const through = rel.through;
+        if (!through) {
+            throw new ValidationError(`[turbine] manyToMany relation "${rel.name}" is missing its junction (\`through\`).`);
+        }
+        const sourceRef = normalizeKeyColumns(rel.referenceKey);
+        const sourceJ = normalizeKeyColumns(through.sourceKey);
+        if (sourceRef.length > 1 || sourceJ.length > 1) {
+            throw new UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}" — use the default 'join' strategy for composite-key m2m _count`);
+        }
+        parentKeyCol = sourceRef[0];
+        childTable = through.table;
+        childKeyCol = sourceJ[0];
+    }
+    else {
+        // hasMany: child FK correlates to the parent reference key.
+        const fk = normalizeKeyColumns(rel.foreignKey);
+        const rk = normalizeKeyColumns(rel.referenceKey);
+        if (fk.length > 1 || rk.length > 1) {
+            throw new UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}" — use the default 'join' strategy for composite-key _count`);
+        }
+        parentKeyCol = rk[0];
+        childTable = rel.to;
+        childKeyCol = fk[0];
+    }
+    const parentKeyField = ctx.parentMeta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
+    const keys = uniqueKeys(parents, parentKeyField);
+    const counts = new Map();
+    if (keys.length > 0) {
+        const qChild = ctx.quote(childTable);
+        const qKey = ctx.quote(childKeyCol);
+        const chunks = [];
+        for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
+            chunks.push(keys.slice(i, i + MAX_RELATION_KEYS));
+        // Global filter on the counted target, matching the join strategy so the
+        // two strategies return identical counts under a filter. hasMany filters
+        // the counted table directly; m2m counts junction rows but restricts them
+        // to junction rows whose TARGET survives the target table's filter via
+        // EXISTS — mirroring buildRelationCountExpr's EXISTS-on-target (which also
+        // skips the filter when the junction targetKey arity doesn't match the
+        // target PK). Rendered after the $1 key array.
+        let gf = null;
+        if (ctx.tableGlobalFilter) {
+            if (rel.type === 'manyToMany' && rel.through) {
+                const targetKeys = normalizeKeyColumns(rel.through.targetKey);
+                const targetMeta = ctx.schema.tables[rel.to];
+                const pk = targetMeta?.primaryKey ?? [];
+                if (targetMeta && pk.length > 0 && pk.length === targetKeys.length) {
+                    const targetGf = ctx.tableGlobalFilter(rel.to, 't', 1);
+                    if (targetGf) {
+                        const join = targetKeys.map((jc, i) => `t.${ctx.quote(pk[i])} = ${qChild}.${ctx.quote(jc)}`).join(' AND ');
+                        gf = {
+                            clause: `EXISTS (SELECT 1 FROM ${ctx.quote(rel.to)} t WHERE ${join} AND ${targetGf.clause})`,
+                            params: targetGf.params,
+                        };
+                    }
+                }
+            }
+            else if (rel.type !== 'manyToMany') {
+                gf = ctx.tableGlobalFilter(childTable, qChild, 1);
+            }
+        }
+        const gfAnd = gf ? ` AND ${gf.clause}` : '';
+        const results = await Promise.all(chunks.map((chunk) => {
+            const params = [ctx.inClauseParam(chunk), ...(gf ? gf.params : [])];
+            const predicate = ctx.buildInClause(`${qChild}.${qKey}`, ctx.paramPlaceholder(1), false);
+            const sql = `SELECT ${qChild}.${qKey} AS "k", COUNT(*) AS "c" FROM ${qChild} ` +
+                `WHERE ${predicate}${gfAnd} GROUP BY ${qChild}.${qKey}`;
+            return ctx.exec(sql, params);
+        }));
+        for (const { rows } of results) {
+            for (const row of rows) {
+                counts.set(keyOf(row.k), Number(row.c));
+            }
+        }
+    }
+    for (const parent of parents) {
+        parent._count[rel.name] = counts.get(keyOf(parent[parentKeyField])) ?? 0;
+    }
+}
 // ---------------------------------------------------------------------------
 // Small helpers
 // ---------------------------------------------------------------------------

package/dist/query/builder.d.ts

@@ -13,7 +13,7 @@
 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, GroupByArgs, QueryResult, RelationLoadStrategy, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.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
@@ -114,6 +114,13 @@ export interface QueryInterfaceOptions {
      * `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. */
@@ -145,6 +152,13 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly relationLoadStrategy;
     /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
     private readonly jsonEncoding;
+    /**
+     * Client-level automatic WHERE filters keyed by table accessor (soft-delete /
+     * multi-tenancy). AND-merged into every query on the keyed table and every
+     * relation subquery targeting it. Undefined when none are configured, in
+     * which case every path is byte-identical to the pre-0.28 behavior.
+     */
+    private readonly globalFilters?;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -176,6 +190,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly options?;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     private currentAction;
+    /**
+     * The active query's `skipGlobalFilters` opt-out, set at the top of each
+     * `build*` method and read deep in the (synchronous) SQL-build + param-collect
+     * tree — so relation subqueries, relation filters, `_count`, and relation
+     * `orderBy` all see it without threading it through dozens of signatures.
+     * Only load-bearing when {@link globalFilters} is configured; build+collect are
+     * synchronous per call, so this transient is never observed across an await.
+     */
+    private currentSkip;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Quote an identifier through the active SQL dialect. */
     private q;
@@ -451,6 +474,21 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Returns null if neither is provided (meaning all columns).
      */
     private resolveColumns;
+    /**
+     * Reject any write against a view (H4). Views are introspected with
+     * `isView: true` and are read-only in every engine; a write raises a
+     * {@link ValidationError} (E003) rather than emitting SQL Postgres would
+     * reject (or, worse, silently applying to an updatable view).
+     */
+    private assertWritable;
+    /**
+     * Reject a write whose `data` names a `GENERATED ALWAYS AS (...) STORED`
+     * column (H3). Postgres computes these from other columns and errors if you
+     * try to write them; we fail early with a clear {@link ValidationError} (E003)
+     * instead of surfacing a cryptic driver error. Undefined values are ignored
+     * (they're stripped from the statement anyway).
+     */
+    private assertNoGeneratedColumns;
     /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
     private toColumn;
     /** Convert camelCase field name to a double-quoted SQL identifier */
@@ -496,7 +534,17 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * @internal Exposed as package-private for testing.
      */
     collectWhereParams(where: Record<string, unknown>, params: unknown[]): void;
-    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
+    /**
+     * Param-collect mirror of {@link buildRelationFilter} for one relation-filter
+     * object (`{ some/every/none/is/isNot }`, already normalized). Pushes, per
+     * present branch and in the canonical order some→none→every→is→isNot, the
+     * branch's sub-where params THEN the target table's global-filter params —
+     * exactly the order buildRelationFilter emits. When no global filter applies
+     * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
+     * Shared by every collect site that mirrors buildRelationFilter
+     * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
+     */
+    private collectRelationFilterParams;
     private collectRelFilterParams;
     /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
     private collectOperatorParams;
@@ -545,13 +593,55 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /** Build WHERE clause from a where object (supports operators, NULL, OR) */
     private buildWhere;
     /**
-     * Refuse mutations with an empty predicate unless explicitly opted in.
-     *
-     * An empty `where` (e.g. `{}` or `{ id: undefined }`) resolves to a
-     * mutation with no filter — a common footgun when a caller's filter
-     * value accidentally resolves to `undefined`. This guard throws
-     * `ValidationError` in that case unless `allowFullTableScan: true`.
+     * Resolve the configured global filter for `table`, evaluating a function
+     * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
+     * no filter applies, the query opted out, or the filter is empty.
+     */
+    private resolveGlobalFilter;
+    /**
+     * AND-merge this table's resolved global filter into a user `where`. Either
+     * side may be absent. When no filter applies the user where is returned by
+     * reference, so fingerprints/SQL stay byte-identical to the pre-0.28 path.
      */
+    private mergeGlobalFilter;
+    /**
+     * SQL clause for `targetTable`'s global filter rendered against `alias`
+     * (relation subqueries, `_count`, relation `orderBy`). Pushes its params to
+     * `params`; returns `''` when no filter applies. Mirror:
+     * {@link collectTargetGlobalFilterAlias}.
+     */
+    private targetGlobalFilterAlias;
+    /** Param-collect mirror of {@link targetGlobalFilterAlias}. */
+    private collectTargetGlobalFilterAlias;
+    /**
+     * SQL clause for `targetTable`'s global filter rendered against the bare
+     * (unaliased) table name — the form used inside relation-filter `EXISTS`
+     * subqueries. Pushes its params; `''` when none. Mirror:
+     * {@link collectTargetGlobalFilterExists}.
+     */
+    private targetGlobalFilterExists;
+    /** Param-collect mirror of {@link targetGlobalFilterExists}. */
+    private collectTargetGlobalFilterExists;
+    /**
+     * Value-invariant SQL-cache-key segment for the active global-filter
+     * environment. Relation-subquery / relation-filter / `_count` / relation-
+     * `orderBy` global filters are rendered at build time but their SHAPE is not
+     * otherwise in the where/with fingerprint, so this segment guards the cache:
+     * two different filter shapes never collide on one cached SQL text, while two
+     * function-filter results of the SAME shape (differing only in values) share
+     * the entry and bind their own params. Empty (`''`) when no filter applies, so
+     * cache keys stay byte-identical when the feature is unused.
+     */
+    private globalFilterCacheSegment;
+    /**
+     * True when the USER-supplied `where` compiles to no predicate (`{}`,
+     * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
+     * signal the empty-`where` guard needs — the compiled emptiness, NOT the
+     * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
+     * any configured global filter, so a global filter never lets an unguarded
+     * mass mutation through.
+     */
+    private userPredicateIsEmpty;
     private assertMutationHasPredicate;
     /**
      * Build the inner WHERE expression (without the WHERE keyword).
@@ -619,7 +709,65 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * findMany path). When `params` is omitted (groupBy / relation path) a vector
      * ordering throws — KNN ordering is only supported at the top level.
      */
+    /**
+     * Value-shape fingerprint for a single orderBy entry, so two queries whose
+     * ORDER BY differs only in nulls placement, vector metric, or relation-count
+     * vs relation-column never collide on one cached SQL string. Captures the
+     * SQL-shaping bits (direction, nulls, metric, relation keys) — never values.
+     */
+    private orderByEntryFingerprint;
     private buildOrderBy;
+    /**
+     * True when an orderBy value is a relation-ordering object: a plain object
+     * that is neither a vector KNN ordering nor an {@link OrderBySpec}. Its key
+     * in the orderBy clause is a relation name.
+     */
+    private isRelationOrderByValue;
+    /**
+     * Render the ` NULLS FIRST` / ` NULLS LAST` suffix for a column ordering.
+     * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar — on any
+     * other engine a caller asking for explicit nulls placement gets a clear
+     * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
+     */
+    private nullsSuffix;
+    /**
+     * Compile a relation ordering term. For a to-many relation the only allowed
+     * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
+     * to-one relation each entry names a target column and becomes a correlated
+     * scalar subquery (supporting {@link OrderBySpec} nulls placement).
+     *
+     * Validation: relation must exist (E005); to-many only allows `_count`, and
+     * to-one only allows real target columns (E003).
+     */
+    private buildRelationOrderBy;
+    /**
+     * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
+     * relation, correlated to `parentRef`. hasMany counts child rows via the FK;
+     * manyToMany counts junction rows via the source key. Shared by the `_count`
+     * `with` key and to-many relation orderBy.
+     *
+     * When `params` is supplied and the target has a global filter, it is
+     * AND-merged so the count only sees surviving rows (a soft-deleted child is
+     * not counted): hasMany filters the counted rows directly; manyToMany adds an
+     * `EXISTS` on the target through the junction (the junction rows themselves
+     * carry no filter). Params are mirrored by {@link collectRelationCountParams}.
+     */
+    private buildRelationCountExpr;
+    /**
+     * `EXISTS (SELECT 1 FROM <target> <talias> WHERE <join> AND <gf>)` restricting
+     * a manyToMany `_count` to targets that survive their global filter. `''` when
+     * the target has no filter. Pushes gf params; mirror:
+     * {@link collectManyToManyTargetGlobalFilter}.
+     */
+    private manyToManyTargetGlobalFilterExists;
+    /** Param-collect mirror of {@link manyToManyTargetGlobalFilterExists}. */
+    private collectManyToManyTargetGlobalFilter;
+    /**
+     * Param-collect mirror of {@link buildRelationCountExpr}'s global-filter
+     * params (hasMany direct filter, or manyToMany EXISTS-on-target). Only pushes
+     * when a filter applies — no-op otherwise.
+     */
+    private collectRelationCountParams;
     /**
      * Resolve a {@link VectorMetric} to its pgvector distance operator from a
      * fixed allow-list, validating the target column is actually a `vector`