@adonis-agora/filter 0.1.0

package/dist/src/lucid_adapter.js

@@ -0,0 +1,303 @@
+import { escapeLike } from './escape-like.js';
+import { normalizeOperator } from './validate-column-filter.js';
+/** pgvector distance operator for each {@link VectorDistanceMetric}. */
+const VECTOR_OPERATORS = {
+    cosine: '<=>',
+    l2: '<->',
+    innerProduct: '<#>',
+};
+/** A safe SQL identifier: an unquoted column, optionally `table.column` qualified. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+/** Quote a (possibly dotted) identifier for Postgres, one segment at a time. */
+function quoteColumn(column) {
+    return column
+        .split('.')
+        .map((seg) => `"${seg}"`)
+        .join('.');
+}
+/**
+ * Serialize a numeric embedding to a pgvector literal (`[1,2,3]`). Returns `null`
+ * for an empty vector (a no-op signal). Throws on a non-finite component so a bad
+ * embedding fails loudly rather than emitting `NaN`/`Infinity` into SQL.
+ */
+function serializeVector(vector) {
+    if (vector.length === 0)
+        return null;
+    for (const n of vector) {
+        if (typeof n !== 'number' || !Number.isFinite(n)) {
+            throw new TypeError('Vector search embedding must contain only finite numbers.');
+        }
+    }
+    return `[${vector.join(',')}]`;
+}
+/**
+ * Apply an **embedding similarity** ordering (pgvector) to a Lucid query builder.
+ *
+ * This is *not* full-text search — it ranks rows by distance between a stored
+ * embedding column and a query *embedding vector*. For matching a text query
+ * string, use {@link applyFullTextSearch} instead.
+ *
+ * pgvector expresses similarity through raw distance operators (`<=>`, `<->`,
+ * `<#>`) that no structured query-builder method covers, so this drives the
+ * adapter's raw seam ({@link QueryBuilderLike.whereRaw}/`orderByRaw`) with the
+ * query embedding passed as a positional binding — the column name is the only
+ * interpolated fragment, and it is validated against a strict identifier charset
+ * so it can never carry injection. The distance expression is
+ * `<column> <op> ?::vector`, cast to `vector` so a text binding compares against
+ * the column.
+ *
+ * A no-op when the embedding is empty. When `order` is not `false`, rows are
+ * ordered nearest-first (ascending distance); `threshold` adds a max-distance
+ * filter; `topK` truncates to the K nearest.
+ */
+export function applyVectorSimilarity(qb, opts) {
+    const literal = serializeVector(opts.vector);
+    if (literal === null)
+        return;
+    if (!SAFE_IDENTIFIER.test(opts.column)) {
+        throw new TypeError(`Invalid vector column name: ${JSON.stringify(opts.column)}`);
+    }
+    const operator = VECTOR_OPERATORS[opts.metric ?? 'cosine'];
+    const distance = `${quoteColumn(opts.column)} ${operator} ?::vector`;
+    if (opts.threshold !== undefined) {
+        qb.whereRaw(`${distance} < ?`, [literal, opts.threshold]);
+    }
+    if (opts.order !== false) {
+        qb.orderByRaw(`${distance} asc`, [literal]);
+    }
+    if (opts.topK !== undefined) {
+        qb.limit(opts.topK);
+    }
+}
+/**
+ * Apply a Postgres **tsvector full-text search** to a Lucid query builder — the
+ * parity port of the NestJS reference's `applyVectorSearch` (tsvector), NOT the
+ * embedding similarity {@link applyVectorSimilarity}.
+ *
+ * Injection-safety: the user `query` string ALWAYS travels as a positional
+ * binding (`websearch_to_tsquery('<lang>', ?)`); it is never interpolated.
+ * `websearch_to_tsquery` (not the raw `to_tsquery`) parses arbitrary user input
+ * — multi-word text, `"quoted phrases"`, `-exclude`, `or` — without throwing a
+ * syntax error. The only spliced fragments are the column name(s) and the
+ * language config, each validated against the strict identifier charset
+ * ({@link SAFE_IDENTIFIER}) before use, so neither can carry injection.
+ *
+ * The match predicate is `<document> @@ websearch_to_tsquery('<lang>', ?)` where
+ * `<document>` is either the tsvector column directly, or
+ * `to_tsvector('<lang>', coalesce(col1,'') || ' ' || coalesce(col2,''))` for
+ * text columns. When `rank` is set, rows are additionally ordered by descending
+ * `ts_rank(<document>, websearch_to_tsquery('<lang>', ?))`. A no-op for a blank
+ * query.
+ */
+export function applyFullTextSearch(qb, opts) {
+    const query = opts.query.trim();
+    if (query.length === 0)
+        return;
+    const columns = Array.isArray(opts.column) ? opts.column : [opts.column];
+    if (columns.length === 0)
+        return;
+    for (const col of columns) {
+        if (!SAFE_IDENTIFIER.test(col)) {
+            throw new TypeError(`Invalid full-text search column name: ${JSON.stringify(col)}`);
+        }
+    }
+    const language = opts.language ?? 'english';
+    if (!SAFE_IDENTIFIER.test(language)) {
+        throw new TypeError(`Invalid full-text search language: ${JSON.stringify(language)}`);
+    }
+    // The user query is a positional binding; only the validated language splices in.
+    const tsquery = `websearch_to_tsquery('${language}', ?)`;
+    // A precomputed tsvector column is matched directly; text columns are tokenized
+    // at query time via to_tsvector, coalescing NULLs so a null column can't null
+    // the whole document.
+    const kind = opts.columnKind ?? (columns.length > 1 ? 'text' : 'tsvector');
+    const document = kind === 'text'
+        ? `to_tsvector('${language}', ${columns
+            .map((c) => `coalesce(${quoteColumn(c)}, '')`)
+            .join(" || ' ' || ")})`
+        : quoteColumn(columns[0]);
+    qb.whereRaw(`${document} @@ ${tsquery}`, [query]);
+    if (opts.rank) {
+        qb.orderByRaw(`ts_rank(${document}, ${tsquery}) desc`, [query]);
+    }
+}
+/** Wrap a value as a LIKE pattern with escaped metacharacters. */
+function like(value, kind) {
+    const v = escapeLike(String(value));
+    if (kind === 'startsWith')
+        return `${v}%`;
+    if (kind === 'endsWith')
+        return `%${v}`;
+    return `%${v}%`;
+}
+/**
+ * Apply a single (leaf) column filter to the builder.
+ *
+ * A dotted `field` is a **relation path** (`posts.title`, `posts.comments.body`):
+ * every segment but the last is a relation hop, translated into a nested Lucid
+ * `whereHas` subquery, and the final segment is the bare column the operator
+ * lands on inside the innermost relation query — so `posts.title = x` becomes
+ * `whereHas('posts', (q) => q.where('title', x))`. Depth is already bounded by
+ * the spec's `maxDepth` allow-list before a filter reaches the adapter, so this
+ * only translates paths that were explicitly whitelisted. A non-dotted `field`
+ * is a plain base column and takes the operator switch directly.
+ */
+function applyLeaf(qb, field, operator, value) {
+    const dot = field.indexOf('.');
+    if (dot !== -1) {
+        const relation = field.slice(0, dot);
+        const rest = field.slice(dot + 1);
+        qb.whereHas(relation, (sub) => applyLeaf(sub, rest, operator, value));
+        return;
+    }
+    switch (operator) {
+        case 'equals':
+            qb.where(field, value);
+            break;
+        case 'notEquals':
+            qb.whereNot(field, value);
+            break;
+        case 'contains':
+        case 'iContains':
+            qb.whereILike(field, like(value, 'contains'));
+            break;
+        case 'startsWith':
+            qb.whereILike(field, like(value, 'startsWith'));
+            break;
+        case 'endsWith':
+            qb.whereILike(field, like(value, 'endsWith'));
+            break;
+        case 'notContains':
+            qb.where((sub) => sub.whereNot(field, value).whereNotNull(field));
+            break;
+        case 'gt':
+            qb.where(field, '>', value);
+            break;
+        case 'gte':
+            qb.where(field, '>=', value);
+            break;
+        case 'lt':
+            qb.where(field, '<', value);
+            break;
+        case 'lte':
+            qb.where(field, '<=', value);
+            break;
+        case 'between':
+            qb.whereBetween(field, value);
+            break;
+        case 'notBetween':
+            qb.whereNotBetween(field, value);
+            break;
+        case 'in':
+        case 'isAnyOf':
+            qb.whereIn(field, value);
+            break;
+        case 'notIn':
+            qb.whereNotIn(field, value);
+            break;
+        case 'isNull':
+        case 'notExists':
+            qb.whereNull(field);
+            break;
+        case 'isNotNull':
+        case 'exists':
+            qb.whereNotNull(field);
+            break;
+        case 'isEmpty':
+            qb.where(field, '');
+            break;
+        case 'isNotEmpty':
+            qb.whereNot(field, '');
+            break;
+    }
+}
+/**
+ * Apply one {@link ColumnFilter} (possibly an AND/OR group) to a builder. A leaf
+ * is a single condition; `AND`/`OR` recurse into a grouped sub-builder so the
+ * boolean structure maps to Lucid's nested `where`/`orWhere` closures.
+ */
+function applyOne(qb, filter) {
+    const op = normalizeOperator(filter.operator);
+    const hasField = typeof filter.field === 'string' && filter.field.length > 0;
+    qb.where((group) => {
+        if (hasField) {
+            applyLeaf(group, filter.field, op, filter.value);
+        }
+        if (filter.AND) {
+            for (const sub of filter.AND) {
+                group.where((g) => applyOne(g, sub));
+            }
+        }
+        if (filter.OR) {
+            for (const sub of filter.OR) {
+                group.orWhere((g) => applyOne(g, sub));
+            }
+        }
+    });
+}
+/** Apply an array of column filters (combined with AND) to a Lucid query builder. */
+export function applyColumnFilters(qb, filters) {
+    for (const filter of filters) {
+        applyOne(qb, filter);
+    }
+}
+/** Apply sort directives to a Lucid query builder, in order. */
+export function applySort(qb, sorts) {
+    for (const sort of sorts) {
+        qb.orderBy(sort.field, sort.direction);
+    }
+}
+/**
+ * Apply a keyset (cursor) seek predicate to a Lucid query builder for row-value
+ * comparison across the keyset columns.
+ *
+ * Given a keyset (the active sort columns plus a primary-key tiebreaker, each
+ * with a direction) and a boundary row's values, this constrains the query to
+ * rows strictly *after* the boundary in keyset order. The row-value comparison
+ * is expanded into the portable "OR of AND tiers" form that works across all
+ * SQL dialects:
+ *
+ * ```text
+ *   (c0 OP0 v0)
+ *   OR (c0 = v0 AND c1 OP1 v1)
+ *   OR (c0 = v0 AND c1 = v1 AND c2 OP2 v2) ...
+ * ```
+ *
+ * where `OPi` is `>` for an `asc` column and `<` for a `desc` column. The whole
+ * predicate is wrapped in one AND-group so it composes with any existing
+ * `where` conditions. A no-op when the keyset is empty or `values` does not line
+ * up positionally with it.
+ */
+export function applyKeyset(qb, keyset, values) {
+    if (keyset.length === 0 || values.length !== keyset.length)
+        return;
+    qb.where((outer) => {
+        for (let tier = 0; tier < keyset.length; tier++) {
+            const buildTier = (inner) => {
+                // Equality on every column before this tier.
+                for (let i = 0; i < tier; i++) {
+                    inner.where(keyset[i].field, values[i]);
+                }
+                const cmp = keyset[tier].direction === 'asc' ? '>' : '<';
+                inner.where(keyset[tier].field, cmp, values[tier]);
+            };
+            // First tier seeds the group with AND; the rest OR onto it.
+            if (tier === 0)
+                outer.where(buildTier);
+            else
+                outer.orWhere(buildTier);
+        }
+    });
+}
+/** Apply a free-text ILIKE search across `columns` (OR-combined) to a Lucid query builder. */
+export function applySearch(qb, term, columns) {
+    if (columns.length === 0 || term.length === 0)
+        return;
+    const pattern = like(term, 'contains');
+    qb.where((group) => {
+        for (const column of columns) {
+            group.orWhereILike(column, pattern);
+        }
+    });
+}
+//# sourceMappingURL=lucid_adapter.js.map

