@adonis-agora/filter 0.6.0 → 0.7.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@adonis-agora/filter",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Server-side query filtering/sorting/pagination for AdonisJS — Spatie-style input, a Lucid adapter, and field allow-listing. Part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/DavideCarvalho/adonis-filter.git",
+    "url": "git+https://github.com/DavideCarvalho/adonis-agora-filter.git",
     "directory": "packages/core"
   },
   "author": "Davi Carvalho <davi@goflip.ai>",
@@ -23,6 +23,11 @@
       "import": "./dist/src/testing.js",
       "default": "./dist/src/testing.js"
     },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js",
+      "default": "./dist/configure.js"
+    },
     "./commands": {
       "types": "./dist/commands/main.d.ts",
       "import": "./dist/commands/main.js",
@@ -37,7 +42,8 @@
   "files": [
     "dist/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "sideEffects": false,
   "peerDependencies": {
@@ -53,15 +59,17 @@
     }
   },
   "devDependencies": {
-    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/assembler": "8.4.0",
+    "@tanstack/intent": "^0.3.2",
+    "@adonisjs/core": "7.4.0",
     "@adonisjs/lucid": "22.4.2",
-    "@types/luxon": "^3.7.2",
-    "@types/node": "^20.0.0",
-    "@types/pg": "^8.20.0",
-    "luxon": "^3.7.2",
-    "pg": "^8.22.0",
-    "typescript": "^5.4.0",
-    "vitest": "^3.0.0"
+    "@types/luxon": "3.7.4",
+    "@types/node": "20.19.43",
+    "@types/pg": "8.21.0",
+    "luxon": "3.7.2",
+    "pg": "8.23.0",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
   },
   "engines": {
     "node": ">=20.6.0"
@@ -74,7 +82,8 @@
     "query",
     "spatie",
     "pagination",
-    "agora"
+    "agora",
+    "tanstack-intent"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/filter-basics/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: filter-basics
+description: >
+  Add Spatie/JSON:API-style query filtering to an AdonisJS endpoint with
+  @adonis-agora/filter. Covers parseFilterRequest(qs), applyFilter(query, input,
+  { allowed, sortable, searchable }) with the returned/clamped { page, size },
+  the declarative defineFilter + applyFilterFromRequest flow (tenant scope,
+  defaultFilters, defaultSort, defaultSize/maxSize), the optional provider
+  macros .applyFilterFromRequest() / .filterPaginate(), wire format parsing
+  (filter[field][op]=value, sort=-createdAt, page/size), and input sourcing from
+  query string, POST body, or a nested key. Use when building a filtered list
+  endpoint, wiring a reusable filter policy, or deciding free functions vs macros.
+metadata:
+  type: core
+  library: "@adonis-agora/filter"
+  library_version: "0.7.0"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-filter:docs/getting-started.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/controllers.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/filter-classes.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/provider.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/operators.mdx"
+---
+
+# Filter basics: parse a request, apply it to a Lucid query
+
+The whole server surface is two functions: `parseFilterRequest(request.qs())`
+reshapes the request into a structured `FilterInput`, then
+`applyFilter(query, input, config)` validates it, prunes it against an
+allow-list, mutates your Lucid query in place, and returns the resolved
+`{ page, size }`. No config file, no decorators; the optional service provider
+only adds chainable macros.
+
+## Setup
+
+```bash
+npm install @adonis-agora/filter
+```
+
+```typescript
+// app/controllers/users_controller.ts
+import type { HttpContext } from '@adonisjs/core/http'
+import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'
+import User from '#models/user'
+
+export default class UsersController {
+  async index({ request }: HttpContext) {
+    const input = parseFilterRequest(request.qs())
+    const query = User.query()
+
+    const { page, size } = applyFilter(query, input, {
+      allowed: ['name', 'email', 'age', 'status'],
+      sortable: ['name', 'createdAt'],
+      searchable: ['name', 'email'],
+      defaultSize: 25,
+      maxSize: 100,
+    })
+
+    return query.paginate(page, size)
+  }
+}
+```
+
+```typescript
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+const UsersController = () => import('#controllers/users_controller')
+
+router.get('/users', [UsersController, 'index'])
+```
+
+A request like
+`GET /users?filter[status]=active&filter[age][gte]=18&search=fleet&sort=-createdAt&page=1&size=25`
+parses, validates, prunes against the allow-list, applies WHERE/ORDER BY/ILIKE,
+and returns `{ page: 1, size: 25 }` for `query.paginate()`.
+
+## Core patterns
+
+### 1. Two-function primitive — parse once, apply once
+
+`parseFilterRequest` is a pure reshape (no validation, no allow-listing);
+`applyFilter` owns validation and pruning. It reads any decoded object, so the
+same controller serves GET query strings and structured POST bodies:
+
+```typescript
+import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'
+
+// GET — decoded query string
+const input = parseFilterRequest(request.qs())
+
+// POST /search — the body may be the flat Spatie shape or the structured
+// object the client builder's .build() returns ({ filter: { where }, sort, paginate })
+const bodyInput = parseFilterRequest(request.body())
+```
+
+Source: `docs/guides/controllers.mdx`, `docs/guides/operators.mdx`
+
+### 2. Reusable policies with defineFilter + applyFilterFromRequest
+
+When a policy spans endpoints, declare a `FilterSpec` once at module scope and
+apply it in one call. Server scope (tenant + `defaultFilters`) is injected
+before allow-listed request filters; `defaultSort` applies when the request has
+none:
+
+```typescript
+// app/filters/user_filter.ts
+import { defineFilter } from '@adonis-agora/filter'
+import User from '#models/user'
+
+export const userFilter = defineFilter({
+  filterable: ['name', 'email', 'age', 'status'],
+  sortable: ['name', 'createdAt'],
+  searchable: ['name', 'email'],
+  relations: { posts: { filterable: ['title', 'status'] } },
+  tenant: { column: 'tenantId', resolve: (ctx) => (ctx as any).auth.user!.tenantId },
+  defaultFilters: [{ field: 'deletedAt', operator: 'isNull' }],
+  defaultSort: [{ field: 'createdAt', direction: 'desc' }],
+  defaultSize: 25,
+  maxSize: 100,
+})
+```
+
+```typescript
+// app/controllers/users_controller.ts
+import { applyFilterFromRequest } from '@adonis-agora/filter'
+import { userFilter } from '#filters/user_filter'
+import User from '#models/user'
+
+async index(ctx: HttpContext) {
+  const query = User.query()
+  const { page, size } = applyFilterFromRequest(query, userFilter, ctx)
+  return query.paginate(page, size)
+}
+```
+
+Source: `docs/definitions/index.mdx`
+
+### 3. Optional macros — inline chaining
+
+Register the provider (`node ace add @adonis-agora/filter`, or add
+`() => import('@adonis-agora/filter/filter_provider')` under `providers` in
+`adonisrc.ts`) and every model query gains `.applyFilterFromRequest(spec)` /
+`.filterPaginate(spec)`:
+
+```typescript
+import { userFilter } from '#filters/user_filter'
+import User from '#models/user'
+
+// ctx read from AsyncLocalStorage inside a request
+return User.query().where('active', true).applyFilterFromRequest(userFilter)
+
+// filter + paginate in one terminal call
+return User.query().filterPaginate(userFilter)
+```
+
+The free `applyFilterFromRequest(query, spec, ctx, options?)` always needs an
+explicit `ctx` — the AsyncLocalStorage fallback exists only in the macro layer.
+
+Source: `docs/guides/provider.mdx`
+
+### 4. Pagination is returned, not applied
+
+`applyFilter` resolves `size = clamp(input.size ?? defaultSize ?? 25, 1, maxSize ?? 100)`
+and `page = max(1, input.page ?? 1)` but leaves execution to you — so you can
+paginate, run plain `.exec()`, or layer a DISTINCT projection on the same
+filtered query.
+
+Source: `docs/getting-started.mdx`, `docs/guides/filter-classes.mdx`
+
+## Common mistakes
+
+### [CRITICAL] Feeding raw request page/size to paginate()
+
+Wrong:
+
+```typescript
+const input = parseFilterRequest(request.qs())
+await User.query().paginate(input.page ?? 1, input.size ?? 25)
+```
+
+Correct:
+
+```typescript
+const query = User.query()
+const { page, size } = applyFilter(query, input, { allowed: ['name'], maxSize: 100 })
+return query.paginate(page, size)
+```
+
+`applyFilter` clamps size into `[1, maxSize]` and floors page at 1; values taken
+straight off the query string skip the clamp entirely, so `?size=500000`
+executes against the database.
+
+Source: docs/getting-started.mdx ("Why pagination is returned, not applied"); docs/guides/filter-classes.mdx (Pagination bounds)
+
+### [HIGH] Putting the tenant column in the allow-list
+
+Wrong:
+
+```typescript
+export const userFilter = defineFilter({
+  filterable: ['name', 'tenantId'], // client can now constrain tenantId too
+  tenant: { column: 'tenantId', resolve: (ctx) => ctx.tenantId },
+})
+```
+
+Correct:
+
+```typescript
+export const userFilter = defineFilter({
+  filterable: ['name'],
+  tenant: { column: 'tenantId', resolve: (ctx) => ctx.tenantId },
+})
+```
+
+The tenant scope always lands as trusted server policy; if the same column is
+also client-filterable, a sent value AND-combines with it and silently returns
+an empty result set. Same rule for pre-scoped queries: constrain before
+`applyFilter` and leave the column out of `allowed`.
+
+Source: docs/definitions/index.mdx ("Tenant scope is un-tamperable"); docs/guides/controllers.mdx
+
+### [MEDIUM] Expecting `search` to work without `searchable`
+
+Wrong:
+
+```typescript
+applyFilter(query, input, { allowed: ['name'] })
+// ?search=fleet is silently skipped — no searchable columns declared
+```
+
+Correct:
+
+```typescript
+applyFilter(query, input, {
+  allowed: ['name'],
+  searchable: ['name', 'email'],
+})
+```
+
+The free-text term only routes anywhere when `searchable` is non-empty;
+otherwise it is dropped with no error and rows come back unfiltered by search.
+
+Source: docs/guides/filter-classes.mdx ("searchable enables free-text search")
+
+See also: `../filter-safety/SKILL.md` (tightening the boundary before exposing
+the endpoint publicly), `../filter-definitions/SKILL.md` (growing the policy
+into a reusable spec).

package/skills/filter-codegen/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: filter-codegen
+description: >
+  Generate a typed @adonis-agora/filter-client builder from a defineFilter spec
+  in @adonis-agora/filter — generateFilterClient(spec, options) pure string
+  transform, generateFilterClients(manifest), the make:filter-client ace command
+  with a FilterClientManifest in config/filter.ts, emitted artifacts
+  (<Name>FilterFields union, <Name>FilterFieldTypes interface,
+  <Name>FilterFieldMeta, <Name>FilterQuery factory), fieldTypes operator
+  narrowing (kind | enumValues | typeRef | nullable), maxDepth/banner/clientModule
+  options, filterableFieldPaths/sortableFieldPaths enumerators, and adonisrc.ts
+  commands-barrel registration. Use when sharing one field allow-list between
+  browser and server, regenerating clients after spec changes, or emitting
+  enum-aware typed builders.
+metadata:
+  type: core
+  library: "@adonis-agora/filter"
+  library_version: "0.7.0"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-filter:docs/codegen/index.mdx"
+  - "DavideCarvalho/adonis-filter:docs/definitions/index.mdx"
+---
+
+# Client codegen: one spec, both ends of the wire
+
+A `defineFilter` spec already knows which fields are filterable. Codegen turns
+that spec into a typed front-end module — a `filterQueryTyped<Fields, FieldTypes>()`
+builder scoped to the spec's fields — so browser and server share one
+field-name allow-list, checked at compile time. Generation is a pure function
+of the spec: string in, string out, no AST walk, no reflection.
+
+## Setup
+
+Register the command barrel, declare a manifest, run the command:
+
+```typescript
+// adonisrc.ts
+{
+  commands: [
+    // ...
+    () => import('@adonis-agora/filter/commands'),
+  ],
+}
+```
+
+```typescript
+// config/filter.ts
+import { defineFilter } from '@adonis-agora/filter'
+import type { FilterClientManifest } from '@adonis-agora/filter'
+
+export const filters: FilterClientManifest = {
+  people: {
+    spec: defineFilter({
+      filterable: ['age', 'name', 'status'],
+      sortable: ['age', 'name'],
+      searchable: ['name'],
+      relations: { posts: { filterable: ['title', 'published'] } },
+      defaultSort: [{ field: 'name', direction: 'asc' }],
+      defaultSize: 25,
+      maxSize: 100,
+    }),
+    fieldTypes: { age: { kind: 'number' }, status: { enumValues: ['active', 'inactive'] } },
+  },
+}
+```
+
+```bash
+node ace make:filter-client
+# create app/generated/filters/people_filter_client.ts
+```
+
+Defaults: entrypoint `config/filter.js`, output `app/generated/filters`. Pass
+an explicit entrypoint/dir with
+`node ace make:filter-client config/filter.js --output app/generated/filters`.
+
+## Core patterns
+
+### 1. The pure core — generateFilterClient
+
+Skip the command entirely when you want to own the IO:
+
+```typescript
+import { defineFilter, generateFilterClient } from '@adonis-agora/filter'
+
+const spec = defineFilter({
+  filterable: ['age', 'name', 'status'],
+  sortable: ['age', 'name'],
+})
+
+const code = generateFilterClient(spec, {
+  name: 'people',
+  fieldTypes: { age: { kind: 'number' }, status: { enumValues: ['active', 'inactive'] } },
+})
+// code is a TypeScript module string — write it wherever you like
+```
+
+For `name: 'people'` the module exports: `type PeopleFilterFields` (union of
+filterable paths — base plus relation-dotted), `interface PeopleFilterFieldTypes`
+(only when `fieldTypes` supplied), `const peopleFilterMeta` (runtime metadata),
+and `function peopleFilterQuery()` (a `filterQueryTyped` factory).
+
+Options: `clientModule` (import specifier, default `@adonis-agora/filter-client`),
+`maxDepth` (relation-path cap, defaults to `spec.maxDepth`), `banner`
+(the DO NOT EDIT header, default `true`).
+
+Source: `docs/codegen/index.mdx`
+
+### 2. Consume the generated client
+
+Import the generated factory and get field-name-checked, operator-narrowed
+queries:
+
+```typescript
+// web/people-table.ts
+import { peopleFilterQuery } from '#generated/filters/people_filter_client'
+
+const qs = peopleFilterQuery()
+  .contains('name', 'Al')   // 'name' checked against PeopleFilterFields
+  .gte('age', 18)           // number ops via fieldTypes narrowing
+  .toQueryString()
+
+await fetch(`/people?${qs}`)
+```
+
+Source: `docs/codegen/index.mdx`
+
+### 3. fieldTypes drives operator narrowing
+
+The spec carries the allow-list but not column value types (Lucid models are
+not reflected). Supply kinds per field path to unlock type-aware narrowing:
+
+| `FilterFieldTypeInfo` | Emits |
+|---|---|
+| `{ kind: 'string' \| 'number' \| 'boolean' \| 'date' \| 'json' }` | matching TS type |
+| `{ enumValues: ['A', 'B'] }` | union `"A" \| "B"` (wins over `kind`) |
+| `{ typeRef: 'Role' }` | named type verbatim (wins over everything) |
+| `{ nullable: true }` | appends `\| null` |
+
+Without `fieldTypes` the client stays field-name-safe but operator-permissive.
+On the server side the same declaration powers value coercion — one
+declaration, both ends.
+
+Source: `docs/codegen/index.mdx`, `docs/definitions/index.mdx`
+
+### 4. Just enumerate the paths
+
+`filterableFieldPaths(spec)` / `sortableFieldPaths(spec)` export the enumerated
+field-path lists if you're building your own artifact:
+
+```typescript
+import { filterableFieldPaths } from '@adonis-agora/filter'
+
+const paths = filterableFieldPaths(peopleSpec)
+// ['age', 'name', 'status', 'posts.title', 'posts.published']
+```
+
+Source: `docs/codegen/index.mdx`
+
+## Common mistakes
+
+### [HIGH] Running make:filter-client with the commands barrel unregistered
+
+Wrong:
+
+```typescript
+// adonisrc.ts — no filter commands entry
+{ commands: [] }
+```
+
+Correct:
+
+```typescript
+{ commands: [() => import('@adonis-agora/filter/commands')] }
+```
+
+Ace only sees commands an app opts into; without the barrel the command fails
+with "command not found", which reads as though it does not exist.
+`node ace add @adonis-agora/filter` adds the entry for you.
+
+Source: docs/codegen/index.mdx (Step 1 callout)
+
+### [HIGH] Hand-editing generated clients instead of regenerating
+
+Wrong:
+
+```typescript
+// renamed a spec field, then edited people_filter_client.ts by hand
+```
+
+Correct:
+
+```bash
+node ace make:filter-client # regenerate after every spec change
+```
+
+Generated modules carry a DO NOT EDIT banner and are a pure function of the
+spec; a stale client keeps sending fields the server now drops, so filters
+silently stop applying with no error on either end.
+
+Source: docs/codegen/index.mdx (banner option, Step 4)
+
+### [MEDIUM] Expecting codegen unions from a '*' allow-list
+
+Wrong:
+
+```typescript
+defineFilter({ filterable: ['*'] }) // PeopleFilterFields falls back to string
+```
+
+Correct:
+
+```typescript
+defineFilter({ filterable: ['age', 'name', 'status'] }) // enumerable literal union
+```
+
+A star list cannot be enumerated, so the emitter degrades to a permissive
+string union — the generated client looks typed but checks nothing.
+
+Source: docs/codegen/index.mdx (filterableFieldPaths callout)
+
+### [MEDIUM] Skipping fieldTypes then expecting operator narrowing
+
+Wrong:
+
+```typescript
+generateFilterClient(spec, { name: 'people' })
+peopleFilterQuery().gte('name', 5) // compiles — gte gated to orderable fields only
+```
+
+Correct:
+
+```typescript
+generateFilterClient(spec, {
+  name: 'people',
+  fieldTypes: { age: { kind: 'number' }, status: { enumValues: ['active', 'inactive'] } },
+})
+```
+
+Without a field-type map every field is kind-unknown, so all operators compile
+and mismatches surface only server-side as drops or coercion errors.
+
+Source: docs/codegen/index.mdx ("fieldTypes — unlock operator narrowing")
+
+See also: `packages/client/skills/filter-query-builder/SKILL.md` (the runtime
+the generated code targets), `../filter-definitions/SKILL.md` (spec authoring).