@adonis-agora/filter 0.0.0-beta-20261110131309

package/dist/src/coerce_value.js

@@ -0,0 +1,82 @@
+/**
+ * Coerce a raw filter value to its declared column kind, or reject it.
+ *
+ * Why this exists: a filter value arriving over a query string is ALWAYS a string
+ * (`?filter[dayOfWeek][equals]=3` yields `'3'`). Postgres papers over the benign cases with an
+ * implicit cast — `day_of_week = '3'` and `is_recurring = 'false'` both work — so the gap is
+ * invisible until a client sends something that ISN'T castable: `is_recurring = 'xyz'` raises
+ * `invalid input syntax for type boolean` at the database, which surfaces as a 500 on a public
+ * endpoint from pure user input. The allow-list guards which FIELD may be filtered; this guards
+ * what VALUE may reach the column.
+ *
+ * Rejection is not an exception here: the caller maps it onto the spec's existing `throwOnInvalid`
+ * semantics, so a bad value behaves exactly like a disallowed field — dropped by default, or a
+ * loud `InvalidColumnFilterError` (→ 400) when the spec asks for it.
+ */
+export function coerceFilterValue(value, kind) {
+    // `null` is meaningful for every kind (`equals: null` is a legitimate IS NULL comparison) and
+    // never triggers a cast error, so it short-circuits before any kind-specific parsing.
+    if (value === null)
+        return { ok: true, value: null };
+    switch (kind) {
+        case 'number': {
+            if (typeof value === 'number') {
+                return Number.isFinite(value)
+                    ? { ok: true, value }
+                    : { ok: false, reason: 'not a finite number' };
+            }
+            if (typeof value === 'string') {
+                const trimmed = value.trim();
+                // Number('') === 0 and Number(' ') === 0 — both would silently become a valid 0, so an
+                // empty string is rejected up front rather than coerced into a filter nobody asked for.
+                if (trimmed === '')
+                    return { ok: false, reason: 'empty string is not a number' };
+                const n = Number(trimmed);
+                // Number('12abc') is NaN, which is what rejects partial garbage.
+                return Number.isFinite(n) ? { ok: true, value: n } : { ok: false, reason: 'not a number' };
+            }
+            return { ok: false, reason: 'not a number' };
+        }
+        case 'boolean': {
+            if (typeof value === 'boolean')
+                return { ok: true, value };
+            if (typeof value === 'string') {
+                const v = value.trim().toLowerCase();
+                if (v === 'true' || v === '1')
+                    return { ok: true, value: true };
+                if (v === 'false' || v === '0')
+                    return { ok: true, value: false };
+                return { ok: false, reason: 'not a boolean' };
+            }
+            return { ok: false, reason: 'not a boolean' };
+        }
+        case 'date': {
+            if (value instanceof Date) {
+                return Number.isNaN(value.getTime())
+                    ? { ok: false, reason: 'invalid date' }
+                    : { ok: true, value };
+            }
+            if (typeof value === 'string') {
+                const t = Date.parse(value);
+                // The string is handed back VERBATIM rather than as a Date: the driver already parses ISO
+                // strings, and converting here would silently re-zone a date-only value ('2026-07-15'
+                // becomes midnight UTC, which shifts the day for any negative-offset client). Date.parse is
+                // used only to reject, never to rewrite.
+                return Number.isNaN(t) ? { ok: false, reason: 'invalid date' } : { ok: true, value };
+            }
+            return { ok: false, reason: 'not a date' };
+        }
+        case 'string': {
+            if (typeof value === 'string')
+                return { ok: true, value };
+            if (typeof value === 'number' || typeof value === 'boolean') {
+                return { ok: true, value: String(value) };
+            }
+            return { ok: false, reason: 'not a string' };
+        }
+        // No column-level contract to enforce — pass through untouched.
+        default:
+            return { ok: true, value };
+    }
+}
+//# sourceMappingURL=coerce_value.js.map

