@adonis-agora/filter 0.0.0-beta-20261110131309

package/dist/src/filter_spec.d.ts

@@ -0,0 +1,231 @@
+import { type LucidModelLike } from './aggregate.js';
+import type { FieldAliases } from './field_aliases.js';
+import type { FilterFieldTypeInfo } from './generate_client.js';
+import type { ColumnFilter } from './operators.js';
+import type { ComputedFields, FilterConfig, FilterFieldKind, FullTextSearchConfig, SortItem, VectorSimilarityConfig } from './types.js';
+/**
+ * Thrown when a {@link defineFilter} declaration is itself invalid (a developer
+ * error surfaced at wiring time, not a bad client request). Request-time
+ * violations (a disallowed field under `throwOnInvalid`) still surface as
+ * `InvalidColumnFilterError` from the runner — this is the one new typed error,
+ * for the declaration boundary the NestJS `@Filterable` decorator guarded.
+ */
+export declare class FilterDefinitionError extends Error {
+    constructor(message: string);
+}
+/** Column-level allow-list for a relation: `'*'` (any column) or a bare-name list. */
+export type RelationColumns = string[] | '*';
+/**
+ * The colocated allow-list form: field name → its column kind, declaring both at once.
+ *
+ * The array form makes every non-string field appear twice (once in `filterable`, once in
+ * `fieldTypes`); this states each field and its type in one place, and desugars to exactly that
+ * pair. Fields whose kind carries no contract can still use `'string'` — it is the no-op kind.
+ *
+ * ```ts
+ * defineFilter({ filterable: { advisorId: 'string', dayOfWeek: 'number', isRecurring: 'boolean' } })
+ * ```
+ */
+export type FilterableMap = Record<string, FilterFieldKind>;
+/** `filterable` as accepted on input: the classic list/`'*'`, or the colocated map. */
+export type FilterableInput = RelationColumns | FilterableMap;
+/**
+ * The filterable/sortable declaration for one whitelisted relation, keyed by the
+ * relation name on the owning model. Column names are **bare** (unprefixed) — the
+ * request field is the dotted path `relation.column`. Nesting `relations` again
+ * whitelists deeper paths (`relation.child.column`), bounded by `maxDepth`.
+ */
+export interface RelationSpec {
+    /** Columns of the related model clients may filter on. Defaults to `'*'`. */
+    filterable?: RelationColumns;
+    /** Columns of the related model clients may sort on. Defaults to `filterable`. */
+    sortable?: RelationColumns;
+    /** Further whitelisted relations reachable from this one (one hop deeper). */
+    relations?: Record<string, RelationSpec>;
+    /**
+     * Numeric child columns exposed to the to-many aggregate functions
+     * (`$sum`/`$avg`/`$min`/`$max`) — e.g. `['views', 'total']` makes
+     * `posts.$sum.views` and `posts.$max.total` filterable/sortable. `$count`
+     * needs no column and is synthesised for every to-many relation regardless.
+     *
+     * Because Lucid does not reflect a column's SQL type, listing a column here is
+     * how the developer asserts it is numeric (the aggregate allow-list). Only
+     * meaningful when the owning {@link DefineFilterOptions.model} is set so the
+     * relation's FK/pivot metadata can be discovered; ignored otherwise.
+     */
+    aggregates?: string[];
+}
+/**
+ * Reads the current tenant id from the request context (the AdonisJS
+ * `HttpContext`, or any object the caller passes). A `null`/`undefined` result
+ * means "no tenant in context" — tenant scoping is then skipped (opt-in, exactly
+ * like the NestJS `@TenantScoped` no-op when no tenant resolves).
+ */
+export type TenantResolver = (ctx: unknown) => string | number | null | undefined;
+/** Tenant auto-scope: constrain `column` to the tenant id resolved from ctx. */
+export interface TenantScopeSpec {
+    /** The model column constrained to the current tenant id (e.g. `'tenantId'`). */
+    column: string;
+    /** Resolves the tenant id from the request ctx. Nullish → scope is skipped. */
+    resolve: TenantResolver;
+}
+/**
+ * The declarative filter definition — the idiomatic AdonisJS reimplementation of
+ * everything the NestJS `@Filterable`/`@Relations`/`@TenantScoped` decorators
+ * encoded, as a plain options object (no decorators, no metadata reflection).
+ */
+export interface DefineFilterOptions {
+    /**
+     * Columns clients may filter on. Three forms:
+     * - `['a', 'b']` — a bare allow-list.
+     * - `'*'` — any base column (use with care).
+     * - `{ a: 'string', b: 'number' }` — the colocated form: allow-list AND {@link
+     *   DefineFilterOptions.fieldTypes} in one place, so a non-string field is not written twice.
+     */
+    filterable: FilterableInput;
+    /** Columns clients may sort on. Defaults to {@link DefineFilterOptions.filterable}. */
+    sortable?: RelationColumns;
+    /**
+     * Columns the free-text `search` term scans with a portable ILIKE — the
+     * default search path when {@link DefineFilterOptions.fullText} is not set.
+     */
+    searchable?: string[];
+    /**
+     * Per-field column value types. Declaring a field here does two things at once:
+     *
+     * 1. **Server-side validation.** A query-string filter value is always a string, and Postgres
+     *    silently casts the benign cases (`day_of_week = '3'` works) — so the gap stays invisible
+     *    until a client sends something uncastable (`is_recurring = 'xyz'`), which raises
+     *    `invalid input syntax for type boolean` at the database and surfaces as a **500 driven by
+     *    user input**. With a declared kind the value is coerced up front, and one that can't be
+     *    coerced is treated exactly like a disallowed field: dropped, or a loud
+     *    `InvalidColumnFilterError` (→ 400) under {@link DefineFilterOptions.throwOnInvalid}.
+     * 2. **Type-aware client codegen.** `make:filter-client` reads the same declaration, so the
+     *    emitted client narrows operators per field instead of being operator-permissive.
+     *
+     * One declaration, both ends. Undeclared fields keep the previous behaviour (no coercion), so
+     * adding this to an existing spec is opt-in and backwards compatible.
+     */
+    fieldTypes?: Record<string, FilterFieldTypeInfo>;
+    /**
+     * Opt-in Postgres tsvector full-text search. When set, the request `search`
+     * string routes through `websearch_to_tsquery`/`@@` (and optional `ts_rank`)
+     * instead of the ILIKE `searchable` scan. Column(s) + language + rank.
+     */
+    fullText?: FullTextSearchConfig;
+    /** Whitelisted relations and their nested filterable/sortable columns. */
+    relations?: Record<string, RelationSpec>;
+    /**
+     * The owning Lucid model — enables to-many aggregate fields
+     * (`$count`/`$sum`/`$avg`/`$min`/`$max`). Its relation metadata (hasMany /
+     * manyToMany FK + pivot columns) is introspected at build time to synthesise
+     * aggregate computed sources for the whitelisted {@link relations}. Optional;
+     * without it, aggregate fields are simply not available (the feature degrades
+     * gracefully) — every other feature works with or without it. Also supplies
+     * the default {@link table} (the model's table name) used as the correlated
+     * subquery's outer alias.
+     */
+    model?: LucidModelLike;
+    /**
+     * Maximum relation-path depth (number of relation hops; a base column is
+     * depth 0, `posts.title` is depth 1, `posts.comments.body` is depth 2).
+     * Defaults to the deepest declared relation nesting. An explicit smaller value
+     * caps paths even when a deeper relation is declared.
+     */
+    maxDepth?: number;
+    /** Client-alias → resolved-target field remapping (see {@link resolveFieldAlias}). */
+    aliases?: FieldAliases;
+    /**
+     * Opt-in pgvector embedding-similarity ordering (distinct from text `search`):
+     * declares the vector column (and metric / threshold / top-K) rows are ranked
+     * by when a request carries a query embedding. Additive — a spec without this
+     * is unchanged.
+     */
+    vectorSimilarity?: VectorSimilarityConfig;
+    /**
+     * Virtual/computed fields — alias → dev-declared SQL expression
+     * ({@link ComputedFields}). Two source forms: a verbatim string
+     * (`{ fullName: "first || ' ' || last" }`) or a function
+     * (`{ postCount: ({ alias }) => \`(SELECT COUNT(*) FROM posts WHERE posts.author_id = ${alias}.id)\` }`)
+     * for correlated subqueries. A declared alias becomes filterable and sortable
+     * as if it were a real column; the client value stays parameterized and only
+     * the dev expression is inlined. Function-form sources need {@link table}.
+     */
+    computed?: ComputedFields;
+    /**
+     * The root model's table name, surfaced to computed-field functions as the
+     * outer alias (Lucid gives the main table no generated alias, so the table
+     * name IS the alias). Required for function-form computed fields and to-many
+     * aggregate fields whose correlated subqueries reference the outer row.
+     */
+    table?: string;
+    /** Opt-in tenant auto-scope read from ctx. */
+    tenant?: TenantScopeSpec;
+    /**
+     * Server-declared filters always applied (in real column terms, AND-combined
+     * with the request filters). Not subject to the allow-list — they are trusted
+     * server policy, never client input.
+     */
+    defaultFilters?: ColumnFilter[];
+    /** Sort applied when the request supplies none (stable default ordering). */
+    defaultSort?: SortItem[];
+    /** Default page size when the request gives none. Default 25 (in the runner). */
+    defaultSize?: number;
+    /** Hard cap on page size. Default 100 (in the runner). */
+    maxSize?: number;
+    /** Throw `InvalidColumnFilterError` on a disallowed field instead of dropping it. */
+    throwOnInvalid?: boolean;
+}
+/**
+ * A resolved, reusable, frozen filter definition produced by {@link defineFilter}.
+ * Build it once (module scope) and hand it to {@link applyFilterFromRequest} on
+ * every request. The `isFilterable`/`isSortable` predicates are the allow-list
+ * boundary — relation-path and depth aware — that the runner enforces.
+ */
+export interface FilterSpec {
+    readonly filterable: RelationColumns;
+    readonly sortable: RelationColumns;
+    readonly searchable: readonly string[];
+    /** Declared column value kinds — drives value coercion AND client codegen. */
+    readonly fieldTypes: Readonly<Record<string, FilterFieldTypeInfo>> | undefined;
+    readonly fullText: FullTextSearchConfig | undefined;
+    readonly relations: Readonly<Record<string, RelationSpec>>;
+    readonly maxDepth: number;
+    readonly aliases: FieldAliases | undefined;
+    readonly vectorSimilarity: VectorSimilarityConfig | undefined;
+    /** Declared computed/virtual fields (alias → SQL source). */
+    readonly computed: ComputedFields | undefined;
+    /** Root table name surfaced to computed-field functions as the outer alias. */
+    readonly table: string | undefined;
+    readonly tenant: TenantScopeSpec | undefined;
+    readonly defaultFilters: readonly ColumnFilter[];
+    readonly defaultSort: readonly SortItem[];
+    readonly defaultSize: number | undefined;
+    readonly maxSize: number | undefined;
+    readonly throwOnInvalid: boolean;
+    /** Is this (possibly relation-dotted, alias-resolved) field filterable? */
+    isFilterable(field: string): boolean;
+    /** Is this (possibly relation-dotted, alias-resolved) field sortable? */
+    isSortable(field: string): boolean;
+}
+/**
+ * Build a reusable {@link FilterSpec} from a declarative {@link DefineFilterOptions}.
+ *
+ * This is the AdonisJS-idiomatic replacement for the NestJS decorator stack:
+ * instead of `@Filterable`/`@Relations`/`@TenantScoped` metadata read by an
+ * interceptor, the definition is an explicit, framework-free config object built
+ * once and passed explicitly to {@link applyFilterFromRequest}. It captures the
+ * same feature set the decorators encoded — filterable/sortable allow-listing,
+ * a relation whitelist with a depth cap, field aliases, tenant scoping, and
+ * default filters/sort.
+ */
+export declare function defineFilter(options: DefineFilterOptions): FilterSpec;
+/**
+ * Project a {@link FilterSpec} onto the per-call {@link FilterConfig} the runner's
+ * {@link applyFilter}/{@link applyCursor} consume. The allow-lists become
+ * predicates (so relation-path + depth rules survive), and `defaultSort` fields
+ * are unioned into the sortable predicate so a server-declared default ordering
+ * is never dropped by the client-facing sort allow-list.
+ */
+export declare function specToFilterConfig(spec: FilterSpec): FilterConfig;
+//# sourceMappingURL=filter_spec.d.ts.map

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

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

