@adonis-agora/filter 0.7.0 → 0.8.0

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"}

package/dist/src/decorators.d.ts

@@ -0,0 +1,73 @@
+import type { FilterFieldKind } from './types.js';
+/**
+ * A decorator that works under both flavours — the legacy `(prototype, key, descriptor)` form
+ * AdonisJS compiles today (`experimentalDecorators`, which Lucid's `@column` requires) and the
+ * TC39 standard `(value, context)` form TypeScript 5 emits when that flag is off. Which one runs
+ * is decided at call time, from the shape of the second argument.
+ */
+export interface DualDecorator {
+    (target: object, propertyKey: string | symbol, descriptor?: PropertyDescriptor): void;
+    (value: unknown, context: StandardDecoratorContext): void;
+}
+/** The slice of a TC39 decorator context this library reads. */
+export interface StandardDecoratorContext {
+    kind: string;
+    name: string | symbol;
+    metadata?: object;
+}
+/**
+ * Bind a filter method to the request key(s) it answers, instead of deriving the key from the
+ * method's name.
+ *
+ * Worth reaching for exactly twice: when the key cannot be a method name (`team.name`), and when
+ * one method should answer several keys. It also pins the public contract — with a binding, the
+ * key survives renaming the method.
+ *
+ * ```ts
+ * export default class UserFilter extends BaseModelFilter {
+ *   @filterFor('team.name')
+ *   byTeamName(value: string) {
+ *     this.$query.whereHas('team', (team) => team.whereILike('name', `%${value}%`))
+ *   }
+ *
+ *   @filterFor('q', 'query')
+ *   freeText(value: string) { … }
+ * }
+ * ```
+ *
+ * A bound method answers **only** its declared keys: `?filter[byTeamName]=…` stops working, which
+ * is the point — the method name becomes an implementation detail.
+ */
+export declare function filterFor(...keys: string[]): DualDecorator;
+/**
+ * Mark a model column as filterable — the allow-list, declared where the column is, stacked under
+ * Lucid's own `@column()`.
+ *
+ * ```ts
+ * export default class User extends compose(BaseModel, Filterable) {
+ *   @column()
+ *   @filterable()
+ *   declare status: string
+ *
+ *   @column()
+ *   @filterable('number')
+ *   declare age: number
+ *
+ *   @column({ serializeAs: null })
+ *   declare passwordHash: string   // undecorated — unreachable, as it should be
+ * }
+ * ```
+ *
+ * A filter class picks these up through its `static model`. Anything the filter declares itself
+ * still wins outright, so a stricter filter over a shared model can narrow the surface:
+ * `static filterable = ['status']` exposes that column and no other.
+ *
+ * The optional kind is the same one the colocated `filterable` map takes: it drives value
+ * coercion and the generated client's types.
+ */
+export declare function filterable(kind?: FilterFieldKind): DualDecorator;
+/** Mark a model column as sortable — `?sort=-createdAt` reaches it, nothing else does. */
+export declare function sortable(): DualDecorator;
+/** Mark a model column as scanned by the free-text `?search=` term. */
+export declare function searchable(): DualDecorator;
+//# sourceMappingURL=decorators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtF,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC3D;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAwCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAmB1D;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,aAAa,CAKhE;AAED,0FAA0F;AAC1F,wBAAgB,QAAQ,IAAI,aAAa,CAKxC;AAED,uEAAuE;AACvE,wBAAgB,UAAU,IAAI,aAAa,CAK1C"}

package/dist/src/decorators.js

