@orthacms/utils-server 0.0.0-reserve.0

package/dist/lib/filters/parse-filter-tree.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFilterTree = parseFilterTree;
+const filter_exceptions_1 = require("./filter-exceptions");
+const resolve_leaf_1 = require("./resolve-leaf");
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_MAX_NODES = 50;
+const DEFAULT_MAX_GROUP_DEPTH = 5;
+const DEFAULT_MAX_IN_LIST = 100;
+/**
+ * Parse a `filter` payload into a tree the translator can walk. Two
+ * input shapes are accepted:
+ *
+ * 1. `string` — a JSON-encoded tree, so a controller can forward
+ *    `?filter=<json>` without pre-parsing. Throws `InvalidJson` on
+ *    malformed input.
+ * 2. Object — already-parsed tree (`{ and: [...] }` / `{ or: [...] }` /
+ *    single rule `{ field, op, value }`). Recursively validated; each
+ *    leaf flows through the same schema/op/coercion check.
+ *
+ * Returns `null` when the input is missing, empty, or `{}` so callers
+ * can skip the WHERE clause without an empty-array dance.
+ */
+function parseFilterTree(rawFilter, schema) {
+    if (rawFilter === undefined || rawFilter === null)
+        return null;
+    let value = rawFilter;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return null;
+        try {
+            value = JSON.parse(trimmed);
+        }
+        catch (err) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidJson, 'filter string is not valid JSON', { reason: err.message });
+        }
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidShape, 'expected object');
+    }
+    const obj = value;
+    if (Object.keys(obj).length === 0)
+        return null;
+    const ctx = {
+        nodeCount: 0,
+        maxNodes: schema.maxNodes ?? DEFAULT_MAX_NODES,
+        maxGroupDepth: schema.maxGroupDepth ?? DEFAULT_MAX_GROUP_DEPTH,
+        maxDepth: schema.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxInListLength: schema.maxInListLength ?? DEFAULT_MAX_IN_LIST
+    };
+    return walkNode(obj, schema, 0, ctx);
+}
+function walkNode(raw, schema, depth, ctx) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'tree node must be an object');
+    }
+    ctx.nodeCount += 1;
+    if (ctx.nodeCount > ctx.maxNodes) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.MaxNodesExceeded, `filter exceeds max node count ${ctx.maxNodes}`, { maxNodes: ctx.maxNodes });
+    }
+    const node = raw;
+    // `Object.hasOwn`, not `in`: `parseFilterTree` also accepts an
+    // already-parsed object, which a caller could hand over with a prototype
+    // that carries these names. Shape detection must read what the payload
+    // itself declares.
+    const isAnd = Object.hasOwn(node, 'and');
+    const isOr = Object.hasOwn(node, 'or');
+    if (isAnd && isOr) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'group node must declare exactly one of `and` or `or`');
+    }
+    if (isAnd || isOr) {
+        if (depth >= ctx.maxGroupDepth) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.GroupDepthExceeded, `group nesting exceeds max depth ${ctx.maxGroupDepth}`, { maxGroupDepth: ctx.maxGroupDepth });
+        }
+        const combinator = isAnd ? 'and' : 'or';
+        const children = node[combinator];
+        if (!Array.isArray(children)) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, `\`${combinator}\` must be an array of nodes`);
+        }
+        if (children.length === 0) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, `\`${combinator}\` group must contain at least one child`);
+        }
+        return {
+            kind: 'group',
+            combinator,
+            children: children.map((c) => walkNode(c, schema, depth + 1, ctx))
+        };
+    }
+    if (Object.hasOwn(node, 'field') && Object.hasOwn(node, 'op')) {
+        const field = node.field;
+        const op = node.op;
+        if (typeof field !== 'string' || field.length === 0) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'rule `field` must be a non-empty string');
+        }
+        if (typeof op !== 'string' || op.length === 0) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'rule `op` must be a non-empty string');
+        }
+        const path = field.split('.');
+        const leaf = (0, resolve_leaf_1.resolveLeaf)(path, op, node.value, schema, ctx.maxDepth, ctx.maxInListLength);
+        return toRule(leaf);
+    }
+    throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, 'tree node must have `and`, `or`, or (`field` + `op`)');
+}
+function toRule(leaf) {
+    return { kind: 'rule', ...leaf };
+}