package/dist/src/filter_spec.js

@@ -0,0 +1,182 @@
+import { discoverAggregateSources } from './aggregate.js';
+/**
+ * Thrown when a {@link defineFilter} declaration is itself invalid (a developer
+ * error surfaced at wiring time, not a bad client request). Request-time
+ * violations (a disallowed field under `throwOnInvalid`) still surface as
+ * `InvalidColumnFilterError` from the runner — this is the one new typed error,
+ * for the declaration boundary the NestJS `@Filterable` decorator guarded.
+ */
+export class FilterDefinitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FilterDefinitionError';
+    }
+}
+/** True for the colocated map form (a plain object, not an array and not `'*'`). */
+function isFilterableMap(input) {
+    return typeof input === 'object' && input !== null && !Array.isArray(input);
+}
+/** Desugar `filterable` to the allow-list the rest of the lib consumes. */
+function normalizeFilterable(input) {
+    return isFilterableMap(input) ? Object.keys(input) : input;
+}
+/** Extract the `fieldTypes` a colocated `filterable` map declares, or undefined for other forms. */
+function fieldTypesFromFilterable(input) {
+    if (!isFilterableMap(input))
+        return undefined;
+    const out = {};
+    for (const [field, kind] of Object.entries(input))
+        out[field] = { kind };
+    return out;
+}
+/** Blocked path segments that could otherwise index inherited prototype members. */
+const BLOCKED_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype', 'toString', 'valueOf']);
+/** Deepest relation nesting declared under `relations` (0 when none). */
+function declaredDepth(relations) {
+    if (!relations)
+        return 0;
+    let max = 0;
+    for (const rel of Object.values(relations)) {
+        max = Math.max(max, 1 + declaredDepth(rel.relations));
+    }
+    return max;
+}
+/** Does an allow-list admit a bare column name? `undefined` → treated as `'*'`. */
+function columnAllowed(list, column) {
+    if (list === undefined || list === '*')
+        return true;
+    return list.includes(column);
+}
+/**
+ * Resolve a (possibly dotted) field path against the base allow-lists and the
+ * relation whitelist, enforcing `maxDepth`. Pure — the client-supplied `field`
+ * is only ever read, and each segment is guarded against prototype-pollution
+ * lookups before it indexes the relations map.
+ */
+function pathAllowed(field, kind, baseFilterable, baseSortable, relations, maxDepth) {
+    const segments = field.split('.');
+    // Base column (no relation hop).
+    if (segments.length === 1) {
+        const seg = segments[0];
+        if (seg.length === 0 || BLOCKED_SEGMENTS.has(seg))
+            return false;
+        return columnAllowed(kind === 'filterable' ? baseFilterable : baseSortable, seg);
+    }
+    // Relation path — bounded by maxDepth (hops = segments - 1).
+    if (segments.length - 1 > maxDepth)
+        return false;
+    let node = relations;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        if (seg.length === 0 || BLOCKED_SEGMENTS.has(seg))
+            return false;
+        if (!node || !Object.hasOwn(node, seg))
+            return false;
+        const rel = node[seg];
+        // Last hop: the final segment is the leaf column on this relation.
+        if (i === segments.length - 2) {
+            const leaf = segments[segments.length - 1];
+            if (leaf.length === 0 || BLOCKED_SEGMENTS.has(leaf))
+                return false;
+            const list = kind === 'filterable' ? rel.filterable : (rel.sortable ?? rel.filterable);
+            return columnAllowed(list, leaf);
+        }
+        node = rel.relations;
+    }
+    return false;
+}
+/**
+ * Build a reusable {@link FilterSpec} from a declarative {@link DefineFilterOptions}.
+ *
+ * This is the AdonisJS-idiomatic replacement for the NestJS decorator stack:
+ * instead of `@Filterable`/`@Relations`/`@TenantScoped` metadata read by an
+ * interceptor, the definition is an explicit, framework-free config object built
+ * once and passed explicitly to {@link applyFilterFromRequest}. It captures the
+ * same feature set the decorators encoded — filterable/sortable allow-listing,
+ * a relation whitelist with a depth cap, field aliases, tenant scoping, and
+ * default filters/sort.
+ */
+export function defineFilter(options) {
+    if (!options || options.filterable === undefined) {
+        throw new FilterDefinitionError('defineFilter requires a `filterable` allow-list.');
+    }
+    if (options.maxDepth !== undefined &&
+        (!Number.isInteger(options.maxDepth) || options.maxDepth < 0)) {
+        throw new FilterDefinitionError('`maxDepth` must be a non-negative integer.');
+    }
+    const relations = options.relations ?? {};
+    // The colocated map form desugars here, at the boundary: the keys become the allow-list and the
+    // values become `fieldTypes`. Everything downstream (the predicates, the runner, the codegen)
+    // keeps seeing the array form it always saw, so this is purely an authoring convenience.
+    const filterable = normalizeFilterable(options.filterable);
+    const sortable = options.sortable ?? filterable;
+    const declaredTypes = fieldTypesFromFilterable(options.filterable);
+    // An explicit `fieldTypes` entry wins per field: the map form can only express a bare kind, so
+    // this is how a caller adds codegen-only richness (enumValues/typeRef) on top of it.
+    const fieldTypes = declaredTypes || options.fieldTypes ? { ...declaredTypes, ...options.fieldTypes } : undefined;
+    const maxDepth = options.maxDepth ?? declaredDepth(relations);
+    // Root table (the correlated-subquery outer alias): explicit `table` wins,
+    // else the model's own table name.
+    const table = options.table ?? options.model?.table;
+    // Discover to-many aggregate computed sources from the model's relation
+    // metadata, then let dev-declared `computed` win on any key collision. The
+    // discovery is capability-gated (no model → empty map) and per-relation
+    // fault-tolerant, so this never throws at wiring time.
+    const aggregateSources = discoverAggregateSources(options.model, relations);
+    const computed = Object.keys(aggregateSources).length > 0 || options.computed
+        ? { ...aggregateSources, ...options.computed }
+        : undefined;
+    const spec = {
+        filterable,
+        sortable,
+        searchable: options.searchable ?? [],
+        fieldTypes,
+        fullText: options.fullText,
+        relations,
+        maxDepth,
+        aliases: options.aliases,
+        vectorSimilarity: options.vectorSimilarity,
+        computed,
+        table,
+        tenant: options.tenant,
+        defaultFilters: options.defaultFilters ?? [],
+        defaultSort: options.defaultSort ?? [],
+        defaultSize: options.defaultSize,
+        maxSize: options.maxSize,
+        throwOnInvalid: options.throwOnInvalid ?? false,
+        isFilterable(field) {
+            return pathAllowed(field, 'filterable', filterable, sortable, relations, maxDepth);
+        },
+        isSortable(field) {
+            return pathAllowed(field, 'sortable', filterable, sortable, relations, maxDepth);
+        },
+    };
+    return Object.freeze(spec);
+}
+/**
+ * Project a {@link FilterSpec} onto the per-call {@link FilterConfig} the runner's
+ * {@link applyFilter}/{@link applyCursor} consume. The allow-lists become
+ * predicates (so relation-path + depth rules survive), and `defaultSort` fields
+ * are unioned into the sortable predicate so a server-declared default ordering
+ * is never dropped by the client-facing sort allow-list.
+ */
+export function specToFilterConfig(spec) {
+    const defaultSortFields = new Set(spec.defaultSort.map((s) => s.field));
+    const allowed = (field) => spec.isFilterable(field);
+    const sortable = (field) => spec.isSortable(field) || defaultSortFields.has(field);
+    return {
+        allowed,
+        sortable,
+        ...(spec.searchable.length > 0 && { searchable: [...spec.searchable] }),
+        ...(spec.fieldTypes && { fieldTypes: spec.fieldTypes }),
+        ...(spec.fullText && { fullText: spec.fullText }),
+        ...(spec.aliases && { aliases: spec.aliases }),
+        ...(spec.vectorSimilarity && { vectorSimilarity: spec.vectorSimilarity }),
+        ...(spec.computed && { computed: spec.computed }),
+        ...(spec.table !== undefined && { table: spec.table }),
+        ...(spec.defaultSize !== undefined && { defaultSize: spec.defaultSize }),
+        ...(spec.maxSize !== undefined && { maxSize: spec.maxSize }),
+        throwOnInvalid: spec.throwOnInvalid,
+    };
+}
+//# sourceMappingURL=filter_spec.js.map

