@adonis-agora/filter 0.1.0

package/dist/src/runner.d.ts

@@ -0,0 +1,46 @@
+import { type CursorParams, type ResolvedCursor } from './cursor.js';
+import { type QueryBuilderLike } from './lucid_adapter.js';
+import type { FilterConfig, FilterInput } from './types.js';
+/** The resolved offset pagination to hand to Lucid's `query.paginate(page, size)`. */
+export interface ResolvedPagination {
+    page: number;
+    size: number;
+}
+/**
+ * Apply a parsed {@link FilterInput} to a Lucid query builder under a
+ * {@link FilterConfig} policy, and return the resolved offset pagination.
+ *
+ * The allow-lists are the security boundary — fields not in `allowed`/`sortable`/
+ * `searchable` are dropped (or rejected with `throwOnInvalid`). Pagination is
+ * returned (not applied) so the caller drives Lucid's `query.paginate()`:
+ *
+ * ```ts
+ * const { page, size } = applyFilter(Users.query(), input, { allowed: ['name', 'age'] })
+ * const result = await Users.query()... // or: await query.paginate(page, size)
+ * ```
+ */
+export declare function applyFilter(qb: QueryBuilderLike, input: FilterInput, config: FilterConfig): ResolvedPagination;
+/** Per-call policy for {@link applyCursor} — a {@link FilterConfig} plus the keyset tiebreaker. */
+export interface CursorConfig extends FilterConfig {
+    /** Primary-key column appended to the keyset as a stable tiebreaker. Default `'id'`. */
+    primaryKey?: string;
+}
+/**
+ * Apply a parsed {@link FilterInput} plus {@link CursorParams} to a Lucid query
+ * builder as a **keyset (cursor) page** under a {@link CursorConfig} policy.
+ *
+ * Filters/search go through the same allow-list boundary as {@link applyFilter}.
+ * The effective (allow-listed) sort, plus the primary-key tiebreaker, forms the
+ * keyset; a supplied `after`/`before` cursor becomes a row-value seek predicate,
+ * and the builder is ordered + limited to `size + 1` (one extra row to detect a
+ * further page). Feed the fetched rows and the returned {@link ResolvedCursor}
+ * to {@link buildCursorPage} to assemble the page and its boundary cursors:
+ *
+ * ```ts
+ * const resolved = applyCursor(Users.query(), input, { allowed: ['name'], primaryKey: 'id' })
+ * const rows = await Users.query()...exec()
+ * const page = buildCursorPage(rows, resolved)
+ * ```
+ */
+export declare function applyCursor(qb: QueryBuilderLike, input: FilterInput & CursorParams, config: CursorConfig): ResolvedCursor;
+//# sourceMappingURL=runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EAIpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,KAAK,gBAAgB,EAOtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAa,YAAY,EAAE,WAAW,EAAY,MAAM,YAAY,CAAC;AAGjF,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AA8HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,gBAAgB,EACpB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,YAAY,GACnB,kBAAkB,CA+BpB;AAED,mGAAmG;AACnG,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,gBAAgB,EACpB,KAAK,EAAE,WAAW,GAAG,YAAY,EACjC,MAAM,EAAE,YAAY,GACnB,cAAc,CA0BhB"}

package/dist/src/runner.js