package/dist/lib/filters/relation-exists.d.ts

@@ -0,0 +1,35 @@
+import { type SQL } from 'drizzle-orm';
+import { type DbLike, type TableLike } from './table-helpers';
+import type { ParsedFilter, RelationSchema } from './types';
+/**
+ * Build an `EXISTS (...)` subquery that applies `inner` against the
+ * relation's target/through table. The `kind` discriminant selects the
+ * SQL shape:
+ *
+ * - `one-to-one` / `one-to-many`: target FK references parent.
+ * - `many-to-one`: parent FK references target.
+ * - `many-to-many`: join via `through`; add inner join to target when
+ *   filtering on a target field.
+ * - `self-referential`: parent and target are the same physical table,
+ *   so the target is aliased to give the subquery its own correlation
+ *   name (an unaliased subquery would bind both correlation sides to the
+ *   inner scope and silently degrade to "a row that is its own parent").
+ *
+ * Every branch ANDs the relation's optional `scope` predicate (workspace
+ * + soft-delete guard) inside the EXISTS, so a relation filter never
+ * traverses rows the root query itself excludes.
+ *
+ * Every column that lives on the PARENT side (`fk` for `many-to-one` /
+ * `self-referential`, and any `parentKey`) is re-resolved against `parent`
+ * via {@link rebind}, because `parent` may be an alias of the physical
+ * table — see that helper for why an unaliased column silently correlates
+ * to the wrong row.
+ */
+export declare function relationExists(rel: RelationSchema, parent: TableLike, inner: ParsedFilter, db: DbLike): SQL;
+/**
+ * Apply the next segment of a filter path against `currentTable`.
+ * If the path has one segment left it resolves to a scalar condition;
+ * otherwise it descends through the next nested relation.
+ */
+export declare function descend(rel: RelationSchema, currentTable: TableLike, f: ParsedFilter, db: DbLike): SQL;
+//# sourceMappingURL=relation-exists.d.ts.map

package/dist/lib/filters/relation-exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-exists.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/relation-exists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAM7D,OAAO,EAIH,KAAK,MAAM,EACX,KAAK,SAAS,EACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAC1B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,GACX,GAAG,CA6GL;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACnB,GAAG,EAAE,cAAc,EACnB,YAAY,EAAE,SAAS,EACvB,CAAC,EAAE,YAAY,EACf,EAAE,EAAE,MAAM,GACX,GAAG,CAeL"}

