@adonis-agora/filter 0.1.0

package/dist/src/testing.js

@@ -0,0 +1,113 @@
+/**
+ * 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;
+    }
+    whereNot(column, value) {
+        return this.record('whereNot', column, value);
+    }
+    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);
+    }
+    /**
+     * 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,130 @@
+import type { FieldAliases } from './field_aliases.js';
+import type { FullTextSearchOptions, VectorDistanceMetric } from './lucid_adapter.js';
+import type { ColumnFilter } from './operators.js';
+/** A sort directive: field + direction. */
+export interface SortItem {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * 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);
+/**
+ * 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[];
+    /**
+     * 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 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[];
+    /**
+     * 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;
+}
+//# 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":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,2CAA2C;AAC3C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,OAAO,GACP,MAAM,GAEN,CAAC,MAAM,GAAG,EAAE,CAAC,GACb,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,WAAW,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;AAEpF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,yCAAyC;IACzC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,OAAO,EAAE,SAAS,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mHAAmH;IACnH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C"}

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;gBACrC,OAAO,EAAE,MAAM;CAI5B;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"}

package/dist/src/validate-column-filter.js

@@ -0,0 +1,148 @@
+import { FILTER_OPERATORS, OPERATOR_ALIASES, } from './operators.js';
+const operatorSet = new Set(FILTER_OPERATORS);
+/**
+ * Normalizes an operator string to its canonical {@link FilterOperator},
+ * resolving SQL-symbol aliases (`=` -> `equals`, `!=` -> `notEquals`, ...).
+ * Canonical operators (and unknown strings) pass through unchanged.
+ */
+export function normalizeOperator(operator) {
+    return (OPERATOR_ALIASES[operator] ?? operator);
+}
+/**
+ * Operators that require no value (unary operators).
+ */
+const UNARY_OPERATORS = new Set([
+    'isEmpty',
+    'isNotEmpty',
+    'isNull',
+    'isNotNull',
+    'exists',
+    'notExists',
+]);
+/**
+ * Operators that require an array value.
+ */
+const ARRAY_OPERATORS = new Set([
+    'in',
+    'notIn',
+    'isAnyOf',
+    'between',
+    'notBetween',
+]);
+/**
+ * Maximum allowed nesting depth for AND/OR filter composition.
+ * Prevents stack overflow from maliciously deep payloads (DoS).
+ */
+export const MAX_FILTER_DEPTH = 10;
+export class InvalidColumnFilterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidColumnFilterError';
+    }
+}
+/**
+ * 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 function validateColumnFilter(filter, depth = 0) {
+    if (depth > MAX_FILTER_DEPTH) {
+        throw new InvalidColumnFilterError(`Filter nesting exceeds maximum depth (${MAX_FILTER_DEPTH}).`);
+    }
+    if (!filter || typeof filter !== 'object') {
+        throw new InvalidColumnFilterError('Column filter must be a non-null object.');
+    }
+    // Pure group node: `{ AND: [...] }` / `{ OR: [...] }` with no column of its
+    // own composes child filters and has no field/operator/value to validate.
+    // The client builder emits these (sometimes with an empty `field`), so treat
+    // an empty field as absent. Validate only the nested arrays, then stop.
+    const isGroupNode = (filter.AND !== undefined || filter.OR !== undefined) &&
+        (filter.field === undefined || filter.field === '');
+    if (isGroupNode) {
+        for (const key of ['AND', 'OR']) {
+            const group = filter[key];
+            if (group !== undefined) {
+                if (!Array.isArray(group)) {
+                    throw new InvalidColumnFilterError(`"${key}" must be an array of ColumnFilter.`);
+                }
+                for (const sub of group) {
+                    validateColumnFilter(sub, depth + 1);
+                }
+            }
+        }
+        return;
+    }
+    // Validate field
+    if (typeof filter.field !== 'string' || filter.field.length === 0) {
+        throw new InvalidColumnFilterError('Column filter "field" must be a non-empty string.');
+    }
+    // Reject field names that contain SQL-unsafe characters
+    if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(filter.field)) {
+        throw new InvalidColumnFilterError(`Column filter field "${filter.field}" contains invalid characters. Only letters, digits, underscores, and dots are allowed.`);
+    }
+    // Validate operator, accepting SQL-symbol aliases (`=`, `!=`, `<`, ...).
+    const op = normalizeOperator(filter.operator);
+    if (!operatorSet.has(op)) {
+        throw new InvalidColumnFilterError(`Unknown filter operator "${filter.operator}". ` +
+            `Valid operators: ${FILTER_OPERATORS.join(', ')}.`);
+    }
+    // Persist the canonical form so downstream query builders never see aliases.
+    filter.operator = op;
+    // Reject null for non-unary operators (point to isNull instead)
+    if (!UNARY_OPERATORS.has(op) && filter.value === null) {
+        throw new InvalidColumnFilterError(`Operator "${op}" received null. Use "isNull" for NULL checks.`);
+    }
+    // Validate value
+    if (UNARY_OPERATORS.has(op)) {
+        // Unary operators don't need a value — ignore any provided value
+    }
+    else if (op === 'between' || op === 'notBetween') {
+        if (!Array.isArray(filter.value) || filter.value.length !== 2) {
+            throw new InvalidColumnFilterError(`Operator "${op}" requires a value that is a 2-element array, got: ${JSON.stringify(filter.value)}.`);
+        }
+    }
+    else if (ARRAY_OPERATORS.has(op)) {
+        if (!Array.isArray(filter.value)) {
+            throw new InvalidColumnFilterError(`Operator "${op}" requires an array value, got: ${typeof filter.value}.`);
+        }
+    }
+    else {
+        if (filter.value === undefined) {
+            throw new InvalidColumnFilterError(`Operator "${op}" requires a value.`);
+        }
+    }
+    // Validate nested AND
+    if (filter.AND !== undefined) {
+        if (!Array.isArray(filter.AND)) {
+            throw new InvalidColumnFilterError('"AND" must be an array of ColumnFilter.');
+        }
+        for (const sub of filter.AND) {
+            validateColumnFilter(sub, depth + 1);
+        }
+    }
+    // Validate nested OR
+    if (filter.OR !== undefined) {
+        if (!Array.isArray(filter.OR)) {
+            throw new InvalidColumnFilterError('"OR" must be an array of ColumnFilter.');
+        }
+        for (const sub of filter.OR) {
+            validateColumnFilter(sub, depth + 1);
+        }
+    }
+}
+/**
+ * Validates an array of ColumnFilter objects.
+ */
+export function validateColumnFilters(filters) {
+    if (!Array.isArray(filters)) {
+        throw new InvalidColumnFilterError('Column filters must be an array.');
+    }
+    for (const filter of filters) {
+        validateColumnFilter(filter);
+    }
+}
+//# sourceMappingURL=validate-column-filter.js.map