@@ -0,0 +1,118 @@
+import { legacyRecord, standardRecord } from './decorator_metadata.js';
+import { isReservedKey } from './filter_class.js';
+import { FilterDefinitionError } from './filter_spec.js';
+/** Standard decorators are handed a context object; legacy ones a property key. */
+function isStandardContext(value) {
+    return typeof value === 'object' && value !== null && 'kind' in value;
+}
+/**
+ * Resolve where a decorator should write, whichever flavour invoked it: the declared member's
+ * name, and the record for the class that declared it.
+ */
+function target(what, expectedKinds, first, second) {
+    if (isStandardContext(second)) {
+        if (!expectedKinds.includes(second.kind)) {
+            throw new FilterDefinitionError(`${what} goes on ${expectedKinds.join(' or ')}, not on a ${second.kind}.`);
+        }
+        if (!second.metadata) {
+            throw new FilterDefinitionError(`${what} needs decorator metadata, which this runtime does not provide. Polyfill \`Symbol.metadata\` (\`Symbol.metadata ??= Symbol('Symbol.metadata')\`), or compile with \`experimentalDecorators\` as AdonisJS does.`);
+        }
+        return { name: String(second.name), record: standardRecord(second.metadata) };
+    }
+    if (typeof first === 'function') {
+        throw new FilterDefinitionError(`${what} goes on an instance member, not a static one.`);
+    }
+    if (typeof first !== 'object' || first === null) {
+        throw new FilterDefinitionError(`${what} was applied to something that is not a class member.`);
+    }
+    return { name: String(second), record: legacyRecord(first) };
+}
+/**
+ * Bind a filter method to the request key(s) it answers, instead of deriving the key from the
+ * method's name.
+ *
+ * Worth reaching for exactly twice: when the key cannot be a method name (`team.name`), and when
+ * one method should answer several keys. It also pins the public contract — with a binding, the
+ * key survives renaming the method.
+ *
+ * ```ts
+ * export default class UserFilter extends BaseModelFilter {
+ *   @filterFor('team.name')
+ *   byTeamName(value: string) {
+ *     this.$query.whereHas('team', (team) => team.whereILike('name', `%${value}%`))
+ *   }
+ *
+ *   @filterFor('q', 'query')
+ *   freeText(value: string) { … }
+ * }
+ * ```
+ *
+ * A bound method answers **only** its declared keys: `?filter[byTeamName]=…` stops working, which
+ * is the point — the method name becomes an implementation detail.
+ */
+export function filterFor(...keys) {
+    if (keys.length === 0) {
+        throw new FilterDefinitionError('@filterFor() needs at least one request key.');
+    }
+    for (const key of keys) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new FilterDefinitionError('@filterFor() keys must be non-empty strings.');
+        }
+        if (isReservedKey(key)) {
+            throw new FilterDefinitionError(`@filterFor('${key}') — '${key}' is a key the wire format itself owns (page, sort, search, …), so it never reaches a method. Bind another key.`);
+        }
+    }
+    return ((first, second) => {
+        const { name, record } = target('@filterFor()', ['method'], first, second);
+        record.filterFor = { ...record.filterFor, [name]: [...keys] };
+    });
+}
+/** The member kinds a column decorator may sit on. */
+const COLUMN_KINDS = ['field', 'accessor', 'getter', 'setter'];
+/**
+ * Mark a model column as filterable — the allow-list, declared where the column is, stacked under
+ * Lucid's own `@column()`.
+ *
+ * ```ts
+ * export default class User extends compose(BaseModel, Filterable) {
+ *   @column()
+ *   @filterable()
+ *   declare status: string
+ *
+ *   @column()
+ *   @filterable('number')
+ *   declare age: number
+ *
+ *   @column({ serializeAs: null })
+ *   declare passwordHash: string   // undecorated — unreachable, as it should be
+ * }
+ * ```
+ *
+ * A filter class picks these up through its `static model`. Anything the filter declares itself
+ * still wins outright, so a stricter filter over a shared model can narrow the surface:
+ * `static filterable = ['status']` exposes that column and no other.
+ *
+ * The optional kind is the same one the colocated `filterable` map takes: it drives value
+ * coercion and the generated client's types.
+ */
+export function filterable(kind) {
+    return ((first, second) => {
+        const { name, record } = target('@filterable()', COLUMN_KINDS, first, second);
+        record.filterable = { ...record.filterable, [name]: kind ?? null };
+    });
+}
+/** Mark a model column as sortable — `?sort=-createdAt` reaches it, nothing else does. */
+export function sortable() {
+    return ((first, second) => {
+        const { name, record } = target('@sortable()', COLUMN_KINDS, first, second);
+        record.sortable = [...(record.sortable ?? []), name];
+    });
+}
+/** Mark a model column as scanned by the free-text `?search=` term. */
+export function searchable() {
+    return ((first, second) => {
+        const { name, record } = target('@searchable()', COLUMN_KINDS, first, second);
+        record.searchable = [...(record.searchable ?? []), name];
+    });
+}
+//# sourceMappingURL=decorators.js.map