package/dist/lib/filters/relation-exists.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relationExists = relationExists;
+exports.descend = descend;
+const drizzle_orm_1 = require("drizzle-orm");
+const pg_core_1 = require("drizzle-orm/pg-core");
+const filter_exceptions_1 = require("./filter-exceptions");
+const own_property_1 = require("./own-property");
+const scalar_op_1 = require("./scalar-op");
+const table_helpers_1 = require("./table-helpers");
+const types_1 = require("./types");
+/**
+ * Build an `EXISTS (...)` subquery that applies `inner` against the
+ * relation's target/through table. The `kind` discriminant selects the
+ * SQL shape:
+ *
+ * - `one-to-one` / `one-to-many`: target FK references parent.
+ * - `many-to-one`: parent FK references target.
+ * - `many-to-many`: join via `through`; add inner join to target when
+ *   filtering on a target field.
+ * - `self-referential`: parent and target are the same physical table,
+ *   so the target is aliased to give the subquery its own correlation
+ *   name (an unaliased subquery would bind both correlation sides to the
+ *   inner scope and silently degrade to "a row that is its own parent").
+ *
+ * Every branch ANDs the relation's optional `scope` predicate (workspace
+ * + soft-delete guard) inside the EXISTS, so a relation filter never
+ * traverses rows the root query itself excludes.
+ *
+ * Every column that lives on the PARENT side (`fk` for `many-to-one` /
+ * `self-referential`, and any `parentKey`) is re-resolved against `parent`
+ * via {@link rebind}, because `parent` may be an alias of the physical
+ * table — see that helper for why an unaliased column silently correlates
+ * to the wrong row.
+ */
+function relationExists(rel, parent, inner, db) {
+    switch (rel.kind) {
+        case types_1.RelationKind.OneToOne:
+        case types_1.RelationKind.OneToMany: {
+            const parentKey = rel.parentKey
+                ? (0, table_helpers_1.rebind)(rel.parentKey, parent)
+                : (0, table_helpers_1.primaryKey)(parent);
+            const condition = (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(rel.fk, parentKey), rel.scope?.(rel.table), descend(rel, rel.table, inner, db));
+            return (0, drizzle_orm_1.exists)(db
+                .select({ one: (0, drizzle_orm_1.sql) `1` })
+                .from(rel.table)
+                .where(condition));
+        }
+        case types_1.RelationKind.ManyToOne: {
+            const targetKey = rel.targetKey ?? (0, table_helpers_1.primaryKey)(rel.table);
+            const condition = (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(targetKey, (0, table_helpers_1.rebind)(rel.fk, parent)), rel.scope?.(rel.table), descend(rel, rel.table, inner, db));
+            return (0, drizzle_orm_1.exists)(db
+                .select({ one: (0, drizzle_orm_1.sql) `1` })
+                .from(rel.table)
+                .where(condition));
+        }
+        case types_1.RelationKind.SelfReferential: {
+            // Parent and target are the same physical table, so an
+            // unaliased subquery would bind BOTH sides of the correlation
+            // to the inner scope. The alias gives the inner table its own
+            // correlation name; `rel.fk` stays bound to the OUTER row.
+            const target = (0, pg_core_1.alias)(rel.table, rel.alias);
+            const targetKey = (0, table_helpers_1.columnOf)(target, 'id');
+            const condition = (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(targetKey, (0, table_helpers_1.rebind)(rel.fk, parent)), rel.scope?.(target), descend(rel, target, inner, db));
+            return (0, drizzle_orm_1.exists)(db
+                .select({ one: (0, drizzle_orm_1.sql) `1` })
+                .from(target)
+                .where(condition));
+        }
+        case types_1.RelationKind.ManyToMany: {
+            const parentKey = rel.parentKey
+                ? (0, table_helpers_1.rebind)(rel.parentKey, parent)
+                : (0, table_helpers_1.primaryKey)(parent);
+            // The junction-only fast path reads the target FK straight off
+            // the join row, skipping the target table. A `scope` lives on
+            // that target table, so it can only be enforced through the
+            // join — the fast path must yield to it, or `relation.id in (…)`
+            // would silently bypass the workspace / soft-delete guards that
+            // `relation.field` enforces.
+            const onlyTargetFk = !rel.scope && inner.path.length === 1 && inner.path[0] === 'id';
+            if (onlyTargetFk) {
+                return (0, drizzle_orm_1.exists)(db
+                    .select({ one: (0, drizzle_orm_1.sql) `1` })
+                    .from(rel.through)
+                    .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(rel.fk, parentKey), (0, scalar_op_1.scalar)(rel.targetFk, inner.op, inner.value))));
+            }
+            if (!rel.table) {
+                throw new filter_exceptions_1.FilterSchemaException('many-to-many filter on target field requires `table`');
+            }
+            const targetKey = rel.targetKey ?? (0, table_helpers_1.primaryKey)(rel.table);
+            return (0, drizzle_orm_1.exists)(db
+                .select({ one: (0, drizzle_orm_1.sql) `1` })
+                .from(rel.through)
+                .innerJoin(rel.table, (0, drizzle_orm_1.eq)(targetKey, rel.targetFk))
+                .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(rel.fk, parentKey), rel.scope?.(rel.table), descend(rel, rel.table, inner, db))));
+        }
+        default:
+            // Unreachable through the `RelationSchema` union, but a schema
+            // assembled at runtime can carry an unrecognised `kind`. Falling
+            // out of the switch returned `undefined`, and an `undefined`
+            // predicate is dropped by drizzle's `and()`/`or()` — the filter
+            // would silently widen instead of failing.
+            throw new filter_exceptions_1.FilterSchemaException(`relation declares unknown kind "${String(rel.kind)}"`);
+    }
+}
+/**
+ * Apply the next segment of a filter path against `currentTable`.
+ * If the path has one segment left it resolves to a scalar condition;
+ * otherwise it descends through the next nested relation.
+ */
+function descend(rel, currentTable, f, db) {
+    if (f.path.length === 1) {
+        return (0, scalar_op_1.scalar)((0, table_helpers_1.columnOf)(currentTable, f.path[0]), f.op, f.value);
+    }
+    const next = (0, own_property_1.own)(rel.relations, f.path[0]);
+    if (!next)
+        throw new filter_exceptions_1.FilterSchemaException(`nested relation missing: ${f.path[0]}`);
+    return relationExists(next, currentTable, { ...f, path: f.path.slice(1) }, db);
+}