package/dist/src/coerce_value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce_value.js","sourceRoot":"","sources":["../../src/coerce_value.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,IAAqB;IACrE,8FAA8F;IAC9F,sFAAsF;IACtF,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAErD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,EAAE,CAAC;YACd,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAC3B,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;oBACrB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;YACnD,CAAC;YACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC7B,uFAAuF;gBACvF,wFAAwF;gBACxF,IAAI,OAAO,KAAK,EAAE;oBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;gBACjF,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC1B,iEAAiE;gBACjE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;YAC7F,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAC/C,CAAC;QAED,KAAK,SAAS,EAAE,CAAC;YACf,IAAI,OAAO,KAAK,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBACrC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG;oBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;gBAChE,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,GAAG;oBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YAChD,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QAChD,CAAC;QAED,KAAK,MAAM,EAAE,CAAC;YACZ,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;gBAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;oBAClC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;oBACvC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YAC1B,CAAC;YACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC5B,0FAA0F;gBAC1F,sFAAsF;gBACtF,4FAA4F;gBAC5F,yCAAyC;gBACzC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YACvF,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QAC7C,CAAC;QAED,KAAK,QAAQ,EAAE,CAAC;YACd,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC5D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAC/C,CAAC;QAED,gEAAgE;QAChE;YACE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/dist/src/cursor.d.ts

