@adonis-agora/filter 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # @adonis-agora/filter
 
+## 0.7.0
+
+### Minor Changes
+
+- [#23](https://github.com/DavideCarvalho/adonis-agora-filter/pull/23) [`2bd4e7b`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/2bd4e7baa50d3d0b4a25c834fc9edf612f7d854a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `parseSpatieRequest` now parses `distinct`, matching `parseFilterRequest`.
+
+  `parseSpatieRequest` is documented as the additive counterpart to
+  `parseFilterRequest` — same filter, sort and search shapes, plus cursor
+  pagination, includes and sparse fieldsets — so a controller can swap one for the
+  other. It did not read `distinct`, even though the runner applies it. Swapping
+  the parser turned a working `?distinct=city` into a full, un-deduped result set
+  with nothing to signal that the parameter had been dropped.
+
+  Both string (`distinct=city,tier`) and repeated (`distinct[]=city&distinct[]=tier`)
+  forms now parse identically in the two parsers.
+
+- [#23](https://github.com/DavideCarvalho/adonis-agora-filter/pull/23) [`2bd4e7b`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/2bd4e7baa50d3d0b4a25c834fc9edf612f7d854a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add the `configure` hook, so `node ace add @adonis-agora/filter` actually wires the package.
+
+  The install instructions have always said to run `node ace add @adonis-agora/filter`,
+  but the package shipped no `configure` hook, so the command installed the
+  dependency and wired nothing. Two things silently did not happen: the provider
+  was never added to `adonisrc.ts` (no `applyFilterFromRequest` / `filterPaginate`
+  macros on `ModelQueryBuilder`), and the commands barrel was never registered, so
+  `make:filter-client` never appeared in `node ace list`.
+
+  `node ace add @adonis-agora/filter` — or `node ace configure @adonis-agora/filter`
+  on an already-installed package — now registers both:
+
+  ```ts
+  // adonisrc.ts
+  providers: [() => import('@adonis-agora/filter/filter_provider')],
+  commands: [() => import('@adonis-agora/filter/commands')],
+  ```
+
+  Nothing is published to `config/`: a filter policy is a per-model
+  `defineFilterSpec` call in your own code, not global configuration. Apps that
+  wired those two entries by hand need no change — the codemod is idempotent.
+
+- [#23](https://github.com/DavideCarvalho/adonis-agora-filter/pull/23) [`2bd4e7b`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/2bd4e7baa50d3d0b4a25c834fc9edf612f7d854a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `parseFilterRequest` now understands the client builder's structured shape, closing a silent unfiltered-response bug.
+
+  A POST search endpoint that hands `filterQuery()…build()` straight to
+  `parseFilterRequest` — the pairing the guides describe — did not work. The
+  builder returns
+
+  ```ts
+  { filter: { where: [{ field: 'status', operator: 'in', value: [...] }] },
+    sort: [{ field: 'createdAt', direction: 'desc' }],
+    paginate: { page: 2, size: 25 } }
+  ```
+
+  and the parser reshaped it as if `where` were a column: the entire condition list
+  became one `in` filter on a field named `where`, which the allow-list then
+  pruned, while `sort` and `paginate` were discarded for not being strings. The
+  endpoint answered with **every row, unsorted and unpaginated**, and raised
+  nothing — the failure looked like a working search with a broad result set.
+
+  The same shape reaches a plain GET too, because OR/AND groups serialize to a
+  top-level `where[0][field]=…`, so grouped queries were silently unfiltered as
+  well.
+
+  `parseFilterRequest` now recognises an already-structured condition list — under
+  `filter.where` or at the top level — and takes it as the filters, with nested
+  `AND`/`OR` groups intact. It also reads `sort` in the `[{ field, direction }]`
+  form and maps `paginate: { page, size }` onto `page`/`size`.
+
+  Existing requests are unaffected: `filter[field]=…`, `sort=-createdAt`,
+  `page`/`size` and `page[number]`/`page[size]` parse exactly as before, and a real
+  column named `where` (`filter[where]=lobby`, `filter[where][contains]=lob`,
+  `filter[where][]=a&filter[where][]=b`) is still treated as a column — only an
+  array of `{ field, operator }` records is read as a structured list, and a query
+  string cannot produce one by accident.
+
+  Note that `include` is still not consumed: eager-loading stays the caller's
+  `preload` call.
+
+### Patch Changes
+
+- [#23](https://github.com/DavideCarvalho/adonis-agora-filter/pull/23) [`2bd4e7b`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/2bd4e7baa50d3d0b4a25c834fc9edf612f7d854a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Report the real version from the exported `VERSION` constant.
+
+  `VERSION` is a hand-written literal next to a "keep in sync with package.json"
+  comment, and it had not been touched since the first release: the package shipped
+  `0.2.0` through `0.6.0` while `VERSION` still answered `'0.1.0'`. Anything gating
+  on it — a feature check, a bug report, a diagnostics banner — got a wrong answer.
+
+  It now reads `0.6.0`, and a test compares it against `package.json` so the next
+  release cannot silently drift again.
+
+- [#22](https://github.com/DavideCarvalho/adonis-agora-filter/pull/22) [`a33b2fe`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/a33b2febc48baa3dafcf6a703e4250bdebbde275) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fix a 500 when `distinct` is given a relation path.
+
+  `distinct` was gated on the `allowed` list and nothing else. A relation path like
+  `posts.title` is filterable by design — declaring `relations: { posts: { filterable: ['title'] } }`
+  whitelists it, and `make:filter-client` enumerates it into the generated field
+  union — so `?distinct=posts.title` cleared the check and was handed to Lucid
+  verbatim:
+
+  ```sql
+  select distinct "posts"."title" from "users"
+  --> ERROR: missing FROM-clause entry for table "posts"
+  ```
+
+  Lucid filters a relation with a correlated `EXISTS` subquery, so the relation is
+  never joined into the outer `FROM` and there is no alias to project a column
+  from. A `whereHas` on the same relation in the same request does not help.
+
+  **If your `distinct` works today, nothing changes.** Root-table columns —
+  including ones qualified with the root table's own name — behave exactly as
+  before, as do the alias resolution and the allow-list drop.
+
+  **If you pass a relation path** (`posts.title`) or a to-many aggregate path
+  (`posts.$count`), you now get a defined refusal instead of a database error: the
+  field is dropped from the `distinct` list (the remaining fields still apply), or
+  raises `InvalidColumnFilterError` — a 400, not a 500 — when your spec sets
+  `throwOnInvalid`. The message names the cause: it is the missing join, not the
+  allow-list, so adding the path to `filterable` will not (and should not) change
+  it. Filtering on that path keeps working; only projecting it is refused.
+
+- [#23](https://github.com/DavideCarvalho/adonis-agora-filter/pull/23) [`2bd4e7b`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/2bd4e7baa50d3d0b4a25c834fc9edf612f7d854a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Declare a supported Node range in `engines` again, instead of one exact version.
+
+  Both packages shipped `"engines": { "node": "v26.7.0" }` — an exact version, and
+  plainly the output of `node -v`, leading `v` and all. Every consumer on any other
+  Node got an unsatisfied-engine warning on install, and anyone running with
+  `engine-strict` (or a package manager that treats it as fatal) could not install
+  at all. The pinned version was also higher than anything the project itself uses:
+  CI runs Node 22 and `.nvmrc` names Node 20.
+
+  `engines` states the floor the package actually supports, which is `>=20.6.0` —
+  the same range it declared before, and the one the rest of the Agora packages
+  use. Nothing about the code changed; this only stops a false incompatibility
+  signal.
+
+## 0.6.0
+
+### Minor Changes
+
+- Parity sync from nestjs-filter: execute the server-side `distinct` projection (was a silent no-op), computed (virtual) fields for filter + sort (verbatim-string + `({alias}) => sql` forms), and native to-many aggregate fields (`$count`/`$sum`/`$avg`/`$min`/`$max`) auto-discovered from Lucid relation metadata — value stays parameterized (injection-safe), identifiers quoted.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # `@adonis-agora/filter`
 
 Server-side query filtering, sorting, and pagination for AdonisJS. Parses the
-Spatie/JSON:API query the `@agora/filter-client` builder emits, applies it to a
+Spatie/JSON:API query the `@adonis-agora/filter-client` builder emits, applies it to a
 Lucid query through a field allow-list, and resolves offset or keyset (cursor)
 pagination.
 

package/dist/configure.d.ts

@@ -0,0 +1,15 @@
+import type Configure from '@adonisjs/core/commands/configure';
+/**
+ * `node ace add @adonis-agora/filter` (or `node ace configure @adonis-agora/filter`)
+ * — auto-wires the package into an AdonisJS app:
+ *
+ * 1. registers the service provider in `adonisrc.ts`, which installs the
+ *    chainable `applyFilterFromRequest` / `filterPaginate` Lucid macros;
+ * 2. registers the ace commands barrel, which is what makes `make:filter-client`
+ *    show up in `node ace list`.
+ *
+ * There is no config file to publish: a filter policy is a per-model
+ * `defineFilterSpec` call in your own code, not global configuration.
+ */
+export declare function configure(command: Configure): Promise<void>;
+//# sourceMappingURL=configure.d.ts.map

package/dist/configure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAOjD"}

package/dist/configure.js

@@ -0,0 +1,20 @@
+/**
+ * `node ace add @adonis-agora/filter` (or `node ace configure @adonis-agora/filter`)
+ * — auto-wires the package into an AdonisJS app:
+ *
+ * 1. registers the service provider in `adonisrc.ts`, which installs the
+ *    chainable `applyFilterFromRequest` / `filterPaginate` Lucid macros;
+ * 2. registers the ace commands barrel, which is what makes `make:filter-client`
+ *    show up in `node ace list`.
+ *
+ * There is no config file to publish: a filter policy is a per-model
+ * `defineFilterSpec` call in your own code, not global configuration.
+ */
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    await codemods.updateRcFile((rcFile) => {
+        rcFile.addProvider('@adonis-agora/filter/filter_provider');
+        rcFile.addCommand('@adonis-agora/filter/commands');
+    });
+}
+//# sourceMappingURL=configure.js.map

package/dist/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,sCAAsC,CAAC,CAAC;QAC3D,MAAM,CAAC,UAAU,CAAC,+BAA+B,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/aggregate.d.ts

@@ -0,0 +1,61 @@
+import type { RelationSpec } from './filter_spec.js';
+import type { ComputedFields } from './types.js';
+/**
+ * The structural slice of a booted Lucid relation the aggregate-subquery
+ * compiler reads. A real `@adonisjs/lucid` `HasMany` / `ManyToMany` relation
+ * satisfies it — declared locally so this module never hard-imports Lucid. The
+ * key-column fields are optional because they differ by relation kind
+ * (one-to-many exposes `foreignKeyColumnName`; many-to-many exposes the pivot
+ * fields), and only the relevant ones are read per kind.
+ */
+export interface LucidRelationLike {
+    /** Relation kind — `'hasMany'` / `'manyToMany'` are the to-many kinds we correlate. */
+    type: string;
+    /** Compute the relation's key columns from the naming strategy (idempotent). */
+    boot(): void;
+    /** The related (child) model — its `table` is the child table name. */
+    relatedModel(): {
+        table?: string;
+    };
+    foreignKeyColumnName?: string;
+    localKeyColumnName?: string;
+    relatedKeyColumnName?: string;
+    pivotTable?: string;
+    pivotForeignKey?: string;
+    pivotRelatedForeignKey?: string;
+}
+/**
+ * The structural slice of a Lucid model the aggregate discovery reads: its table
+ * name and a relation accessor. `$getRelation` is typed with `any` for the same
+ * reason `QueryBuilderLike.whereHas` is — Lucid types it with a generic
+ * literal-union `Name`, and `string` is not assignable to that union, so a
+ * narrower signature would make every real model fail to satisfy this interface.
+ */
+export interface LucidModelLike {
+    table?: string;
+    $getRelation(name: any): LucidRelationLike | undefined;
+}
+/**
+ * Discover to-many aggregate {@link ComputedSource}s from a Lucid model's
+ * relation metadata, for the relations the spec whitelisted. For each declared
+ * to-many relation (hasMany / manyToMany) this synthesises:
+ *
+ * - `<rel>.$count` — always;
+ * - `<rel>.$sum|$avg|$min|$max.<col>` — one per column the relation's
+ *   {@link RelationSpec.aggregates} declares (Lucid does not reflect SQL column
+ *   types, so the dev asserts numeric-ness by listing the column there).
+ *
+ * To-one relations (belongsTo / hasOne) are excluded. The whole thing degrades
+ * gracefully: a relation that is not on the model, is to-one, or cannot be
+ * booted (e.g. no DB adapter yet) is simply skipped, and a model without the
+ * introspection capability yields an empty map — so aggregates activate only
+ * when the metadata is actually available.
+ *
+ * The result is merged into the spec's `computed` map, so aggregate fields ARE
+ * computed fields with auto-generated correlated-subquery sources — they reuse
+ * the exact same runner routing, allow-list bypass (their discovery IS their
+ * allow-list, gated by the relation whitelist), injection-safe value binding,
+ * and codegen surfacing.
+ */
+export declare function discoverAggregateSources(model: LucidModelLike | undefined, relations: Readonly<Record<string, RelationSpec>>): ComputedFields;
+//# sourceMappingURL=aggregate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../src/aggregate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,YAAY,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,IAAI,IAAI,CAAC;IACb,uEAAuE;IACvE,YAAY,IAAI;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEnC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,iBAAiB,GAAG,SAAS,CAAC;CACxD;AA+ED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,cAAc,GAAG,SAAS,EACjC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,GAChD,cAAc,CA8DhB"}

package/dist/src/aggregate.js

@@ -0,0 +1,132 @@
+/** Column functions (need a numeric child column); `count` needs none. */
+const COLUMN_FNS = ['sum', 'avg', 'min', 'max'];
+/** Double-quote one identifier segment for Postgres, escaping embedded quotes. */
+function q(ident) {
+    return `"${ident.replace(/"/g, '""')}"`;
+}
+/**
+ * The scalar aggregate expression over an (already-quoted) child column. Empty
+ * collection semantics: `sum` coalesces to 0; `avg`/`min`/`max` stay NULL (their
+ * natural result over zero rows); `count` is naturally 0.
+ */
+function aggregateExpr(fn, quotedColumn) {
+    switch (fn) {
+        case 'count':
+            return 'COUNT(*)';
+        case 'sum':
+            return `COALESCE(SUM(${quotedColumn}),0)`;
+        case 'avg':
+            return `AVG(${quotedColumn})`;
+        case 'min':
+            return `MIN(${quotedColumn})`;
+        case 'max':
+            return `MAX(${quotedColumn})`;
+    }
+}
+/**
+ * ONE_TO_MANY correlation: a direct FK on the child row points back at the
+ * root's PK. `column` omitted → `$count`.
+ *
+ *   (SELECT <agg> FROM "child" WHERE "child"."fk" = "<alias>"."pk")
+ */
+function oneToManySource(fn, childTable, fk, pk, column) {
+    const agg = aggregateExpr(fn, column ? `${q(childTable)}.${q(column)}` : '');
+    return ({ alias }) => `(SELECT ${agg} FROM ${q(childTable)} WHERE ${q(childTable)}.${q(fk)} = ${q(alias)}.${q(pk)})`;
+}
+/**
+ * MANY_TO_MANY correlation, mediated by a pivot table. `$count` counts pivot
+ * rows directly; the column functions JOIN pivot → child INSIDE the scalar
+ * subquery to reach the child column.
+ *
+ *   $count: (SELECT COUNT(*) FROM "pivot" WHERE "pivot"."ownerFk" = "<alias>"."ownerPk")
+ *   $agg:   (SELECT <agg> FROM "child"
+ *             JOIN "pivot" ON "child"."childPk" = "pivot"."inverseFk"
+ *             WHERE "pivot"."ownerFk" = "<alias>"."ownerPk")
+ */
+function manyToManySource(fn, meta, column) {
+    if (fn === 'count') {
+        return ({ alias }) => `(SELECT COUNT(*) FROM ${q(meta.pivot)} WHERE ${q(meta.pivot)}.${q(meta.ownerFk)} = ${q(alias)}.${q(meta.ownerPk)})`;
+    }
+    const agg = aggregateExpr(fn, column ? `${q(meta.childTable)}.${q(column)}` : '');
+    return ({ alias }) => `(SELECT ${agg} FROM ${q(meta.childTable)} JOIN ${q(meta.pivot)} ON ${q(meta.childTable)}.${q(meta.childPk)} = ${q(meta.pivot)}.${q(meta.inverseFk)} WHERE ${q(meta.pivot)}.${q(meta.ownerFk)} = ${q(alias)}.${q(meta.ownerPk)})`;
+}
+/**
+ * Discover to-many aggregate {@link ComputedSource}s from a Lucid model's
+ * relation metadata, for the relations the spec whitelisted. For each declared
+ * to-many relation (hasMany / manyToMany) this synthesises:
+ *
+ * - `<rel>.$count` — always;
+ * - `<rel>.$sum|$avg|$min|$max.<col>` — one per column the relation's
+ *   {@link RelationSpec.aggregates} declares (Lucid does not reflect SQL column
+ *   types, so the dev asserts numeric-ness by listing the column there).
+ *
+ * To-one relations (belongsTo / hasOne) are excluded. The whole thing degrades
+ * gracefully: a relation that is not on the model, is to-one, or cannot be
+ * booted (e.g. no DB adapter yet) is simply skipped, and a model without the
+ * introspection capability yields an empty map — so aggregates activate only
+ * when the metadata is actually available.
+ *
+ * The result is merged into the spec's `computed` map, so aggregate fields ARE
+ * computed fields with auto-generated correlated-subquery sources — they reuse
+ * the exact same runner routing, allow-list bypass (their discovery IS their
+ * allow-list, gated by the relation whitelist), injection-safe value binding,
+ * and codegen surfacing.
+ */
+export function discoverAggregateSources(model, relations) {
+    if (!model || typeof model.$getRelation !== 'function')
+        return {};
+    const out = {};
+    for (const [relName, relSpec] of Object.entries(relations)) {
+        let rel;
+        try {
+            rel = model.$getRelation(relName);
+            if (!rel)
+                continue;
+            rel.boot();
+        }
+        catch {
+            continue; // Un-bootable relation (no adapter yet, etc.) → skip its aggregates.
+        }
+        const columns = relSpec.aggregates ?? [];
+        const childTable = rel.relatedModel?.().table;
+        if (rel.type === 'hasMany') {
+            const fk = rel.foreignKeyColumnName;
+            const pk = rel.localKeyColumnName;
+            if (!childTable || !fk || !pk)
+                continue;
+            out[`${relName}.$count`] = oneToManySource('count', childTable, fk, pk, undefined);
+            for (const col of columns) {
+                for (const fn of COLUMN_FNS) {
+                    out[`${relName}.$${fn}.${col}`] = oneToManySource(fn, childTable, fk, pk, col);
+                }
+            }
+        }
+        else if (rel.type === 'manyToMany') {
+            const pivot = rel.pivotTable;
+            const ownerFk = rel.pivotForeignKey;
+            const inverseFk = rel.pivotRelatedForeignKey;
+            const ownerPk = rel.localKeyColumnName;
+            const childPk = rel.relatedKeyColumnName;
+            if (!pivot || !ownerFk || !ownerPk)
+                continue;
+            out[`${relName}.$count`] = manyToManySource('count', {
+                childTable: childTable ?? '',
+                childPk: childPk ?? '',
+                pivot,
+                ownerFk,
+                inverseFk: inverseFk ?? '',
+                ownerPk,
+            }, undefined);
+            if (childTable && inverseFk && childPk) {
+                for (const col of columns) {
+                    for (const fn of COLUMN_FNS) {
+                        out[`${relName}.$${fn}.${col}`] = manyToManySource(fn, { childTable, childPk, pivot, ownerFk, inverseFk, ownerPk }, col);
+                    }
+                }
+            }
+        }
+        // to-one (belongsTo / hasOne) and any other kind → no aggregate keys.
+    }
+    return out;
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/src/aggregate.js.map

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

package/dist/src/aggregate_path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure, ORM-agnostic parser for to-many aggregate field paths — a verbatim port
+ * of the NestJS `nestjs-filter` `aggregate/aggregate-path.ts` (commit 3f21e1f).
+ * It only parses the client-facing field *string* into a structured
+ * {@link AggregatePath}; turning that into SQL (a correlated subquery) is the
+ * Lucid-specific compiler's job (see `filter_spec.ts` aggregate discovery).
+ */
+export type AggregateFn = 'count' | 'sum' | 'avg' | 'min' | 'max';
+export interface AggregatePath {
+    relation: string;
+    fn: AggregateFn;
+    column?: string;
+}
+/**
+ * Parses a to-many aggregate field path.
+ *
+ * Grammar (single relation hop only):
+ * - `<relation>.$count`              → { relation, fn: 'count' }
+ * - `<relation>.$<fn>.<childColumn>` → { relation, fn, column } for fn in sum|avg|min|max
+ *
+ * Returns `null` for anything else so callers can fall through to
+ * non-aggregate field handling instead of throwing.
+ */
+export declare function parseAggregatePath(path: string): AggregatePath | null;
+//# sourceMappingURL=aggregate_path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate_path.d.ts","sourceRoot":"","sources":["../../src/aggregate_path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,WAAW,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAWrE"}

package/dist/src/aggregate_path.js

@@ -0,0 +1,35 @@
+/**
+ * Pure, ORM-agnostic parser for to-many aggregate field paths — a verbatim port
+ * of the NestJS `nestjs-filter` `aggregate/aggregate-path.ts` (commit 3f21e1f).
+ * It only parses the client-facing field *string* into a structured
+ * {@link AggregatePath}; turning that into SQL (a correlated subquery) is the
+ * Lucid-specific compiler's job (see `filter_spec.ts` aggregate discovery).
+ */
+const COLUMN_FNS = new Set(['sum', 'avg', 'min', 'max']);
+/**
+ * Parses a to-many aggregate field path.
+ *
+ * Grammar (single relation hop only):
+ * - `<relation>.$count`              → { relation, fn: 'count' }
+ * - `<relation>.$<fn>.<childColumn>` → { relation, fn, column } for fn in sum|avg|min|max
+ *
+ * Returns `null` for anything else so callers can fall through to
+ * non-aggregate field handling instead of throwing.
+ */
+export function parseAggregatePath(path) {
+    const parts = path.split('.');
+    // <rel>.$<fn>            → 2 parts, $count
+    // <rel>.$<fn>.<col>      → 3 parts, column fns
+    if (parts.length < 2 || parts.length > 3)
+        return null;
+    const [relation, token, column] = parts;
+    if (!relation || !token || !token.startsWith('$'))
+        return null;
+    const fn = token.slice(1);
+    if (fn === 'count')
+        return parts.length === 2 ? { relation, fn } : null;
+    if (COLUMN_FNS.has(fn))
+        return parts.length === 3 && column ? { relation, fn, column } : null;
+    return null;
+}
+//# sourceMappingURL=aggregate_path.js.map

package/dist/src/aggregate_path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate_path.js","sourceRoot":"","sources":["../../src/aggregate_path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,2CAA2C;IAC3C,+CAA+C;IAC/C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IACxC,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAgB,CAAC;IACzC,IAAI,EAAE,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9F,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/field_aliases.d.ts

@@ -25,4 +25,6 @@ export declare function resolveFieldAlias(aliases: FieldAliases | undefined, fie
 export declare function remapFilterAliases(filter: ColumnFilter, aliases: FieldAliases): ColumnFilter;
 /** Resolves every sort directive's field through the alias map (returns a new array). */
 export declare function remapSortAliases(sorts: SortItem[], aliases: FieldAliases): SortItem[];
+/** Resolves every distinct field name through the alias map (returns a new array). */
+export declare function remapDistinctAliases(fields: string[], aliases: FieldAliases): string[];
 //# sourceMappingURL=field_aliases.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"field_aliases.d.ts","sourceRoot":"","sources":["../../src/field_aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkB3C,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAS5F;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,QAAQ,EAAE,CAKrF"}
+{"version":3,"file":"field_aliases.d.ts","sourceRoot":"","sources":["../../src/field_aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkB3C,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAS5F;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,QAAQ,EAAE,CAKrF;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAEtF"}

package/dist/src/field_aliases.js

@@ -58,4 +58,8 @@ export function remapSortAliases(sorts, aliases) {
         direction: sort.direction,
     }));
 }
+/** Resolves every distinct field name through the alias map (returns a new array). */
+export function remapDistinctAliases(fields, aliases) {
+    return fields.map((field) => resolveFieldAlias(aliases, field));
+}
 //# sourceMappingURL=field_aliases.js.map

package/dist/src/field_aliases.js.map

@@ -1 +1 @@
-{"version":3,"file":"field_aliases.js","sourceRoot":"","sources":["../../src/field_aliases.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,WAAW;IACX,aAAa;IACb,WAAW;IACX,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAKH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC,EAAE,KAAa;IAChF,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAChF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAoB,EAAE,OAAqB;IAC5E,MAAM,IAAI,GAAiB;QACzB,KAAK,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;IACF,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC1D,IAAI,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,gBAAgB,CAAC,KAAiB,EAAE,OAAqB;IACvE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,KAAK,EAAE,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;QAC7C,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"field_aliases.js","sourceRoot":"","sources":["../../src/field_aliases.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,WAAW;IACX,aAAa;IACb,WAAW;IACX,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAKH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC,EAAE,KAAa;IAChF,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAChF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAoB,EAAE,OAAqB;IAC5E,MAAM,IAAI,GAAiB;QACzB,KAAK,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;IACF,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC1D,IAAI,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,gBAAgB,CAAC,KAAiB,EAAE,OAAqB;IACvE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,KAAK,EAAE,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;QAC7C,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC,CAAC;AACN,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,oBAAoB,CAAC,MAAgB,EAAE,OAAqB;IAC1E,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/src/filter_spec.d.ts

@@ -1,7 +1,8 @@
+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 { FilterFieldKind } from './types.js';
+import type { ComputedFields, FilterFieldKind } from './types.js';
 import type { FilterConfig, FullTextSearchConfig, SortItem, VectorSimilarityConfig } from './types.js';
 /**
  * Thrown when a {@link defineFilter} declaration is itself invalid (a developer
@@ -42,6 +43,18 @@ export interface RelationSpec {
     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
@@ -103,6 +116,17 @@ export interface DefineFilterOptions {
     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).
@@ -119,6 +143,23 @@ export interface DefineFilterOptions {
      * 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;
     /**
@@ -153,6 +194,10 @@ export interface FilterSpec {
     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[];

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

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