package/dist/lib/filters/resolve-leaf.d.ts

@@ -0,0 +1,8 @@
+import type { FilterSchema, ParsedFilter } from './types';
+/**
+ * Walk a single dotted path against the schema, validate the operator,
+ * and coerce the value to the declared type. Produces the `ParsedFilter`
+ * leaf shape the tree parser tags with `kind: 'rule'`.
+ */
+export declare function resolveLeaf(path: string[], op: string, value: unknown, schema: FilterSchema, maxDepth: number, maxInListLength: number): ParsedFilter;
+//# sourceMappingURL=resolve-leaf.d.ts.map

package/dist/lib/filters/resolve-leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-leaf.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/resolve-leaf.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAqB,MAAM,SAAS,CAAC;AAQ7E;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACxB,YAAY,CAkEd"}

package/dist/lib/filters/resolve-leaf.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLeaf = resolveLeaf;
+const filter_exceptions_1 = require("./filter-exceptions");
+const operator_support_1 = require("./operator-support");
+const own_property_1 = require("./own-property");
+const types_1 = require("./types");
+const OPS = Object.values(types_1.FilterOperator);
+/** Canonical 8-4-4-4-12 hex UUID — what Postgres' `uuid` type actually accepts. */
+const UUID_CANONICAL = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Walk a single dotted path against the schema, validate the operator,
+ * and coerce the value to the declared type. Produces the `ParsedFilter`
+ * leaf shape the tree parser tags with `kind: 'rule'`.
+ */
+function resolveLeaf(path, op, value, schema, maxDepth, maxInListLength) {
+    if (path.length === 0) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.EmptyPath, 'empty filter path');
+    }
+    if (path.length > maxDepth) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.DepthExceeded, `filter path exceeds max depth ${maxDepth}`, { path: path.join('.'), maxDepth });
+    }
+    if (!OPS.includes(op)) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.UnknownOperator, `unknown operator "${op}"`, { op });
+    }
+    let fields = schema.fields ?? {};
+    let relations = schema.relations ?? {};
+    for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        const last = i === path.length - 1;
+        if (last) {
+            const field = (0, own_property_1.own)(fields, seg);
+            if (!field) {
+                throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.UnknownField, `unknown field "${path.join('.')}"`, { path: path.join('.') });
+            }
+            assertOperatorAllowed(field, op, path);
+            return {
+                path,
+                op: op,
+                value: coerce(value, field, op, path, maxInListLength)
+            };
+        }
+        const rel = (0, own_property_1.own)(relations, seg);
+        if (!rel) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.UnknownRelation, `unknown relation "${seg}" in "${path.join('.')}"`, { segment: seg, path: path.join('.') });
+        }
+        fields = rel.fields ?? {};
+        relations = rel.relations ?? {};
+    }
+    throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidShape, 'unreachable: path walker ended without a leaf');
+}
+/**
+ * Reject an operator the field's column type cannot answer.
+ *
+ * Runs **before** coercion, so the reported issue is the operator rather than a
+ * value the operator would never have accepted anyway — `embargoUntil ilike
+ * "%2020%"` should say "ilike is not available on a date field", not "not a
+ * date: %2020%". The context carries `path`, `op` and the `allowed` list, so a
+ * client can render a per-field issue and offer the operators that do work.
+ *
+ * An unrecognised declared type is left alone: that is a **schema** bug, and
+ * `scalarOf` already raises the 500 (`FilterSchemaException`) that names it.
+ * Blaming the client with a 400 here would hide it.
+ */
+function assertOperatorAllowed(field, op, path) {
+    const allowed = (0, operator_support_1.operatorsFor)(field.type);
+    if (!allowed || allowed.includes(op)) {
+        return;
+    }
+    throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.OperatorNotAllowed, `operator "${op}" is not available on "${path.join('.')}" (a ${field.type} field)`, { path: path.join('.'), op, fieldType: field.type, allowed });
+}
+function coerce(raw, field, op, path, maxInListLength) {
+    const pathStr = path.join('.');
+    if (op === types_1.FilterOperator.Null) {
+        if (raw === 'true' || raw === true)
+            return true;
+        if (raw === 'false' || raw === false)
+            return false;
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, 'null filter accepts only true|false', { path: pathStr, op, value: raw });
+    }
+    if (op === types_1.FilterOperator.In || op === types_1.FilterOperator.Nin) {
+        const items = Array.isArray(raw)
+            ? raw
+            : typeof raw === 'string'
+                ? raw.split(',')
+                : [raw];
+        // An empty list would translate to `IN ()` / `NOT IN ()`, which
+        // Drizzle emits as `false` / `true` — a silent no-op (matches
+        // nothing) or inverted filter (matches everything). Reject it so
+        // the client gets a clean 400 instead of a surprising result set.
+        if (items.length === 0) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.EmptyInList, `${op} requires at least one value`, { path: pathStr, op });
+        }
+        // Cap the list so a single rule (one node, under maxNodes) can't
+        // blow up into an arbitrarily large IN clause.
+        if (items.length > maxInListLength) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.MaxInListExceeded, `${op} value list exceeds max length ${maxInListLength}`, { path: pathStr, op, maxInListLength, length: items.length });
+        }
+        return items.map((v) => scalarOf(v, field, pathStr));
+    }
+    return scalarOf(raw, field, pathStr);
+}
+function scalarOf(v, field, pathStr) {
+    // A filter value has to be a scalar. `String(v)` on anything else produces
+    // a plausible-looking string that is then MATCHED AGAINST rather than
+    // rejected: `null` → `"null"`, a missing `value` key → `"undefined"`,
+    // `{}` → `"[object Object]"`, `[1,2]` → `"1,2"`, and (for a number field)
+    // `[]` → `""` → `0`. Each returns 200 with a wrong, usually empty, result
+    // set that the client reads as "no matches" instead of "bad request" —
+    // the one silent failure mode in a library that 400s every other bad
+    // value. A JSON client meaning "is null" wants the `null` operator.
+    if (v === null ||
+        (typeof v !== 'string' &&
+            typeof v !== 'number' &&
+            typeof v !== 'boolean')) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, v === undefined
+            ? 'value is required'
+            : 'value must be a string, number or boolean', { path: pathStr, expectedType: field.type });
+    }
+    const s = typeof v === 'string' ? v : String(v);
+    switch (field.type) {
+        case types_1.ScalarFieldType.String:
+            return s;
+        case types_1.ScalarFieldType.Number: {
+            const n = Number(s);
+            if (!Number.isFinite(n)) {
+                throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `not a number: ${s}`, { path: pathStr, expectedType: 'number', value: s });
+            }
+            return n;
+        }
+        case types_1.ScalarFieldType.Boolean:
+            if (s === 'true')
+                return true;
+            if (s === 'false')
+                return false;
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `not a boolean: ${s}`, { path: pathStr, expectedType: 'boolean', value: s });
+        case types_1.ScalarFieldType.Uuid:
+            // Canonical 8-4-4-4-12 form — stricter than a loose `[0-9a-f-]{36}`,
+            // which would let malformed values (e.g. 36 dashes) pass coercion
+            // and then fail Postgres' uuid cast as a 500 instead of a clean 400.
+            if (!UUID_CANONICAL.test(s)) {
+                throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `not a uuid: ${s}`, { path: pathStr, expectedType: 'uuid', value: s });
+            }
+            return s;
+        case types_1.ScalarFieldType.Date: {
+            const d = new Date(s);
+            if (Number.isNaN(d.getTime())) {
+                throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `not a date: ${s}`, { path: pathStr, expectedType: 'date', value: s });
+            }
+            return d;
+        }
+        case types_1.ScalarFieldType.Enum:
+            if (!field.enumValues?.includes(s)) {
+                throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidValue, `not in enum: ${s}`, {
+                    path: pathStr,
+                    expectedType: 'enum',
+                    value: s,
+                    allowed: field.enumValues
+                });
+            }
+            return s;
+        default:
+            // Not reachable through the type system, but a schema built at
+            // runtime (the content plugin derives one per content type) can
+            // land here with an unrecognised `type`. Falling out of the switch
+            // returned `undefined`, which drizzle renders as the same broken
+            // `$1 = ` fragment an inherited field name used to produce.
+            throw new filter_exceptions_1.FilterSchemaException(`field "${pathStr}" declares unknown type "${String(field.type)}"`);
+    }
+}