@@ -0,0 +1,92 @@
+import type { SortItem } from './types.js';
+/**
+ * A decoded keyset cursor: the ordered values of the keyset columns (the active
+ * sort columns plus a stable primary-key tiebreaker) captured from a boundary
+ * row. The values line up positionally with the keyset's {@link SortItem}[].
+ */
+export type CursorValues = unknown[];
+/**
+ * Cursor (keyset) pagination parameters, as parsed from a request:
+ *
+ * - `after` — return the page immediately following this opaque cursor (forward).
+ * - `before` — return the page immediately preceding this opaque cursor (backward).
+ * - `first` / `last` — page size for forward / backward paging respectively.
+ *
+ * `after` and `before` are mutually exclusive; if both are given, `after` wins.
+ */
+export interface CursorParams {
+    after?: string;
+    before?: string;
+    first?: number;
+    last?: number;
+}
+/**
+ * A single page of keyset-paginated results assembled by {@link buildCursorPage}.
+ *
+ * - `items` — the rows for this page, in the requested order.
+ * - `nextCursor` — opaque cursor for the next forward page, or `null` when this
+ *   is the last page.
+ * - `prevCursor` — opaque cursor for the previous (backward) page, or `null`
+ *   when this is the first page.
+ * - `hasNext` / `hasPrev` — convenience booleans mirroring the cursors.
+ */
+export interface CursorPage<T> {
+    items: T[];
+    nextCursor: string | null;
+    prevCursor: string | null;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Encodes keyset cursor values into a compact, URL-safe opaque string
+ * (base64url of a JSON array). The shape is intentionally opaque to clients —
+ * only this module reads it back.
+ *
+ * `Date` values are encoded as `{ $d: <iso> }` so they round-trip to `Date`
+ * instances on decode (plain JSON would yield a string and break date keyset
+ * comparisons).
+ */
+export declare function encodeCursor(values: CursorValues): string;
+/**
+ * Decodes an opaque cursor string back into its keyset values. Returns `null`
+ * when the cursor is malformed (bad base64, bad JSON, or not an array) so the
+ * caller can ignore an invalid cursor instead of crashing.
+ */
+export declare function decodeCursor(cursor: string): CursorValues | null;
+/**
+ * Builds the keyset {@link SortItem}[] for cursor pagination: the caller's
+ * effective sorts, with a stable primary-key tiebreaker appended if it is not
+ * already present. The tiebreaker inherits the direction of the last sort column
+ * so the overall ordering stays monotonic (important for a correct
+ * `(cols, pk) > (...)` comparison).
+ */
+export declare function buildKeyset(sorts: SortItem[], primaryKey: string): SortItem[];
+/** Flips every keyset column's direction (for backward cursor paging). */
+export declare function reverseKeyset(keyset: SortItem[]): SortItem[];
+/**
+ * Extracts the keyset values from a fetched row, in keyset column order.
+ * Supports dotted relation paths (e.g. `author.name`) by walking the object.
+ */
+export declare function extractCursorValues(row: Record<string, unknown>, keyset: SortItem[]): CursorValues;
+/** The keyset shape {@link applyCursor} resolves and hands to {@link buildCursorPage}. */
+export interface ResolvedCursor {
+    /** The base keyset (effective sort + primary-key tiebreaker), in forward order. */
+    keyset: SortItem[];
+    /** Effective page size — the number of rows to keep for this page. */
+    size: number;
+    /** True when paging backward (a `before` cursor was supplied). */
+    backward: boolean;
+    /** True when a cursor (`after`/`before`) was supplied — the opposite page is then known to exist. */
+    hasCursor: boolean;
+}
+/**
+ * Assembles a {@link CursorPage} from the rows fetched for a keyset query.
+ *
+ * The query is expected to have been built by {@link applyCursor}, which fetches
+ * one extra row (`limit = size + 1`) so we can detect a further page. For
+ * backward paging the rows come back reversed and are flipped here to restore
+ * the caller's requested order. Boundary cursors are computed from the base
+ * keyset so they round-trip regardless of paging direction.
+ */
+export declare function buildCursorPage<T extends Record<string, unknown>>(rows: T[], resolved: ResolvedCursor): CursorPage<T>;
+//# sourceMappingURL=cursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAOzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAahE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE,CAK7E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAK5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,QAAQ,EAAE,GACjB,YAAY,CAUd;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;IAClB,qGAAqG;IACrG,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,IAAI,EAAE,CAAC,EAAE,EACT,QAAQ,EAAE,cAAc,GACvB,UAAU,CAAC,CAAC,CAAC,CAwBf"}

package/dist/src/cursor.js

@@ -0,0 +1,107 @@
+/**
+ * Encodes keyset cursor values into a compact, URL-safe opaque string
+ * (base64url of a JSON array). The shape is intentionally opaque to clients —
+ * only this module reads it back.
+ *
+ * `Date` values are encoded as `{ $d: <iso> }` so they round-trip to `Date`
+ * instances on decode (plain JSON would yield a string and break date keyset
+ * comparisons).
+ */
+export function encodeCursor(values) {
+    // Pre-map Date values to a tagged form. We cannot detect dates in the
+    // JSON.stringify replacer because Date.toJSON() has already converted them to
+    // strings by the time the replacer sees the value.
+    const tagged = values.map((v) => (v instanceof Date ? { $d: v.toISOString() } : v));
+    const json = JSON.stringify(tagged);
+    return Buffer.from(json, 'utf8').toString('base64url');
+}
+/**
+ * Decodes an opaque cursor string back into its keyset values. Returns `null`
+ * when the cursor is malformed (bad base64, bad JSON, or not an array) so the
+ * caller can ignore an invalid cursor instead of crashing.
+ */
+export function decodeCursor(cursor) {
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf8');
+        const parsed = JSON.parse(json, (_key, value) => {
+            if (value && typeof value === 'object' && typeof value.$d === 'string') {
+                return new Date(value.$d);
+            }
+            return value;
+        });
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Builds the keyset {@link SortItem}[] for cursor pagination: the caller's
+ * effective sorts, with a stable primary-key tiebreaker appended if it is not
+ * already present. The tiebreaker inherits the direction of the last sort column
+ * so the overall ordering stays monotonic (important for a correct
+ * `(cols, pk) > (...)` comparison).
+ */
+export function buildKeyset(sorts, primaryKey) {
+    const hasPk = sorts.some((s) => s.field === primaryKey);
+    if (hasPk)
+        return sorts;
+    const lastDirection = sorts[sorts.length - 1]?.direction ?? 'asc';
+    return [...sorts, { field: primaryKey, direction: lastDirection }];
+}
+/** Flips every keyset column's direction (for backward cursor paging). */
+export function reverseKeyset(keyset) {
+    return keyset.map((s) => ({
+        field: s.field,
+        direction: s.direction === 'asc' ? 'desc' : 'asc',
+    }));
+}
+/**
+ * Extracts the keyset values from a fetched row, in keyset column order.
+ * Supports dotted relation paths (e.g. `author.name`) by walking the object.
+ */
+export function extractCursorValues(row, keyset) {
+    return keyset.map((s) => {
+        if (!s.field.includes('.'))
+            return row[s.field];
+        let current = row;
+        for (const segment of s.field.split('.')) {
+            if (current == null || typeof current !== 'object')
+                return undefined;
+            current = current[segment];
+        }
+        return current;
+    });
+}
+/**
+ * Assembles a {@link CursorPage} from the rows fetched for a keyset query.
+ *
+ * The query is expected to have been built by {@link applyCursor}, which fetches
+ * one extra row (`limit = size + 1`) so we can detect a further page. For
+ * backward paging the rows come back reversed and are flipped here to restore
+ * the caller's requested order. Boundary cursors are computed from the base
+ * keyset so they round-trip regardless of paging direction.
+ */
+export function buildCursorPage(rows, resolved) {
+    const { keyset, size, backward, hasCursor } = resolved;
+    const hasExtra = rows.length > size;
+    let pageRows = hasExtra ? rows.slice(0, size) : rows;
+    if (backward)
+        pageRows = pageRows.slice().reverse();
+    const firstRow = pageRows[0];
+    const lastRow = pageRows[pageRows.length - 1];
+    const startCursor = firstRow ? encodeCursor(extractCursorValues(firstRow, keyset)) : null;
+    const endCursor = lastRow ? encodeCursor(extractCursorValues(lastRow, keyset)) : null;
+    // With a cursor present, the opposite-direction page is known to exist; the
+    // same-direction page exists iff we saw the extra row.
+    const hasNext = backward ? hasCursor : hasExtra;
+    const hasPrev = backward ? hasExtra : hasCursor;
+    return {
+        items: pageRows,
+        nextCursor: hasNext ? endCursor : null,
+        prevCursor: hasPrev ? startCursor : null,
+        hasNext,
+        hasPrev,
+    };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/src/cursor.js.map

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

package/dist/src/custom_filter.d.ts

@@ -0,0 +1,36 @@
+import type { FilterRequestContext } from './apply_from_request.js';
+import type { BaseFilter } from './base_filter.js';
+import type { FilterInput } from './types.js';
+/**
+ * A filter class over a custom backend, as the container hands it back: constructible, extending
+ * {@link BaseFilter} — the model form's {@link FilterClass} for drafts.
+ */
+export type CustomFilterClass<D> = new (...args: any[]) => BaseFilter<D>;
+/** Options for {@link applyCustomFilter}. */
+export interface ApplyCustomFilterOptions {
+    /**
+     * Pre-parsed input to use instead of reading `ctx.request.qs()`. Useful for non-HTTP callers
+     * and tests; when omitted the query string is parsed via {@link parseFilterRequest}.
+     */
+    input?: FilterInput;
+}
+/**
+ * Run a custom filter class against a caller-created draft from a request context: bind the
+ * per-request state onto the instance, run `setup()`, then hand each filter to its owning method
+ * as `(value, operator, field)`.
+ *
+ * The custom-backend counterpart of
+ * {@link import('./apply_from_request.js').applyFilterFromRequest}: that helper ends in SQL (a
+ * `QueryBuilderLike`), this one ends in whatever the draft accumulates — a `RunQuery`, an engine
+ * client query, an in-memory predicate. The wire format, the parsing, the method dispatch and the
+ * error shapes are shared, so a console can move between a Lucid listing and a custom-backend one
+ * without relearning the spelling.
+ *
+ * ```ts
+ * const draft = new RunQueryDraft();
+ * await applyCustomFilter(draft, RunFilter, ctx);
+ * const runs = await engine.listRuns(draft.query);
+ * ```
+ */
+export declare function applyCustomFilter<D>(draft: D, cls: CustomFilterClass<D>, ctx: FilterRequestContext | undefined, options?: ApplyCustomFilterOptions): Promise<void>;
+//# sourceMappingURL=custom_filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"custom_filter.d.ts","sourceRoot":"","sources":["../../src/custom_filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAO9C;;;GAGG;AAEH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC;AAEzE,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AA+GD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EACzB,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAyBf"}

package/dist/src/custom_filter.js

@@ -0,0 +1,127 @@
+import { methodForKey } from './filter_class.js';
+import { FILTER_OPERATORS } from './operators.js';
+import { parseFilterRequest } from './parse_request.js';
+import { InvalidColumnFilterError, MAX_FILTER_DEPTH, normalizeOperator, } from './validate-column-filter.js';
+/**
+ * Resolve a custom filter class through the request's IoC container when there is one — the same
+ * resolver a controller is constructed with, so `@inject()` on the filter behaves identically —
+ * and fall back to plain construction outside an AdonisJS request (a test, a script).
+ */
+async function resolveCustomFilter(cls, ctx) {
+    const resolver = ctx?.containerResolver;
+    if (resolver && typeof resolver.make === 'function') {
+        return (await resolver.make(cls));
+    }
+    return new cls();
+}
+/**
+ * The method owning `field`: an exact `@filterFor`/own-method match first, else the head segment
+ * (`attr.tier` reaches `attr`) so one method can own a whole dynamic subtree. The full field still
+ * rides along as the method's third argument, so the method always knows which key it was reached
+ * through.
+ *
+ * The cast is sound: method dispatch only walks the prototype chain and reads static knobs, both
+ * of which a custom filter class carries exactly like a model filter class (the walk simply ends
+ * at `Object.prototype` instead of `BaseModelFilter.prototype`, with the same result — and at
+ * `BaseFilter.prototype` for the shared members, which are never dispatchable).
+ */
+function resolveMethod(cls, field) {
+    const asModelFilter = cls;
+    const exact = methodForKey(asModelFilter, field);
+    if (exact !== undefined)
+        return exact;
+    const dot = field.indexOf('.');
+    if (dot > 0)
+        return methodForKey(asModelFilter, field.slice(0, dot));
+    return undefined;
+}
+/**
+ * Collect the calls a parsed input dispatches to: every structured filter to its owning method
+ * (`AND` groups recurse; `OR` is rejected — a draft is an ANDed predicate bag and cannot express
+ * cross-field OR), then every bare top-level key the wire format does not own (`?tag=etl`, the
+ * legacy spelling) to its same-named method. Unknown BARE keys are ignored — they are how old
+ * callers send pagination and other endpoint mechanics — while an unknown STRUCTURED field is
+ * rejected outright: the new spelling fails loudly on typos instead of silently widening.
+ */
+function collectCalls(cls, raw, parsed) {
+    const calls = [];
+    const visit = (filter, depth) => {
+        if (depth > MAX_FILTER_DEPTH) {
+            throw new InvalidColumnFilterError(`Filter nesting exceeds maximum depth (${MAX_FILTER_DEPTH}).`);
+        }
+        const isGroupNode = (filter.AND !== undefined || filter.OR !== undefined) &&
+            (filter.field === undefined || filter.field === '');
+        if (isGroupNode) {
+            if (filter.OR !== undefined) {
+                throw new InvalidColumnFilterError('This filter does not support OR groups — a draft is an ANDed predicate bag.');
+            }
+            for (const sub of filter.AND ?? [])
+                visit(sub, depth + 1);
+            return;
+        }
+        if (typeof filter.field !== 'string' || filter.field === '') {
+            throw new InvalidColumnFilterError('Column filter needs a field.');
+        }
+        // SQL-symbol aliases (`=`, `!=`, …) normalize to canonical operators first, so methods only
+        // ever see the canonical spelling — the same normalization the SQL path applies.
+        const operator = normalizeOperator(String(filter.operator));
+        if (!FILTER_OPERATORS.includes(operator)) {
+            throw new InvalidColumnFilterError(`Unknown filter operator: "${String(filter.operator)}".`);
+        }
+        const method = resolveMethod(cls, filter.field);
+        if (method === undefined) {
+            throw new InvalidColumnFilterError(`Unknown filter field: "${filter.field}".`);
+        }
+        calls.push({ method, value: filter.value, operator, field: filter.field });
+    };
+    for (const filter of parsed.filters ?? [])
+        visit(filter, 0);
+    // A bare top-level key (`?tag=etl`) reaches a method of the same name too — the legacy spelling
+    // — as long as the wire format does not own the key and no structured filter already claimed it.
+    // The reserved gate inside `methodForKey` is what keeps endpoint mechanics (`limit`, `sort`, …)
+    // from ever reaching a method here.
+    for (const [key, value] of Object.entries(raw)) {
+        const method = resolveMethod(cls, key);
+        if (method !== undefined && !calls.some((call) => call.method === method)) {
+            calls.push({ method, value, operator: 'equals', field: key });
+        }
+    }
+    return calls;
+}
+/**
+ * Run a custom filter class against a caller-created draft from a request context: bind the
+ * per-request state onto the instance, run `setup()`, then hand each filter to its owning method
+ * as `(value, operator, field)`.
+ *
+ * The custom-backend counterpart of
+ * {@link import('./apply_from_request.js').applyFilterFromRequest}: that helper ends in SQL (a
+ * `QueryBuilderLike`), this one ends in whatever the draft accumulates — a `RunQuery`, an engine
+ * client query, an in-memory predicate. The wire format, the parsing, the method dispatch and the
+ * error shapes are shared, so a console can move between a Lucid listing and a custom-backend one
+ * without relearning the spelling.
+ *
+ * ```ts
+ * const draft = new RunQueryDraft();
+ * await applyCustomFilter(draft, RunFilter, ctx);
+ * const runs = await engine.listRuns(draft.query);
+ * ```
+ */
+export async function applyCustomFilter(draft, cls, ctx, options = {}) {
+    const raw = ctx?.request?.qs?.() ?? {};
+    const parsed = options.input ?? parseFilterRequest(raw);
+    const instance = await resolveCustomFilter(cls, ctx);
+    Object.assign(instance, {
+        $query: draft,
+        $input: raw,
+        $parsed: parsed,
+        $ctx: ctx,
+    });
+    await instance.setup?.();
+    for (const { method, value, operator, field } of collectCalls(cls, raw, parsed)) {
+        const fn = instance[method];
+        if (typeof fn === 'function') {
+            await fn.call(instance, value, operator, field);
+        }
+    }
+}
+//# sourceMappingURL=custom_filter.js.map

package/dist/src/custom_filter.js.map

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

package/dist/src/decorator_metadata.d.ts

@@ -0,0 +1,41 @@
+import type { FilterFieldKind } from './types.js';
+/**
+ * What the decorators record about a class, per declaration site.
+ *
+ * Two storage channels back this, because two decorator flavours exist in the wild:
+ *
+ * - **legacy** (`experimentalDecorators`, what AdonisJS uses today — Lucid's `@column` requires
+ *   it) hands the decorator the *prototype*, so the record is kept in a `WeakMap` keyed by it;
+ * - **standard** (TC39 stage 3, TypeScript 5's default when the flag is off) hands the decorator
+ *   a context object carrying a per-class `metadata` bag, so the record is kept in there.
+ *
+ * Both are read back the same way, so a class works under either flavour — and inheritance falls
+ * out of the walk: prototype chain for the first, the metadata object's own prototype chain
+ * (which the standard emit links to the base class's) for the second.
+ */
+export interface FilterDecoratorRecord {
+    /** Method name → the request keys `@filterFor` bound it to. */
+    filterFor?: Record<string, string[]>;
+    /** Column name → the kind `@filterable` declared, or `null` when it declared none. */
+    filterable?: Record<string, FilterFieldKind | null>;
+    /** Columns marked `@sortable`. */
+    sortable?: string[];
+    /** Columns marked `@searchable`. */
+    searchable?: string[];
+}
+/** The record a legacy decorator writes into, created on first use. */
+export declare function legacyRecord(prototype: object): FilterDecoratorRecord;
+/**
+ * The record a standard decorator writes into. The bag a subclass receives *inherits* from its
+ * base's, so the record is defined as an **own** property — writing through the inherited one
+ * would leak a subclass's bindings back onto the parent.
+ */
+export declare function standardRecord(metadata: object): FilterDecoratorRecord;
+/**
+ * The merged declaration for a class — its own decorators layered over everything it inherits.
+ *
+ * Not memoized: decorators run at class-definition time, but a model's columns and a filter's
+ * methods are read once per compiled spec, which is itself cached by the caller.
+ */
+export declare function readDecorators(cls: object): FilterDecoratorRecord;
+//# sourceMappingURL=decorator_metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorator_metadata.d.ts","sourceRoot":"","sources":["../../src/decorator_metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC,CAAC;IACpD,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAoBD,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,CAMrE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAUtE;AA6BD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CASjE"}

package/dist/src/decorator_metadata.js

@@ -0,0 +1,83 @@
+/** The key the record is filed under inside a standard decorator's metadata bag. */
+const NAMESPACE = '@adonis-agora/filter';
+/** Legacy channel: prototype (or model prototype) → record. */
+const LEGACY = new WeakMap();
+/**
+ * The symbols a standard decorator's metadata bag may be stamped on: the real `Symbol.metadata`
+ * when the runtime (or a polyfill) has it, and the registered fallback TypeScript's emit uses
+ * otherwise. Resolved on every read rather than captured once, so a polyfill installed after this
+ * module loads is still seen.
+ */
+function metadataSymbols() {
+    const native = Symbol.metadata;
+    const fallback = Symbol.for('Symbol.metadata');
+    return native && native !== fallback ? [native, fallback] : [fallback];
+}
+/** The record a legacy decorator writes into, created on first use. */
+export function legacyRecord(prototype) {
+    const existing = LEGACY.get(prototype);
+    if (existing)
+        return existing;
+    const record = {};
+    LEGACY.set(prototype, record);
+    return record;
+}
+/**
+ * The record a standard decorator writes into. The bag a subclass receives *inherits* from its
+ * base's, so the record is defined as an **own** property — writing through the inherited one
+ * would leak a subclass's bindings back onto the parent.
+ */
+export function standardRecord(metadata) {
+    if (!Object.hasOwn(metadata, NAMESPACE)) {
+        Object.defineProperty(metadata, NAMESPACE, {
+            value: {},
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return metadata[NAMESPACE];
+}
+/** Every record that applies to a class, base first — so a subclass's declaration wins. */
+function recordsFor(cls) {
+    const found = [];
+    const prototype = cls.prototype;
+    let proto = prototype ?? null;
+    while (proto !== null && proto !== Object.prototype) {
+        const record = LEGACY.get(proto);
+        if (record)
+            found.push(record);
+        proto = Object.getPrototypeOf(proto);
+    }
+    for (const symbol of metadataSymbols()) {
+        let bag = cls[symbol] ?? null;
+        while (bag !== null) {
+            if (Object.hasOwn(bag, NAMESPACE)) {
+                found.push(bag[NAMESPACE]);
+            }
+            bag = Object.getPrototypeOf(bag);
+        }
+    }
+    return found.reverse();
+}
+/**
+ * The merged declaration for a class — its own decorators layered over everything it inherits.
+ *
+ * Not memoized: decorators run at class-definition time, but a model's columns and a filter's
+ * methods are read once per compiled spec, which is itself cached by the caller.
+ */
+export function readDecorators(cls) {
+    const merged = {};
+    for (const record of recordsFor(cls)) {
+        if (record.filterFor)
+            merged.filterFor = { ...merged.filterFor, ...record.filterFor };
+        if (record.filterable)
+            merged.filterable = { ...merged.filterable, ...record.filterable };
+        if (record.sortable)
+            merged.sortable = [...(merged.sortable ?? []), ...record.sortable];
+        if (record.searchable)
+            merged.searchable = [...(merged.searchable ?? []), ...record.searchable];
+    }
+    return merged;
+}
+//# sourceMappingURL=decorator_metadata.js.map

package/dist/src/decorator_metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator_metadata.js","sourceRoot":"","sources":["../../src/decorator_metadata.ts"],"names":[],"mappings":"AA2BA,oFAAoF;AACpF,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEzC,+DAA+D;AAC/D,MAAM,MAAM,GAAG,IAAI,OAAO,EAAiC,CAAC;AAE5D;;;;;GAKG;AACH,SAAS,eAAe;IACtB,MAAM,MAAM,GAAI,MAA2C,CAAC,QAAQ,CAAC;IACrE,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC/C,OAAO,MAAM,IAAI,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE;YACzC,KAAK,EAAE,EAAkC;YACzC,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC;IACD,OAAQ,QAAkD,CAAC,SAAS,CAA0B,CAAC;AACjG,CAAC;AAED,2FAA2F;AAC3F,SAAS,UAAU,CAAC,GAAW;IAC7B,MAAM,KAAK,GAA4B,EAAE,CAAC;IAE1C,MAAM,SAAS,GAAI,GAA8B,CAAC,SAAS,CAAC;IAC5D,IAAI,KAAK,GAAkB,SAAS,IAAI,IAAI,CAAC;IAC7C,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/B,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAkB,CAAC;IACxD,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,EAAE,CAAC;QACvC,IAAI,GAAG,GAAI,GAA0C,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;QACtE,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC;gBAClC,KAAK,CAAC,IAAI,CACP,GAA6C,CAAC,SAAS,CAA0B,CACnF,CAAC;YACJ,CAAC;YACD,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAkB,CAAC;QACpD,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,KAAK,MAAM,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,MAAM,CAAC,SAAS;YAAE,MAAM,CAAC,SAAS,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QACtF,IAAI,MAAM,CAAC,UAAU;YAAE,MAAM,CAAC,UAAU,GAAG,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1F,IAAI,MAAM,CAAC,QAAQ;YAAE,MAAM,CAAC,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxF,IAAI,MAAM,CAAC,UAAU;YAAE,MAAM,CAAC,UAAU,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}