@adonis-agora/filter 0.0.0-beta-20261110131309

package/CHANGELOG.md

@@ -0,0 +1,417 @@
+# @adonis-agora/filter
+
+## 0.0.0-beta-20261110131309
+
+### Patch Changes
+
+- [#135](https://github.com/DavideCarvalho/adonis-agora-filter/pull/135) [`ed96cf0`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/ed96cf067d8e4d0983cde35c1c59eab81f94bac8) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fix `node ace add @adonis-agora/filter`: the package's main entry now exports the `configure` hook, so the provider and the commands barrel get registered in `adonisrc.ts`.
+  
+  Fix `node ace make:filter`, which crashed with `SyntaxError: Unexpected identifier 'filterable'` while compiling its stub.
+
+## 0.11.2
+
+### Patch Changes
+
+- [#128](https://github.com/DavideCarvalho/adonis-agora-filter/pull/128) [`456d256`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/456d256e1f9001751a03193e4aa98cc4740781c0) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - perf(in-memory): read each row's sort values at most once (lazily memoized) instead of twice per comparison, memoize the reader used for to-one relation hops, and hoist per-field kind lookups out of the distinct/group-by row loops. Sorting 20k rows by a virtual field is ~2x faster and by a to-one relation path ~5x faster; results and error behaviour are unchanged.
+
+## 0.11.1
+
+### Patch Changes
+
+- [#126](https://github.com/DavideCarvalho/adonis-agora-filter/pull/126) [`e03c7b7`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/e03c7b7a833ba4e3a8a2012dfbd3efae62162262) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Faster list queries, and a `notContains` fix.
+  
+  - `filterPaginate` (the query macro and `Model.filterPaginate`) reads the page before the total and skips Lucid's `COUNT(*)` when the page comes back short, since `offset + rows` already is the total. Full pages, and empty pages past the first, still count. Models with `before:paginate` / `before:fetch` hooks, and select lists that can change the row count (`distinct`, aggregates, raw expressions, `union`), keep Lucid's own `paginate`. The paginator and its meta are unchanged.
+  - The keyset seek ANDs a redundant `c0 >= v0` (`<=` for a `desc` lead) in front of its OR-of-tiers predicate, so Postgres can seek a `(c0, id)` index to the cursor instead of scanning from the start of it. Skipped when the boundary value is NULL.
+  - A to-many `$count` filter that only tests emptiness (`gt 0`, `gte 1`, `notEquals 0`, `equals 0`, `lte 0`, `lt 1`) compiles to `EXISTS` / `NOT EXISTS` instead of a correlated `COUNT(*)`. Same rows.
+  - Fix: `notContains` compiled to a not-equals test. It now is the negation of `contains` — `field IS NOT NULL AND NOT (field ILIKE '%v%')` — with the same case-insensitivity and LIKE escaping. `QueryBuilderLike` gains the `whereNot(callback)` overload this needs (Lucid, the in-memory builder and `MockQueryBuilder` implement it).
+
+## 0.11.0
+
+### Minor Changes
+
+- [#105](https://github.com/DavideCarvalho/adonis-agora-filter/pull/105) [`72ff139`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/72ff139e16c9ac05f326d490a997579ac5fb3273) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Drop Node.js 20 and 22: `engines.node` is now `>=24`. Node 20 reached end-of-life on 2026-04-30, and AdonisJS 7, which these packages require as a peer, needs Node 24 or later (`@adonisjs/core` declares `engines.node >=24.0.0`). The supported lines are the ones Node still maintains that AdonisJS 7 accepts: 24 and 26, both tested in CI.
+
+## 0.10.0
+
+### Minor Changes
+
+- [#67](https://github.com/DavideCarvalho/adonis-agora-filter/pull/67) [`1dd11c3`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/1dd11c3563cd015d27627808cc3e23830ed4be50) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - In-memory adapter at `@adonis-agora/filter/in-memory`: `defineCollection({ fields, primaryKey, relations })` declares a row source (field types incl. `'string[]'`-style arrays, virtual fields, to-one/to-many relations), and `collection.query(rows)` is a `QueryBuilderLike` the existing runner drives unchanged — `applyFilter`, `applyCursor`, `applyFilterFromRequest`, `applyCursorFromRequest` and `groupByCountFromRequest` all work over a plain array with the same parsing, allow-listing and coercion. Evaluation mirrors the SQL the Lucid adapter emits (ILIKE, three-valued NULL logic, NULLS LAST asc / FIRST desc, EXISTS for to-many paths). `filterInMemory` / `cursorInMemory` do it in one call; `InMemoryQueryError` is thrown for SQL-only features (`computed`, `fullText`, `vectorSimilarity`).
+
+## 0.9.0
+
+### Minor Changes
+
+- [#35](https://github.com/DavideCarvalho/adonis-agora-filter/pull/35) [`b6424ec`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/b6424ec696dbf8b50928e03a619d0227f5436345) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - One class style that does everything: `BaseFilter<TQuery>` — the generic base behind `BaseModelFilter` (Lucid) and custom backends alike — plus `applyCustomFilter` (methods per key over a caller-created draft, same envelope, loud rejections) and `groupByCount` end to end (`FilterQueryBuilder.groupByCount()` + `groupByCount[field]` envelope + `groupByCountFromRequest` over Lucid `GROUP BY` or a `GroupByCountAdapter`, with scope, search and paging). Lucid gains the `select`/`count`/`groupBy`/`offset` aggregation seam (optional, non-breaking).
+
+## 0.8.1
+
+### Patch Changes
+
+- [#32](https://github.com/DavideCarvalho/adonis-agora-filter/pull/32) [`1fe94ce`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/1fe94cee8ef847c25b163b68f3eaba9eb4c1c7ac) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Declare `@adonisjs/core` as a required peer, not an optional one.
+
+  The package's main entry point reads the ambient `HttpContext` (the Lucid macros and the
+  `Filterable` mixin both resolve the request context from AsyncLocalStorage when no `ctx` is
+  passed), so importing `@adonis-agora/filter` without `@adonisjs/core` installed failed at load
+  with `ERR_MODULE_NOT_FOUND` rather than warning at install. The peer now says what the code does.
+
+  `@adonisjs/lucid` stays optional and structural — the library talks to any `QueryBuilderLike`. A
+  new test walks the barrel's import graph and fails on any value import of `@adonisjs/lucid`, which
+  is the promise that _is_ kept.
+
+## 0.8.0
+
+### Minor Changes
+
+- [#29](https://github.com/DavideCarvalho/adonis-agora-filter/pull/29) [`2fd4700`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/2fd47000b87b025edf4c117ef97b1d9b731731a0) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Filter classes — the `adonis-lucid-filter` authoring shape, with the whole pipeline behind it.
+
+  A filter can now be a class:
+
+  ```ts
+  @inject()
+  export default class UserFilter extends BaseModelFilter {
+    declare $query: ModelQueryBuilderContract<typeof User>;
+    constructor(private tenants: TenantsService) {
+      super();
+    }
+
+    static model = User;
+    static filterable = ["name", "email", "status"];
+    static sortable = ["name", "createdAt"];
+    static searchable = ["name", "email"];
+
+    setup() {
+      this.$query.where("tenantId", this.tenants.current(this.$ctx));
+    }
+
+    fullName(value: string) {
+      this.$query.whereRaw("first_name || ' ' || last_name ilike ?", [
+        `%${value}%`,
+      ]);
+    }
+  }
+  ```
+
+  - **`BaseModelFilter`** — a method per request key, the builder on `this.$query`, a `setup()` that
+    runs before anything the request asked for. Writing the method is what exposes the key, so it
+    needs no allow-list entry; plain columns stay declarative in the statics.
+  - **Container-resolved** — the class is constructed through the request's IoC resolver, so
+    `@inject()` on the constructor works exactly as it does in a controller.
+  - **`Filterable` model mixin** — `static $filter = () => UserFilter`, then
+    `User.filterPaginate(ctx)` for the whole endpoint, or `const { query } = await User.filter(ctx)`
+    to keep composing and `query.filterPaginate()` to page it with what the request asked for.
+  - **The macros take a class** too, and `filterPaginate()` with no arguments pages a query a
+    previous call already filtered.
+  - **`node ace make:filter user`** scaffolds the class.
+  - Key matching follows the same conventions as `adonis-lucid-filter`: `static blacklist`,
+    `static dropId`, `static camelCase`, and a bare top-level key (`?minAge=21`) reaching a method of
+    that name. Keys the wire format owns (`sort`, `page`, `search`, …) are never dispatched.
+
+  Everything compiles to the same `FilterSpec` the declarative `defineFilter` produces, so classes
+  and specs share one runner — same allow-listing, operators, search, sort and page clamping.
+
+  Note for the class form: `applyFilterFromRequest(query, UserFilter, ctx)` and `User.filter(ctx)`
+  resolve to `{ page, size }` and `{ query, page, size }` respectively, never to the builder as the
+  promise's own value — a Lucid query builder is thenable, so a promise resolving to one would run
+  the query instead of handing it back.
+
+- [#30](https://github.com/DavideCarvalho/adonis-agora-filter/pull/30) [`9796b85`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/9796b851b078d6d1aa977bbe5a396058d8059d55) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Decorators for the class form, and a `FilterClass` type fix.
+
+  `@filterFor('team.name')` binds a filter method to the request key(s) it answers, for keys a method
+  name could never spell and for one method answering several keys; a bound method stops answering to
+  its own name, so the public key survives a rename. A key the wire format owns (`sort`, `page`, …)
+  is refused when the class is defined.
+
+  `@filterable()`, `@sortable()` and `@searchable()` declare a model's filterable surface on the
+  columns themselves, stacked under Lucid's `@column()`; a filter picks them up through its
+  `static model`, and a static on the filter still replaces the list outright so a stricter filter can
+  narrow a shared model. `@filterable('number')` also declares the field's kind.
+
+  Both work under legacy (`experimentalDecorators`, what AdonisJS compiles) and standard TC39
+  decorators — the flavour is detected at call time.
+
+  Fixes `FilterClass`, which intersected `Record<string, unknown>`: no concrete
+  `class UserFilter extends BaseModelFilter` satisfied that, so `static $filter = () => UserFilter`
+  on a model did not typecheck. A type test over a real Lucid model now covers it.
+
+## 0.7.1
+
+### Patch Changes
+
+- [#26](https://github.com/DavideCarvalho/adonis-agora-filter/pull/26) [`9b07c15`](https://github.com/DavideCarvalho/adonis-agora-filter/commit/9b07c159716c5032812bbf5c2360ff82df7be4c5) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Ship TanStack Intent AI-agent skills: five core skills under `packages/core/skills/` (filter-basics, filter-safety, filter-definitions, filter-querying, filter-codegen) and one under `packages/client/skills/` (filter-query-builder), plus repo-level `_artifacts/` (domain map, skill spec, skill tree) and a `check-skills` GitHub workflow validating them on PRs. Skills are included in each package's `files` so they land in `node_modules` on install.
+
+## 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
+
+- [#6](https://github.com/DavideCarvalho/adonis-filter/pull/6) [`e39da2c`](https://github.com/DavideCarvalho/adonis-filter/commit/e39da2c6f7e47553990f3295414b23d508894c9a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Os macros `query.applyFilterFromRequest(spec, ctx?)` e `query.filterPaginate(spec, ctx?)` passam a aceitar `ctx` opcional: quando omitido, leem o `HttpContext` ativo do AsyncLocalStorage do Adonis (`HttpContext.getOrFail()`). Nos controllers (99% dos casos) você chama `query.applyFilterFromRequest(spec)` sem passar o ctx. Fora de uma request (job/command), passe o ctx explicitamente. O default vive só no macro (camada Adonis); a função livre `applyFilterFromRequest` continua framework-agnostic, exigindo o ctx.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#4](https://github.com/DavideCarvalho/adonis-filter/pull/4) [`76b2ca8`](https://github.com/DavideCarvalho/adonis-filter/commit/76b2ca82d27811b09dbd98629be6964e9aee6167) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add chainable Lucid query-builder macros via an optional `FilterProvider`
+
+  Register `@adonis-agora/filter/filter_provider` to get the method-call form of
+  `applyFilterFromRequest` on any Lucid query builder:
+
+  ```ts
+  // filter + sort + search, then keep chaining:
+  const rows = await User.query()
+    .where("tenantId", tenant.id)
+    .applyFilterFromRequest(userFilter, ctx)
+    .orderBy("createdAt", "desc");
+
+  // filter + paginate in one terminal call (returns Lucid's paginator):
+  const page = await User.query().filterPaginate(userFilter, ctx);
+  ```
+
+  `applyFilterFromRequest` applies the spec's server scope + allow-listed
+  filter/sort/search and returns the query for chaining (pagination resolved but
+  not applied); `filterPaginate` additionally calls `paginate(page, size)`. The
+  free functions are unchanged and work without the provider — the macros only add
+  the chainable sugar, so `@adonisjs/lucid` is an optional peer. `registerFilterMacros`
+  is also exported for manual registration.
+
+## 0.3.1
+
+### Patch Changes
+
+- [`e6fb05c`](https://github.com/DavideCarvalho/adonis-filter/commit/e6fb05c0e137cd4ab3bad1f9ce5626216e670a8f) - Fix `QueryBuilderLike` rejecting every real Lucid query builder
+
+  Passing a Lucid builder to `applyFilterFromRequest` (or any adapter entry
+  point) failed to typecheck in consuming apps:
+
+  ```
+  Argument of type 'ModelQueryBuilderContract<typeof Post, Post>' is not
+  assignable to parameter of type 'QueryBuilderLike'.
+    Types of property 'where' are incompatible.
+  ```
+
+  The message blames `where`, but `where` was fine — TS reports the first member
+  it tries. The real culprit was `whereHas`, declared here as
+  `whereHas(relation: string, ...)`. Lucid types its own as
+  `<Name extends ExtractModelRelations<Model>>(relation: Name, ...)`, a union of
+  the model's literal relation names, and `string` is not assignable to that
+  union under the contravariant parameter check — so no real builder ever
+  satisfied the interface. Runtime was always fine; this was types-only.
+
+  `relation` is now `any`, which is the only type that both accepts the `string`
+  the adapter passes and is assignable to each model's relation-name union.
+  Marking the member optional does not help: an optional member that is present
+  is still checked.
+
+  A compile-time guard against real `@adonisjs/lucid` types now covers this
+  (`test/types/lucid_compat.types.ts`, run by `pnpm typecheck`). Lucid is a
+  devDependency only — nothing under `src/` imports it, so the package stays
+  framework-free. A hand-transcribed stub of Lucid's types was tried first and
+  compiled clean while real Lucid did not, so the guard uses Lucid's own `.d.ts`.
+
+## 0.3.0
+
+### Minor Changes
+
+- [`d20245c`](https://github.com/DavideCarvalho/adonis-filter/commit/d20245cc6818120098d0f9027b59284380fd9f7e) - `filterable` accepts a colocated map: field name and its kind in one place
+
+  The array form makes every non-string field appear twice — once in `filterable`, once in
+  `fieldTypes` — which is ceremony for what is usually a short list:
+
+  ```ts
+  filterable: ['advisorId', 'dayOfWeek', 'isRecurring'],
+  fieldTypes: { dayOfWeek: { kind: 'number' }, isRecurring: { kind: 'boolean' } },
+  ```
+
+  `filterable` now also accepts a map, declaring both at once:
+
+  ```ts
+  filterable: { advisorId: 'string', dayOfWeek: 'number', isRecurring: 'boolean' },
+  ```
+
+  It desugars at the `defineFilter` boundary — the keys become the allow-list, the values become
+  `fieldTypes` — so everything downstream (predicates, runner, codegen) sees exactly the spec the
+  array form produces. An explicit `fieldTypes` entry still wins per field, which is how a caller
+  adds codegen-only richness (`enumValues`/`typeRef`) on top of a bare kind.
+
+  Both existing forms (`string[]` and `'*'`) are untouched and remain the right choice when no field
+  needs a declared type — `'string'` is the no-op kind, so a spec of only string columns should keep
+  using the array.
+
+## 0.2.0
+
+### Minor Changes
+
+- [`058f0c0`](https://github.com/DavideCarvalho/adonis-filter/commit/058f0c0ef3dd224277663e6a5d40c0ef58e6bbd7) - `fieldTypes` on `defineFilter`: server-side value validation, and one type declaration for both ends
+
+  A filter value arriving over a query string is always a string, and Postgres implicitly casts the
+  benign cases — `day_of_week = '3'` and `is_recurring = 'false'` both work — so the gap stayed
+  invisible. It surfaces when a client sends something uncastable: `?filter[isRecurring][equals]=xyz`
+  becomes `is_recurring = 'xyz'`, which Postgres rejects with `invalid input syntax for type boolean`.
+  That is a **500 on a public endpoint, driven entirely by user input**. The allow-list guarded which
+  FIELD could be filtered; nothing guarded the VALUE that reached the column.
+
+  `defineFilter` now accepts `fieldTypes`, and a declared field has its value coerced before it ever
+  reaches the driver. An uncoercible value is treated exactly like a disallowed field — dropped by
+  default, or a loud `InvalidColumnFilterError` (→ 400 instead of 500) under `throwOnInvalid`. The
+  existing semantics are reused rather than a second error path invented.
+
+  ```ts
+  export const availabilityFilter = defineFilter({
+    filterable: ["advisorId", "dayOfWeek", "isRecurring"],
+    fieldTypes: {
+      dayOfWeek: { kind: "number" },
+      isRecurring: { kind: "boolean" },
+    },
+  });
+  ```
+
+  The same declaration now also feeds `make:filter-client`, which previously required repeating the
+  types in the codegen manifest. Declaring a kind once drives both value coercion and the client's
+  operator narrowing; an explicit manifest `fieldTypes` still wins when the client wants richer
+  codegen-only info (`enumValues`/`typeRef`).
+
+  Details:
+
+  - Array-valued operators (`in`, `between`, ...) coerce element-wise and fail as a whole if any
+    element fails — a partially-coerced list would filter on something the client never asked for.
+  - Pattern operators (`contains`, `startsWith`, ...) are never coerced: their argument is a LIKE
+    pattern, so turning `contains: '3'` into the number `3` would destroy it.
+  - `date` values are validated but handed back verbatim, never rewritten — converting `'2026-07-15'`
+    to a `Date` would silently re-zone a date-only value and shift the day for negative-offset clients.
+  - Undeclared fields are untouched, so this is backwards compatible and opt-in.
+  - `FilterFieldKind` moved from `generate_client.ts` to `types.ts` (it is no longer codegen-only) and
+    is re-exported from its old path.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# `@adonis-agora/filter`
+
+[![npm version](https://img.shields.io/npm/v/@adonis-agora/filter)](https://www.npmjs.com/package/@adonis-agora/filter) [![npm downloads](https://img.shields.io/npm/dm/@adonis-agora/filter)](https://www.npmjs.com/package/@adonis-agora/filter) [![CI](https://github.com/DavideCarvalho/adonis-agora-filter/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/DavideCarvalho/adonis-agora-filter/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@adonis-agora/filter)](https://www.npmjs.com/package/@adonis-agora/filter)
+
+Server-side query filtering, sorting, and pagination for AdonisJS. Parses the
+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.
+
+```ts
+import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'
+
+const input = parseFilterRequest(ctx.request.qs())
+const query = User.query()
+const { page, size } = applyFilter(query, input, {
+  allowed: ['name', 'email', 'age'],
+  searchable: ['name', 'email'],
+})
+return query.paginate(page, size)
+```
+
+### Chainable macros (optional)
+
+Register the `FilterProvider` to get the method-call form of
+`applyFilterFromRequest` on any Lucid query builder — the same operation, but
+chainable:
+
+```ts
+// adonisrc.ts → providers
+() => import('@adonis-agora/filter/filter_provider')
+```
+
+```ts
+// filter + sort + search, then keep chaining:
+const rows = await User.query()
+  .where('tenantId', tenant.id)
+  .applyFilterFromRequest(userFilter, ctx)
+  .orderBy('createdAt', 'desc')
+
+// filter + paginate in one terminal call (returns Lucid's paginator):
+const page = await User.query().filterPaginate(userFilter, ctx)
+```
+
+`applyFilterFromRequest` returns the query (pagination resolved but not applied);
+`filterPaginate` pages it with the resolved values, returning Lucid's paginator — it
+reads the page first and skips the `COUNT(*)` when the page comes back short. The free
+functions work without the provider — the macros only add the chainable sugar, so
+`@adonisjs/lucid` stays an optional peer.
+
+Operators: equals/notEquals, contains/iContains/startsWith/endsWith, gt/gte/lt/lte,
+between/notBetween, in/notIn/isAnyOf, isNull/isNotNull/isEmpty/isNotEmpty, plus
+AND/OR composition. The `allowed`/`sortable`/`searchable` lists are the security
+boundary. The Lucid binding is structural (`QueryBuilderLike`) so any Lucid query
+builder works and the adapter is unit-testable.
+
+### In-memory lists
+
+`@adonis-agora/filter/in-memory` runs the same input against a plain array — an
+in-memory `QueryBuilderLike` the runner drives exactly like a Lucid query:
+
+```ts
+import { defineCollection, filterInMemory } from '@adonis-agora/filter/in-memory'
+
+const users = defineCollection<UserRow>({
+  fields: { name: 'string', age: 'number', fullName: { type: 'string', get: (u) => u.first + ' ' + u.last } },
+})
+const page = filterInMemory(users, rows, input, { allowed: ['name', 'age', 'fullName'] })
+// { data, meta: { total, perPage, currentPage, lastPage, firstPage } }
+```
+
+See the [repository README](https://github.com/DavideCarvalho/adonis-filter).
+
+## License
+
+MIT © Davi Carvalho

package/dist/commands/main.d.ts

@@ -0,0 +1,19 @@
+import { ListLoader } from '@adonisjs/core/ace';
+import MakeFilter from './make_filter.js';
+import MakeFilterClient from './make_filter_client.js';
+/**
+ * The commands barrel for `@adonis-agora/filter`. An app registers it in its
+ * `adonisrc` via `rcFile.addCommand('@adonis-agora/filter/commands')`. A
+ * {@link ListLoader} exposes the `make:filter-client` command's metadata and
+ * constructors to the ace kernel: `make:filter` (scaffold a filter class) and
+ * `make:filter-client` (emit the typed front-end builders).
+ *
+ * `@adonisjs/core` is an *optional* peer of this otherwise framework-free core —
+ * only this `./commands` subpath imports it, so the main entrypoint stays
+ * dependency-free.
+ */
+declare const loader: ListLoader<typeof MakeFilter | typeof MakeFilterClient>;
+export declare const getMetaData: () => Promise<import("@adonisjs/core/types/ace").CommandMetaData[]>;
+export declare const getCommand: (metaData: import("@adonisjs/core/types/ace").CommandMetaData) => Promise<typeof MakeFilter | typeof MakeFilterClient | null>;
+export default loader;
+//# sourceMappingURL=main.d.ts.map

package/dist/commands/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,UAAU,MAAM,kBAAkB,CAAC;AAC1C,OAAO,gBAAgB,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,QAAA,MAAM,MAAM,yDAAiD,CAAC;AAE9D,eAAO,MAAM,WAAW,qEAAkC,CAAC;AAC3D,eAAO,MAAM,UAAU,+HAAiC,CAAC;eAE1C,MAAM"}

package/dist/commands/main.js

@@ -0,0 +1,19 @@
+import { ListLoader } from '@adonisjs/core/ace';
+import MakeFilter from './make_filter.js';
+import MakeFilterClient from './make_filter_client.js';
+/**
+ * The commands barrel for `@adonis-agora/filter`. An app registers it in its
+ * `adonisrc` via `rcFile.addCommand('@adonis-agora/filter/commands')`. A
+ * {@link ListLoader} exposes the `make:filter-client` command's metadata and
+ * constructors to the ace kernel: `make:filter` (scaffold a filter class) and
+ * `make:filter-client` (emit the typed front-end builders).
+ *
+ * `@adonisjs/core` is an *optional* peer of this otherwise framework-free core —
+ * only this `./commands` subpath imports it, so the main entrypoint stays
+ * dependency-free.
+ */
+const loader = new ListLoader([MakeFilter, MakeFilterClient]);
+export const getMetaData = loader.getMetaData.bind(loader);
+export const getCommand = loader.getCommand.bind(loader);
+export default loader;
+//# sourceMappingURL=main.js.map

package/dist/commands/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,UAAU,MAAM,kBAAkB,CAAC;AAC1C,OAAO,gBAAgB,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAe,MAAM,CAAC"}

package/dist/commands/make_filter.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+/**
+ * `node ace make:filter <name>` — scaffold a filter class under `app/filters/`.
+ *
+ * The generated class extends `BaseModelFilter`: allow-lists as statics for the plain columns, a
+ * `setup()` for the scope the client cannot relax, and a method per key that needs SQL of its own.
+ * It is `@inject()`ed, so a constructor dependency resolves through the container exactly as a
+ * controller's does.
+ */
+export default class MakeFilter extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    name: string;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=make_filter.d.ts.map

package/dist/commands/make_filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_filter.d.ts","sourceRoot":"","sources":["../../commands/make_filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,WAAW;IACjD,OAAgB,WAAW,SAAiB;IAC5C,OAAgB,WAAW,SAA+B;IAC1D,OAAgB,OAAO,EAAE,cAAc,CAA+B;IAG9D,IAAI,EAAE,MAAM,CAAC;IAEN,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAMlC;CACF"}

package/dist/commands/make_filter.js

@@ -0,0 +1,32 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { args, BaseCommand } from '@adonisjs/core/ace';
+import { stubsRoot } from '../stubs/main.js';
+/**
+ * `node ace make:filter <name>` — scaffold a filter class under `app/filters/`.
+ *
+ * The generated class extends `BaseModelFilter`: allow-lists as statics for the plain columns, a
+ * `setup()` for the scope the client cannot relax, and a method per key that needs SQL of its own.
+ * It is `@inject()`ed, so a constructor dependency resolves through the container exactly as a
+ * controller's does.
+ */
+export default class MakeFilter extends BaseCommand {
+    static commandName = 'make:filter';
+    static description = 'Create a new filter class';
+    static options = { allowUnknownFlags: true };
+    async run() {
+        const codemods = await this.createCodemods();
+        await codemods.makeUsingStub(stubsRoot, 'make/filter/main.stub', {
+            flags: this.parsed.flags,
+            entity: this.app.generators.createEntity(this.name),
+        });
+    }
+}
+__decorate([
+    args.string({ description: 'Name of the filter (e.g. user)' })
+], MakeFilter.prototype, "name", void 0);
+//# sourceMappingURL=make_filter.js.map

package/dist/commands/make_filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_filter.js","sourceRoot":"","sources":["../../commands/make_filter.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,WAAW;IACjD,MAAM,CAAU,WAAW,GAAG,aAAa,CAAC;IAC5C,MAAM,CAAU,WAAW,GAAG,2BAA2B,CAAC;IAC1D,MAAM,CAAU,OAAO,GAAmB,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAK7D,KAAK,CAAC,GAAG;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC7C,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,uBAAuB,EAAE;YAC/D,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;YACxB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;SACpD,CAAC,CAAC;IACL,CAAC;CACF;AATS;IADP,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC;wCAC1C"}