@orthacms/utils-server 0.0.0-reserve.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/utils-server
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/utils-server
+```

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { parseFilterTree } from './lib/filters/parse-filter-tree';
+export { applyFilterTree, type ApplyFilterTreeOptions, type FilterExtensionResolver } from './lib/filters/tree-to-drizzle';
+export type { DbLike, TableLike } from './lib/filters/table-helpers';
+export { FilterOperator, ScalarFieldType, RelationKind } from './lib/filters/types';
+export { OPERATORS_BY_TYPE, operatorsFor } from './lib/filters/operator-support';
+export type { ScalarFieldSchema, FieldSchema, RelationSchema, RelationScope, FilterSchema, ParsedRule, ParsedGroup, ParsedNode } from './lib/filters/types';
+export { FilterException, FilterErrorCode, FilterSchemaException } from './lib/filters/filter-exceptions';
+export { clampInt } from './lib/clamp-int';
+export { isForeignKeyViolation, isUniqueViolation, violatedConstraint } from './lib/pg-errors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EACH,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACH,cAAc,EACd,eAAe,EACf,YAAY,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACR,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACH,eAAe,EACf,eAAe,EACf,qBAAqB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EACrB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.violatedConstraint = exports.isUniqueViolation = exports.isForeignKeyViolation = exports.clampInt = exports.FilterSchemaException = exports.FilterErrorCode = exports.FilterException = exports.operatorsFor = exports.OPERATORS_BY_TYPE = exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = exports.applyFilterTree = exports.parseFilterTree = void 0;
+var parse_filter_tree_1 = require("./lib/filters/parse-filter-tree");
+Object.defineProperty(exports, "parseFilterTree", { enumerable: true, get: function () { return parse_filter_tree_1.parseFilterTree; } });
+var tree_to_drizzle_1 = require("./lib/filters/tree-to-drizzle");
+Object.defineProperty(exports, "applyFilterTree", { enumerable: true, get: function () { return tree_to_drizzle_1.applyFilterTree; } });
+var types_1 = require("./lib/filters/types");
+Object.defineProperty(exports, "FilterOperator", { enumerable: true, get: function () { return types_1.FilterOperator; } });
+Object.defineProperty(exports, "ScalarFieldType", { enumerable: true, get: function () { return types_1.ScalarFieldType; } });
+Object.defineProperty(exports, "RelationKind", { enumerable: true, get: function () { return types_1.RelationKind; } });
+var operator_support_1 = require("./lib/filters/operator-support");
+Object.defineProperty(exports, "OPERATORS_BY_TYPE", { enumerable: true, get: function () { return operator_support_1.OPERATORS_BY_TYPE; } });
+Object.defineProperty(exports, "operatorsFor", { enumerable: true, get: function () { return operator_support_1.operatorsFor; } });
+var filter_exceptions_1 = require("./lib/filters/filter-exceptions");
+Object.defineProperty(exports, "FilterException", { enumerable: true, get: function () { return filter_exceptions_1.FilterException; } });
+Object.defineProperty(exports, "FilterErrorCode", { enumerable: true, get: function () { return filter_exceptions_1.FilterErrorCode; } });
+Object.defineProperty(exports, "FilterSchemaException", { enumerable: true, get: function () { return filter_exceptions_1.FilterSchemaException; } });
+var clamp_int_1 = require("./lib/clamp-int");
+Object.defineProperty(exports, "clampInt", { enumerable: true, get: function () { return clamp_int_1.clampInt; } });
+var pg_errors_1 = require("./lib/pg-errors");
+Object.defineProperty(exports, "isForeignKeyViolation", { enumerable: true, get: function () { return pg_errors_1.isForeignKeyViolation; } });
+Object.defineProperty(exports, "isUniqueViolation", { enumerable: true, get: function () { return pg_errors_1.isUniqueViolation; } });
+Object.defineProperty(exports, "violatedConstraint", { enumerable: true, get: function () { return pg_errors_1.violatedConstraint; } });

package/dist/lib/clamp-int.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parse a query-string integer with a default and inclusive bounds. A missing or
+ * non-numeric `raw` falls back to `fallback`; a numeric one is truncated and
+ * clamped into `[min, maxValue]`. Handy for pagination params (`?page=`,
+ * `?pageSize=`) where the caller wants a safe integer regardless of input.
+ */
+export declare function clampInt(raw: string | undefined, fallback: number, min: number, maxValue: number): number;
+//# sourceMappingURL=clamp-int.d.ts.map

package/dist/lib/clamp-int.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp-int.d.ts","sourceRoot":"","sources":["../../src/lib/clamp-int.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,QAAQ,CACpB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACjB,MAAM,CAIR"}

package/dist/lib/clamp-int.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampInt = clampInt;
+/**
+ * Parse a query-string integer with a default and inclusive bounds. A missing or
+ * non-numeric `raw` falls back to `fallback`; a numeric one is truncated and
+ * clamped into `[min, maxValue]`. Handy for pagination params (`?page=`,
+ * `?pageSize=`) where the caller wants a safe integer regardless of input.
+ */
+function clampInt(raw, fallback, min, maxValue) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(maxValue, Math.max(min, Math.trunc(parsed)));
+}

package/dist/lib/filters/filter-exceptions.d.ts

@@ -0,0 +1,92 @@
+import { BadRequestException, InternalServerErrorException } from '@nestjs/common';
+/** Machine-readable codes for filter parse errors. */
+export declare const FilterErrorCode: {
+    /** `filter` was not an object (e.g. a string or array). */
+    readonly InvalidShape: "FILTER_INVALID_SHAPE";
+    /** Parser reached a leaf with no path segments. */
+    readonly EmptyPath: "FILTER_EMPTY_PATH";
+    /** Dotted path longer than `schema.maxDepth`. */
+    readonly DepthExceeded: "FILTER_DEPTH_EXCEEDED";
+    /** Operator not in the global operator vocabulary. */
+    readonly UnknownOperator: "FILTER_UNKNOWN_OPERATOR";
+    /**
+     * Operator is a real one, but not one the field's declared type can be
+     * asked — e.g. `ilike` against a `date`, a `number`, a `boolean` or a
+     * `uuid`. Postgres has no `~~` for those column types, so without this the
+     * rule reached the driver and came back as an unhandled 500 instead of a
+     * per-field issue.
+     */
+    readonly OperatorNotAllowed: "FILTER_OPERATOR_NOT_ALLOWED";
+    /** Final segment names a field not declared on the schema. */
+    readonly UnknownField: "FILTER_UNKNOWN_FIELD";
+    /** Mid-path segment names a relation not declared on the schema. */
+    readonly UnknownRelation: "FILTER_UNKNOWN_RELATION";
+    /** Value failed type coercion (uuid/number/boolean/date/enum/null). */
+    readonly InvalidValue: "FILTER_INVALID_VALUE";
+    /** `filter` was a string but did not parse as JSON. */
+    readonly InvalidJson: "FILTER_INVALID_JSON";
+    /** Tree node was neither a recognised group nor a rule. */
+    readonly InvalidNode: "FILTER_INVALID_NODE";
+    /** Tree exceeded `schema.maxNodes` (default 50). */
+    readonly MaxNodesExceeded: "FILTER_MAX_NODES_EXCEEDED";
+    /** Group nesting exceeded `schema.maxGroupDepth` (default 5). */
+    readonly GroupDepthExceeded: "FILTER_GROUP_DEPTH_EXCEEDED";
+    /**
+     * `in`/`nin` value list was empty. Rejected because an empty `in`
+     * matches no rows and an empty `nin` matches every row — a silent
+     * no-op/inverted filter rather than the user's intent.
+     */
+    readonly EmptyInList: "FILTER_EMPTY_IN_LIST";
+    /** `in`/`nin` value list exceeded `schema.maxInListLength` (default 100). */
+    readonly MaxInListExceeded: "FILTER_MAX_IN_LIST_EXCEEDED";
+};
+/** One of the {@link FilterErrorCode} values. */
+export type FilterErrorCode = (typeof FilterErrorCode)[keyof typeof FilterErrorCode];
+/**
+ * Typed 400 exception thrown by the filter parser.
+ *
+ * Still a `BadRequestException` under the hood so NestJS returns HTTP 400,
+ * but the response body carries a `code` (from {@link FilterErrorCode}) and
+ * a `context` object so clients can key off the category rather than
+ * string-matching the message.
+ *
+ * Example response body:
+ * ```json
+ * {
+ *     "statusCode": 400,
+ *     "error": "Bad Request",
+ *     "code": "FILTER_UNKNOWN_FIELD",
+ *     "message": "filter: unknown field \"secretField\"",
+ *     "path": "secretField"
+ * }
+ * ```
+ */
+export declare class FilterException extends BadRequestException {
+    /** Machine-readable error category. */
+    readonly code: FilterErrorCode;
+    /** Structured context about where the error occurred. */
+    readonly context: Readonly<Record<string, unknown>>;
+    constructor(code: FilterErrorCode, message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when the **schema** a caller declared cannot be translated — a
+ * `many-to-many` with target fields but no `table`, a `fields` entry naming a
+ * column that is not on the table, a nested `fields` map with no matching
+ * `relations` entry, or a table with no `id` and no explicit key.
+ *
+ * Deliberately a **500**, not a {@link FilterException} 400: the request was
+ * well-formed and the whitelist accepted it — what is broken is the schema the
+ * plugin author wrote. Answering 400 would blame the client, hide the fault
+ * from alerting (4xx is a client error) and leave the schema bug in place. What
+ * the bare `Error` these replace got wrong is only that it was untyped and
+ * indistinguishable from a genuine crash: a named class with a `code` lets a
+ * transport adapter (MCP's JSON-RPC mapping, the copilot run loop) report
+ * "this endpoint's filter surface is misconfigured" instead of an opaque
+ * "internal error".
+ */
+export declare class FilterSchemaException extends InternalServerErrorException {
+    /** Machine-readable error category — always `FILTER_SCHEMA_INVALID`. */
+    readonly code = "FILTER_SCHEMA_INVALID";
+    constructor(message: string);
+}
+//# sourceMappingURL=filter-exceptions.d.ts.map

package/dist/lib/filters/filter-exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-exceptions.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/filter-exceptions.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,mBAAmB,EACnB,4BAA4B,EAC/B,MAAM,gBAAgB,CAAC;AAExB,sDAAsD;AACtD,eAAO,MAAM,eAAe;IACxB,2DAA2D;;IAE3D,mDAAmD;;IAEnD,iDAAiD;;IAEjD,sDAAsD;;IAEtD;;;;;;OAMG;;IAEH,8DAA8D;;IAE9D,oEAAoE;;IAEpE,uEAAuE;;IAEvE,uDAAuD;;IAEvD,2DAA2D;;IAE3D,oDAAoD;;IAEpD,iEAAiE;;IAEjE;;;;OAIG;;IAEH,6EAA6E;;CAEvE,CAAC;AAEX,iDAAiD;AACjD,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,mBAAmB;IACpD,uCAAuC;IACvC,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,yDAAyD;IACzD,SAAgB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAGvD,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAkB5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,SAAQ,4BAA4B;IACnE,wEAAwE;IACxE,SAAgB,IAAI,2BAA2B;gBAEnC,OAAO,EAAE,MAAM;CAQ9B"}

package/dist/lib/filters/filter-exceptions.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterSchemaException = exports.FilterException = exports.FilterErrorCode = void 0;
+const common_1 = require("@nestjs/common");
+/** Machine-readable codes for filter parse errors. */
+exports.FilterErrorCode = {
+    /** `filter` was not an object (e.g. a string or array). */
+    InvalidShape: 'FILTER_INVALID_SHAPE',
+    /** Parser reached a leaf with no path segments. */
+    EmptyPath: 'FILTER_EMPTY_PATH',
+    /** Dotted path longer than `schema.maxDepth`. */
+    DepthExceeded: 'FILTER_DEPTH_EXCEEDED',
+    /** Operator not in the global operator vocabulary. */
+    UnknownOperator: 'FILTER_UNKNOWN_OPERATOR',
+    /**
+     * Operator is a real one, but not one the field's declared type can be
+     * asked — e.g. `ilike` against a `date`, a `number`, a `boolean` or a
+     * `uuid`. Postgres has no `~~` for those column types, so without this the
+     * rule reached the driver and came back as an unhandled 500 instead of a
+     * per-field issue.
+     */
+    OperatorNotAllowed: 'FILTER_OPERATOR_NOT_ALLOWED',
+    /** Final segment names a field not declared on the schema. */
+    UnknownField: 'FILTER_UNKNOWN_FIELD',
+    /** Mid-path segment names a relation not declared on the schema. */
+    UnknownRelation: 'FILTER_UNKNOWN_RELATION',
+    /** Value failed type coercion (uuid/number/boolean/date/enum/null). */
+    InvalidValue: 'FILTER_INVALID_VALUE',
+    /** `filter` was a string but did not parse as JSON. */
+    InvalidJson: 'FILTER_INVALID_JSON',
+    /** Tree node was neither a recognised group nor a rule. */
+    InvalidNode: 'FILTER_INVALID_NODE',
+    /** Tree exceeded `schema.maxNodes` (default 50). */
+    MaxNodesExceeded: 'FILTER_MAX_NODES_EXCEEDED',
+    /** Group nesting exceeded `schema.maxGroupDepth` (default 5). */
+    GroupDepthExceeded: 'FILTER_GROUP_DEPTH_EXCEEDED',
+    /**
+     * `in`/`nin` value list was empty. Rejected because an empty `in`
+     * matches no rows and an empty `nin` matches every row — a silent
+     * no-op/inverted filter rather than the user's intent.
+     */
+    EmptyInList: 'FILTER_EMPTY_IN_LIST',
+    /** `in`/`nin` value list exceeded `schema.maxInListLength` (default 100). */
+    MaxInListExceeded: 'FILTER_MAX_IN_LIST_EXCEEDED'
+};
+/**
+ * Typed 400 exception thrown by the filter parser.
+ *
+ * Still a `BadRequestException` under the hood so NestJS returns HTTP 400,
+ * but the response body carries a `code` (from {@link FilterErrorCode}) and
+ * a `context` object so clients can key off the category rather than
+ * string-matching the message.
+ *
+ * Example response body:
+ * ```json
+ * {
+ *     "statusCode": 400,
+ *     "error": "Bad Request",
+ *     "code": "FILTER_UNKNOWN_FIELD",
+ *     "message": "filter: unknown field \"secretField\"",
+ *     "path": "secretField"
+ * }
+ * ```
+ */
+class FilterException extends common_1.BadRequestException {
+    /** Machine-readable error category. */
+    code;
+    /** Structured context about where the error occurred. */
+    context;
+    constructor(code, message, context = {}) {
+        // `context` is spread FIRST so the four reserved keys always win. The
+        // whole contract of this class is that a client can branch on `code`
+        // and on the 400 status; a context key named `code` / `statusCode` /
+        // `error` / `message` must not be able to rewrite them — a caller adding
+        // a plausible context field (`message: 'why'`) would otherwise silently
+        // break every consumer of the envelope.
+        super({
+            ...context,
+            statusCode: 400,
+            error: 'Bad Request',
+            code,
+            message: `filter: ${message}`
+        });
+        this.code = code;
+        this.context = context;
+    }
+}
+exports.FilterException = FilterException;
+/**
+ * Thrown when the **schema** a caller declared cannot be translated — a
+ * `many-to-many` with target fields but no `table`, a `fields` entry naming a
+ * column that is not on the table, a nested `fields` map with no matching
+ * `relations` entry, or a table with no `id` and no explicit key.
+ *
+ * Deliberately a **500**, not a {@link FilterException} 400: the request was
+ * well-formed and the whitelist accepted it — what is broken is the schema the
+ * plugin author wrote. Answering 400 would blame the client, hide the fault
+ * from alerting (4xx is a client error) and leave the schema bug in place. What
+ * the bare `Error` these replace got wrong is only that it was untyped and
+ * indistinguishable from a genuine crash: a named class with a `code` lets a
+ * transport adapter (MCP's JSON-RPC mapping, the copilot run loop) report
+ * "this endpoint's filter surface is misconfigured" instead of an opaque
+ * "internal error".
+ */
+class FilterSchemaException extends common_1.InternalServerErrorException {
+    /** Machine-readable error category — always `FILTER_SCHEMA_INVALID`. */
+    code = 'FILTER_SCHEMA_INVALID';
+    constructor(message) {
+        super({
+            statusCode: 500,
+            error: 'Internal Server Error',
+            code: 'FILTER_SCHEMA_INVALID',
+            message: `filter schema: ${message}`
+        });
+    }
+}
+exports.FilterSchemaException = FilterSchemaException;

package/dist/lib/filters/negation.d.ts

@@ -0,0 +1,33 @@
+import { FilterOperator } from './types';
+import type { ParsedFilter } from './types';
+/**
+ * Whether a leaf asks for the ABSENCE of a match rather than the presence
+ * of one. `null` is operator-and-value dependent: `value: true` is
+ * "is empty" (negating), `value: false` is "is not empty" (positive).
+ */
+export declare function isNegatingLeaf(op: FilterOperator, value: unknown): boolean;
+/**
+ * The positive twin of a negating leaf — the predicate whose *absence*
+ * the original asserts. `ne`→`eq`, `nin`→`in`, `nilike`→`ilike`, and
+ * "is empty"→"is not empty".
+ *
+ * Used to rewrite a negating rule on a RELATION path from
+ * `EXISTS(… NOT p …)` into `NOT EXISTS(… p …)`. The two are not the same
+ * statement once a relation can hold more than one row:
+ *
+ * - `tags.name is-none-of ['x']` as `EXISTS(tag WHERE name <> 'x')` means
+ *   "has SOME tag that isn't x" — an entry tagged `[x, y]` matches, which
+ *   is the opposite of what the filter says. As
+ *   `NOT EXISTS(tag WHERE name = 'x')` it means "has NO tag named x". ✔
+ * - `author.id is-empty` as `EXISTS(author WHERE author.id IS NULL)` can
+ *   never be true (`id` is a NOT NULL primary key) — a dead filter. As
+ *   `NOT EXISTS(author WHERE author.id IS NOT NULL)` it means "has no
+ *   author". ✔
+ *
+ * For a to-ONE relation the rewrite also reads correctly and, as a bonus,
+ * stops silently dropping rows whose FK is null: "author is not Ada" now
+ * includes entries with no author at all, matching the same rule's
+ * behaviour on a plain column (see `scalar()`'s null handling).
+ */
+export declare function positiveLeaf(leaf: ParsedFilter): ParsedFilter;
+//# sourceMappingURL=negation.d.ts.map

package/dist/lib/filters/negation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negation.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/negation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAW1E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAa7D"}

package/dist/lib/filters/negation.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNegatingLeaf = isNegatingLeaf;
+exports.positiveLeaf = positiveLeaf;
+const types_1 = require("./types");
+/**
+ * Whether a leaf asks for the ABSENCE of a match rather than the presence
+ * of one. `null` is operator-and-value dependent: `value: true` is
+ * "is empty" (negating), `value: false` is "is not empty" (positive).
+ */
+function isNegatingLeaf(op, value) {
+    switch (op) {
+        case types_1.FilterOperator.Ne:
+        case types_1.FilterOperator.Nin:
+        case types_1.FilterOperator.Nilike:
+            return true;
+        case types_1.FilterOperator.Null:
+            return value === true;
+        default:
+            return false;
+    }
+}
+/**
+ * The positive twin of a negating leaf — the predicate whose *absence*
+ * the original asserts. `ne`→`eq`, `nin`→`in`, `nilike`→`ilike`, and
+ * "is empty"→"is not empty".
+ *
+ * Used to rewrite a negating rule on a RELATION path from
+ * `EXISTS(… NOT p …)` into `NOT EXISTS(… p …)`. The two are not the same
+ * statement once a relation can hold more than one row:
+ *
+ * - `tags.name is-none-of ['x']` as `EXISTS(tag WHERE name <> 'x')` means
+ *   "has SOME tag that isn't x" — an entry tagged `[x, y]` matches, which
+ *   is the opposite of what the filter says. As
+ *   `NOT EXISTS(tag WHERE name = 'x')` it means "has NO tag named x". ✔
+ * - `author.id is-empty` as `EXISTS(author WHERE author.id IS NULL)` can
+ *   never be true (`id` is a NOT NULL primary key) — a dead filter. As
+ *   `NOT EXISTS(author WHERE author.id IS NOT NULL)` it means "has no
+ *   author". ✔
+ *
+ * For a to-ONE relation the rewrite also reads correctly and, as a bonus,
+ * stops silently dropping rows whose FK is null: "author is not Ada" now
+ * includes entries with no author at all, matching the same rule's
+ * behaviour on a plain column (see `scalar()`'s null handling).
+ */
+function positiveLeaf(leaf) {
+    switch (leaf.op) {
+        case types_1.FilterOperator.Ne:
+            return { ...leaf, op: types_1.FilterOperator.Eq };
+        case types_1.FilterOperator.Nin:
+            return { ...leaf, op: types_1.FilterOperator.In };
+        case types_1.FilterOperator.Nilike:
+            return { ...leaf, op: types_1.FilterOperator.Ilike };
+        case types_1.FilterOperator.Null:
+            return { ...leaf, op: types_1.FilterOperator.Null, value: false };
+        default:
+            return leaf;
+    }
+}

package/dist/lib/filters/operator-support.d.ts

@@ -0,0 +1,25 @@
+import { FilterOperator, ScalarFieldType } from './types';
+/**
+ * Operators offered per declared scalar type. See the note above for why this
+ * is wider than the admin's picker table.
+ *
+ * `enum` is text-backed (a `select` field is a `text` column), so the pattern
+ * operators are legal SQL on it — and unreachable in practice anyway, since
+ * value coercion already requires an exact `enumValues` member. Listing them
+ * keeps this table a statement about the **column**, which is what it is for.
+ */
+export declare const OPERATORS_BY_TYPE: Record<ScalarFieldType, readonly FilterOperator[]>;
+/**
+ * The operators `type` accepts, or `undefined` when the type is not one this
+ * table knows.
+ *
+ * `Object.hasOwn`, not a bare lookup: `OPERATORS_BY_TYPE` is a plain object
+ * literal and a `FilterSchema` can be built at runtime (the content plugin
+ * derives one per content type), so a field declaring `type: 'constructor'`
+ * would otherwise read back a truthy non-array. An unknown type is reported by
+ * `scalarOf`'s `FilterSchemaException` — a schema bug, a 500 — so this returns
+ * `undefined` and lets the operator check stand aside rather than blame the
+ * client for it.
+ */
+export declare function operatorsFor(type: ScalarFieldType): readonly FilterOperator[] | undefined;
+//# sourceMappingURL=operator-support.d.ts.map

package/dist/lib/filters/operator-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-support.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/operator-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAsD1D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAClC,eAAe,EACf,SAAS,cAAc,EAAE,CAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CACxB,IAAI,EAAE,eAAe,GACtB,SAAS,cAAc,EAAE,GAAG,SAAS,CAIvC"}

package/dist/lib/filters/operator-support.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERATORS_BY_TYPE = void 0;
+exports.operatorsFor = operatorsFor;
+const types_1 = require("./types");
+/**
+ * Which operators each declared scalar type can actually be asked.
+ *
+ * The third axis of a filter leaf. `resolveLeaf` already validated the **field**
+ * (against the schema whitelist) and the **value** (against the field's declared
+ * type); nothing validated that the **operator** is one the underlying column
+ * can answer. So `?filter={"field":"embargoUntil","op":"ilike","value":"%2020%"}`
+ * passed both checks and reached Postgres as
+ * `"embargo_until" ilike $3`, which raises
+ * `operator does not exist: timestamp with time zone ~~* unknown` — a
+ * **user-triggerable 500 from a shareable link** on every filterable endpoint,
+ * reported as an unhandled driver error rather than as a per-field issue the
+ * client can render.
+ *
+ * The table is drawn from what the **column type can answer**, not from what a
+ * UI chooses to offer. The admin's `OPS_FOR_TYPE` is deliberately narrower —
+ * it drops `eq` on dates (its editor is minute-precision against a millisecond
+ * `timestamptz`) and everything but `eq` on booleans — but those are editor
+ * ergonomics, not SQL legality, and this is the boundary an API token, a
+ * hand-written URL and the GraphQL adapter all cross. Rejecting a legal
+ * `publishedAt eq <instant>` here would be a regression, not a fix.
+ *
+ * What that leaves is the pattern family: `like` / `ilike` / `nilike` are the
+ * `~~` operator class, which Postgres defines for text only. Every non-textual
+ * column type therefore rejects them, and everything else stays as permissive
+ * as the database is. `null` (IS NULL) and `in`/`nin` are legal on every type.
+ */
+const PATTERN_OPERATORS = [
+    types_1.FilterOperator.Like,
+    types_1.FilterOperator.Ilike,
+    types_1.FilterOperator.Nilike
+];
+/** Comparison + membership + null — legal on every scalar type. */
+const COMPARABLE_OPERATORS = [
+    types_1.FilterOperator.Eq,
+    types_1.FilterOperator.Ne,
+    types_1.FilterOperator.Gt,
+    types_1.FilterOperator.Gte,
+    types_1.FilterOperator.Lt,
+    types_1.FilterOperator.Lte,
+    types_1.FilterOperator.In,
+    types_1.FilterOperator.Nin,
+    types_1.FilterOperator.Null
+];
+/** {@link COMPARABLE_OPERATORS} plus the text-only `~~` family. */
+const TEXT_OPERATORS = [
+    ...COMPARABLE_OPERATORS,
+    ...PATTERN_OPERATORS
+];
+/**
+ * Operators offered per declared scalar type. See the note above for why this
+ * is wider than the admin's picker table.
+ *
+ * `enum` is text-backed (a `select` field is a `text` column), so the pattern
+ * operators are legal SQL on it — and unreachable in practice anyway, since
+ * value coercion already requires an exact `enumValues` member. Listing them
+ * keeps this table a statement about the **column**, which is what it is for.
+ */
+exports.OPERATORS_BY_TYPE = {
+    [types_1.ScalarFieldType.String]: TEXT_OPERATORS,
+    [types_1.ScalarFieldType.Enum]: TEXT_OPERATORS,
+    [types_1.ScalarFieldType.Number]: COMPARABLE_OPERATORS,
+    [types_1.ScalarFieldType.Boolean]: COMPARABLE_OPERATORS,
+    [types_1.ScalarFieldType.Uuid]: COMPARABLE_OPERATORS,
+    [types_1.ScalarFieldType.Date]: COMPARABLE_OPERATORS
+};
+/**
+ * The operators `type` accepts, or `undefined` when the type is not one this
+ * table knows.
+ *
+ * `Object.hasOwn`, not a bare lookup: `OPERATORS_BY_TYPE` is a plain object
+ * literal and a `FilterSchema` can be built at runtime (the content plugin
+ * derives one per content type), so a field declaring `type: 'constructor'`
+ * would otherwise read back a truthy non-array. An unknown type is reported by
+ * `scalarOf`'s `FilterSchemaException` — a schema bug, a 500 — so this returns
+ * `undefined` and lets the operator check stand aside rather than blame the
+ * client for it.
+ */
+function operatorsFor(type) {
+    return Object.hasOwn(exports.OPERATORS_BY_TYPE, type)
+        ? exports.OPERATORS_BY_TYPE[type]
+        : undefined;
+}

package/dist/lib/filters/own-property.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Look a **user-supplied** name up in a schema map, ignoring anything the map
+ * merely inherits.
+ *
+ * Every whitelist in this package — `FilterSchema.fields`, `.relations`, a
+ * `RelationSchema`'s nested maps, drizzle's own column map — is a plain object
+ * literal, so a bare `map[name]` also resolves `constructor`, `toString`,
+ * `valueOf`, `hasOwnProperty` and the rest of `Object.prototype` to truthy
+ * values. A `!map[name]` guard therefore accepts a name nobody declared, and
+ * the schema stops being the security boundary it is documented to be.
+ *
+ * Downstream neither outcome is a harmless no-match:
+ *
+ * - a scalar path (`?filter={"field":"constructor",…}`) reaches `columnOf`,
+ *   which resolves the same inherited member off the column map and hands a
+ *   `Function` to drizzle as a `Column`. The emitted fragment is `$1 = ` —
+ *   a Postgres syntax error, i.e. a **user-triggerable 500** on every
+ *   filterable endpoint.
+ * - a relation-shaped path (`?filter={"field":"toString.constructor",…}`)
+ *   falls out of `relationExists`'s `switch (rel.kind)` as `undefined`, so the
+ *   predicate is **silently dropped** and the endpoint answers 200 unfiltered.
+ *
+ * Returning `undefined` here lets each call site raise its own
+ * `FILTER_UNKNOWN_FIELD` / `FILTER_UNKNOWN_RELATION`, which is what a caller
+ * asking for an undeclared name should always have got.
+ */
+export declare function own<T>(map: Record<string, T> | undefined, name: string): T | undefined;
+//# sourceMappingURL=own-property.d.ts.map

package/dist/lib/filters/own-property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-property.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/own-property.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,GAAG,CAAC,CAAC,EACjB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACb,CAAC,GAAG,SAAS,CAGf"}

package/dist/lib/filters/own-property.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.own = own;
+/**
+ * Look a **user-supplied** name up in a schema map, ignoring anything the map
+ * merely inherits.
+ *
+ * Every whitelist in this package — `FilterSchema.fields`, `.relations`, a
+ * `RelationSchema`'s nested maps, drizzle's own column map — is a plain object
+ * literal, so a bare `map[name]` also resolves `constructor`, `toString`,
+ * `valueOf`, `hasOwnProperty` and the rest of `Object.prototype` to truthy
+ * values. A `!map[name]` guard therefore accepts a name nobody declared, and
+ * the schema stops being the security boundary it is documented to be.
+ *
+ * Downstream neither outcome is a harmless no-match:
+ *
+ * - a scalar path (`?filter={"field":"constructor",…}`) reaches `columnOf`,
+ *   which resolves the same inherited member off the column map and hands a
+ *   `Function` to drizzle as a `Column`. The emitted fragment is `$1 = ` —
+ *   a Postgres syntax error, i.e. a **user-triggerable 500** on every
+ *   filterable endpoint.
+ * - a relation-shaped path (`?filter={"field":"toString.constructor",…}`)
+ *   falls out of `relationExists`'s `switch (rel.kind)` as `undefined`, so the
+ *   predicate is **silently dropped** and the endpoint answers 200 unfiltered.
+ *
+ * Returning `undefined` here lets each call site raise its own
+ * `FILTER_UNKNOWN_FIELD` / `FILTER_UNKNOWN_RELATION`, which is what a caller
+ * asking for an undeclared name should always have got.
+ */
+function own(map, name) {
+    if (!map)
+        return undefined;
+    return Object.hasOwn(map, name) ? map[name] : undefined;
+}

package/dist/lib/filters/parse-filter-tree.d.ts

@@ -0,0 +1,17 @@
+import type { FilterSchema, ParsedNode } from './types';
+/**
+ * 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.
+ */
+export declare function parseFilterTree(rawFilter: unknown, schema: FilterSchema): ParsedNode | null;
+//# sourceMappingURL=parse-filter-tree.d.ts.map

package/dist/lib/filters/parse-filter-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-filter-tree.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/parse-filter-tree.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAgB,UAAU,EAAE,MAAM,SAAS,CAAC;AAOtE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC3B,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,YAAY,GACrB,UAAU,GAAG,IAAI,CAoCnB"}