package/dist/src/lucid_adapter.js.map

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

package/dist/src/normalizer.d.ts

@@ -0,0 +1,21 @@
+import type { InputNormalizer } from './types.js';
+export interface NormalizeOptions {
+    /** Key transform — a built-in case mode or a custom mapping function. */
+    normalizer: InputNormalizer;
+    /** Strip a trailing `Id`/`_id` (and drop a bare `id`) from each key. Default false. */
+    dropId?: boolean;
+    /** Strip `null`/`undefined`/empty-string values. Default true. */
+    stripEmpty?: boolean;
+}
+/**
+ * Normalize a decoded input object's top-level keys — case-transforming them via
+ * the chosen {@link InputNormalizer}, optionally stripping `Id` suffixes and
+ * empty values — into a null-prototype object.
+ *
+ * Prototype-pollution keys (`__proto__`, `constructor`, `prototype`, `toString`,
+ * `valueOf`) are dropped both before and after normalization, and the result has
+ * a null prototype, so a hostile key can never reach `Object.prototype`. Nested
+ * values are left untouched — only top-level keys are normalized.
+ */
+export declare function normalizeInput(input: unknown, options: NormalizeOptions): Record<string, unknown>;
+//# sourceMappingURL=normalizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../src/normalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,UAAU,EAAE,eAAe,CAAC;IAC5B,uFAAuF;IACvF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBjG"}