@@ -0,0 +1,190 @@
+import { buildKeyset, decodeCursor, reverseKeyset, } from './cursor.js';
+import { remapFilterAliases, remapSortAliases } from './field_aliases.js';
+import { applyColumnFilters, applyFullTextSearch, applyKeyset, applySearch, applySort, applyVectorSimilarity, } from './lucid_adapter.js';
+import { InvalidColumnFilterError, validateColumnFilters } from './validate-column-filter.js';
+function isAllowed(field, allow) {
+    if (allow === '*')
+        return true;
+    if (typeof allow === 'function')
+        return allow(field);
+    return allow.includes(field);
+}
+function clamp(n, min, max) {
+    return Math.min(max, Math.max(min, n));
+}
+/**
+ * Recursively prune a filter against the allow-list. A leaf on a disallowed field
+ * is dropped (or throws when `throwOnInvalid`). Group nodes keep only their
+ * surviving children; a group left empty is itself dropped (returns `null`).
+ */
+function prune(filter, allowed, throwOnInvalid) {
+    const hasField = typeof filter.field === 'string' && filter.field.length > 0;
+    if (hasField && !isAllowed(filter.field, allowed)) {
+        if (throwOnInvalid) {
+            throw new InvalidColumnFilterError(`Field "${filter.field}" is not filterable.`);
+        }
+        return null;
+    }
+    const next = { field: filter.field, operator: filter.operator };
+    if (filter.value !== undefined)
+        next.value = filter.value;
+    if (filter.AND) {
+        const kept = filter.AND.map((f) => prune(f, allowed, throwOnInvalid)).filter((f) => f !== null);
+        if (kept.length > 0)
+            next.AND = kept;
+    }
+    if (filter.OR) {
+        const kept = filter.OR.map((f) => prune(f, allowed, throwOnInvalid)).filter((f) => f !== null);
+        if (kept.length > 0)
+            next.OR = kept;
+    }
+    // A pure group node (no field of its own) with no surviving children is empty.
+    if (!hasField && next.AND === undefined && next.OR === undefined) {
+        return null;
+    }
+    return next;
+}
+/**
+ * Resolve aliases, structurally validate, and prune `input.filters`/`input.search`
+ * against the allow-lists, applying the survivors to the builder. Shared by both
+ * {@link applyFilter} (offset) and {@link applyCursor} (keyset) so the security
+ * boundary is identical for either pagination style.
+ */
+function applyFilterConditions(qb, input, config) {
+    const throwOnInvalid = config.throwOnInvalid ?? false;
+    if (input.filters && input.filters.length > 0) {
+        // Alias resolution runs FIRST — the allow-list, validation and query builder
+        // all see the resolved target column, never the client-facing alias key.
+        const aliased = config.aliases
+            ? input.filters.map((f) => remapFilterAliases(f, config.aliases))
+            : input.filters;
+        // Structural validation next (operator/value shape, depth, field charset).
+        validateColumnFilters(aliased);
+        const safe = aliased
+            .map((f) => prune(f, config.allowed, throwOnInvalid))
+            .filter((f) => f !== null);
+        if (safe.length > 0) {
+            applyColumnFilters(qb, safe);
+        }
+    }
+    if (input.search) {
+        const term = input.search.trim();
+        if (term.length > 0) {
+            // tsvector full-text search is the primary path when the policy declares
+            // it; otherwise fall back to the portable ILIKE scan across `searchable`.
+            if (config.fullText) {
+                applyFullTextSearch(qb, {
+                    query: term,
+                    column: config.fullText.column,
+                    ...(config.fullText.language !== undefined && { language: config.fullText.language }),
+                    ...(config.fullText.rank !== undefined && { rank: config.fullText.rank }),
+                    ...(config.fullText.columnKind !== undefined && {
+                        columnKind: config.fullText.columnKind,
+                    }),
+                });
+            }
+            else if (config.searchable && config.searchable.length > 0) {
+                applySearch(qb, term, config.searchable);
+            }
+        }
+    }
+}
+/** Resolve the alias-mapped, allow-listed sort directives for the request. */
+function resolveSafeSort(sort, config) {
+    const throwOnInvalid = config.throwOnInvalid ?? false;
+    const sortable = config.sortable ?? config.allowed;
+    const aliased = config.aliases
+        ? remapSortAliases(sort, config.aliases)
+        : sort;
+    const safe = [];
+    for (const item of aliased) {
+        if (isAllowed(item.field, sortable)) {
+            safe.push(item);
+        }
+        else if (throwOnInvalid) {
+            throw new InvalidColumnFilterError(`Field "${item.field}" is not sortable.`);
+        }
+    }
+    return safe;
+}
+/**
+ * Apply a parsed {@link FilterInput} to a Lucid query builder under a
+ * {@link FilterConfig} policy, and return the resolved offset pagination.
+ *
+ * The allow-lists are the security boundary — fields not in `allowed`/`sortable`/
+ * `searchable` are dropped (or rejected with `throwOnInvalid`). Pagination is
+ * returned (not applied) so the caller drives Lucid's `query.paginate()`:
+ *
+ * ```ts
+ * const { page, size } = applyFilter(Users.query(), input, { allowed: ['name', 'age'] })
+ * const result = await Users.query()... // or: await query.paginate(page, size)
+ * ```
+ */
+export function applyFilter(qb, input, config) {
+    applyFilterConditions(qb, input, config);
+    // Embedding-similarity ranking (opt-in, additive): only when the policy declares
+    // a similarity column AND the request carries a query embedding. Applied before
+    // the user sort so nearest-first distance is the primary ordering; any allowed
+    // sort then acts as a tiebreaker.
+    if (config.vectorSimilarity && input.vectorSimilarity && input.vectorSimilarity.length > 0) {
+        applyVectorSimilarity(qb, {
+            column: config.vectorSimilarity.column,
+            vector: input.vectorSimilarity,
+            ...(config.vectorSimilarity.metric !== undefined && {
+                metric: config.vectorSimilarity.metric,
+            }),
+            ...(config.vectorSimilarity.threshold !== undefined && {
+                threshold: config.vectorSimilarity.threshold,
+            }),
+            ...(config.vectorSimilarity.topK !== undefined && { topK: config.vectorSimilarity.topK }),
+        });
+    }
+    if (input.sort && input.sort.length > 0) {
+        const safeSort = resolveSafeSort(input.sort, config);
+        if (safeSort.length > 0) {
+            applySort(qb, safeSort);
+        }
+    }
+    const size = clamp(input.size ?? config.defaultSize ?? 25, 1, config.maxSize ?? 100);
+    const page = Math.max(1, input.page ?? 1);
+    return { page, size };
+}
+/**
+ * Apply a parsed {@link FilterInput} plus {@link CursorParams} to a Lucid query
+ * builder as a **keyset (cursor) page** under a {@link CursorConfig} policy.
+ *
+ * Filters/search go through the same allow-list boundary as {@link applyFilter}.
+ * The effective (allow-listed) sort, plus the primary-key tiebreaker, forms the
+ * keyset; a supplied `after`/`before` cursor becomes a row-value seek predicate,
+ * and the builder is ordered + limited to `size + 1` (one extra row to detect a
+ * further page). Feed the fetched rows and the returned {@link ResolvedCursor}
+ * to {@link buildCursorPage} to assemble the page and its boundary cursors:
+ *
+ * ```ts
+ * const resolved = applyCursor(Users.query(), input, { allowed: ['name'], primaryKey: 'id' })
+ * const rows = await Users.query()...exec()
+ * const page = buildCursorPage(rows, resolved)
+ * ```
+ */
+export function applyCursor(qb, input, config) {
+    applyFilterConditions(qb, input, config);
+    const safeSort = input.sort && input.sort.length > 0 ? resolveSafeSort(input.sort, config) : [];
+    const baseKeyset = buildKeyset(safeSort, config.primaryKey ?? 'id');
+    const backward = input.before !== undefined && input.after === undefined;
+    const cursorStr = input.after ?? input.before;
+    const requested = backward ? input.last : input.first;
+    const size = clamp(requested ?? config.defaultSize ?? 25, 1, config.maxSize ?? 100);
+    // For backward paging, reverse keyset directions so the boundary seek and
+    // ordering walk the other way; buildCursorPage re-reverses the rows.
+    const queryKeyset = backward ? reverseKeyset(baseKeyset) : baseKeyset;
+    if (cursorStr !== undefined) {
+        const values = decodeCursor(cursorStr);
+        if (values && values.length === queryKeyset.length) {
+            applyKeyset(qb, queryKeyset, values);
+        }
+    }
+    applySort(qb, queryKeyset);
+    qb.limit(size + 1);
+    return { keyset: baseKeyset, size, backward, hasCursor: cursorStr !== undefined };
+}
+//# sourceMappingURL=runner.js.map

