@eienjs/adonisjs-api-query 2.0.0 → 3.0.1

package/README.md

@@ -39,6 +39,144 @@ export default class MyController {
 }
 ```
 
+### 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/).

package/build/configure.d.ts

@@ -1,6 +1,2 @@
 import Configure from "@adonisjs/core/commands/configure";
-
-//#region configure.d.ts
-declare const configure: (command: Configure) => Promise<void>;
-//#endregion
-export { configure };
+export declare const configure: (command: Configure) => Promise<void>;

package/build/configure.js

@@ -1,5 +1,5 @@
 import { stubsRoot } from "./stubs/main.js";
-//#region configure.ts
+// configure.ts
 const configure = async (command) => {
 	const codemods = await command.createCodemods();
 	await codemods.updateRcFile((rcFile) => {
@@ -7,5 +7,4 @@ const configure = async (command) => {
 	});
 	await codemods.makeUsingStub(stubsRoot, "config.stub", {});
 };
-//#endregion
 export { configure };

package/build/index.d.ts

@@ -1,32 +1,38 @@
 import { configure } from "./configure.js";
-import { FilterOperator } from "./src/enums/filter_operator.js";
 import { AllowedFilter } from "./src/allowed_filter.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 { Filterable, filterable } from "./src/decorators/filterable.js";
 import { defineConfig } from "./src/define_config.js";
+import { FilterOperator } from "./src/enums/filter_operator.js";
 import { SortDirection } from "./src/enums/sort_direction.js";
 import { AllowedFieldsMustBeCalledBeforeAllowedIncludes } from "./src/exceptions/allowed_fields_must_be_called_before_allowed_includes.js";
-import { InvalidQuery } from "./src/exceptions/invalid_query.js";
+import { FilterableNotConfigured } from "./src/exceptions/filterable_not_configured.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 { InvalidQuery } from "./src/exceptions/invalid_query.js";
 import { InvalidSortQuery } from "./src/exceptions/invalid_sort_query.js";
 import { UnknownIncludedFieldsQuery } from "./src/exceptions/unknown_included_fields_query.js";
-import { FiltersExact } from "./src/filters/filters_exact.js";
-import { FiltersPartial } from "./src/filters/filters_partial.js";
+import { VineNotInstalledException } from "./src/exceptions/vine_not_installed.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 { FiltersExact } from "./src/filters/filters_exact.js";
 import { FiltersOperator } from "./src/filters/filters_operator.js";
+import { FiltersPartial } from "./src/filters/filters_partial.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 * 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 };
+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,32 +1,38 @@
-import { stubsRoot } from "./stubs/main.js";
 import { configure } from "./configure.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 { 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 { ApiQueryBuilderRequest } from "./src/api_query_builder_request.js";
+import { BaseFilterable } from "./src/base_filterable.js";
+import { Filterable, filterable } from "./src/decorators/filterable.js";
 import { defineConfig } from "./src/define_config.js";
+import { FilterOperator } from "./src/enums/filter_operator.js";
+import { SortDirection } from "./src/enums/sort_direction.js";
 import { AllowedFieldsMustBeCalledBeforeAllowedIncludes } from "./src/exceptions/allowed_fields_must_be_called_before_allowed_includes.js";
-import { InvalidQuery } from "./src/exceptions/invalid_query.js";
+import { FilterableNotConfigured } from "./src/exceptions/filterable_not_configured.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 { InvalidQuery } from "./src/exceptions/invalid_query.js";
 import { InvalidSortQuery } from "./src/exceptions/invalid_sort_query.js";
 import { UnknownIncludedFieldsQuery } from "./src/exceptions/unknown_included_fields_query.js";
-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 };
+import { VineNotInstalledException } from "./src/exceptions/vine_not_installed.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 { FiltersExact } from "./src/filters/filters_exact.js";
+import { FiltersOperator } from "./src/filters/filters_operator.js";
+import { FiltersPartial } from "./src/filters/filters_partial.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/providers/api_query_provider.d.ts

@@ -1,16 +1,14 @@
-import { ExtractKeys, HintedString, SortUnionKeyParams } from "../types.js";
 import { AllowedFilter } from "../src/allowed_filter.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 { Collection } from "collect.js";
+import { BaseFilterable } from "../src/base_filterable.js";
+import { ExtractKeys, FilterableConstructor, FilterableTarget, HintedString, SortUnionKeyParams } from "../types.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";
-
-//#region providers/api_query_provider.d.ts
-declare class ApiQueryProvider {
+export default class ApiQueryProvider {
   protected app: ApplicationService;
   constructor(app: ApplicationService);
   boot(): Promise<void>;
@@ -25,11 +23,19 @@ declare module '@adonisjs/lucid/orm' {
     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;
+    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 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;
@@ -38,9 +44,10 @@ declare module '@adonisjs/lucid/types/model' {
     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;
+    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>;
   }
-}
-//#endregion
-export { ApiQueryProvider as default };
+}

package/build/providers/api_query_provider.js

@@ -1,7 +1,7 @@
 import { RuntimeException } from "@adonisjs/core/exceptions";
+import { BaseModel, ModelQueryBuilder } from "@adonisjs/lucid/orm";
 import { configProvider } from "@adonisjs/core";
-import { ModelQueryBuilder } from "@adonisjs/lucid/orm";
-//#region providers/api_query_provider.ts
+// providers/api_query_provider.ts
 var ApiQueryProvider = class {
 	app;
 	constructor(app) {
@@ -12,14 +12,18 @@ var ApiQueryProvider = class {
 		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);
 	}
 };
-//#endregion
 export { ApiQueryProvider as default };

package/build/src/allowed_filter.d.ts

@@ -1,19 +1,20 @@
 import { FilterOperator } from "./enums/filter_operator.js";
-import { EnumType, ExtractKeys, Filter } from "../types.js";
-import { Collection } from "collect.js";
+import { EnumType, ExtractKeys, Filter, ScopeUnionKeyParams } from "../types.js";
 import { LucidModel, ModelAttributes, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
 import { StrictValuesWithoutRaw } from "@adonisjs/lucid/types/querybuilder";
-
-//#region src/allowed_filter.d.ts
-declare class AllowedFilter<Model extends LucidModel> {
+import { SchemaTypes } from "@vinejs/vine/types";
+export declare class AllowedFilter<Model extends LucidModel> {
   protected name: string;
   protected filterClass: Filter<Model>;
   protected internalName: string;
-  protected ignored: Collection<unknown>;
+  protected ignored: unknown[];
   protected default: unknown;
   protected $hasDefault: boolean;
   protected nullable: boolean;
-  constructor(name: string, filterClass: Filter<Model>, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>);
+  protected validationRule?: SchemaTypes;
+  constructor(name: string, filterClass: Filter<Model>, internalName?: string);
+  rule(rule: SchemaTypes): this;
+  getRule(): SchemaTypes | undefined;
   filter(query: ModelQueryBuilderContract<Model>, value: unknown): void;
   getFilterClass(): Filter<Model>;
   getName(): string;
@@ -28,14 +29,17 @@ declare class AllowedFilter<Model extends LucidModel> {
   unsetDefault(): this;
   protected resolveValueForFiltering(value: unknown): StrictValuesWithoutRaw | null;
   static setFilterArrayValueDelimiter(delimiter?: string): void;
+  /**
+   * Map of filter name to its Vine rule, for every allowed filter that declares one.
+   */
+  static extractRules(filters: readonly unknown[]): Record<string, SchemaTypes>;
   static exact<Model extends LucidModel>(name: string, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, shouldAddRelationConstraint?: boolean, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static partial<Model extends LucidModel>(name: string, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, shouldAddRelationConstraint?: boolean, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static beginsWithStrict<Model extends LucidModel>(name: string, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, shouldAddRelationConstraint?: boolean, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static endsWithStrict<Model extends LucidModel>(name: string, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, shouldAddRelationConstraint?: boolean, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static callback<Model extends LucidModel>(name: string, callback: (query: ModelQueryBuilderContract<Model>, value: unknown, property: string) => void, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static trashed<Model extends LucidModel>(name?: string, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>): AllowedFilter<Model>;
+  static scope<Model extends LucidModel = LucidModel>(name: string, internalName?: ScopeUnionKeyParams<Model>, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static custom<Model extends LucidModel>(name: string, filterClass: Filter<Model>, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, arrayValueDelimiter?: string): AllowedFilter<Model>;
   static operator<Model extends LucidModel>(name: string, filterOperator: EnumType<typeof FilterOperator>, boolean?: 'and' | 'or', internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>, shouldAddRelationConstraint?: boolean, arrayValueDelimiter?: string): AllowedFilter<Model>;
-}
-//#endregion
-export { AllowedFilter };
+}

package/build/src/allowed_filter.js

@@ -1,30 +1,37 @@
 import { ApiQueryBuilderRequest } from "./api_query_builder_request.js";
-import { FiltersExact } from "./filters/filters_exact.js";
-import { FiltersPartial } from "./filters/filters_partial.js";
 import { FiltersBeginWithStrict } from "./filters/filters_begin_with_strict.js";
 import { FiltersCallback } from "./filters/filters_callback.js";
 import { FiltersEndsWithStrict } from "./filters/filters_ends_with_strict.js";
+import { FiltersExact } from "./filters/filters_exact.js";
 import { FiltersOperator } from "./filters/filters_operator.js";
+import { FiltersPartial } from "./filters/filters_partial.js";
+import { FiltersScope } from "./filters/filters_scope.js";
 import { FiltersTrashed } from "./filters/filters_trashed.js";
-import { Collection } from "collect.js";
-//#region src/allowed_filter.ts
+// src/allowed_filter.ts
 var AllowedFilter = class AllowedFilter {
 	name;
 	filterClass;
 	internalName;
-	ignored;
+	ignored = [];
 	default;
 	$hasDefault = false;
 	nullable = false;
+	validationRule;
 	constructor(name, filterClass, internalName) {
 		this.name = name;
 		this.filterClass = filterClass;
-		this.ignored = new Collection();
 		this.internalName = internalName ?? this.name;
 	}
+	rule(rule) {
+		this.validationRule = rule;
+		return this;
+	}
+	getRule() {
+		return this.validationRule;
+	}
 	filter(query, value) {
 		const valueToFilter = this.resolveValueForFiltering(value);
-		if (!this.nullable && valueToFilter === null) return;
+		if (valueToFilter === null && !this.nullable) return;
 		this.filterClass.handle(query, valueToFilter, this.internalName);
 	}
 	getFilterClass() {
@@ -37,11 +44,11 @@ var AllowedFilter = class AllowedFilter {
 		return this.name === filterName;
 	}
 	ignore(...values) {
-		this.ignored = this.ignored.merge(values).flatten();
+		this.ignored.push(...values.flat(Infinity));
 		return this;
 	}
 	getIgnored() {
-		return this.ignored.toArray();
+		return this.ignored;
 	}
 	getInternalName() {
 		return this.internalName;
@@ -69,14 +76,26 @@ var AllowedFilter = class AllowedFilter {
 	}
 	resolveValueForFiltering(value) {
 		if (Array.isArray(value)) {
-			const remainingProperties = value.map((subValue) => this.resolveValueForFiltering(subValue));
+			const remainingProperties = value.map((subValue) => this.resolveValueForFiltering(subValue)).filter((subValue) => subValue !== null);
 			return remainingProperties.length === 0 ? null : remainingProperties;
 		}
-		return this.ignored.contains(value) ? null : value;
+		return this.ignored.includes(value) ? null : value;
 	}
 	static setFilterArrayValueDelimiter(delimiter) {
 		if (delimiter) ApiQueryBuilderRequest.setFilterArrayValueDelimiter(delimiter);
 	}
+	/**
+	* Map of filter name to its Vine rule, for every allowed filter that declares one.
+	*/
+	static extractRules(filters) {
+		const rules = {};
+		for (const filter of filters) {
+			if (!(filter instanceof this)) continue;
+			const rule = filter.getRule();
+			if (rule) rules[filter.getName()] = rule;
+		}
+		return rules;
+	}
 	static exact(name, internalName, shouldAddRelationConstraint = true, arrayValueDelimiter) {
 		this.setFilterArrayValueDelimiter(arrayValueDelimiter);
 		return new AllowedFilter(name, new FiltersExact(shouldAddRelationConstraint), internalName);
@@ -100,6 +119,10 @@ var AllowedFilter = class AllowedFilter {
 	static trashed(name = "trashed", internalName) {
 		return new AllowedFilter(name, new FiltersTrashed(), internalName);
 	}
+	static scope(name, internalName, arrayValueDelimiter) {
+		this.setFilterArrayValueDelimiter(arrayValueDelimiter);
+		return new AllowedFilter(name, new FiltersScope(), internalName);
+	}
 	static custom(name, filterClass, internalName, arrayValueDelimiter) {
 		this.setFilterArrayValueDelimiter(arrayValueDelimiter);
 		return new AllowedFilter(name, filterClass, internalName);
@@ -109,5 +132,4 @@ var AllowedFilter = class AllowedFilter {
 		return new AllowedFilter(name, new FiltersOperator(shouldAddRelationConstraint, filterOperator, boolean), internalName);
 	}
 };
-//#endregion
 export { AllowedFilter };

package/build/src/allowed_include.d.ts

@@ -1,10 +1,7 @@
 import { Include } from "../types.js";
-import { Collection } from "collect.js";
 import { LucidModel, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
 import { ModelRelations } from "@adonisjs/lucid/types/relations";
-
-//#region src/allowed_include.d.ts
-declare class AllowedInclude<Model extends LucidModel> {
+export declare class AllowedInclude<Model extends LucidModel> {
   protected internalName: string;
   protected name: string;
   protected includeClass: Include<Model>;
@@ -12,10 +9,8 @@ declare class AllowedInclude<Model extends LucidModel> {
   include(query: ModelQueryBuilderContract<Model>): void;
   getName(): string;
   isForInclude(includeName: string): boolean;
-  static relationship<ParentModel extends LucidModel>(name: string, internalName?: string): Collection<AllowedInclude<ParentModel>>;
-  static count<ParentModel extends LucidModel>(name: string, internalName?: string): Collection<AllowedInclude<ParentModel>>;
-  static callback<ParentModel extends LucidModel, RelatedModel extends LucidModel>(name: string, callback: (query: ModelRelations<RelatedModel, ParentModel>['builder'] | ModelRelations<RelatedModel, ParentModel>['subQuery']) => void, internalName?: string): Collection<AllowedInclude<ParentModel>>;
-  static custom<ParentModel extends LucidModel>(name: string, includeClass: Include<ParentModel>, internalName?: string): Collection<AllowedInclude<ParentModel>>;
-}
-//#endregion
-export { AllowedInclude };
+  static relationship<ParentModel extends LucidModel>(name: string, internalName?: string): AllowedInclude<ParentModel>[];
+  static count<ParentModel extends LucidModel>(name: string, internalName?: string): AllowedInclude<ParentModel>[];
+  static callback<ParentModel extends LucidModel, RelatedModel extends LucidModel>(name: string, callback: (query: ModelRelations<RelatedModel, ParentModel>['builder'] | ModelRelations<RelatedModel, ParentModel>['subQuery']) => void, internalName?: string): AllowedInclude<ParentModel>[];
+  static custom<ParentModel extends LucidModel>(name: string, includeClass: Include<ParentModel>, internalName?: string): AllowedInclude<ParentModel>[];
+}

package/build/src/allowed_include.js

@@ -1,9 +1,8 @@
 import { IncludedCallback } from "./includes/included_callback.js";
 import { IncludedCount } from "./includes/included_count.js";
 import { IncludedRelationship } from "./includes/included_relationship.js";
-import { Collection } from "collect.js";
 import app from "@adonisjs/core/services/app";
-//#region src/allowed_include.ts
+// src/allowed_include.ts
 var AllowedInclude = class AllowedInclude {
 	internalName;
 	name;
@@ -24,25 +23,25 @@ var AllowedInclude = class AllowedInclude {
 	}
 	static relationship(name, internalName) {
 		internalName ??= name;
-		return IncludedRelationship.getIndividualRelationshipPathsFromInclude(internalName).zip(IncludedRelationship.getIndividualRelationshipPathsFromInclude(name).toArray()).reduce((includes, args) => {
-			const [relationship, alias] = args;
-			includes = includes.push(new AllowedInclude(alias, new IncludedRelationship(), relationship));
-			if (!relationship.includes(".")) {
-				const countSuffix = app.config.get("apiquery.countSuffix", "Count");
-				for (const countAllowedInclude of this.count(`${alias}${countSuffix}`, `${relationship}${countSuffix}`)) includes = includes.push(countAllowedInclude);
-			}
-			return includes;
-		}, new Collection());
+		const relationships = IncludedRelationship.getIndividualRelationshipPathsFromInclude(internalName);
+		const aliases = IncludedRelationship.getIndividualRelationshipPathsFromInclude(name);
+		const countSuffix = app.config.get("apiquery.countSuffix", "Count");
+		const includes = [];
+		for (const [index, relationship] of relationships.entries()) {
+			const alias = aliases[index];
+			includes.push(new AllowedInclude(alias, new IncludedRelationship(), relationship));
+			if (!relationship.includes(".")) includes.push(...this.count(`${alias}${countSuffix}`, `${relationship}${countSuffix}`));
+		}
+		return includes;
 	}
 	static count(name, internalName) {
-		return new Collection([new AllowedInclude(name, new IncludedCount(), internalName)]);
+		return [new AllowedInclude(name, new IncludedCount(), internalName)];
 	}
 	static callback(name, callback, internalName) {
-		return new Collection([new AllowedInclude(name, new IncludedCallback(callback), internalName)]);
+		return [new AllowedInclude(name, new IncludedCallback(callback), internalName)];
 	}
 	static custom(name, includeClass, internalName) {
-		return new Collection([new AllowedInclude(name, includeClass, internalName)]);
+		return [new AllowedInclude(name, includeClass, internalName)];
 	}
 };
-//#endregion
 export { AllowedInclude };

package/build/src/allowed_sort.d.ts

@@ -1,8 +1,6 @@
 import { ExtractKeys, Sort } from "../types.js";
 import { LucidModel, ModelAttributes, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
-
-//#region src/allowed_sort.d.ts
-declare class AllowedSort<Model extends LucidModel> {
+export declare class AllowedSort<Model extends LucidModel> {
   protected defaultDirection: string;
   protected internalName: string;
   protected name: string;
@@ -17,6 +15,4 @@ declare class AllowedSort<Model extends LucidModel> {
   static field<Model extends LucidModel>(name: string, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>): AllowedSort<Model>;
   static custom<Model extends LucidModel>(name: string, sortClass: Sort<Model>, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>): AllowedSort<Model>;
   static callback<Model extends LucidModel>(name: string, callback: (query: ModelQueryBuilderContract<Model>, isDescending: boolean, property: string) => void, internalName?: ExtractKeys<ModelAttributes<InstanceType<Model>>>): AllowedSort<Model>;
-}
-//#endregion
-export { AllowedSort };
+}

package/build/src/allowed_sort.js

@@ -2,7 +2,7 @@ import { SortDirection } from "./enums/sort_direction.js";
 import { InvalidDirection } from "./exceptions/invalid_direction.js";
 import { SortsCallback } from "./sorts/sorts_callback.js";
 import { SortsField } from "./sorts/sorts_field.js";
-//#region src/allowed_sort.ts
+// src/allowed_sort.ts
 const REMOVE_HYPHEN_STARTING_IN_ANY_POSITION = /^-+/;
 var AllowedSort = class AllowedSort {
 	defaultDirection;
@@ -46,5 +46,4 @@ var AllowedSort = class AllowedSort {
 		return new AllowedSort(name, new SortsCallback(callback), internalName);
 	}
 };
-//#endregion
 export { AllowedSort };