package/dist/src/validate-column-filter.js.map

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

package/dist/src/value-shape.d.ts

@@ -0,0 +1,18 @@
+import { type ColumnFilter } from './operators.js';
+/**
+ * True when `value` is a non-empty plain object whose keys are ALL filter operators — i.e. an
+ * operator map like `{ gt: 5, lt: 10 }` rather than a scalar equality value. Arrays and `null` are
+ * not operator objects. Single source of the shape classifier every adapter's auto-field path uses.
+ */
+export declare function isOperatorObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Normalize a raw auto-field value to canonical {@link ColumnFilter}[]:
+ * - an array → a single `in` filter,
+ * - an {@link isOperatorObject operator object} → one filter per operator,
+ * - any other (scalar) value → a single `equals` filter.
+ *
+ * Lets an adapter's auto-field/relation/computed surfaces drive the same `ColumnFilter` path the
+ * structured-filter input already uses, instead of re-implementing the scalar/array/object ladder.
+ */
+export declare function valueToColumnFilters(field: string, value: unknown): ColumnFilter[];
+//# sourceMappingURL=value-shape.d.ts.map

package/dist/src/value-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-shape.d.ts","sourceRoot":"","sources":["../../src/value-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAyC,MAAM,gBAAgB,CAAC;AAK1F;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CAUlF"}

package/dist/src/value-shape.js

@@ -0,0 +1,36 @@
+import { FILTER_OPERATORS } from './operators.js';
+/** Every canonical operator name, for the operator-object shape check. */
+const OPERATOR_SET = new Set(FILTER_OPERATORS);
+/**
+ * True when `value` is a non-empty plain object whose keys are ALL filter operators — i.e. an
+ * operator map like `{ gt: 5, lt: 10 }` rather than a scalar equality value. Arrays and `null` are
+ * not operator objects. Single source of the shape classifier every adapter's auto-field path uses.
+ */
+export function isOperatorObject(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k) => OPERATOR_SET.has(k));
+}
+/**
+ * Normalize a raw auto-field value to canonical {@link ColumnFilter}[]:
+ * - an array → a single `in` filter,
+ * - an {@link isOperatorObject operator object} → one filter per operator,
+ * - any other (scalar) value → a single `equals` filter.
+ *
+ * Lets an adapter's auto-field/relation/computed surfaces drive the same `ColumnFilter` path the
+ * structured-filter input already uses, instead of re-implementing the scalar/array/object ladder.
+ */
+export function valueToColumnFilters(field, value) {
+    if (Array.isArray(value))
+        return [{ field, operator: 'in', value }];
+    if (isOperatorObject(value)) {
+        return Object.entries(value).map(([operator, opVal]) => ({
+            field,
+            operator: operator,
+            value: opVal,
+        }));
+    }
+    return [{ field, operator: 'equals', value }];
+}
+//# sourceMappingURL=value-shape.js.map

package/dist/src/value-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-shape.js","sourceRoot":"","sources":["../../src/value-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,gBAAgB,EAAuB,MAAM,gBAAgB,CAAC;AAE1F,0EAA0E;AAC1E,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAS,gBAAgB,CAAC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,KAAc;IAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACvD,KAAK;YACL,QAAQ,EAAE,QAA0B;YACpC,KAAK,EAAE,KAAK;SACb,CAAC,CAAC,CAAC;IACN,CAAC;IACD,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@adonis-agora/filter",
+  "version": "0.1.0",
+  "description": "Server-side query filtering/sorting/pagination for AdonisJS — Spatie-style input, a Lucid adapter, and field allow-listing. Part of the Agora ecosystem.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/adonis-filter.git",
+    "directory": "packages/core"
+  },
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing.d.ts",
+      "import": "./dist/src/testing.js",
+      "default": "./dist/src/testing.js"
+    },
+    "./commands": {
+      "types": "./dist/commands/main.d.ts",
+      "import": "./dist/commands/main.js",
+      "default": "./dist/commands/main.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@adonisjs/core": "^7.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@adonisjs/core": "^7.3.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "filter",
+    "lucid",
+    "query",
+    "spatie",
+    "pagination",
+    "agora"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}