package/dist/src/filter_spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter_spec.js","sourceRoot":"","sources":["../../src/filter_spec.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,EAE5B,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,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,CA6D5B"}

package/dist/src/filterable_mixin.js

@@ -0,0 +1,47 @@
+import { HttpContext } from '@adonisjs/core/http';
+import { applyFilterFromRequest, } from './apply_from_request.js';
+import { paginate } from './paginate.js';
+import { stashPagination } from './pagination_stash.js';
+export function Filterable(superclass) {
+    class FilterableModel extends superclass {
+        /** The filter this model is read through. A thunk, so the filter may import the model back. */
+        static $filter;
+        /**
+         * Apply the model's filter to a fresh query and hand back the **query builder** plus the
+         * pagination the request resolved to — filters, search and sort applied, nothing executed.
+         * Compose whatever else the endpoint needs on the builder, then page it with
+         * `filterPaginate()` (no arguments) or `paginate(page, size)`.
+         */
+        static async filter(ctx, filter, options) {
+            // `this` is the model the static was called on (a subclass of the mixin), which is exactly
+            // what these helpers need — the rule's suggestion (name the class) would pin every model to
+            // the anonymous mixin class instead.
+            // biome-ignore lint/complexity/noThisInStatic: `this` is the calling model, by design.
+            const model = this;
+            const target = filter ?? model.$filter?.();
+            if (!target) {
+                throw new Error(
+                // biome-ignore lint/complexity/noThisInStatic: names the model the call was made on.
+                `${this.name} has no filter — declare \`static $filter = () => YourFilter\` on the model, or pass one to filter().`);
+            }
+            // biome-ignore lint/complexity/noThisInStatic: the calling model builds its own query.
+            const query = this.query();
+            const pagination = await applyFilterFromRequest(query, target, ctx ?? HttpContext.getOrFail(), options);
+            stashPagination(query, pagination);
+            return { query, page: pagination.page, size: pagination.size };
+        }
+        /**
+         * The same, then `paginate(page, size)` with the pagination the request resolved to — the
+         * whole list endpoint in one call.
+         */
+        static async filterPaginate(ctx, filter, options) {
+            // biome-ignore lint/complexity/noThisInStatic: `this` is the calling model, by design.
+            const model = this;
+            // biome-ignore lint/complexity/noThisInStatic: forwards the call to the same model.
+            const { query, page, size } = await model.filter.call(this, ctx, filter, options);
+            return paginate(query, page, size);
+        }
+    }
+    return FilterableModel;
+}
+//# sourceMappingURL=filterable_mixin.js.map

