@adonis-agora/filter 0.0.0-beta-20261110131309

package/dist/src/validate-column-filter.js

@@ -0,0 +1,148 @@
+import { FILTER_OPERATORS, OPERATOR_ALIASES, } from './operators.js';
+const operatorSet = new Set(FILTER_OPERATORS);
+/**
+ * Normalizes an operator string to its canonical {@link FilterOperator},
+ * resolving SQL-symbol aliases (`=` -> `equals`, `!=` -> `notEquals`, ...).
+ * Canonical operators (and unknown strings) pass through unchanged.
+ */
+export function normalizeOperator(operator) {
+    return (OPERATOR_ALIASES[operator] ?? operator);
+}
+/**
+ * Operators that require no value (unary operators).
+ */
+const UNARY_OPERATORS = new Set([
+    'isEmpty',
+    'isNotEmpty',
+    'isNull',
+    'isNotNull',
+    'exists',
+    'notExists',
+]);
+/**
+ * Operators that require an array value.
+ */
+const ARRAY_OPERATORS = new Set([
+    'in',
+    'notIn',
+    'isAnyOf',
+    'between',
+    'notBetween',
+]);
+/**
+ * Maximum allowed nesting depth for AND/OR filter composition.
+ * Prevents stack overflow from maliciously deep payloads (DoS).
+ */
+export const MAX_FILTER_DEPTH = 10;
+export class InvalidColumnFilterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidColumnFilterError';
+    }
+}
+/**
+ * Validates a ColumnFilter at runtime:
+ * - field must be a non-empty string with no SQL-unsafe characters
+ * - operator must be a known FilterOperator
+ * - value is required for non-unary operators
+ * - 'between' requires a 2-element array
+ * - 'in'/'isAnyOf' require arrays
+ * - AND/OR arrays are validated recursively
+ */
+export function validateColumnFilter(filter, depth = 0) {
+    if (depth > MAX_FILTER_DEPTH) {
+        throw new InvalidColumnFilterError(`Filter nesting exceeds maximum depth (${MAX_FILTER_DEPTH}).`);
+    }
+    if (!filter || typeof filter !== 'object') {
+        throw new InvalidColumnFilterError('Column filter must be a non-null object.');
+    }
+    // Pure group node: `{ AND: [...] }` / `{ OR: [...] }` with no column of its
+    // own composes child filters and has no field/operator/value to validate.
+    // The client builder emits these (sometimes with an empty `field`), so treat
+    // an empty field as absent. Validate only the nested arrays, then stop.
+    const isGroupNode = (filter.AND !== undefined || filter.OR !== undefined) &&
+        (filter.field === undefined || filter.field === '');
+    if (isGroupNode) {
+        for (const key of ['AND', 'OR']) {
+            const group = filter[key];
+            if (group !== undefined) {
+                if (!Array.isArray(group)) {
+                    throw new InvalidColumnFilterError(`"${key}" must be an array of ColumnFilter.`);
+                }
+                for (const sub of group) {
+                    validateColumnFilter(sub, depth + 1);
+                }
+            }
+        }
+        return;
+    }
+    // Validate field
+    if (typeof filter.field !== 'string' || filter.field.length === 0) {
+        throw new InvalidColumnFilterError('Column filter "field" must be a non-empty string.');
+    }
+    // Reject field names that contain SQL-unsafe characters
+    if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(filter.field)) {
+        throw new InvalidColumnFilterError(`Column filter field "${filter.field}" contains invalid characters. Only letters, digits, underscores, and dots are allowed.`);
+    }
+    // Validate operator, accepting SQL-symbol aliases (`=`, `!=`, `<`, ...).
+    const op = normalizeOperator(filter.operator);
+    if (!operatorSet.has(op)) {
+        throw new InvalidColumnFilterError(`Unknown filter operator "${filter.operator}". ` +
+            `Valid operators: ${FILTER_OPERATORS.join(', ')}.`);
+    }
+    // Persist the canonical form so downstream query builders never see aliases.
+    filter.operator = op;
+    // Reject null for non-unary operators (point to isNull instead)
+    if (!UNARY_OPERATORS.has(op) && filter.value === null) {
+        throw new InvalidColumnFilterError(`Operator "${op}" received null. Use "isNull" for NULL checks.`);
+    }
+    // Validate value
+    if (UNARY_OPERATORS.has(op)) {
+        // Unary operators don't need a value — ignore any provided value
+    }
+    else if (op === 'between' || op === 'notBetween') {
+        if (!Array.isArray(filter.value) || filter.value.length !== 2) {
+            throw new InvalidColumnFilterError(`Operator "${op}" requires a value that is a 2-element array, got: ${JSON.stringify(filter.value)}.`);
+        }
+    }
+    else if (ARRAY_OPERATORS.has(op)) {
+        if (!Array.isArray(filter.value)) {
+            throw new InvalidColumnFilterError(`Operator "${op}" requires an array value, got: ${typeof filter.value}.`);
+        }
+    }
+    else {
+        if (filter.value === undefined) {
+            throw new InvalidColumnFilterError(`Operator "${op}" requires a value.`);
+        }
+    }
+    // Validate nested AND
+    if (filter.AND !== undefined) {
+        if (!Array.isArray(filter.AND)) {
+            throw new InvalidColumnFilterError('"AND" must be an array of ColumnFilter.');
+        }
+        for (const sub of filter.AND) {
+            validateColumnFilter(sub, depth + 1);
+        }
+    }
+    // Validate nested OR
+    if (filter.OR !== undefined) {
+        if (!Array.isArray(filter.OR)) {
+            throw new InvalidColumnFilterError('"OR" must be an array of ColumnFilter.');
+        }
+        for (const sub of filter.OR) {
+            validateColumnFilter(sub, depth + 1);
+        }
+    }
+}
+/**
+ * Validates an array of ColumnFilter objects.
+ */
+export function validateColumnFilters(filters) {
+    if (!Array.isArray(filters)) {
+        throw new InvalidColumnFilterError('Column filters must be an array.');
+    }
+    for (const filter of filters) {
+        validateColumnFilter(filter);
+    }
+}
+//# sourceMappingURL=validate-column-filter.js.map