package/dist/src/decorators.js.map

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

package/dist/src/filter_class.d.ts

@@ -0,0 +1,46 @@
+import { BaseModelFilter } from './base_model_filter.js';
+import { type FilterSpec } from './filter_spec.js';
+/**
+ * A filter class as the container hands it back: constructible, extending {@link BaseModelFilter}
+ * — and carrying that base's static declarations (`filterable`, `sortable`, `blacklist`, …).
+ *
+ * Spelled as an intersection with `typeof BaseModelFilter` rather than an index signature: a
+ * concrete `class UserFilter extends BaseModelFilter` has no index signature, so
+ * `Record<string, unknown>` here would make every real filter class *unassignable* to this type —
+ * `static $filter = () => UserFilter` on a model would not compile.
+ */
+export type FilterClass = new (...args: any[]) => BaseModelFilter;
+/**
+ * Is this a filter class (as opposed to a `defineFilter` spec)? Checked structurally — a class
+ * that extends {@link BaseModelFilter} — so the two forms can share one entry point.
+ */
+export declare function isFilterClass(value: unknown): value is FilterClass;
+/**
+ * The request keys a class owns with a method of its own, walking the prototype chain up to (but
+ * not including) {@link BaseModelFilter} — so a shared abstract filter's methods are inherited
+ * like any other. `setup`, the constructor, `$`-prefixed members and anything on the class's
+ * `blacklist` are excluded.
+ *
+ * Memoized per class: the shape of a class does not change between requests.
+ */
+export declare function dispatchKeys(cls: FilterClass): ReadonlySet<string>;
+/**
+ * Compile a filter class's static declarations into the {@link FilterSpec} the runner consumes —
+ * the same object `defineFilter` produces, so a class and a spec take the identical code path
+ * through allow-listing, search, sort and pagination.
+ *
+ * A class that declares no `filterable` is method-only: nothing reaches SQL except through the
+ * methods it wrote, which is the tightest allow-list there is.
+ *
+ * Memoized per class — the declaration is static, so it is compiled once per process.
+ */
+export declare function specFromFilterClass(cls: FilterClass): FilterSpec;
+/**
+ * Find the method a request key maps to, honouring the class's `camelCase` (a `snake_case` key
+ * matches a camelCase method — on by default) and `dropId` (`companyId` matches `company`) knobs.
+ * Returns the method name, or `undefined` when the class does not own the key.
+ */
+export declare function methodForKey(cls: FilterClass, key: string): string | undefined;
+/** Is this key one the wire format owns (so it is never dispatched to a method)? */
+export declare function isReservedKey(key: string): boolean;
+//# sourceMappingURL=filter_class.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filter_class.d.ts","sourceRoot":"","sources":["../../src/filter_class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,kBAAkB,CAAC;AAGjE;;;;;;;;GAQG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,eAAe,CAAC;AAkDlE;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC,CAmBlE;AAkCD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,CA8BhE;AAoDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuB9E;AAcD,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD"}

package/dist/src/filter_class.js