package/dist/src/filterable_mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filterable_mixin.js","sourceRoot":"","sources":["../../src/filterable_mixin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOlD,OAAO,EAEL,sBAAsB,GAEvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAwDxD,MAAM,UAAU,UAAU,CACxB,UAAa;IAEb,MAAM,eAAgB,SAAQ,UAAU;QACtC,+FAA+F;QAC/F,MAAM,CAAC,OAAO,CAAkC;QAEhD;;;;;WAKG;QACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAEjB,GAA0B,EAC1B,MAAiC,EACjC,OAAiC;YAEjC,2FAA2F;YAC3F,4FAA4F;YAC5F,qCAAqC;YACrC,uFAAuF;YACvF,MAAM,KAAK,GAAG,IAAyC,CAAC;YACxD,MAAM,MAAM,GAAG,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK;gBACb,qFAAqF;gBACrF,GAAG,IAAI,CAAC,IAAI,uGAAuG,CACpH,CAAC;YACJ,CAAC;YAED,uFAAuF;YACvF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAkC,CAAC;YAC3D,MAAM,UAAU,GAAG,MAAM,sBAAsB,CAC7C,KAAc,EACd,MAAe,EACf,GAAG,IAAI,WAAW,CAAC,SAAS,EAAE,EAC9B,OAAO,CACR,CAAC;YACF,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YACnC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;QACjE,CAAC;QAED;;;WAGG;QACH,MAAM,CAAC,KAAK,CAAC,cAAc,CAEzB,GAA0B,EAC1B,MAAiC,EACjC,OAAiC;YAEjC,uFAAuF;YACvF,MAAM,KAAK,GAAG,IAAyC,CAAC;YACxD,oFAAoF;YACpF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YAClF,OAAO,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAqD,CAAC;QACzF,CAAC;KACF;IAED,OAAO,eAAwD,CAAC;AAClE,CAAC"}