package/dist/src/validate-column-filter.js.map

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

package/dist/src/value-shape.d.ts

@@ -0,0 +1,18 @@
+import { type ColumnFilter } from './operators.js';
+/**
+ * True when `value` is a non-empty plain object whose keys are ALL filter operators — i.e. an
+ * operator map like `{ gt: 5, lt: 10 }` rather than a scalar equality value. Arrays and `null` are
+ * not operator objects. Single source of the shape classifier every adapter's auto-field path uses.
+ */
+export declare function isOperatorObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Normalize a raw auto-field value to canonical {@link ColumnFilter}[]:
+ * - an array → a single `in` filter,
+ * - an {@link isOperatorObject operator object} → one filter per operator,
+ * - any other (scalar) value → a single `equals` filter.
+ *
+ * Lets an adapter's auto-field/relation/computed surfaces drive the same `ColumnFilter` path the
+ * structured-filter input already uses, instead of re-implementing the scalar/array/object ladder.
+ */
+export declare function valueToColumnFilters(field: string, value: unknown): ColumnFilter[];
+//# sourceMappingURL=value-shape.d.ts.map

package/dist/src/value-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-shape.d.ts","sourceRoot":"","sources":["../../src/value-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAyC,MAAM,gBAAgB,CAAC;AAK1F;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,EAAE,CAUlF"}

package/dist/src/value-shape.js