package/dist/lib/filters/scalar-op.d.ts

@@ -0,0 +1,14 @@
+import { type AnyColumn, type SQL } from 'drizzle-orm';
+import { FilterOperator } from './types';
+/**
+ * Translate a single operator + value pair against `col` into a Drizzle
+ * SQL fragment. Array-valued ops (`in`/`nin`) expect the caller's value
+ * to already be an array; `null` expects a boolean.
+ *
+ * Negative operators are NULL-inclusive — see {@link negative}. (On a
+ * relation path a negative operator never reaches here: the translator
+ * rewrites it into `NOT EXISTS(… positive …)` first, which is the only
+ * correct reading once the relation can hold more than one row.)
+ */
+export declare function scalar(col: AnyColumn, op: FilterOperator, value: unknown): SQL;
+//# sourceMappingURL=scalar-op.d.ts.map

package/dist/lib/filters/scalar-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-op.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/scalar-op.ts"],"names":[],"mappings":"AAAA,OAAO,EAeH,KAAK,SAAS,EACd,KAAK,GAAG,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAiBzC;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAClB,GAAG,EAAE,SAAS,EACd,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,OAAO,GACf,GAAG,CAqCL"}

package/dist/lib/filters/scalar-op.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scalar = scalar;
+const drizzle_orm_1 = require("drizzle-orm");
+const filter_exceptions_1 = require("./filter-exceptions");
+const types_1 = require("./types");
+/**
+ * A negative predicate that also matches NULL.
+ *
+ * SQL's three-valued logic makes `col <> 'x'`, `col NOT IN (…)` and
+ * `col NOT ILIKE '%x%'` all evaluate to NULL — i.e. *not matched* — when
+ * the column is NULL. That reads as a silent data-loss bug to an editor:
+ * a publishable type keeps its required fields **nullable** (they're only
+ * required to publish), so "Title does not contain foo" would quietly hide
+ * every draft whose title is still empty. An empty value is not the value
+ * being excluded, so it belongs in the result.
+ */
+function negative(col, predicate) {
+    return (0, drizzle_orm_1.or)(predicate, (0, drizzle_orm_1.isNull)(col));
+}
+/**
+ * Translate a single operator + value pair against `col` into a Drizzle
+ * SQL fragment. Array-valued ops (`in`/`nin`) expect the caller's value
+ * to already be an array; `null` expects a boolean.
+ *
+ * Negative operators are NULL-inclusive — see {@link negative}. (On a
+ * relation path a negative operator never reaches here: the translator
+ * rewrites it into `NOT EXISTS(… positive …)` first, which is the only
+ * correct reading once the relation can hold more than one row.)
+ */
+function scalar(col, op, value) {
+    switch (op) {
+        case types_1.FilterOperator.Eq:
+            return (0, drizzle_orm_1.eq)(col, value);
+        case types_1.FilterOperator.Ne:
+            return negative(col, (0, drizzle_orm_1.ne)(col, value));
+        case types_1.FilterOperator.Gt:
+            return (0, drizzle_orm_1.gt)(col, value);
+        case types_1.FilterOperator.Gte:
+            return (0, drizzle_orm_1.gte)(col, value);
+        case types_1.FilterOperator.Lt:
+            return (0, drizzle_orm_1.lt)(col, value);
+        case types_1.FilterOperator.Lte:
+            return (0, drizzle_orm_1.lte)(col, value);
+        case types_1.FilterOperator.In:
+            return (0, drizzle_orm_1.inArray)(col, value);
+        case types_1.FilterOperator.Nin:
+            return negative(col, (0, drizzle_orm_1.notInArray)(col, value));
+        case types_1.FilterOperator.Like:
+            return (0, drizzle_orm_1.like)(col, String(value));
+        case types_1.FilterOperator.Ilike:
+            return (0, drizzle_orm_1.ilike)(col, String(value));
+        case types_1.FilterOperator.Nilike:
+            return negative(col, (0, drizzle_orm_1.notIlike)(col, String(value)));
+        case types_1.FilterOperator.Null:
+            return value === true ? (0, drizzle_orm_1.isNull)(col) : (0, drizzle_orm_1.isNotNull)(col);
+        default:
+            // The parser validates `op` against the vocabulary, so this is
+            // unreachable — but falling out of the switch returned `undefined`,
+            // and drizzle's `and()`/`or()` drop an undefined member, so a
+            // future operator added to `FilterOperator` without a case here
+            // would silently widen the filter instead of failing the build's
+            // intent. Fail loudly instead.
+            throw new filter_exceptions_1.FilterSchemaException(`no translation for operator "${String(op)}"`);
+    }
+}