package/dist/src/generate_client.d.ts

@@ -0,0 +1,107 @@
+import type { FilterSpec } from './filter_spec.js';
+/**
+ * Codegen for the typed client — the AdonisJS-idiomatic port of the NestJS
+ * `nestjs-filter` codegen. Where the NestJS package ships a standalone
+ * `reflect-metadata` bin that reads decorator metadata off entity classes and
+ * emits `filterQuery: () => filterQueryTyped<Fields, TypeMap>()` members into a
+ * generated `api.ts`, the Adonis port has no decorators: the filter declaration
+ * is already a plain runtime {@link FilterSpec} produced by `defineFilter(...)`.
+ *
+ * So generation is a **pure function of the spec** — string in, string out, no
+ * AST walk, no metadata reflection, no framework. The ace command
+ * (`make:filter-client`) is the thin IO wrapper that loads the app's declared
+ * specs and writes the emitted module to disk. Keeping the generator pure keeps
+ * it trivially testable (snapshot/string assertions) and framework-free, exactly
+ * like the rest of this core.
+ *
+ * The emitted module targets `@adonis-agora/filter-client`'s `filterQueryTyped<Fields,
+ * FieldTypes>()` factory — the same client the NestJS codegen emitted against —
+ * so the two ecosystems share one browser runtime.
+ */
+import type { FilterFieldKind } from './types.js';
+export type { FilterFieldKind };
+/**
+ * Optional per-field type information. A {@link FilterSpec} carries the
+ * allow-list but not column value types (Lucid models aren't reflected here), so
+ * the caller supplies types to unlock the client's type-aware operator narrowing.
+ * Without it the emitted client is still field-name-safe, just operator-permissive.
+ */
+export interface FilterFieldTypeInfo {
+    /** Classified value kind. Ignored when {@link typeRef} or {@link enumValues} is set. */
+    kind?: FilterFieldKind;
+    /** Enum literal members — emitted as a union (`"A" | "B"` or `1 | 2`). Wins over {@link kind}. */
+    enumValues?: readonly (string | number)[];
+    /** A named TS type (e.g. `'Role'`) — emitted verbatim. Wins over everything. */
+    typeRef?: string;
+    /** Nullable column — appends `| null` to the emitted type. */
+    nullable?: boolean;
+}
+/** Options for {@link generateFilterClient}. */
+export interface GenerateFilterClientOptions {
+    /**
+     * Base name for the emitted identifiers — e.g. `'people'` yields
+     * `PeopleFilterFields`, `PeopleFilterFieldTypes`, `peopleFilterMeta` and
+     * `peopleFilterQuery()`. Non-identifier characters are stripped.
+     */
+    name: string;
+    /** Per-field value types keyed by (dotted) field path. Unlocks operator narrowing. */
+    fieldTypes?: Record<string, FilterFieldTypeInfo>;
+    /** Import specifier for `filterQueryTyped`. Default `'@adonis-agora/filter-client'`. */
+    clientModule?: string;
+    /** Cap relation-path depth of the emitted field union. Default {@link FilterSpec.maxDepth}. */
+    maxDepth?: number;
+    /** Emit the "generated — do not edit" banner. Default `true`. */
+    banner?: boolean;
+}
+/** Enumerate the filterable field paths a spec admits, capped at `maxDepth` relation hops. */
+export declare function filterableFieldPaths(spec: FilterSpec, maxDepth?: number): string[];
+/** Enumerate the sortable field paths a spec admits, capped at `maxDepth` relation hops. */
+export declare function sortableFieldPaths(spec: FilterSpec, maxDepth?: number): string[];
+/**
+ * Generate a typed filter client module for one {@link FilterSpec} — a pure
+ * string transform. The emitted module exports, for a spec named `people`:
+ *
+ * - `type PeopleFilterFields` — the union of filterable field paths (the security
+ *   boundary, as concrete string literals);
+ * - `interface PeopleFilterFieldTypes` — the per-field value-type map (only when
+ *   `fieldTypes` is supplied), which drives the client's operator/value narrowing;
+ * - `const peopleFilterMeta` — runtime metadata (filterable/sortable/searchable
+ *   fields, whitelisted relations, per-field kinds, and the default sort / page
+ *   size / max size + cursor keyset the runner paginates by);
+ * - `function peopleFilterQuery()` — a `filterQueryTyped<Fields, FieldTypes>()`
+ *   factory returning a type-safe builder scoped to this spec.
+ */
+export declare function generateFilterClient(spec: FilterSpec, options: GenerateFilterClientOptions): string;
+/**
+ * One entry in a {@link FilterClientManifest}: a declared spec plus the optional
+ * type info / codegen overrides the emitter needs. This is what an app exports
+ * from `config/filter.ts` (as `filters`) for the `make:filter-client` command to
+ * consume — the specs are already `defineFilter(...)` results, so no reflection.
+ */
+export interface FilterClientEntry {
+    /** The `defineFilter(...)` result to generate a client for. */
+    spec: FilterSpec;
+    /** Per-field value types (see {@link GenerateFilterClientOptions.fieldTypes}). */
+    fieldTypes?: Record<string, FilterFieldTypeInfo>;
+    /** Override the client import specifier for this entry. */
+    clientModule?: string;
+    /** Override the relation-path depth cap for this entry. */
+    maxDepth?: number;
+}
+/** A map of client name → declared spec, keyed by the emitted client's base name. */
+export type FilterClientManifest = Record<string, FilterClientEntry>;
+/** A single generated client: its name, its AdonisJS-conventional file name, and its code. */
+export interface GeneratedFilterClient {
+    name: string;
+    /** `snake_case`d file name, e.g. `blog_post_filter_client.ts`. */
+    filename: string;
+    code: string;
+}
+/**
+ * Expand a whole {@link FilterClientManifest} into per-spec generated modules —
+ * the pure core the `make:filter-client` ace command writes to disk. Kept pure
+ * (manifest in, modules out) so the command stays a thin IO wrapper and the
+ * expansion is itself testable without a running app.
+ */
+export declare function generateFilterClients(manifest: FilterClientManifest): GeneratedFilterClient[];
+//# sourceMappingURL=generate_client.d.ts.map