package/dist/src/normalizer.js

@@ -0,0 +1,61 @@
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype', 'toString', 'valueOf']);
+/**
+ * Normalize a decoded input object's top-level keys — case-transforming them via
+ * the chosen {@link InputNormalizer}, optionally stripping `Id` suffixes and
+ * empty values — into a null-prototype object.
+ *
+ * Prototype-pollution keys (`__proto__`, `constructor`, `prototype`, `toString`,
+ * `valueOf`) are dropped both before and after normalization, and the result has
+ * a null prototype, so a hostile key can never reach `Object.prototype`. Nested
+ * values are left untouched — only top-level keys are normalized.
+ */
+export function normalizeInput(input, options) {
+    if (input == null || typeof input !== 'object')
+        return {};
+    const norm = pickNormalizer(options.normalizer);
+    const drop = options.dropId === true;
+    const strip = options.stripEmpty !== false;
+    const out = Object.create(null);
+    for (const [rawKey, value] of Object.entries(input)) {
+        if (BLOCKED_KEYS.has(rawKey))
+            continue;
+        if (strip && (value === null || value === undefined || value === ''))
+            continue;
+        let key = norm(rawKey);
+        if (BLOCKED_KEYS.has(key))
+            continue;
+        if (drop)
+            key = stripId(key);
+        if (key.length === 0)
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function pickNormalizer(spec) {
+    if (typeof spec === 'function')
+        return spec;
+    if (spec === 'camelCase')
+        return toCamelCase;
+    return toSnakeCase;
+}
+function toCamelCase(key) {
+    const result = key.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
+    return result.charAt(0).toLowerCase() + result.slice(1);
+}
+function toSnakeCase(key) {
+    return key
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase();
+}
+function stripId(key) {
+    if (key.endsWith('Id'))
+        return key.slice(0, -2);
+    if (key.endsWith('_id'))
+        return key.slice(0, -3);
+    if (key === 'id')
+        return '';
+    return key;
+}
+//# sourceMappingURL=normalizer.js.map

package/dist/src/normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.js","sourceRoot":"","sources":["../../src/normalizer.ts"],"names":[],"mappings":"AAWA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAE/F;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,OAAyB;IACtE,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC1D,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,KAAK,KAAK,CAAC;IAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAA4B,CAAC;IAC3D,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC/E,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,SAAS;QACvC,IAAI,KAAK,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC;YAAE,SAAS;QAC/E,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QACpC,IAAI,IAAI;YAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,IAAqB;IAC3C,IAAI,OAAO,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAC7C,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAE,CAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/E,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,GAAG;SACP,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,SAAS,OAAO,CAAC,GAAW;IAC1B,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjD,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC5B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/operators.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Supported filter operators for generic column-based filtering.
+ *
+ * Compatible with flip-nestjs SqlQueryBuilderService ColumnFilter[].
+ */
+export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'iContains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'notBetween' | 'in' | 'notIn' | 'isAnyOf' | 'isEmpty' | 'isNotEmpty' | 'isNull' | 'isNotNull' | 'exists' | 'notExists';
+/**
+ * All valid operator strings, used for runtime validation.
+ */
+export declare const FILTER_OPERATORS: readonly FilterOperator[];
+/**
+ * SQL-symbol aliases accepted on input and normalized to a canonical
+ * {@link FilterOperator} before validation and query building. Lets callers
+ * write the familiar `=`/`!=`/`<`/`>` shorthands instead of the named form.
+ */
+export declare const OPERATOR_ALIASES: Readonly<Record<string, FilterOperator>>;
+/**
+ * An operator alias string (e.g. `'='`). Always normalized to a canonical
+ * {@link FilterOperator} via `normalizeOperator`.
+ */
+export type FilterOperatorAlias = keyof typeof OPERATOR_ALIASES;
+/**
+ * Operator value accepted on input: either a canonical {@link FilterOperator}
+ * or one of its SQL-symbol {@link FilterOperatorAlias aliases}.
+ */
+export type FilterOperatorInput = FilterOperator | FilterOperatorAlias;
+/**
+ * A single column filter condition with optional AND/OR composition.
+ */
+export interface ColumnFilter {
+    field: string;
+    operator: FilterOperatorInput;
+    value?: unknown;
+    AND?: ColumnFilter[];
+    OR?: ColumnFilter[];
+}
+//# sourceMappingURL=operators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operators.d.ts","sourceRoot":"","sources":["../../src/operators.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,aAAa,GACb,WAAW,GACX,YAAY,GACZ,UAAU,GACV,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,SAAS,GACT,YAAY,GACZ,IAAI,GACJ,OAAO,GACP,SAAS,GACT,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAEhB;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAuB5C,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAS5D,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC;IACrB,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC;CACrB"}

package/dist/src/operators.js

@@ -0,0 +1,43 @@
+/**
+ * All valid operator strings, used for runtime validation.
+ */
+export const FILTER_OPERATORS = [
+    'equals',
+    'notEquals',
+    'contains',
+    'notContains',
+    'iContains',
+    'startsWith',
+    'endsWith',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'between',
+    'notBetween',
+    'in',
+    'notIn',
+    'isAnyOf',
+    'isEmpty',
+    'isNotEmpty',
+    'isNull',
+    'isNotNull',
+    'exists',
+    'notExists',
+];
+/**
+ * SQL-symbol aliases accepted on input and normalized to a canonical
+ * {@link FilterOperator} before validation and query building. Lets callers
+ * write the familiar `=`/`!=`/`<`/`>` shorthands instead of the named form.
+ */
+export const OPERATOR_ALIASES = {
+    '=': 'equals',
+    '==': 'equals',
+    '!=': 'notEquals',
+    '<>': 'notEquals',
+    '>': 'gt',
+    '>=': 'gte',
+    '<': 'lt',
+    '<=': 'lte',
+};
+//# sourceMappingURL=operators.js.map

package/dist/src/operators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operators.js","sourceRoot":"","sources":["../../src/operators.ts"],"names":[],"mappings":"AA6BA;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD,QAAQ;IACR,WAAW;IACX,UAAU;IACV,aAAa;IACb,WAAW;IACX,YAAY;IACZ,UAAU;IACV,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,SAAS;IACT,YAAY;IACZ,IAAI;IACJ,OAAO;IACP,SAAS;IACT,SAAS;IACT,YAAY;IACZ,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,WAAW;CACH,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA6C;IACxE,GAAG,EAAE,QAAQ;IACb,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,GAAG,EAAE,IAAI;IACT,IAAI,EAAE,KAAK;IACX,GAAG,EAAE,IAAI;IACT,IAAI,EAAE,KAAK;CACH,CAAC"}

package/dist/src/parse_request.d.ts

@@ -0,0 +1,22 @@
+import type { ColumnFilter } from './operators.js';
+import type { FilterInput, SortItem } from './types.js';
+/** Map one `filter[field]=…` entry to `ColumnFilter[]` (Spatie/JSON:API shapes). */
+export declare function toColumnFilters(field: string, value: unknown): ColumnFilter[];
+/** Parse the `sort` param (`-createdAt,name` or `sort[]=…`) into ordered {@link SortItem}s. */
+export declare function parseSort(sort: unknown): SortItem[];
+/**
+ * Parse a decoded request query object — e.g. AdonisJS `ctx.request.qs()` — into
+ * a structured {@link FilterInput}. Understands the Spatie / JSON:API shapes the
+ * `@adonis-agora/filter-client` builder emits:
+ *
+ * - `filter[status]=active` → equals
+ * - `filter[id]=1,2,3` / `filter[id][]=1&filter[id][]=2` → IN
+ * - `filter[age][gte]=18` → operator filter
+ * - `sort=-createdAt,name` → sort items
+ * - `search=term`, `page`/`size` (or `page[number]`/`page[size]`)
+ *
+ * Pure reshape — no validation or allow-listing here; that happens in
+ * {@link applyFilter} against the {@link FilterConfig}.
+ */
+export declare function parseFilterRequest(qs: Record<string, unknown>): FilterInput;
+//# sourceMappingURL=parse_request.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse_request.d.ts","sourceRoot":"","sources":["../../src/parse_request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAWxD,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CA4B7E;AAED,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,EAAE,CAanD;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAqB3E"}

package/dist/src/parse_request.js

@@ -0,0 +1,107 @@
+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;
+}
+/** Map one `filter[field]=…` entry to `ColumnFilter[]` (Spatie/JSON:API shapes). */
+export function toColumnFilters(field, value) {
+    // Array (`filter[id][]=1&filter[id][]=2`) → IN.
+    if (Array.isArray(value)) {
+        return [{ field, operator: 'in', value }];
+    }
+    // Operator object (`filter[age][gte]=18`) → one filter per operator key.
+    if (value != null && typeof value === 'object') {
+        return Object.entries(value).map(([operator, opValue]) => ({
+            field,
+            operator: operator,
+            value: opValue,
+        }));
+    }
+    // Comma-separated scalar (Spatie multi-value convention) → IN.
+    if (typeof value === 'string' && value.includes(',')) {
+        return [
+            {
+                field,
+                operator: 'in',
+                value: value
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0),
+            },
+        ];
+    }
+    // Bare scalar → equals.
+    return [{ field, operator: 'equals', value }];
+}
+/** Parse the `sort` param (`-createdAt,name` or `sort[]=…`) into ordered {@link SortItem}s. */
+export function parseSort(sort) {
+    let raw = [];
+    if (typeof sort === 'string')
+        raw = sort.split(',');
+    else if (Array.isArray(sort))
+        raw = sort.filter((s) => typeof s === 'string');
+    const items = [];
+    for (const entry of raw) {
+        const field = entry.trim();
+        if (field.length === 0)
+            continue;
+        if (field.startsWith('-'))
+            items.push({ field: field.slice(1), direction: 'desc' });
+        else
+            items.push({ field, direction: 'asc' });
+    }
+    return items;
+}
+function parsePagination(qs) {
+    let page = toInt(qs.page);
+    let size = toInt(qs.size);
+    // JSON:API nested form: page[number] / page[size].
+    if (qs.page != null && typeof qs.page === 'object' && !Array.isArray(qs.page)) {
+        const p = qs.page;
+        page = toInt(p.number) ?? page;
+        size = toInt(p.size) ?? size;
+    }
+    return { ...(page !== undefined && { page }), ...(size !== undefined && { size }) };
+}
+/**
+ * Parse a decoded request query object — e.g. AdonisJS `ctx.request.qs()` — into
+ * a structured {@link FilterInput}. Understands the Spatie / JSON:API shapes the
+ * `@adonis-agora/filter-client` builder emits:
+ *
+ * - `filter[status]=active` → equals
+ * - `filter[id]=1,2,3` / `filter[id][]=1&filter[id][]=2` → IN
+ * - `filter[age][gte]=18` → operator filter
+ * - `sort=-createdAt,name` → sort items
+ * - `search=term`, `page`/`size` (or `page[number]`/`page[size]`)
+ *
+ * Pure reshape — no validation or allow-listing here; that happens in
+ * {@link applyFilter} against the {@link FilterConfig}.
+ */
+export function parseFilterRequest(qs) {
+    const out = {};
+    if (qs.filter != null && typeof qs.filter === 'object' && !Array.isArray(qs.filter)) {
+        const filters = [];
+        for (const [field, value] of Object.entries(qs.filter)) {
+            filters.push(...toColumnFilters(field, value));
+        }
+        if (filters.length > 0)
+            out.filters = filters;
+    }
+    const sort = parseSort(qs.sort);
+    if (sort.length > 0)
+        out.sort = sort;
+    if (typeof qs.search === 'string' && qs.search.length > 0)
+        out.search = qs.search;
+    const { page, size } = parsePagination(qs);
+    if (page !== undefined)
+        out.page = page;
+    if (size !== undefined)
+        out.size = size;
+    return out;
+}
+//# sourceMappingURL=parse_request.js.map

