@eienjs/adonisjs-api-query 1.1.1 → 3.0.0

package/{LICENSE.md → LICENSE}

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2025 - EienJS
+Copyright (c) 2025 - 2026 | EienJS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -7,12 +7,176 @@
 [![Build Status][badge-build]][build]
 [![Total Downloads][badge-downloads]][downloads]
 
-> Easily build Lucid queries from API requests
+> Easily build Lucid queries from API requests for your AdonisJS v7 application.
 
 ## Introduction
 
 This package provides a set of macros on `ModelQueryBuilder` to build [Lucid](https://adonisjs.com/docs/lucid) queries from API requests. Inspired by [Spatie's Laravel Query Builder](https://github.com/spatie/laravel-query-builder).
 
+## Quick Start
+
+Install the package using the following command:
+
+```sh
+node ace add @eienjs/adonisjs-api-query
+```
+
+Automatically the command will register the provider. Now you can use with your controller response:
+
+```typescript
+import type { HttpContext } from '@adonisjs/core/http';
+import User from '#models/user';
+
+// inside a controller
+export default class MyController {
+  public async handle({ request }: HttpContext) {
+    const users = await User.query()
+      .withRequest(request) // Pass the request to the query builder if async local storage is not enabled
+      .allowedFilters('name')
+      .allowedIncludes('posts')
+      .allowedSorts('id');
+  }
+}
+```
+
+### Using Filterable Classes
+
+Instead of configuring allowed filters, sorts, and includes directly in your controller, you can encapsulate them in a dedicated filterable class extending `BaseFilterable`:
+
+```typescript
+// app/filters/user_filterable.ts
+import { AllowedFilter, BaseFilterable } from '@eienjs/adonisjs-api-query';
+import User from '#models/user';
+
+export default class UserFilterable extends BaseFilterable.for(() => User) {
+  // Allowed filters: columns, AllowedFilter instances, or custom methods
+  public filters = [
+    'name',
+    'status',
+    AllowedFilter.exact('email'),
+  ];
+
+  // Allowed sorts and default sorts
+  public sorts = ['name', 'createdAt'];
+
+  public defaultSorts = '-createdAt';
+
+  // Allowed relationship includes
+  public includes = ['posts', 'profile'];
+
+  // Optional setup hook to customize/initialize the query builder
+  public setup(query) {
+    query.where('isActive', true);
+  }
+
+  // Custom filter method (auto-bound to 'status' filter)
+  public filterStatus(query, value: unknown) {
+    void query.where('status', value as string);
+  }
+}
+```
+
+Attach the filterable class to your Lucid Model using `static $filterable`, `@filterable` decorator, or `Filterable` mixin:
+
+```typescript
+// app/models/user.ts
+import { BaseModel } from '@adonisjs/lucid/orm';
+import UserFilterable from '#filters/user_filterable';
+
+export default class User extends BaseModel {
+  // Using a lazy thunk prevents circular dependency issues in ESM
+  public static $filterable = () => UserFilterable;
+}
+```
+
+Now you can run the filtered query in controllers using `User.$filter(request)`:
+
+```typescript
+// inside a controller
+export default class UsersController {
+  public async index({ request }: HttpContext) {
+    // Fluent query builder with filters, sorts, includes, and setup automatically applied
+    return await User.$filter(request).paginate(1, 15);
+  }
+}
+```
+
+You can also use it directly on existing queries via `query.filter(request)`, or query directly from the filterable class:
+
+```typescript
+// On an existing query builder instance
+const admins = await User.query().where('role', 'admin').filter(request);
+
+// With an explicit filterable class
+const special = await User.$filter(SpecialUserFilterable, request);
+
+// Or directly from the filterable class
+const users = await UserFilterable.$query(request);
+```
+
+### Request Validation with VineJS (Optional)
+
+You can validate incoming API query parameters (`filter`, `sort`, `include`, etc.) using `@vinejs/vine`. Validation is 100% optional: `@vinejs/vine` is declared as an optional peer dependency (`>=4.4.0`).
+
+#### 1. Defining Rules on a Filterable Class
+
+Declare explicit validation rules using VineJS on your filterable class. You can pass a literal plain object, a `vine.object(...)`, or a compiled `vine.create(...)` directly to `rules`:
+
+```typescript
+import { AllowedFilter, BaseFilterable } from '@eienjs/adonisjs-api-query';
+import vine from '@vinejs/vine';
+import User from '#models/user';
+
+export default class UserFilterable extends BaseFilterable.for(() => User) {
+  public filters = [
+    'name',
+    'status',
+    AllowedFilter.exact('createdAt').rule(vine.date()),
+    AllowedFilter.exact('age').rule(vine.number().min(18)),
+  ];
+
+  public sorts = ['name', 'createdAt'];
+
+  // You can define rules as a literal object, vine.object(), or vine.create():
+  public rules = vine.object({
+    filter: vine.object({
+      name: vine.string().minLength(3).optional(),
+      status: vine.enum(['active', 'inactive']).optional(),
+    }).optional(),
+    sort: vine.string().optional(),
+    include: vine.string().optional(),
+  });
+}
+```
+
+#### 2. Automatic & Explicit Validation
+
+- **Automatic validation during query execution**: When `rules` or `validator` are defined on a filterable class (or on `AllowedFilter.rule(...)`), the query builder automatically executes validation with VineJS before querying the database. If validation fails, it throws a native `ValidationError` (`errors.E_VALIDATION_ERROR`), which AdonisJS automatically transforms into HTTP 422 Unprocessable Entity:
+  ```typescript
+  // Automatically validates before hitting the database:
+  const users = await User.$filter(request).paginate(1, 15);
+  ```
+
+- **Explicit validation & Controller usage**:
+  Validation resides directly inside `ApiQueryBuilderRequest` as the central core of the package:
+  ```typescript
+  // Validate request explicitly via filterable:
+  const payload = await UserFilterable.validate(request);
+
+  // Validate and get the query builder:
+  const users = await UserFilterable.$validateAndQuery(request);
+
+  // Or validate directly via ApiQueryBuilderRequest in controllers:
+  const apiRequest = new ApiQueryBuilderRequest(request);
+  const validated = await apiRequest.validate({
+    filter: vine.object({ name: vine.string() }).optional(),
+    sort: vine.string().optional(),
+  });
+  ```
+
+- **Disabling automatic validation**:
+  You can disable automatic validation per-filterable with `public autoValidate = false;` or globally in `config/apiquery.ts` with `autoValidate: false`.
+
 ## Documentation
 
 The documentation is available on [EienJS](https://eienjs.com/packages/adonisjs-api-query/getting-started/).
@@ -30,7 +194,7 @@ The `@eienjs/adonisjs-api-query` library is licensed for use under the MIT Licen
 [source]: https://github.com/eienjs/adonisjs-api-query
 [node-version]: https://www.npmjs.com/package/@eienjs/adonisjs-api-query
 [release]: https://www.npmjs.com/package/@eienjs/adonisjs-api-query
-[license]: https://github.com/eienjs/adonisjs-api-query/blob/main/LICENSE.md
+[license]: https://github.com/eienjs/adonisjs-api-query/blob/main/LICENSE
 [build]: https://github.com/eienjs/adonisjs-api-query/actions/workflows/build.yml?query=branch:main
 [downloads]: https://www.npmjs.com/package/@eienjs/adonisjs-api-query
 [badge-source]: https://img.shields.io/badge/source-eienjs/adonisjs--api--query-blue.svg?logo=github

package/build/configure.d.ts

@@ -1,2 +1,2 @@
-import type Configure from '@adonisjs/core/commands/configure';
-export declare const configure: (command: Configure) => Promise<void>;
+import Configure from "@adonisjs/core/commands/configure";
+export declare const configure: (command: Configure) => Promise<void>;

package/build/configure.js

@@ -0,0 +1,10 @@
+import { stubsRoot } from "./stubs/main.js";
+// configure.ts
+const configure = async (command) => {
+	const codemods = await command.createCodemods();
+	await codemods.updateRcFile((rcFile) => {
+		rcFile.addProvider("@eienjs/adonisjs-api-query/providers/api_query_provider");
+	});
+	await codemods.makeUsingStub(stubsRoot, "config.stub", {});
+};
+export { configure };

package/build/index.d.ts

@@ -1,31 +1,38 @@
-export { configure } from './configure.js';
-export { AllowedFilter } from './src/allowed_filter.js';
-export { AllowedInclude } from './src/allowed_include.js';
-export { AllowedSort } from './src/allowed_sort.js';
-export { ApiQueryBuilderRequest } from './src/api_query_builder_request.js';
-export { defineConfig } from './src/define_config.js';
-export { FilterOperator } from './src/enums/filter_operator.js';
-export { SortDirection } from './src/enums/sort_direction.js';
-export { AllowedFieldsMustBeCalledBeforeAllowedIncludes } from './src/exceptions/allowed_fields_must_be_called_before_allowed_includes.js';
-export { InvalidAppendQuery } from './src/exceptions/invalid_append_query.js';
-export { InvalidDirection } from './src/exceptions/invalid_direction.js';
-export { InvalidFilterQuery } from './src/exceptions/invalid_filter_query.js';
-export { InvalidFilterValue } from './src/exceptions/invalid_filter_value.js';
-export { InvalidIncludeQuery } from './src/exceptions/invalid_include_query.js';
-export { InvalidQuery } from './src/exceptions/invalid_query.js';
-export { InvalidSortQuery } from './src/exceptions/invalid_sort_query.js';
-export { UnknownIncludedFieldsQuery } from './src/exceptions/unknown_included_fields_query.js';
-export { stubsRoot } from './stubs/main.js';
-export * from 'collect.js';
-export { FiltersBeginWithStrict } from './src/filters/filters_begin_with_strict.js';
-export { FiltersCallback } from './src/filters/filters_callback.js';
-export { FiltersEndsWithStrict } from './src/filters/filters_ends_with_strict.js';
-export { FiltersExact } from './src/filters/filters_exact.js';
-export { FiltersOperator } from './src/filters/filters_operator.js';
-export { FiltersPartial } from './src/filters/filters_partial.js';
-export { FiltersTrashed } from './src/filters/filters_trashed.js';
-export { IncludedCallback } from './src/includes/included_callback.js';
-export { IncludedCount } from './src/includes/included_count.js';
-export { IncludedRelationship } from './src/includes/included_relationship.js';
-export { SortsCallback } from './src/sorts/sorts_callback.js';
-export { SortsField } from './src/sorts/sorts_field.js';
+import { configure } from "./configure.js";
+import { FilterOperator } from "./src/enums/filter_operator.js";
+import { AllowedInclude } from "./src/allowed_include.js";
+import { AllowedSort } from "./src/allowed_sort.js";
+import { ApiQueryBuilderRequest } from "./src/api_query_builder_request.js";
+import { BaseFilterable } from "./src/base_filterable.js";
+import { AllowedFilter } from "./src/allowed_filter.js";
+import { Filterable, filterable } from "./src/decorators/filterable.js";
+import { defineConfig } from "./src/define_config.js";
+import { SortDirection } from "./src/enums/sort_direction.js";
+import { AllowedFieldsMustBeCalledBeforeAllowedIncludes } from "./src/exceptions/allowed_fields_must_be_called_before_allowed_includes.js";
+import { FilterableNotConfigured } from "./src/exceptions/filterable_not_configured.js";
+import { InvalidQuery } from "./src/exceptions/invalid_query.js";
+import { InvalidAppendQuery } from "./src/exceptions/invalid_append_query.js";
+import { InvalidDirection } from "./src/exceptions/invalid_direction.js";
+import { InvalidFieldQuery } from "./src/exceptions/invalid_field_query.js";
+import { InvalidFilterQuery } from "./src/exceptions/invalid_filter_query.js";
+import { InvalidFilterValue } from "./src/exceptions/invalid_filter_value.js";
+import { InvalidIncludeQuery } from "./src/exceptions/invalid_include_query.js";
+import { InvalidSortQuery } from "./src/exceptions/invalid_sort_query.js";
+import { UnknownIncludedFieldsQuery } from "./src/exceptions/unknown_included_fields_query.js";
+import { VineNotInstalledException } from "./src/exceptions/vine_not_installed.js";
+import { FiltersExact } from "./src/filters/filters_exact.js";
+import { FiltersPartial } from "./src/filters/filters_partial.js";
+import { FiltersBeginWithStrict } from "./src/filters/filters_begin_with_strict.js";
+import { FiltersCallback } from "./src/filters/filters_callback.js";
+import { FiltersEndsWithStrict } from "./src/filters/filters_ends_with_strict.js";
+import { FiltersOperator } from "./src/filters/filters_operator.js";
+import { FiltersScope } from "./src/filters/filters_scope.js";
+import { FiltersTrashed } from "./src/filters/filters_trashed.js";
+import { IncludedCallback } from "./src/includes/included_callback.js";
+import { IncludedCount } from "./src/includes/included_count.js";
+import { IncludedRelationship } from "./src/includes/included_relationship.js";
+import { SortsCallback } from "./src/sorts/sorts_callback.js";
+import { SortsField } from "./src/sorts/sorts_field.js";
+import { buildQueryValidator } from "./src/validation/schema_builder.js";
+import { stubsRoot } from "./stubs/main.js";
+export { AllowedFieldsMustBeCalledBeforeAllowedIncludes, AllowedFilter, AllowedInclude, AllowedSort, ApiQueryBuilderRequest, BaseFilterable, FilterOperator, Filterable, FilterableNotConfigured, FiltersBeginWithStrict, FiltersCallback, FiltersEndsWithStrict, FiltersExact, FiltersOperator, FiltersPartial, FiltersScope, FiltersTrashed, IncludedCallback, IncludedCount, IncludedRelationship, InvalidAppendQuery, InvalidDirection, InvalidFieldQuery, InvalidFilterQuery, InvalidFilterValue, InvalidIncludeQuery, InvalidQuery, InvalidSortQuery, SortDirection, SortsCallback, SortsField, UnknownIncludedFieldsQuery, VineNotInstalledException, buildQueryValidator, configure, defineConfig, filterable, stubsRoot };

package/build/index.js

@@ -1,154 +1,38 @@
-import {
-  AllowedSort,
-  InvalidDirection,
-  InvalidSortQuery,
-  SortDirection,
-  SortsCallback,
-  SortsField
-} from "./chunk-3ITWUZL5.js";
-import {
-  AllowedFilter,
-  FilterOperator,
-  FiltersBeginWithStrict,
-  FiltersCallback,
-  FiltersEndsWithStrict,
-  FiltersExact,
-  FiltersOperator,
-  FiltersPartial,
-  FiltersTrashed,
-  InvalidFilterQuery
-} from "./chunk-54HNQTDY.js";
-import {
-  ApiQueryBuilderRequest
-} from "./chunk-MKQ3HMMA.js";
-import {
-  AllowedInclude,
-  IncludedCallback,
-  IncludedCount,
-  IncludedRelationship,
-  InvalidIncludeQuery
-} from "./chunk-IV3B5WO7.js";
-import {
-  InvalidQuery
-} from "./chunk-XIRHVLVQ.js";
-
-// stubs/main.ts
-import path from "path";
-import { fileURLToPath } from "url";
-var stubsRoot = path.dirname(fileURLToPath(import.meta.url));
-
-// configure.ts
-var configure = async (command) => {
-  const codemods = await command.createCodemods();
-  await codemods.updateRcFile((rcFile) => {
-    rcFile.addProvider("@eienjs/adonisjs-api-query/api_query_provider");
-  });
-  await codemods.makeUsingStub(stubsRoot, "config.stub", {});
-};
-
-// src/define_config.ts
-import { configProvider } from "@adonisjs/core";
-var defineConfig = function(config) {
-  return configProvider.create(async (_) => {
-    return {
-      parameters: {
-        include: config.parameters?.include ?? "include",
-        filter: config.parameters?.filter ?? "filter",
-        sort: config.parameters?.sort ?? "sort",
-        fields: config.parameters?.fields ?? "fields",
-        append: config.parameters?.append ?? "append"
-      },
-      countSuffix: config.countSuffix ?? "Count",
-      existsSuffix: config.existsSuffix ?? "Exists",
-      disableInvalidFilterQueryException: config.disableInvalidFilterQueryException ?? false,
-      disableInvalidSortQueryException: config.disableInvalidSortQueryException ?? false,
-      disableInvalidIncludesQueryException: config.disableInvalidIncludesQueryException ?? false,
-      convertRelationNamesToSnakeCasePlural: config.convertRelationNamesToSnakeCasePlural ?? false,
-      convertRelationTableNameStrategy: config.convertRelationTableNameStrategy ?? false,
-      convertFieldNamesToSnakeCase: config.convertFieldNamesToSnakeCase ?? false
-    };
-  });
-};
-
-// src/exceptions/allowed_fields_must_be_called_before_allowed_includes.ts
-import { Exception } from "@adonisjs/core/exceptions";
-var AllowedFieldsMustBeCalledBeforeAllowedIncludes = class extends Exception {
-  static code;
-  static status;
-  constructor() {
-    super("The QueryBuilder's `allowedFields` method must be called before the `allowedIncludes` method");
-  }
-};
-
-// src/exceptions/invalid_append_query.ts
-import { ResponseStatus } from "@adonisjs/core/http";
-var InvalidAppendQuery = class _InvalidAppendQuery extends InvalidQuery {
-  constructor(appendsNotAllowed, allowedAppends) {
-    const notAllowed = appendsNotAllowed.join(", ");
-    const allowed = allowedAppends.join(", ");
-    const message = `Requested append(s) \`${notAllowed}\` are not allowed. Allowed append(s) are \`${allowed}\``;
-    super(message, { status: ResponseStatus.BadRequest });
-  }
-  static appendsNotAllowed(appendsNotAllowed, allowedAppends) {
-    return new _InvalidAppendQuery(appendsNotAllowed, allowedAppends);
-  }
-};
-
-// src/exceptions/invalid_filter_value.ts
-import { Exception as Exception2 } from "@adonisjs/core/exceptions";
-var InvalidFilterValue = class _InvalidFilterValue extends Exception2 {
-  static make(value) {
-    return new _InvalidFilterValue(`Filter value \`${value}\` is invalid`);
-  }
-};
-
-// src/exceptions/unknown_included_fields_query.ts
-import { ResponseStatus as ResponseStatus2 } from "@adonisjs/core/http";
-var UnknownIncludedFieldsQuery = class extends InvalidQuery {
-  unknownFields;
-  constructor(unknownFields) {
-    const notAllowed = unknownFields.join(", ");
-    const message = [
-      `Requested field(s) \`${notAllowed}\` are not allowed (yet). `,
-      "If you want to allow these fields, please make sure to call the QueryBuilder's `allowedFields` method before the `allowedIncludes` method"
-    ].join("");
-    super(message, { status: ResponseStatus2.BadRequest });
-    this.unknownFields = unknownFields;
-  }
-};
-
-// index.ts
-export * from "collect.js";
-export {
-  AllowedFieldsMustBeCalledBeforeAllowedIncludes,
-  AllowedFilter,
-  AllowedInclude,
-  AllowedSort,
-  ApiQueryBuilderRequest,
-  FilterOperator,
-  FiltersBeginWithStrict,
-  FiltersCallback,
-  FiltersEndsWithStrict,
-  FiltersExact,
-  FiltersOperator,
-  FiltersPartial,
-  FiltersTrashed,
-  IncludedCallback,
-  IncludedCount,
-  IncludedRelationship,
-  InvalidAppendQuery,
-  InvalidDirection,
-  InvalidFilterQuery,
-  InvalidFilterValue,
-  InvalidIncludeQuery,
-  InvalidQuery,
-  InvalidSortQuery,
-  SortDirection,
-  SortsCallback,
-  SortsField,
-  UnknownIncludedFieldsQuery,
-  configure,
-  defineConfig,
-  stubsRoot
-};
-//# sourceMappingURL=index.js.map
+import { stubsRoot } from "./stubs/main.js";
+import { configure } from "./configure.js";
+import { VineNotInstalledException } from "./src/exceptions/vine_not_installed.js";
+import { buildQueryValidator } from "./src/validation/schema_builder.js";
+import { ApiQueryBuilderRequest } from "./src/api_query_builder_request.js";
+import { FiltersExact } from "./src/filters/filters_exact.js";
+import { FiltersPartial } from "./src/filters/filters_partial.js";
+import { FiltersBeginWithStrict } from "./src/filters/filters_begin_with_strict.js";
+import { FiltersCallback } from "./src/filters/filters_callback.js";
+import { FiltersEndsWithStrict } from "./src/filters/filters_ends_with_strict.js";
+import { FilterOperator } from "./src/enums/filter_operator.js";
+import { FiltersOperator } from "./src/filters/filters_operator.js";
+import { FiltersScope } from "./src/filters/filters_scope.js";
+import { FiltersTrashed } from "./src/filters/filters_trashed.js";
+import { AllowedFilter } from "./src/allowed_filter.js";
+import { IncludedCallback } from "./src/includes/included_callback.js";
+import { IncludedCount } from "./src/includes/included_count.js";
+import { IncludedRelationship } from "./src/includes/included_relationship.js";
+import { AllowedInclude } from "./src/allowed_include.js";
+import { SortDirection } from "./src/enums/sort_direction.js";
+import { InvalidDirection } from "./src/exceptions/invalid_direction.js";
+import { SortsCallback } from "./src/sorts/sorts_callback.js";
+import { SortsField } from "./src/sorts/sorts_field.js";
+import { AllowedSort } from "./src/allowed_sort.js";
+import { BaseFilterable } from "./src/base_filterable.js";
+import { Filterable, filterable } from "./src/decorators/filterable.js";
+import { defineConfig } from "./src/define_config.js";
+import { AllowedFieldsMustBeCalledBeforeAllowedIncludes } from "./src/exceptions/allowed_fields_must_be_called_before_allowed_includes.js";
+import { FilterableNotConfigured } from "./src/exceptions/filterable_not_configured.js";
+import { InvalidQuery } from "./src/exceptions/invalid_query.js";
+import { InvalidAppendQuery } from "./src/exceptions/invalid_append_query.js";
+import { InvalidFieldQuery } from "./src/exceptions/invalid_field_query.js";
+import { InvalidFilterQuery } from "./src/exceptions/invalid_filter_query.js";
+import { InvalidFilterValue } from "./src/exceptions/invalid_filter_value.js";
+import { InvalidIncludeQuery } from "./src/exceptions/invalid_include_query.js";
+import { InvalidSortQuery } from "./src/exceptions/invalid_sort_query.js";
+import { UnknownIncludedFieldsQuery } from "./src/exceptions/unknown_included_fields_query.js";
+export { AllowedFieldsMustBeCalledBeforeAllowedIncludes, AllowedFilter, AllowedInclude, AllowedSort, ApiQueryBuilderRequest, BaseFilterable, FilterOperator, Filterable, FilterableNotConfigured, FiltersBeginWithStrict, FiltersCallback, FiltersEndsWithStrict, FiltersExact, FiltersOperator, FiltersPartial, FiltersScope, FiltersTrashed, IncludedCallback, IncludedCount, IncludedRelationship, InvalidAppendQuery, InvalidDirection, InvalidFieldQuery, InvalidFilterQuery, InvalidFilterValue, InvalidIncludeQuery, InvalidQuery, InvalidSortQuery, SortDirection, SortsCallback, SortsField, UnknownIncludedFieldsQuery, VineNotInstalledException, buildQueryValidator, configure, defineConfig, filterable, stubsRoot };

package/build/providers/api_query_provider.d.ts

@@ -1,42 +1,53 @@
-import { type Request } from '@adonisjs/core/http';
-import { type ApplicationService } from '@adonisjs/core/types';
-import { type LucidModel } from '@adonisjs/lucid/types/model';
-import { type ExtractModelRelations } from '@adonisjs/lucid/types/relations';
-import { type Collection } from 'collect.js';
-import { type AllowedFilter } from '../src/allowed_filter.js';
-import { type AllowedInclude } from '../src/allowed_include.js';
-import { type AllowedSort } from '../src/allowed_sort.js';
-import { type ApiQueryBuilderRequest } from '../src/api_query_builder_request.js';
-import { type ExtractKeys, type HintedString, type SortUnionKeyParams } from '../src/types.js';
+import { AllowedInclude } from "../src/allowed_include.js";
+import { AllowedSort } from "../src/allowed_sort.js";
+import { ApiQueryBuilderRequest } from "../src/api_query_builder_request.js";
+import { BaseFilterable } from "../src/base_filterable.js";
+import { ExtractKeys, FilterableConstructor, FilterableTarget, HintedString, SortUnionKeyParams } from "../types.js";
+import { AllowedFilter } from "../src/allowed_filter.js";
+import { HttpRequest } from "@adonisjs/core/http";
+import { LucidModel } from "@adonisjs/lucid/types/model";
+import { ExtractModelRelations } from "@adonisjs/lucid/types/relations";
+import { ApplicationService } from "@adonisjs/core/types";
 export default class ApiQueryProvider {
-    protected app: ApplicationService;
-    constructor(app: ApplicationService);
-    boot(): Promise<void>;
+  protected app: ApplicationService;
+  constructor(app: ApplicationService);
+  boot(): Promise<void>;
 }
 declare module '@adonisjs/lucid/orm' {
-    interface ModelQueryBuilder {
-        withRequest(request: Request): this;
-        $apiQueryBuilderRequest: ApiQueryBuilderRequest;
-        allowedSorts(...sorts: (AllowedSort<LucidModel> | string)[]): this;
-        allowedSorts(sorts: (AllowedSort<LucidModel> | string)[]): this;
-        defaultSort(...sorts: (AllowedSort<LucidModel> | string)[]): this;
-        defaultSort(sorts: (AllowedSort<LucidModel> | string)[]): this;
-        allowedFilters(...filters: (AllowedFilter<LucidModel> | string)[]): this;
-        allowedFilters(filters: (AllowedFilter<LucidModel> | string)[]): this;
-        allowedIncludes(...includes: (Collection<AllowedInclude<LucidModel>> | string)[]): this;
-        allowedIncludes(includes: (Collection<AllowedInclude<LucidModel>> | string)[]): this;
-    }
+  interface ModelQueryBuilder {
+    withRequest(request: HttpRequest): this;
+    $apiQueryBuilderRequest: ApiQueryBuilderRequest;
+    allowedSorts(...sorts: (AllowedSort<LucidModel> | string)[]): this;
+    allowedSorts(sorts: (AllowedSort<LucidModel> | string)[]): this;
+    defaultSort(...sorts: (AllowedSort<LucidModel> | string)[]): this;
+    defaultSort(sorts: (AllowedSort<LucidModel> | string)[]): this;
+    allowedFilters(...filters: (AllowedFilter<LucidModel> | string)[]): this;
+    allowedFilters(filters: (AllowedFilter<LucidModel> | string)[]): this;
+    allowedIncludes(...includes: (AllowedInclude<LucidModel> | AllowedInclude<LucidModel>[] | string)[]): this;
+    allowedIncludes(includes: (AllowedInclude<LucidModel> | AllowedInclude<LucidModel>[] | string)[]): this;
+    filter(request?: HttpRequest | ApiQueryBuilderRequest): this;
+    filter(filterable: FilterableConstructor | BaseFilterable, request?: HttpRequest | ApiQueryBuilderRequest): this;
+    validate(): Promise<unknown>;
+  }
 }
 declare module '@adonisjs/lucid/types/model' {
-    interface ModelQueryBuilderContract<Model extends LucidModel, Result = InstanceType<Model>> {
-        withRequest(request: Request): this;
-        allowedSorts(...sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
-        allowedSorts(sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
-        defaultSort(...sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
-        defaultSort(sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
-        allowedFilters(...filters: (AllowedFilter<Model> | HintedString<ExtractKeys<ModelAttributes<InstanceType<Model>>>>)[]): this;
-        allowedFilters(filters: (AllowedFilter<Model> | HintedString<ExtractKeys<ModelAttributes<InstanceType<Model>>>>)[]): this;
-        allowedIncludes(...includes: (Collection<AllowedInclude<Model>> | HintedString<ExtractModelRelations<InstanceType<Model>>>)[]): this;
-        allowedIncludes(includes: (Collection<AllowedInclude<Model>> | HintedString<ExtractModelRelations<InstanceType<Model>>>)[]): this;
-    }
-}
+  interface LucidModel {
+    $filterable?: FilterableTarget;
+    $filter<Model extends LucidModel>(this: Model, request?: HttpRequest | ApiQueryBuilderRequest): ModelQueryBuilderContract<Model, InstanceType<Model>>;
+    $filter<Model extends LucidModel>(this: Model, filterable: FilterableConstructor<Model> | BaseFilterable<Model>, request?: HttpRequest | ApiQueryBuilderRequest): ModelQueryBuilderContract<Model, InstanceType<Model>>;
+  }
+  interface ModelQueryBuilderContract<Model extends LucidModel, Result = InstanceType<Model>> {
+    withRequest(request: HttpRequest): this;
+    allowedSorts(...sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
+    allowedSorts(sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
+    defaultSort(...sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
+    defaultSort(sorts: (AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>>)[]): this;
+    allowedFilters(...filters: (AllowedFilter<Model> | HintedString<ExtractKeys<ModelAttributes<InstanceType<Model>>>>)[]): this;
+    allowedFilters(filters: (AllowedFilter<Model> | HintedString<ExtractKeys<ModelAttributes<InstanceType<Model>>>>)[]): this;
+    allowedIncludes(...includes: (AllowedInclude<Model> | AllowedInclude<Model>[] | HintedString<ExtractModelRelations<InstanceType<Model>>>)[]): this;
+    allowedIncludes(includes: (AllowedInclude<Model> | AllowedInclude<Model>[] | HintedString<ExtractModelRelations<InstanceType<Model>>>)[]): this;
+    filter(request?: HttpRequest | ApiQueryBuilderRequest): this;
+    filter(filterable: FilterableConstructor<Model> | BaseFilterable<Model>, request?: HttpRequest | ApiQueryBuilderRequest): this;
+    validate(): Promise<unknown>;
+  }
+}

package/build/providers/api_query_provider.js

@@ -1,30 +1,29 @@
-// providers/api_query_provider.ts
-import { configProvider } from "@adonisjs/core";
 import { RuntimeException } from "@adonisjs/core/exceptions";
-import { ModelQueryBuilder } from "@adonisjs/lucid/orm";
+import { BaseModel, ModelQueryBuilder } from "@adonisjs/lucid/orm";
+import { configProvider } from "@adonisjs/core";
+// providers/api_query_provider.ts
 var ApiQueryProvider = class {
-  constructor(app) {
-    this.app = app;
-  }
-  async boot() {
-    const { extendModelQueryBuilderWithRequest } = await import("../api_query_request-QXOB4BN6.js");
-    const { extendModelQueryBuilderWithSortsQuery } = await import("../sorts_query-NJTC5UXX.js");
-    const { extendModelQueryBuilderWithFiltersQuery } = await import("../filters_query-LCFH2F2X.js");
-    const { extendModelQueryBuilderWithIncludesQuery } = await import("../includes_query-PVONWQMC.js");
-    const apiQueryConfigProvider = this.app.config.get("apiquery");
-    const config = await configProvider.resolve(this.app, apiQueryConfigProvider);
-    if (!config) {
-      throw new RuntimeException(
-        'Invalid "config/apiquery.ts" file. Make sure you are using the "defineConfig" method'
-      );
-    }
-    extendModelQueryBuilderWithRequest(ModelQueryBuilder);
-    extendModelQueryBuilderWithSortsQuery(ModelQueryBuilder, config);
-    extendModelQueryBuilderWithFiltersQuery(ModelQueryBuilder, config);
-    extendModelQueryBuilderWithIncludesQuery(ModelQueryBuilder, config);
-  }
-};
-export {
-  ApiQueryProvider as default
+	app;
+	constructor(app) {
+		this.app = app;
+	}
+	async boot() {
+		const { extendModelQueryBuilderWithRequest } = await import("../src/bindings/api_query_request.js");
+		const { extendModelQueryBuilderWithSortsQuery } = await import("../src/bindings/sorts_query.js");
+		const { extendModelQueryBuilderWithFiltersQuery } = await import("../src/bindings/filters_query.js");
+		const { extendModelQueryBuilderWithIncludesQuery } = await import("../src/bindings/includes_query.js");
+		const { extendLucidWithFilterable } = await import("../src/bindings/filterable_query.js");
+		const { extendModelQueryBuilderWithValidation } = await import("../src/bindings/validation_query.js");
+		const apiQueryConfigProvider = this.app.config.get("apiquery");
+		const config = await configProvider.resolve(this.app, apiQueryConfigProvider);
+		if (!config) throw new RuntimeException("Invalid \"config/apiquery.ts\" file. Make sure you are using the \"defineConfig\" method");
+		this.app.config.set("apiquery", config);
+		extendModelQueryBuilderWithRequest(ModelQueryBuilder);
+		extendModelQueryBuilderWithSortsQuery(ModelQueryBuilder, config);
+		extendModelQueryBuilderWithFiltersQuery(ModelQueryBuilder, config);
+		extendModelQueryBuilderWithIncludesQuery(ModelQueryBuilder, config);
+		extendLucidWithFilterable(BaseModel, ModelQueryBuilder);
+		extendModelQueryBuilderWithValidation(ModelQueryBuilder);
+	}
 };
-//# sourceMappingURL=api_query_provider.js.map
+export { ApiQueryProvider as default };