package/dist/lib/filters/table-helpers.d.ts

@@ -0,0 +1,67 @@
+import { type AnyColumn, type SQLWrapper } from 'drizzle-orm';
+/**
+ * A minimal Drizzle-like table shape.
+ *
+ * We deliberately do NOT import drizzle-orm's `Table`/`PgTable` here:
+ * drizzle's generic `Column`/`TableConfig` use a protected field that
+ * breaks structural assignment between utils-server and callers'
+ * concrete `PgTableWithColumns<…>` types under nodenext resolution.
+ * The parser is the runtime whitelist that keeps this safe.
+ */
+export type TableLike = object;
+/**
+ * A minimal Drizzle-like database shape. Only `.select().from()` and
+ * `.innerJoin()` are used; parameter/return types are widened so
+ * concrete Drizzle instances (e.g. `NodePgDatabase`) assign here
+ * without cross-package nominal friction.
+ */
+export type DbLike = {
+    select: (...args: any[]) => {
+        from: (t: any) => {
+            where: (cond: any) => SQLWrapper;
+            innerJoin: (t: any, cond: any) => {
+                where: (cond: any) => SQLWrapper;
+            };
+        };
+    };
+};
+/**
+ * Resolve a column on a table by name, or throw if absent.
+ *
+ * The lookup is `Object.hasOwn`-guarded: drizzle's column map is a plain
+ * object, so `cols['constructor']` would otherwise return `Object` itself and
+ * this function would hand a `Function` to drizzle as a `Column`. The parser's
+ * whitelist is the primary guard, but this is the site where an escaped name
+ * turns into malformed SQL rather than an error, so it guards itself too.
+ */
+export declare function columnOf(table: TableLike, name: string): AnyColumn;
+/**
+ * Re-resolve a prebuilt column against the table the translator is actually
+ * querying.
+ *
+ * A `RelationSchema`'s parent-side columns (`fk` on a `many-to-one` /
+ * `self-referential`, and every `parentKey`) are built once, against the
+ * **physical** parent table. That is wrong the moment the parent is an
+ * *alias* — which happens for every relation nested under a
+ * `self-referential` hop, whose subquery is `FROM t AS qb_x`. An unaliased
+ * `t.col` inside that subquery is still resolvable from the OUTERMOST
+ * query's `FROM t`, so Postgres silently binds the correlation to the root
+ * row instead of the aliased one: `parent.author.name` would filter on the
+ * ROOT row's author, and `parent.parent.name` would collapse to
+ * `parent.name`. Valid SQL, wrong rows, no error.
+ *
+ * Rebinding by the column's own DB name against the queried table fixes the
+ * correlation. It is a no-op when the parent is the physical table (the
+ * lookup finds the identical column), so unaliased paths are unaffected.
+ * Only ever call this for columns that live on the parent **by
+ * construction** — never for a target-side `fk` (`one-to-many`), where the
+ * name could collide with an unrelated parent column.
+ */
+export declare function rebind(column: AnyColumn, table: TableLike): AnyColumn;
+/**
+ * Resolve a table's primary key (defaults to an `id` column).
+ * Callers can override with an explicit `parentKey`/`targetKey` in the
+ * relation schema when the table's primary key is named differently.
+ */
+export declare function primaryKey(table: TableLike): AnyColumn;
+//# sourceMappingURL=table-helpers.d.ts.map

package/dist/lib/filters/table-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAG/E;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAG/B;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG;IACjB,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK;QACxB,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK;YACd,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,UAAU,CAAC;YACjC,SAAS,EAAE,CACP,CAAC,EAAE,GAAG,EACN,IAAI,EAAE,GAAG,KACR;gBACD,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,UAAU,CAAC;aACpC,CAAC;SACL,CAAC;KACL,CAAC;CACL,CAAC;AAGF;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAMlE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,CAOrE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAOtD"}