@adonis-agora/filter 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @adonis-agora/filter
 
+## 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

package/README.md

@@ -17,6 +17,33 @@ const { page, size } = applyFilter(query, input, {
 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` applies `paginate(page, size)` with the resolved values. 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

package/dist/providers/filter_provider.d.ts

@@ -0,0 +1,28 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Wires `@adonis-agora/filter`'s chainable Lucid macros into the application.
+ *
+ * On boot it registers the `applyFilterFromRequest` and `filterPaginate` macros
+ * onto Lucid's `ModelQueryBuilder`, so any model query gains the method-call form
+ * of the free `applyFilterFromRequest` helper:
+ *
+ * ```ts
+ * const rows = await User.query()
+ *   .where('tenantId', tenant.id)
+ *   .applyFilterFromRequest(userFilter, ctx)
+ *   .orderBy('createdAt', 'desc')
+ *
+ * const page = await User.query().filterPaginate(userFilter, ctx)
+ * ```
+ *
+ * Register it in `adonisrc.ts` (`providers`). The free functions
+ * (`applyFilterFromRequest`, `applyCursorFromRequest`) work without it — this
+ * provider only adds the chainable sugar, so `@adonisjs/lucid` is loaded lazily
+ * here (not a hard dependency of the package).
+ */
+export default class FilterProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    boot(): Promise<void>;
+}
+//# sourceMappingURL=filter_provider.d.ts.map

package/dist/providers/filter_provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter_provider.d.ts","sourceRoot":"","sources":["../../providers/filter_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,OAAO,OAAO,cAAc;IACrB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAEvC,IAAI;CAIX"}

package/dist/providers/filter_provider.js

@@ -0,0 +1,33 @@
+import { registerFilterMacros } from '../src/lucid_macros.js';
+/**
+ * Wires `@adonis-agora/filter`'s chainable Lucid macros into the application.
+ *
+ * On boot it registers the `applyFilterFromRequest` and `filterPaginate` macros
+ * onto Lucid's `ModelQueryBuilder`, so any model query gains the method-call form
+ * of the free `applyFilterFromRequest` helper:
+ *
+ * ```ts
+ * const rows = await User.query()
+ *   .where('tenantId', tenant.id)
+ *   .applyFilterFromRequest(userFilter, ctx)
+ *   .orderBy('createdAt', 'desc')
+ *
+ * const page = await User.query().filterPaginate(userFilter, ctx)
+ * ```
+ *
+ * Register it in `adonisrc.ts` (`providers`). The free functions
+ * (`applyFilterFromRequest`, `applyCursorFromRequest`) work without it — this
+ * provider only adds the chainable sugar, so `@adonisjs/lucid` is loaded lazily
+ * here (not a hard dependency of the package).
+ */
+export default class FilterProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    async boot() {
+        const { ModelQueryBuilder } = await import('@adonisjs/lucid/orm');
+        registerFilterMacros(ModelQueryBuilder);
+    }
+}
+//# sourceMappingURL=filter_provider.js.map

package/dist/providers/filter_provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter_provider.js","sourceRoot":"","sources":["../../providers/filter_provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,OAAO,OAAO,cAAc;IACX;IAAtB,YAAsB,GAAuB;QAAvB,QAAG,GAAH,GAAG,CAAoB;IAAG,CAAC;IAEjD,KAAK,CAAC,IAAI;QACR,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QAClE,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/src/index.d.ts

@@ -12,6 +12,8 @@ export type { FilterClientEntry, FilterClientManifest, FilterFieldKind, FilterFi
 export type { DefineFilterOptions, FilterSpec, RelationColumns, RelationSpec, TenantResolver, TenantScopeSpec, } from './filter_spec.js';
 export { applyCursorFromRequest, applyFilterFromRequest } from './apply_from_request.js';
 export type { ApplyCursorFromRequestOptions, ApplyFromRequestOptions, FilterRequestContext, } from './apply_from_request.js';
+export { registerFilterMacros } from './lucid_macros.js';
+export type { MacroableQueryBuilder } from './lucid_macros.js';
 export { parseFilterRequest, parseSort, toColumnFilters } from './parse_request.js';
 export { parseSpatieRequest } from './spatie_parser.js';
 export type { SpatieInput } from './spatie_parser.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,YAAY,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,QAAQ,EACR,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACzF,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,YAAY,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,QAAQ,EACR,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACzF,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/index.js

@@ -7,6 +7,7 @@ export { escapeLike } from './escape-like.js';
 export { defineFilter, FilterDefinitionError, specToFilterConfig, } from './filter_spec.js';
 export { filterableFieldPaths, generateFilterClient, generateFilterClients, sortableFieldPaths, } from './generate_client.js';
 export { applyCursorFromRequest, applyFilterFromRequest } from './apply_from_request.js';
+export { registerFilterMacros } from './lucid_macros.js';
 export { parseFilterRequest, parseSort, toColumnFilters } from './parse_request.js';
 export { parseSpatieRequest } from './spatie_parser.js';
 export { applyCursor, applyFilter } from './runner.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAQ/B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAW9C,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAMzF,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,SAAS,EACT,qBAAqB,GAKtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE7F,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAQ/B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAW9C,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAMzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,SAAS,EACT,qBAAqB,GAKtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE7F,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/lucid_macros.d.ts

@@ -0,0 +1,56 @@
+import { type ApplyFromRequestOptions, type FilterRequestContext } from './apply_from_request.js';
+import type { FilterSpec } from './filter_spec.js';
+/**
+ * The static slice of a Lucid query-builder class we register onto: Adonis'
+ * `Macroable.macro(name, fn)` adds `fn` to the builder prototype so every query
+ * instance gains the method. Declared structurally so this module never
+ * hard-imports `@adonisjs/lucid` at runtime (the provider passes the real
+ * `ModelQueryBuilder` in) — matching how the rest of the package stays
+ * framework-free.
+ */
+export interface MacroableQueryBuilder {
+    macro(name: string, fn: (this: unknown, ...args: never[]) => unknown): void;
+}
+/**
+ * Register the chainable filter macros onto a Lucid query-builder class (the
+ * method-call form of {@link applyFilterFromRequest}). Call this from a provider's
+ * `boot()` with `ModelQueryBuilder` (from `@adonisjs/lucid/orm`); the
+ * `@adonis-agora/filter` provider does exactly that.
+ *
+ * Two macros are added:
+ *
+ * - `query.applyFilterFromRequest(spec, ctx, options?)` — applies the spec's
+ *   server scope + allow-listed filter/sort/search and returns the query so it
+ *   chains (`User.query().applyFilterFromRequest(spec, ctx).orderBy(...)`). The
+ *   resolved pagination is dropped; use `filterPaginate` (or the free function)
+ *   when you need it.
+ * - `query.filterPaginate(spec, ctx, options?)` — applies the same and then
+ *   `paginate(page, size)` with the resolved pagination, returning Lucid's
+ *   paginator (`await User.query().filterPaginate(spec, ctx)`).
+ *
+ * Idempotent enough to call once at boot; calling twice re-defines the macros to
+ * the same implementations.
+ */
+export declare function registerFilterMacros(ModelQueryBuilder: MacroableQueryBuilder): void;
+declare module '@adonisjs/lucid/types/model' {
+    interface ModelQueryBuilderContract<Model extends LucidModel, Result = InstanceType<Model>> {
+        /**
+         * Apply a {@link FilterSpec} from the request context (server scope +
+         * allow-listed filter/sort/search) and return the query for chaining — the
+         * method form of the free `applyFilterFromRequest`. Pagination is resolved
+         * but not returned here; use {@link filterPaginate} when you need it.
+         *
+         * `ctx` is optional: when omitted, the active `HttpContext` is read from
+         * AsyncLocalStorage (`HttpContext.getOrFail()`). Pass it explicitly outside a
+         * request scope (e.g. a job/command), where there is no ambient context.
+         */
+        applyFilterFromRequest(spec: FilterSpec, ctx?: FilterRequestContext, options?: ApplyFromRequestOptions): this;
+        /**
+         * Apply a {@link FilterSpec} from the request context and paginate with the
+         * resolved `{ page, size }`, returning Lucid's paginator — filter + paginate
+         * in one terminal call. `ctx` is optional (see {@link applyFilterFromRequest}).
+         */
+        filterPaginate(spec: FilterSpec, ctx?: FilterRequestContext, options?: ApplyFromRequestOptions): ReturnType<this['paginate']>;
+    }
+}
+//# sourceMappingURL=lucid_macros.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lucid_macros.d.ts","sourceRoot":"","sources":["../../src/lucid_macros.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAanD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CAC7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,qBAAqB,GAAG,IAAI,CAoBnF;AAED,OAAO,QAAQ,6BAA6B,CAAC;IAC3C,UAAU,yBAAyB,CAAC,KAAK,SAAS,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC;QACxF;;;;;;;;;WASG;QACH,sBAAsB,CACpB,IAAI,EAAE,UAAU,EAChB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,IAAI,CAAC;QACR;;;;WAIG;QACH,cAAc,CACZ,IAAI,EAAE,UAAU,EAChB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;KACjC;CACF"}

package/dist/src/lucid_macros.js

@@ -0,0 +1,42 @@
+import { HttpContext } from '@adonisjs/core/http';
+import { applyFilterFromRequest, } from './apply_from_request.js';
+/**
+ * O ctx da request para o macro: explícito, ou o `HttpContext` ativo lido do AsyncLocalStorage do
+ * Adonis quando omitido. `getOrFail()` lança quando não há request em escopo (ex.: chamada dentro de
+ * um job/command) — nesse caso passe o ctx explicitamente. Fica no macro (camada Adonis); o
+ * `applyFilterFromRequest` livre continua framework-agnostic, exigindo o ctx.
+ */
+function resolveCtx(ctx) {
+    return ctx ?? HttpContext.getOrFail();
+}
+/**
+ * Register the chainable filter macros onto a Lucid query-builder class (the
+ * method-call form of {@link applyFilterFromRequest}). Call this from a provider's
+ * `boot()` with `ModelQueryBuilder` (from `@adonisjs/lucid/orm`); the
+ * `@adonis-agora/filter` provider does exactly that.
+ *
+ * Two macros are added:
+ *
+ * - `query.applyFilterFromRequest(spec, ctx, options?)` — applies the spec's
+ *   server scope + allow-listed filter/sort/search and returns the query so it
+ *   chains (`User.query().applyFilterFromRequest(spec, ctx).orderBy(...)`). The
+ *   resolved pagination is dropped; use `filterPaginate` (or the free function)
+ *   when you need it.
+ * - `query.filterPaginate(spec, ctx, options?)` — applies the same and then
+ *   `paginate(page, size)` with the resolved pagination, returning Lucid's
+ *   paginator (`await User.query().filterPaginate(spec, ctx)`).
+ *
+ * Idempotent enough to call once at boot; calling twice re-defines the macros to
+ * the same implementations.
+ */
+export function registerFilterMacros(ModelQueryBuilder) {
+    ModelQueryBuilder.macro('applyFilterFromRequest', function (spec, ctx, options) {
+        applyFilterFromRequest(this, spec, resolveCtx(ctx), options);
+        return this;
+    });
+    ModelQueryBuilder.macro('filterPaginate', function (spec, ctx, options) {
+        const { page, size } = applyFilterFromRequest(this, spec, resolveCtx(ctx), options);
+        return this.paginate(page, size);
+    });
+}
+//# sourceMappingURL=lucid_macros.js.map

package/dist/src/lucid_macros.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid_macros.js","sourceRoot":"","sources":["../../src/lucid_macros.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAGL,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAIjC;;;;;GAKG;AACH,SAAS,UAAU,CAAC,GAAqC;IACvD,OAAO,GAAG,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;AACxC,CAAC;AAcD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,iBAAwC;IAC3E,iBAAiB,CAAC,KAAK,CAAC,wBAAwB,EAAE,UAEhD,IAAgB,EAChB,GAA0B,EAC1B,OAAiC;QAEjC,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAiD,CAAC,CAAC;IAEnD,iBAAiB,CAAC,KAAK,CAAC,gBAAgB,EAAE,UAExC,IAAgB,EAChB,GAA0B,EAC1B,OAAiC;QAEjC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QACpF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAiD,CAAC,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/filter",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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": {
@@ -27,6 +27,11 @@
       "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": [
@@ -36,11 +41,15 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@adonisjs/core": "^7.3.0"
+    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/lucid": "^22.0.0"
   },
   "peerDependenciesMeta": {
     "@adonisjs/core": {
       "optional": true
+    },
+    "@adonisjs/lucid": {
+      "optional": true
     }
   },
   "devDependencies": {