@@ -0,0 +1,36 @@
+import { FILTER_OPERATORS } from './operators.js';
+/** Every canonical operator name, for the operator-object shape check. */
+const OPERATOR_SET = new Set(FILTER_OPERATORS);
+/**
+ * True when `value` is a non-empty plain object whose keys are ALL filter operators — i.e. an
+ * operator map like `{ gt: 5, lt: 10 }` rather than a scalar equality value. Arrays and `null` are
+ * not operator objects. Single source of the shape classifier every adapter's auto-field path uses.
+ */
+export function isOperatorObject(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k) => OPERATOR_SET.has(k));
+}
+/**
+ * Normalize a raw auto-field value to canonical {@link ColumnFilter}[]:
+ * - an array → a single `in` filter,
+ * - an {@link isOperatorObject operator object} → one filter per operator,
+ * - any other (scalar) value → a single `equals` filter.
+ *
+ * Lets an adapter's auto-field/relation/computed surfaces drive the same `ColumnFilter` path the
+ * structured-filter input already uses, instead of re-implementing the scalar/array/object ladder.
+ */
+export function valueToColumnFilters(field, value) {
+    if (Array.isArray(value))
+        return [{ field, operator: 'in', value }];
+    if (isOperatorObject(value)) {
+        return Object.entries(value).map(([operator, opVal]) => ({
+            field,
+            operator: operator,
+            value: opVal,
+        }));
+    }
+    return [{ field, operator: 'equals', value }];
+}
+//# sourceMappingURL=value-shape.js.map

package/dist/src/value-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-shape.js","sourceRoot":"","sources":["../../src/value-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,gBAAgB,EAAuB,MAAM,gBAAgB,CAAC;AAE1F,0EAA0E;AAC1E,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAS,gBAAgB,CAAC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,KAAc;IAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACvD,KAAK;YACL,QAAQ,EAAE,QAA0B;YACpC,KAAK,EAAE,KAAK;SACb,CAAC,CAAC,CAAC;IACN,CAAC;IACD,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/stubs/main.d.ts

@@ -0,0 +1,3 @@
+/** Absolute path to this package's stubs, handed to `codemods.makeUsingStub`. */
+export declare const stubsRoot: string;
+//# sourceMappingURL=main.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,eAAO,MAAM,SAAS,QAAgD,CAAC"}

package/dist/stubs/main.js

@@ -0,0 +1,4 @@
+import { fileURLToPath } from 'node:url';
+/** Absolute path to this package's stubs, handed to `codemods.makeUsingStub`. */
+export const stubsRoot = fileURLToPath(new URL('./', import.meta.url));
+//# sourceMappingURL=main.js.map

package/dist/stubs/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iFAAiF;AACjF,MAAM,CAAC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/dist/stubs/make/filter/main.stub