@@ -0,0 +1,238 @@
+import { BaseModelFilter } from './base_model_filter.js';
+import { readDecorators } from './decorator_metadata.js';
+import { defineFilter } from './filter_spec.js';
+/**
+ * A filter class's static side. Read through a cast rather than declared on {@link FilterClass}
+ * itself: an index signature there would make every concrete `class UserFilter extends
+ * BaseModelFilter` *unassignable* to the type — `static $filter = () => UserFilter` on a model
+ * would stop compiling.
+ */
+function statics(cls) {
+    return cls;
+}
+/** Request keys the wire format owns — never dispatched to a method of the same name. */
+const RESERVED_KEYS = new Set([
+    'filter',
+    'filters',
+    'sort',
+    'search',
+    'page',
+    'size',
+    'distinct',
+    'include',
+    'select',
+    'after',
+    'before',
+    'first',
+    'last',
+    'limit',
+    'offset',
+]);
+/** Names on the class that are machinery, not request keys. */
+const RESERVED_METHODS = new Set(['constructor', 'setup', 'input']);
+/**
+ * Is this a filter class (as opposed to a `defineFilter` spec)? Checked structurally — a class
+ * that extends {@link BaseModelFilter} — so the two forms can share one entry point.
+ */
+export function isFilterClass(value) {
+    if (typeof value !== 'function')
+        return false;
+    let proto = Object.getPrototypeOf(value);
+    while (proto !== null && proto !== Function.prototype) {
+        if (proto === BaseModelFilter)
+            return true;
+        proto = Object.getPrototypeOf(proto);
+    }
+    return false;
+}
+/**
+ * The request keys a class owns with a method of its own, walking the prototype chain up to (but
+ * not including) {@link BaseModelFilter} — so a shared abstract filter's methods are inherited
+ * like any other. `setup`, the constructor, `$`-prefixed members and anything on the class's
+ * `blacklist` are excluded.
+ *
+ * Memoized per class: the shape of a class does not change between requests.
+ */
+export function dispatchKeys(cls) {
+    const cached = KEY_CACHE.get(cls);
+    if (cached)
+        return cached;
+    const blacklist = new Set(statics(cls).blacklist ?? []);
+    const bound = explicitBindings(cls).methods;
+    const keys = new Set();
+    let proto = cls.prototype;
+    while (proto !== null && proto !== BaseModelFilter.prototype && proto !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(proto)) {
+            if (RESERVED_METHODS.has(name) || blacklist.has(name) || bound.has(name))
+                continue;
+            if (name.startsWith('$') || name.startsWith('_'))
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+            if (typeof descriptor?.value === 'function')
+                keys.add(name);
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    KEY_CACHE.set(cls, keys);
+    return keys;
+}
+/**
+ * The `@filterFor` bindings a class declares: request key → method, and the set of methods that
+ * are bound (and so no longer answer to their own name).
+ *
+ * Memoized per class alongside the dispatch keys — decorators run at class-definition time, long
+ * before the first request reaches the class.
+ */
+function explicitBindings(cls) {
+    const cached = BINDING_CACHE.get(cls);
+    if (cached)
+        return cached;
+    const keys = new Map();
+    const methods = new Set();
+    const blacklist = new Set(statics(cls).blacklist ?? []);
+    for (const [method, bound] of Object.entries(readDecorators(cls).filterFor ?? {})) {
+        if (blacklist.has(method))
+            continue;
+        methods.add(method);
+        for (const key of bound)
+            keys.set(key, method);
+    }
+    const bindings = { keys, methods };
+    BINDING_CACHE.set(cls, bindings);
+    return bindings;
+}
+const BINDING_CACHE = new WeakMap();
+const KEY_CACHE = new WeakMap();
+const SPEC_CACHE = new WeakMap();
+/**
+ * Compile a filter class's static declarations into the {@link FilterSpec} the runner consumes —
+ * the same object `defineFilter` produces, so a class and a spec take the identical code path
+ * through allow-listing, search, sort and pagination.
+ *
+ * A class that declares no `filterable` is method-only: nothing reaches SQL except through the
+ * methods it wrote, which is the tightest allow-list there is.
+ *
+ * Memoized per class — the declaration is static, so it is compiled once per process.
+ */
+export function specFromFilterClass(cls) {
+    const cached = SPEC_CACHE.get(cls);
+    if (cached)
+        return cached;
+    const declared = declaredByModel(cls);
+    const spec = defineFilter({
+        ...declared,
+        filterable: statics(cls).filterable ?? declared.filterable ?? [],
+        ...pick(cls, [
+            'model',
+            'sortable',
+            'searchable',
+            'relations',
+            'aliases',
+            'computed',
+            'fieldTypes',
+            'fullText',
+            'vectorSimilarity',
+            'tenant',
+            'defaultFilters',
+            'defaultSort',
+            'defaultSize',
+            'maxSize',
+            'maxDepth',
+            'table',
+            'throwOnInvalid',
+        ]),
+    });
+    SPEC_CACHE.set(cls, spec);
+    return spec;
+}
+/**
+ * What the model itself declares through `@filterable` / `@sortable` / `@searchable` on its
+ * columns, read off the filter's `static model`.
+ *
+ * These are **fallbacks**: a static on the filter class replaces the corresponding list outright,
+ * so a stricter filter over a shared model can narrow what the model opens up. Only `fieldTypes`
+ * merges per field — it is metadata about a column, not a decision about who may reach it.
+ */
+function declaredByModel(cls) {
+    const model = statics(cls).model;
+    if (!model)
+        return {};
+    const declared = readDecorators(model);
+    const out = {};
+    if (declared.filterable) {
+        out.filterable = Object.keys(declared.filterable);
+        const fieldTypes = {};
+        for (const [column, kind] of Object.entries(declared.filterable)) {
+            if (kind !== null)
+                fieldTypes[column] = { kind };
+        }
+        const merged = { ...fieldTypes, ...statics(cls).fieldTypes };
+        if (Object.keys(merged).length > 0)
+            out.fieldTypes = merged;
+    }
+    if (declared.sortable)
+        out.sortable = [...new Set(declared.sortable)];
+    if (declared.searchable)
+        out.searchable = [...new Set(declared.searchable)];
+    return out;
+}
+function pick(cls, names) {
+    const out = {};
+    const statics = cls;
+    for (const name of names) {
+        const value = statics[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+/**
+ * Find the method a request key maps to, honouring the class's `camelCase` (a `snake_case` key
+ * matches a camelCase method — on by default) and `dropId` (`companyId` matches `company`) knobs.
+ * Returns the method name, or `undefined` when the class does not own the key.
+ */
+export function methodForKey(cls, key) {
+    if (typeof key !== 'string' || key.length === 0 || RESERVED_KEYS.has(key))
+        return undefined;
+    const bound = explicitBindings(cls).keys.get(key);
+    if (bound !== undefined)
+        return bound;
+    const keys = dispatchKeys(cls);
+    if (keys.has(key))
+        return key;
+    const knobs = statics(cls);
+    if (knobs.camelCase !== false) {
+        const camel = toCamelCase(key);
+        if (keys.has(camel))
+            return camel;
+        if (knobs.dropId === true) {
+            const dropped = stripId(camel);
+            if (dropped.length > 0 && keys.has(dropped))
+                return dropped;
+        }
+    }
+    if (knobs.dropId === true) {
+        const dropped = stripId(key);
+        if (dropped.length > 0 && keys.has(dropped))
+            return dropped;
+    }
+    return undefined;
+}
+function toCamelCase(key) {
+    const result = key.replace(/[_-](\w)/g, (_, char) => char.toUpperCase());
+    return result.charAt(0).toLowerCase() + result.slice(1);
+}
+function stripId(key) {
+    if (key === 'id')
+        return '';
+    if (key.endsWith('Id'))
+        return key.slice(0, -2);
+    if (key.endsWith('_id'))
+        return key.slice(0, -3);
+    return key;
+}
+/** Is this key one the wire format owns (so it is never dispatched to a method)? */
+export function isReservedKey(key) {
+    return RESERVED_KEYS.has(key);
+}
+//# sourceMappingURL=filter_class.js.map

package/dist/src/filter_class.js.map

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

package/dist/src/filterable_mixin.d.ts

@@ -0,0 +1,49 @@
+import type { NormalizeConstructor } from '@adonisjs/core/types/helpers';
+import type { LucidModel, ModelPaginatorContract, ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type ApplyFromRequestOptions, type FilterRequestContext } from './apply_from_request.js';
+import type { FilterClass } from './filter_class.js';
+import type { FilterSpec } from './filter_spec.js';
+import type { ResolvedPagination } from './runner.js';
+/**
+ * Opt a Lucid model into filtering — the `adonis-lucid-filter` shape, with the rest of the
+ * pipeline (search, sort, page bounds) included.
+ *
+ * ```ts
+ * export default class User extends compose(BaseModel, Filterable) {
+ *   static $filter = () => UserFilter
+ * }
+ * ```
+ *
+ * The model then answers two calls, and the first **hands the query builder back** — nothing is
+ * executed until you say so:
+ *
+ * ```ts
+ * // keep composing, then page it with what the request asked for
+ * const { query } = await User.filter(ctx)
+ * query.whereNotNull('confirmedAt').preload('team')
+ * return query.filterPaginate()
+ *
+ * // or the one-liner
+ * return User.filterPaginate(ctx)
+ * ```
+ *
+ * The builder comes back inside an object rather than as the promise's own value on purpose: a
+ * Lucid query builder is *thenable*, so `await`ing a promise that resolves to one would run the
+ * query and hand you rows instead of the builder. Destructuring keeps the builder a builder.
+ */
+/**
+ * What {@link Filterable} adds to a model, spelled out so the mixin's return type can be named
+ * (an inferred anonymous class would drag Lucid's internals into every consumer's build).
+ */
+export interface FilteredQuery<M extends LucidModel> extends ResolvedPagination {
+    /** The query builder, filtered/searched/sorted — yours to keep composing on, not yet executed. */
+    query: ModelQueryBuilderContract<M>;
+}
+export interface FilterableModelStatics {
+    /** The filter this model is read through. A thunk, so the filter may import the model back. */
+    $filter?: () => FilterClass | FilterSpec;
+    filter<M extends LucidModel>(this: M, ctx?: FilterRequestContext, filter?: FilterClass | FilterSpec, options?: ApplyFromRequestOptions): Promise<FilteredQuery<M>>;
+    filterPaginate<M extends LucidModel>(this: M, ctx?: FilterRequestContext, filter?: FilterClass | FilterSpec, options?: ApplyFromRequestOptions): Promise<ModelPaginatorContract<InstanceType<M>>>;
+}
+export declare function Filterable<T extends NormalizeConstructor<LucidModel>>(superclass: T): T & FilterableModelStatics;
+//# sourceMappingURL=filterable_mixin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filterable_mixin.d.ts","sourceRoot":"","sources":["../../src/filterable_mixin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EACV,UAAU,EACV,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,kBAAkB;IAC7E,kGAAkG;IAClG,KAAK,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,WAAW,GAAG,UAAU,CAAC;IACzC,MAAM,CAAC,CAAC,SAAS,UAAU,EACzB,IAAI,EAAE,CAAC,EACP,GAAG,CAAC,EAAE,oBAAoB,EAC1B,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,EACjC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,cAAc,CAAC,CAAC,SAAS,UAAU,EACjC,IAAI,EAAE,CAAC,EACP,GAAG,CAAC,EAAE,oBAAoB,EAC1B,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,EACjC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,sBAAsB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACrD;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,oBAAoB,CAAC,UAAU,CAAC,EACnE,UAAU,EAAE,CAAC,GACZ,CAAC,GAAG,sBAAsB,CA+D5B"}