package/dist/src/runner.js.map

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

package/dist/src/source_resolver.d.ts

@@ -0,0 +1,18 @@
+import type { InputSource } from './types.js';
+/**
+ * Resolve the raw structured input from a request according to an
+ * {@link InputSource}:
+ *
+ * - a function — a custom extractor, called with the request.
+ * - `'query'` / `'body'` — always that container.
+ * - `'auto'` (or any other bare token) — query on reads (GET/HEAD), query+body
+ *   merged (body wins) on writes (POST/PUT/PATCH/DELETE).
+ * - a dot-path (e.g. `'body.filters'`) — the nested object at that path, or `{}`
+ *   when the path is missing or does not resolve to an object.
+ *
+ * The `req` is treated structurally (`{ method, query, body }`), so an AdonisJS
+ * `HttpContext.request` — whose `qs()`/`body()` you pass in — or a plain object
+ * both work. The result is always a fresh shallow copy.
+ */
+export declare function resolveInputFromRequest(req: unknown, source: InputSource): Record<string, unknown>;
+//# sourceMappingURL=source_resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source_resolver.d.ts","sourceRoot":"","sources":["../../src/source_resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAW9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+BzB"}

package/dist/src/source_resolver.js

@@ -0,0 +1,64 @@
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const READ_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * Resolve the raw structured input from a request according to an
+ * {@link InputSource}:
+ *
+ * - a function — a custom extractor, called with the request.
+ * - `'query'` / `'body'` — always that container.
+ * - `'auto'` (or any other bare token) — query on reads (GET/HEAD), query+body
+ *   merged (body wins) on writes (POST/PUT/PATCH/DELETE).
+ * - a dot-path (e.g. `'body.filters'`) — the nested object at that path, or `{}`
+ *   when the path is missing or does not resolve to an object.
+ *
+ * The `req` is treated structurally (`{ method, query, body }`), so an AdonisJS
+ * `HttpContext.request` — whose `qs()`/`body()` you pass in — or a plain object
+ * both work. The result is always a fresh shallow copy.
+ */
+export function resolveInputFromRequest(req, source) {
+    if (typeof source === 'function') {
+        const r = source(req);
+        return { ...(r ?? {}) };
+    }
+    const r = (req ?? {});
+    const query = (r.query ?? {});
+    const body = (r.body ?? {});
+    switch (source) {
+        case 'query':
+            return { ...query };
+        case 'body':
+            return { ...body };
+        case 'auto': {
+            const method = (r.method ?? 'GET').toUpperCase();
+            if (READ_METHODS.has(method))
+                return { ...query };
+            if (WRITE_METHODS.has(method))
+                return { ...query, ...body };
+            return { ...query };
+        }
+        default: {
+            if (source.includes('.')) {
+                const resolved = resolveDotPath(r, source);
+                return { ...(resolved ?? {}) };
+            }
+            const method = (r.method ?? 'GET').toUpperCase();
+            if (READ_METHODS.has(method))
+                return { ...query };
+            if (WRITE_METHODS.has(method))
+                return { ...query, ...body };
+            return { ...query };
+        }
+    }
+}
+function resolveDotPath(obj, path) {
+    let current = obj;
+    for (const segment of path.split('.')) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    if (current == null || typeof current !== 'object')
+        return undefined;
+    return current;
+}
+//# sourceMappingURL=source_resolver.js.map