@@ -0,0 +1,45 @@
+{{#var filterName = string(entity.name).pascalCase().removeSuffix('Filter').toString() + 'Filter'}}
+{{#var modelName = string(entity.name).pascalCase().removeSuffix('Filter').toString()}}
+{{#var filterFileName = string(entity.name).snakeCase().removeSuffix('filter').toString() + '_filter'}}
+{{#var modelFileName = string(entity.name).snakeCase().removeSuffix('filter').toString()}}
+{{{
+  exports({
+    to: app.makePath('app/filters', entity.path, filterFileName + '.ts')
+  })
+}}}
+import { BaseModelFilter } from '@adonis-agora/filter'
+import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
+import {{ modelName }} from '#models/{{ modelFileName }}'
+
+export default class {{ filterName }} extends BaseModelFilter {
+  declare $query: ModelQueryBuilderContract<typeof {{ modelName }}>
+
+  static model = {{ modelName }}
+
+  /** Columns clients may filter on with the standard operators — these need no method. */
+  static filterable = ['name']
+  /** Columns clients may sort on. Defaults to the filterable list. */
+  static sortable = ['createdAt']
+  /** Columns the free-text search term scans. */
+  static searchable = ['name']
+
+  static defaultSort = [{ field: 'createdAt', direction: 'desc' as const }]
+  static defaultSize = 25
+  static maxSize = 100
+
+  /**
+   * Runs on every call, before anything the request asked for — the place for a scope the client
+   * cannot relax (a tenant, a soft-delete guard, an ownership check).
+   */
+  setup() {
+    // this.$query.whereNull('deletedAt')
+  }
+
+  /**
+   * One method per request key that needs SQL of its own. ?filter[fullName]=silva lands here;
+   * writing the method IS what exposes the key, so it needs no allow-list entry.
+   */
+  // fullName(value: string) {
+  //   this.$query.whereILike('full_name', '%' + value + '%')
+  // }
+}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@adonis-agora/filter",
+  "version": "0.0.0-beta-20261110131309",
+  "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-agora-filter.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://davidecarvalho.github.io/agora/docs/filter",
+  "bugs": {
+    "url": "https://github.com/DavideCarvalho/adonis-agora-filter/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "filter",
+    "lucid",
+    "query",
+    "spatie",
+    "pagination",
+    "agora",
+    "tanstack-intent"
+  ],
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing.d.ts",
+      "import": "./dist/src/testing.js",
+      "default": "./dist/src/testing.js"
+    },
+    "./in-memory": {
+      "types": "./dist/src/in_memory.d.ts",
+      "import": "./dist/src/in_memory.js",
+      "default": "./dist/src/in_memory.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",
+      "default": "./dist/commands/main.js"
+    },
+    "./filter_provider": {
+      "types": "./dist/providers/filter_provider.d.ts",
+      "import": "./dist/providers/filter_provider.js",
+      "default": "./dist/providers/filter_provider.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "stubs/",
+    "README.md",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/lucid": "^22.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/lucid": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "8.6.0",
+    "@adonisjs/core": "7.6.0",
+    "@adonisjs/lucid": "22.4.2",
+    "@tanstack/intent": "0.5.6",
+    "@types/luxon": "3.7.6",
+    "@types/node": "26.6.5",
+    "@types/pg": "8.23.1",
+    "luxon": "3.7.2",
+    "pg": "8.23.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && pnpm run copy:stubs",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.typetest.json",
+    "copy:stubs": "mkdir -p dist/stubs/make/filter && cp stubs/make/filter/main.stub dist/stubs/make/filter/main.stub"
+  }
+}

package/skills/filter-basics/SKILL.md

@@ -0,0 +1,285 @@
+---
+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, and the in-memory adapter
+  (@adonis-agora/filter/in-memory: defineCollection, filterInMemory,
+  cursorInMemory) for lists that are not a table. Use when building a filtered
+  list endpoint, wiring a reusable filter policy, deciding free functions vs
+  macros, or filtering a plain array with the same wire format.
+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"
+  - "DavideCarvalho/adonis-filter:docs/guides/in-memory.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)
+```
+
+`filterPaginate` returns Lucid's paginator but reads the page before the total:
+a page shorter than `size` gives the total as `offset + rows`, so no `COUNT(*)`
+runs. Full pages, and empty pages past the first, still count. Models with `before:paginate` / `before:fetch` hooks, and `distinct` /
+aggregate / raw / `union` selects, keep Lucid's own `paginate`.
+
+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`
+
+### 5. Lists that are not a table — the in-memory adapter
+
+Rows merged from several sources, static catalogs and remote API pages take the
+same input through `@adonis-agora/filter/in-memory`. `collection.query(rows)` is a
+`QueryBuilderLike`, so every runner entry point (and `defineFilter` specs) drives
+it unchanged; the builder evaluates the calls with Postgres semantics (ILIKE,
+three-valued NULLs, NULLS LAST asc / FIRST desc, EXISTS for to-many paths).
+
+```typescript
+import { defineCollection, filterInMemory } from '@adonis-agora/filter/in-memory'
+
+const users = defineCollection<UserRow>({
+  fields: { name: 'string', age: 'number', tags: 'string[]', fullName: { type: 'string', get: (u) => `${u.first} ${u.last}` } },
+  relations: { posts: { kind: 'one-to-many', target: () => posts, get: (u) => u.posts } },
+})
+
+const page = filterInMemory(users, rows, parseFilterRequest(ctx.request.qs()), {
+  allowed: ['name', 'age', 'fullName', 'posts.title'],
+  fieldTypes: users.fieldTypes,
+})
+// or: const q = users.query(rows); const { page, size } = applyFilterFromRequest(q, spec, ctx); q.paginate(page, size)
+```
+
+Policy `computed`, `fullText` and `vectorSimilarity` are SQL-only and throw
+`InMemoryQueryError` there — declare a virtual field on the collection instead.
+
+Source: `docs/guides/in-memory.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).