package/dist/src/parse_request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_request.js","sourceRoot":"","sources":["../../src/parse_request.ts"],"names":[],"mappings":"AAGA,SAAS,KAAK,CAAC,KAAc;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,KAAc;IAC3D,gDAAgD;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,yEAAyE;IACzE,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;YACpF,KAAK;YACL,QAAQ,EAAE,QAA+B;YACzC,KAAK,EAAE,OAAO;SACf,CAAC,CAAC,CAAC;IACN,CAAC;IACD,+DAA+D;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO;YACL;gBACE,KAAK;gBACL,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,KAAK;qBACT,KAAK,CAAC,GAAG,CAAC;qBACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;qBACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;aAC/B;SACF,CAAC;IACJ,CAAC;IACD,wBAAwB;IACxB,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,IAAI,GAAG,GAAa,EAAE,CAAC;IACvB,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;SAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IAE3F,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;;YAC/E,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,EAA2B;IAClD,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1B,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,IAAI,IAAI,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,MAAM,CAAC,GAAG,EAAE,CAAC,IAA+B,CAAC;QAC7C,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;QAC/B,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAC/B,CAAC;IACD,OAAO,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAA2B;IAC5D,MAAM,GAAG,GAAgB,EAAE,CAAC;IAE5B,IAAI,EAAE,CAAC,MAAM,IAAI,IAAI,IAAI,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;QACpF,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,MAAiC,CAAC,EAAE,CAAC;YAClF,OAAO,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IAErC,IAAI,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;IAElF,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IACxC,IAAI,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IAExC,OAAO,GAAG,CAAC;AACb,CAAC"}