@adonis-agora/filter 0.0.0-beta-20261110131309

package/dist/src/spatie_parser.js

@@ -0,0 +1,134 @@
+import { parseDistinct, parseSort, toColumnFilters } from './parse_request.js';
+function toInt(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+/**
+ * Parse a decoded, Spatie-laravel-query-builder / JSON:API-style query object
+ * into a {@link SpatieInput}. This is the richer, additive counterpart to
+ * {@link parseFilterRequest}: it understands the same `filter`/`sort`/`search`
+ * shapes plus JSON:API `include`, sparse `fields[resource]` sets, and cursor
+ * pagination (`page[after]`/`page[before]`).
+ *
+ * | Query string                    | Decoded input                        | Mapped to                                  |
+ * | ------------------------------- | ------------------------------------ | ------------------------------------------ |
+ * | `filter[name]=Al`               | `{ filter: { name: 'Al' } }`         | `equals` column filter                     |
+ * | `filter[id]=1,2,3`              | `{ filter: { id: '1,2,3' } }`        | `in` column filter                         |
+ * | `filter[age][gte]=18`          | `{ filter: { age: { gte: '18' } } }` | operator column filter                     |
+ * | `sort=-createdAt,name`         | `{ sort: '-createdAt,name' }`        | sort items                                 |
+ * | `distinct=city,tier`           | `{ distinct: 'city,tier' }`          | `distinct: ['city', 'tier']`               |
+ * | `include=posts,comments`       | `{ include: 'posts,comments' }`      | `include: ['posts', 'comments']`           |
+ * | `fields[users]=id,name`        | `{ fields: { users: 'id,name' } }`   | `select: ['id', 'name']`                   |
+ * | `page[number]=2&page[size]=10` | `{ page: { number, size } }`         | offset (`page`/`size`)                     |
+ * | `page[after]=cur&page[size]=10`| `{ page: { after, size } }`          | cursor (`after`/`first`)                   |
+ *
+ * A pure reshape — no validation or allow-listing here; that happens downstream
+ * in `applyFilter` / `applyCursor` against the `FilterConfig`.
+ */
+export function parseSpatieRequest(qs) {
+    if (qs == null || typeof qs !== 'object')
+        return {};
+    const src = qs;
+    const out = {};
+    if (src.filter != null && typeof src.filter === 'object' && !Array.isArray(src.filter)) {
+        const filters = [];
+        for (const [field, value] of Object.entries(src.filter)) {
+            filters.push(...toColumnFilters(field, value));
+        }
+        if (filters.length > 0)
+            out.filters = filters;
+    }
+    const sort = parseSort(src.sort);
+    if (sort.length > 0)
+        out.sort = sort;
+    const distinct = parseDistinct(src.distinct);
+    if (distinct.length > 0)
+        out.distinct = distinct;
+    if (typeof src.search === 'string' && src.search.length > 0)
+        out.search = src.search;
+    const include = parseInclude(src.include);
+    if (include.length > 0)
+        out.include = include;
+    const select = parseSparseFieldsets(src.fields);
+    if (select.length > 0)
+        out.select = select;
+    applyPage(src.page, out);
+    return out;
+}
+/** Parse `include=posts,comments` (string or array) into a relation-name list. */
+function parseInclude(include) {
+    if (typeof include === 'string') {
+        return include
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    if (Array.isArray(include)) {
+        return include.filter((s) => typeof s === 'string' && s.length > 0);
+    }
+    return [];
+}
+/**
+ * Flatten JSON:API sparse fieldsets (`fields[resource]=a,b`) into a single
+ * order-preserving, de-duplicated list of column names. Per-resource keys are
+ * collapsed because a single SELECT applies to the primary entity.
+ */
+function parseSparseFieldsets(fields) {
+    if (fields == null || typeof fields !== 'object' || Array.isArray(fields))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const value of Object.values(fields)) {
+        const cols = typeof value === 'string'
+            ? value.split(',')
+            : Array.isArray(value)
+                ? value.filter((s) => typeof s === 'string')
+                : [];
+        for (const raw of cols) {
+            const col = raw.trim();
+            if (col.length > 0 && !seen.has(col)) {
+                seen.add(col);
+                out.push(col);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Map a JSON:API `page` object onto `out`: `page[after]`/`page[before]` →
+ * cursor (`after`/`first`, `before`/`last`); otherwise `page[number]`/`page[size]`
+ * → offset (`page`/`size`). `after` wins if both cursor bounds are present.
+ */
+function applyPage(page, out) {
+    if (page == null || typeof page !== 'object' || Array.isArray(page))
+        return;
+    const p = page;
+    const after = typeof p.after === 'string' ? p.after : undefined;
+    const before = typeof p.before === 'string' ? p.before : undefined;
+    const size = toInt(p.size);
+    if (after !== undefined || before !== undefined) {
+        if (after !== undefined) {
+            out.after = after;
+            if (size !== undefined)
+                out.first = size;
+        }
+        else if (before !== undefined) {
+            out.before = before;
+            if (size !== undefined)
+                out.last = size;
+        }
+        return;
+    }
+    const number = toInt(p.number);
+    if (number !== undefined)
+        out.page = number;
+    if (size !== undefined)
+        out.size = size;
+}
+//# sourceMappingURL=spatie_parser.js.map

package/dist/src/spatie_parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatie_parser.js","sourceRoot":"","sources":["../../src/spatie_parser.ts"],"names":[],"mappings":"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"}

package/dist/src/testing.d.ts

@@ -0,0 +1,73 @@
+import type { QueryBuilderLike } from './lucid_adapter.js';
+/** A recorded query-builder call: method name + its scalar args. */
+export interface RecordedCall {
+    method: string;
+    args: unknown[];
+}
+/**
+ * A recording stand-in for a Lucid query builder, published under
+ * `@adonis-agora/filter/testing` so consumers can unit-test their own filter
+ * definitions without a database. It satisfies {@link QueryBuilderLike}, so any
+ * of the adapter/runner helpers (or {@link applyFilterFromRequest}) can be
+ * driven against it and the resulting translation asserted.
+ *
+ * Nested `where`/`orWhere` closures run against child recorders, and a dotted
+ * relation-path filter's `whereHas` records the relation name plus runs its
+ * nested callback against a child. {@link flatten} collects every leaf call
+ * (across all groups and relation subqueries) so tests can assert a translation
+ * appeared without caring about the exact grouping nesting.
+ */
+export declare class MockQueryBuilder implements QueryBuilderLike {
+    calls: RecordedCall[];
+    children: MockQueryBuilder[];
+    private record;
+    private group;
+    where(a: any, b?: any, c?: any): this;
+    orWhere(cb: (qb: QueryBuilderLike) => void): this;
+    /**
+     * Record a relation subquery: the `whereHas` call is captured with the
+     * relation name (so `find('whereHas')?.args[0]` is the relation), and the
+     * nested callback runs against a child recorder whose calls surface via
+     * {@link flatten}.
+     */
+    whereHas(relation: string, cb: (qb: QueryBuilderLike) => void): this;
+    whereNot(callback: (qb: QueryBuilderLike) => void): this;
+    whereNot(column: string, value: unknown): this;
+    whereIn(column: string, values: unknown[]): this;
+    whereNotIn(column: string, values: unknown[]): this;
+    whereNull(column: string): this;
+    whereNotNull(column: string): this;
+    whereBetween(column: string, range: [unknown, unknown]): this;
+    whereNotBetween(column: string, range: [unknown, unknown]): this;
+    whereILike(column: string, value: string): this;
+    orWhereILike(column: string, value: string): this;
+    orderBy(column: string, direction: 'asc' | 'desc'): this;
+    /** Record a raw predicate: `args` are `[sql, bindings]` (bindings default `[]`). */
+    whereRaw(sql: string, bindings?: readonly unknown[]): this;
+    /** Record a raw ordering: `args` are `[sql, bindings]` (bindings default `[]`). */
+    orderByRaw(sql: string, bindings?: readonly unknown[]): this;
+    limit(count: number): this;
+    /** Record a row skip: `args` are `[n]`. Only the group-by-count aggregation pages this way. */
+    offset(n: number): this;
+    /** Record a projection: `args` are the select expressions (aggregates included). */
+    select(...columns: string[]): this;
+    /** Record an aggregation: `args` are `[column]` (e.g. `'* AS count'`). */
+    count(column: string): this;
+    /** Record a grouping: `args` are the group columns. */
+    groupBy(...columns: string[]): this;
+    /** Record a DISTINCT projection: `args` are the distinct column names. */
+    distinct(...columns: string[]): this;
+    /**
+     * Every recorded call across this builder and all nested groups and relation
+     * subqueries (excludes the anonymous group markers, but keeps `whereHas` since
+     * its recorded arg is the relation name, not a marker).
+     */
+    flatten(): RecordedCall[];
+    /** Find the first flattened call matching `method`. */
+    find(method: string): RecordedCall | undefined;
+    /** Every flattened call matching `method` (handy for asserting relation subqueries). */
+    findAll(method: string): RecordedCall[];
+}
+/** Factory for a fresh {@link MockQueryBuilder} — the recording Lucid stand-in. */
+export declare function makeMockQueryBuilder(): MockQueryBuilder;
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,YAAW,gBAAgB;IACvD,KAAK,EAAE,YAAY,EAAE,CAAM;IAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAM;IAElC,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,KAAK;IASb,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAGpC;IACD,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAEhD;IACD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAMnE;IACD,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAM/C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAE/C;IACD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAElD;IACD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9B;IACD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjC;IACD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAE5D;IACD,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAE/D;IACD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;IACD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEhD;IACD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAEvD;IACD,oFAAoF;IACpF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,IAAI,CAE7D;IACD,mFAAmF;IACnF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,IAAI,CAE/D;IACD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEzB;IACD,+FAA+F;IAC/F,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAEtB;IACD,oFAAoF;IACpF,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAEjC;IACD,0EAA0E;IAC1E,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE1B;IACD,uDAAuD;IACvD,OAAO,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAElC;IACD,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAEnC;IAED;;;;OAIG;IACH,OAAO,IAAI,YAAY,EAAE,CAGxB;IAED,uDAAuD;IACvD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE7C;IAED,wFAAwF;IACxF,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAEtC;CACF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,IAAI,gBAAgB,CAEvD"}

package/dist/src/testing.js

@@ -0,0 +1,136 @@
+/**
+ * A recording stand-in for a Lucid query builder, published under
+ * `@adonis-agora/filter/testing` so consumers can unit-test their own filter
+ * definitions without a database. It satisfies {@link QueryBuilderLike}, so any
+ * of the adapter/runner helpers (or {@link applyFilterFromRequest}) can be
+ * driven against it and the resulting translation asserted.
+ *
+ * Nested `where`/`orWhere` closures run against child recorders, and a dotted
+ * relation-path filter's `whereHas` records the relation name plus runs its
+ * nested callback against a child. {@link flatten} collects every leaf call
+ * (across all groups and relation subqueries) so tests can assert a translation
+ * appeared without caring about the exact grouping nesting.
+ */
+export class MockQueryBuilder {
+    calls = [];
+    children = [];
+    record(method, ...args) {
+        this.calls.push({ method, args });
+        return this;
+    }
+    group(method, cb) {
+        const child = new MockQueryBuilder();
+        this.children.push(child);
+        this.calls.push({ method, args: ['<group>'] });
+        cb(child);
+        return this;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: structural overloads for the mock.
+    where(a, b, c) {
+        if (typeof a === 'function')
+            return this.group('where', a);
+        return c !== undefined ? this.record('where', a, b, c) : this.record('where', a, b);
+    }
+    orWhere(cb) {
+        return this.group('orWhere', cb);
+    }
+    /**
+     * Record a relation subquery: the `whereHas` call is captured with the
+     * relation name (so `find('whereHas')?.args[0]` is the relation), and the
+     * nested callback runs against a child recorder whose calls surface via
+     * {@link flatten}.
+     */
+    whereHas(relation, cb) {
+        const child = new MockQueryBuilder();
+        this.children.push(child);
+        this.calls.push({ method: 'whereHas', args: [relation] });
+        cb(child);
+        return this;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: structural overloads for the mock.
+    whereNot(a, b) {
+        if (typeof a === 'function')
+            return this.group('whereNot', a);
+        return this.record('whereNot', a, b);
+    }
+    whereIn(column, values) {
+        return this.record('whereIn', column, values);
+    }
+    whereNotIn(column, values) {
+        return this.record('whereNotIn', column, values);
+    }
+    whereNull(column) {
+        return this.record('whereNull', column);
+    }
+    whereNotNull(column) {
+        return this.record('whereNotNull', column);
+    }
+    whereBetween(column, range) {
+        return this.record('whereBetween', column, range);
+    }
+    whereNotBetween(column, range) {
+        return this.record('whereNotBetween', column, range);
+    }
+    whereILike(column, value) {
+        return this.record('whereILike', column, value);
+    }
+    orWhereILike(column, value) {
+        return this.record('orWhereILike', column, value);
+    }
+    orderBy(column, direction) {
+        return this.record('orderBy', column, direction);
+    }
+    /** Record a raw predicate: `args` are `[sql, bindings]` (bindings default `[]`). */
+    whereRaw(sql, bindings = []) {
+        return this.record('whereRaw', sql, bindings);
+    }
+    /** Record a raw ordering: `args` are `[sql, bindings]` (bindings default `[]`). */
+    orderByRaw(sql, bindings = []) {
+        return this.record('orderByRaw', sql, bindings);
+    }
+    limit(count) {
+        return this.record('limit', count);
+    }
+    /** Record a row skip: `args` are `[n]`. Only the group-by-count aggregation pages this way. */
+    offset(n) {
+        return this.record('offset', n);
+    }
+    /** Record a projection: `args` are the select expressions (aggregates included). */
+    select(...columns) {
+        return this.record('select', ...columns);
+    }
+    /** Record an aggregation: `args` are `[column]` (e.g. `'* AS count'`). */
+    count(column) {
+        return this.record('count', column);
+    }
+    /** Record a grouping: `args` are the group columns. */
+    groupBy(...columns) {
+        return this.record('groupBy', ...columns);
+    }
+    /** Record a DISTINCT projection: `args` are the distinct column names. */
+    distinct(...columns) {
+        return this.record('distinct', ...columns);
+    }
+    /**
+     * Every recorded call across this builder and all nested groups and relation
+     * subqueries (excludes the anonymous group markers, but keeps `whereHas` since
+     * its recorded arg is the relation name, not a marker).
+     */
+    flatten() {
+        const own = this.calls.filter((c) => c.args[0] !== '<group>');
+        return [...own, ...this.children.flatMap((c) => c.flatten())];
+    }
+    /** Find the first flattened call matching `method`. */
+    find(method) {
+        return this.flatten().find((c) => c.method === method);
+    }
+    /** Every flattened call matching `method` (handy for asserting relation subqueries). */
+    findAll(method) {
+        return this.flatten().filter((c) => c.method === method);
+    }
+}
+/** Factory for a fresh {@link MockQueryBuilder} — the recording Lucid stand-in. */
+export function makeMockQueryBuilder() {
+    return new MockQueryBuilder();
+}
+//# sourceMappingURL=testing.js.map

package/dist/src/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -0,0 +1,226 @@
+import type { FieldAliases } from './field_aliases.js';
+import type { FullTextSearchOptions, VectorDistanceMetric } from './lucid_adapter.js';
+import type { ColumnFilter } from './operators.js';
+/**
+ * A field's classified value kind — mirrors `@adonis-agora/filter-client`'s `FieldTypeKind`.
+ *
+ * Lives here rather than next to the client codegen because it is no longer codegen-only: the same
+ * declaration drives server-side value coercion (see {@link FilterConfig.fieldTypes}). Re-exported
+ * from `generate_client.ts` for backwards compatibility.
+ */
+export type FilterFieldKind = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'unknown';
+/** A sort directive: field + direction. */
+export interface SortItem {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/** Context handed to a {@link ComputedSource} function — the root table alias. */
+export interface ComputedContext {
+    /**
+     * The root table's SQL alias — for Lucid this is the model's table name (the
+     * main table carries no generated alias), taken from {@link FilterConfig.table}.
+     * A correlated subquery references the outer row through it, e.g.
+     * `` ({ alias }) => `(SELECT COUNT(*) FROM posts WHERE posts.author_id = ${alias}.id)` ``.
+     */
+    alias: string;
+}
+/**
+ * A dev-declared virtual/computed field's SQL source. Two forms:
+ *
+ * - **verbatim string** — inlined exactly as written (`"first || ' ' || last"`).
+ *   No token substitution; a correlated subquery needing the outer alias must
+ *   use the function form.
+ * - **function** `({ alias }) => sql` — receives the root table alias
+ *   ({@link ComputedContext}) so it can emit a correlated subquery referencing
+ *   the outer row.
+ *
+ * SAFETY: the source is authored by the developer at declaration time, never by
+ * the client. The client only references the declared alias name; its filter
+ * VALUE is always a bound parameter. Only this dev expression is inlined.
+ */
+export type ComputedSource = string | ((ctx: ComputedContext) => string);
+/** A map of computed-field alias → its dev-declared {@link ComputedSource}. */
+export type ComputedFields = Record<string, ComputedSource>;
+/**
+ * Where a request's structured input is read from, for {@link resolveInputFromRequest}:
+ *
+ * - `'auto'` — query on reads (GET/HEAD), query+body (body wins) on writes.
+ * - `'query'` / `'body'` — always that container.
+ * - a dot-path (e.g. `'body.filters'`) — the nested object at that path.
+ * - a function — a custom extractor receiving the raw request.
+ */
+export type InputSource = 'auto' | 'query' | 'body' | (string & {}) | ((req: unknown) => Record<string, unknown> | undefined);
+/**
+ * How incoming field-name keys are normalized before matching against the
+ * allow-list — a built-in case transform or a custom mapping function.
+ */
+export type InputNormalizer = 'camelCase' | 'snakeCase' | ((key: string) => string);
+/**
+ * A group-by-count aggregation request: the distinct values of `field` with counts, over the
+ * rows the active filters select. `limit` bounds the rows (highest count first — tag cardinality
+ * grows with the data, so the unbounded answer is a listing); `offset` pages that bound;
+ * `search` narrows to values containing the text, server-side, so a rare value outside the first
+ * page stays reachable by typing.
+ */
+export interface GroupByCountRequest {
+    field: string;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    search?: string | undefined;
+}
+/** Bounds for a group-by-count answer: how many group rows come back, from where, matching what. */
+export interface GroupByCountOptions {
+    limit?: number | undefined;
+    offset?: number | undefined;
+    /** Narrow to groups whose value contains this text (case-insensitive). */
+    search?: string | undefined;
+}
+/**
+ * The parsed, structured input a {@link applyFilter} call consumes — produced by
+ * {@link parseFilterRequest} from a request query string, or built directly.
+ */
+export interface FilterInput {
+    /** Column filter conditions (with optional AND/OR composition). */
+    filters?: ColumnFilter[];
+    /** Sort directives, applied in order. */
+    sort?: SortItem[];
+    /**
+     * Select DISTINCT values of the given field(s) — the active filters, search,
+     * sort and pagination still apply. Useful for populating a filter dropdown
+     * with the distinct values of a column. Fields are alias-resolved and checked
+     * against {@link FilterConfig.allowed} exactly like a `where` field; unknown
+     * fields are dropped (or rejected under {@link FilterConfig.throwOnInvalid}).
+     */
+    distinct?: string[];
+    /**
+     * Free-text search term. Routed through Postgres tsvector full-text search
+     * when the policy declares {@link FilterConfig.fullText}, otherwise a portable
+     * ILIKE scan across {@link FilterConfig.searchable}.
+     */
+    search?: string;
+    /** 1-based page number for offset pagination. */
+    page?: number;
+    /** Page size for offset pagination. */
+    size?: number;
+    /**
+     * A group-by-count aggregation replacing entity-row output: the distinct values of one field
+     * with counts — what populates a filter dropdown. Parsed from the `groupByCount[field]`,
+     * `groupByCount[limit]`, `groupByCount[offset]` and `groupByCount[search]` params the client
+     * builder emits.
+     */
+    groupByCount?: GroupByCountRequest;
+    /**
+     * A query embedding to rank rows by pgvector *similarity* (distinct from the
+     * text `search` above). Applied only when the policy declares a similarity
+     * column (see {@link FilterConfig.vectorSimilarity}) — ignored otherwise, so
+     * non-similarity requests are unchanged. Typically the controller computes
+     * this from an embedding service, not the query string.
+     */
+    vectorSimilarity?: readonly number[];
+}
+/**
+ * Declares a Postgres tsvector full-text search on a policy — the primary
+ * `search` path when set. The request's `search` string is matched against the
+ * configured document via `websearch_to_tsquery`, optionally ranked by
+ * `ts_rank`. Omitting `column`-related fields is a compile error; a policy
+ * without this config falls back to the ILIKE {@link FilterConfig.searchable}
+ * scan. Additive — carries the same shape as {@link FullTextSearchOptions}
+ * minus the per-request `query`.
+ */
+export type FullTextSearchConfig = Omit<FullTextSearchOptions, 'query'>;
+/**
+ * Declares a pgvector **embedding similarity** ordering on a policy — distinct
+ * from full-text `search`. When a request also carries a query embedding
+ * ({@link FilterInput.vectorSimilarity}), the runner ranks rows by ascending
+ * distance to it. Additive — a policy without this behaves exactly as before.
+ */
+export interface VectorSimilarityConfig {
+    /** The pgvector column ranked against the query embedding (e.g. `'embedding'`). */
+    column: string;
+    /** Distance metric → pgvector operator. Default `'cosine'` (`<=>`). */
+    metric?: VectorDistanceMetric;
+    /** Optional max-distance filter — drop rows farther than this from the embedding. */
+    threshold?: number;
+    /** Optional top-K truncation — keep only the K nearest rows. */
+    topK?: number;
+}
+/**
+ * An allow-list of field names — the security boundary for filter/sort. One of:
+ *
+ * - `'*'` — allow any field (use with care);
+ * - `string[]` — allow exactly these field names;
+ * - a predicate `(field) => boolean` — allow fields for which it returns true.
+ *   The predicate form lets a policy express rules a flat list can't (e.g.
+ *   relation-path whitelisting with a depth cap). It is evaluated against the
+ *   already alias-resolved target field, never the client-facing alias key.
+ */
+export type AllowList = '*' | string[] | ((field: string) => boolean);
+/**
+ * Per-call filter policy. The allow-lists are the security boundary: only fields
+ * named here can be filtered/sorted/searched, so client input can never probe
+ * arbitrary columns.
+ */
+export interface FilterConfig {
+    /** Columns clients may filter on. `'*'` allows any (use with care). */
+    allowed: AllowList;
+    /** Columns clients may sort on. Defaults to {@link FilterConfig.allowed}. */
+    sortable?: AllowList;
+    /**
+     * Columns the free-text `search` term scans with a portable ILIKE — the
+     * default search path when {@link FilterConfig.fullText} is not set.
+     */
+    searchable?: string[];
+    /**
+     * Declared column value kinds, keyed by field. A declared field has its filter value coerced to
+     * that kind; a value that can't be coerced is treated exactly like a disallowed field (dropped,
+     * or thrown under {@link FilterConfig.throwOnInvalid}). Guards the column from an uncastable
+     * value that Postgres would otherwise reject at query time as a 500. Undeclared fields are
+     * passed through uncoerced.
+     */
+    fieldTypes?: Readonly<Record<string, {
+        kind?: FilterFieldKind;
+    }>>;
+    /**
+     * Opt-in Postgres tsvector full-text search. When set, the request `search`
+     * string routes through `websearch_to_tsquery`/`@@` (and optional `ts_rank`)
+     * instead of the ILIKE {@link FilterConfig.searchable} scan. Omitted → ILIKE.
+     */
+    fullText?: FullTextSearchConfig;
+    /** Default page size when none is given. Default 25. */
+    defaultSize?: number;
+    /** Hard cap on page size. Default 100. */
+    maxSize?: number;
+    /** Throw `InvalidColumnFilterError` on a disallowed/invalid field instead of dropping it. Default false (drop). */
+    throwOnInvalid?: boolean;
+    /**
+     * Declarative field-name remapping applied to filter and sort fields BEFORE
+     * allow-listing — an alias key resolves to its target column, which is what
+     * the allow-list, validation and query builder then see. Aliases do not
+     * cascade. See {@link resolveFieldAlias}.
+     */
+    aliases?: FieldAliases;
+    /**
+     * Opt-in pgvector embedding-similarity ordering (distinct from text `search`).
+     * When set and the request carries a query embedding
+     * ({@link FilterInput.vectorSimilarity}), rows are ranked nearest-first by
+     * distance to it. Omitted → no similarity ordering (default).
+     */
+    vectorSimilarity?: VectorSimilarityConfig;
+    /**
+     * Virtual/computed fields — a map of alias → dev-declared SQL expression
+     * ({@link ComputedSource}). A declared alias becomes filterable and sortable
+     * as if it were a real column; its declaration IS its allow-list (computed
+     * fields bypass the column `allowed`/`sortable` lists — they are not real
+     * columns). The client value is always parameterized; only the dev expression
+     * is inlined.
+     */
+    computed?: ComputedFields;
+    /**
+     * The root table's SQL alias, surfaced to {@link ComputedSource} functions as
+     * {@link ComputedContext.alias}. For Lucid this is the model's table name.
+     * Required for function-form computed fields (and to-many aggregate fields)
+     * whose correlated subqueries must reference the outer row.
+     */
+    table?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/validate-column-filter.d.ts

@@ -0,0 +1,30 @@
+import { type ColumnFilter, type FilterOperator } from './operators.js';
+/**
+ * Normalizes an operator string to its canonical {@link FilterOperator},
+ * resolving SQL-symbol aliases (`=` -> `equals`, `!=` -> `notEquals`, ...).
+ * Canonical operators (and unknown strings) pass through unchanged.
+ */
+export declare function normalizeOperator(operator: string): FilterOperator;
+/**
+ * Maximum allowed nesting depth for AND/OR filter composition.
+ * Prevents stack overflow from maliciously deep payloads (DoS).
+ */
+export declare const MAX_FILTER_DEPTH = 10;
+export declare class InvalidColumnFilterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a ColumnFilter at runtime:
+ * - field must be a non-empty string with no SQL-unsafe characters
+ * - operator must be a known FilterOperator
+ * - value is required for non-unary operators
+ * - 'between' requires a 2-element array
+ * - 'in'/'isAnyOf' require arrays
+ * - AND/OR arrays are validated recursively
+ */
+export declare function validateColumnFilter(filter: ColumnFilter, depth?: number): void;
+/**
+ * Validates an array of ColumnFilter objects.
+ */
+export declare function validateColumnFilters(filters: ColumnFilter[]): void;
+//# sourceMappingURL=validate-column-filter.d.ts.map

package/dist/src/validate-column-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-column-filter.d.ts","sourceRoot":"","sources":["../../src/validate-column-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAIxB;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAElE;AAyBD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,SAAI,GAAG,IAAI,CAsG1E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI,CAOnE"}