package/dist/src/source_resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_resolver.js","sourceRoot":"","sources":["../../src/source_resolver.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAQ9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAY,EACZ,MAAmB;IAEnB,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAA6B,CAAC;IACrD,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAY,CAAC;IACjC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC;IACzD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAC;IAEvD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACjD,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;YAClD,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC;YAC5D,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;QACtB,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;gBAC3C,OAAO,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;YACjC,CAAC;YACD,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACjD,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;YAClD,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC;YAC5D,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,GAAY,EAAE,IAAY;IAChD,IAAI,OAAO,GAAY,GAAG,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACrE,OAAO,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACrE,OAAO,OAAkC,CAAC;AAC5C,CAAC"}

package/dist/src/spatie_parser.d.ts

@@ -0,0 +1,38 @@
+import type { CursorParams } from './cursor.js';
+import type { FilterInput } from './types.js';
+/**
+ * The richer Spatie / JSON:API input shape produced by {@link parseSpatieRequest}.
+ * A superset of {@link FilterInput}: it adds cursor pagination
+ * ({@link CursorParams}), JSON:API sparse fieldsets (`select`) and relation
+ * includes (`include`). Ready to hand to `applyFilter` (offset) or `applyCursor`
+ * (keyset) — the extra fields are ignored by whichever runner does not use them.
+ */
+export interface SpatieInput extends FilterInput, CursorParams {
+    /** JSON:API sparse fieldsets (`fields[resource]=a,b`), flattened + de-duped. */
+    select?: string[];
+    /** Relation includes (`include=posts,comments`). */
+    include?: string[];
+}
+/**
+ * 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                                 |
+ * | `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 declare function parseSpatieRequest(qs: unknown): SpatieInput;
+//# sourceMappingURL=spatie_parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spatie_parser.d.ts","sourceRoot":"","sources":["../../src/spatie_parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW,EAAE,YAAY;IAC5D,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,WAAW,CA2B3D"}

package/dist/src/spatie_parser.js

@@ -0,0 +1,130 @@
+import { 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                                 |
+ * | `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;
+    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,62 @@
+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(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;
+    /**
+     * 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;IAIrC,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAGjD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAOpE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAG9C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAGhD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAGnD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAG/B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAGlC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI;IAG7D,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI;IAGhE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAG/C,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAGjD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI;IAGxD,oFAAoF;IACpF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,IAAI;IAG9D,mFAAmF;IACnF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,OAAO,EAAO,GAAG,IAAI;IAGhE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1B;;;;OAIG;IACH,OAAO,IAAI,YAAY,EAAE;IAKzB,uDAAuD;IACvD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI9C,wFAAwF;IACxF,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE;CAGxC;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,IAAI,gBAAgB,CAEvD"}