@eienjs/adonisjs-api-query 1.1.1 → 3.0.0

package/build/src/api_query_builder_request.js

@@ -0,0 +1,200 @@
+import { strAfterLast, strBeforeLast } from "./utils/helpers.js";
+import { buildQueryValidator } from "./validation/schema_builder.js";
+import { HttpContext } from "@adonisjs/core/http";
+import app from "@adonisjs/core/services/app";
+// src/api_query_builder_request.ts
+const UNSAFE_OBJECT_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+var ApiQueryBuilderRequest = class ApiQueryBuilderRequest {
+	static includesArrayValueDelimiter = ",";
+	static appendsArrayValueDelimiter = ",";
+	static fieldsArrayValueDelimiter = ",";
+	static sortsArrayValueDelimiter = ",";
+	static filterArrayValueDelimiter = ",";
+	_request;
+	_rules;
+	_filterRules = {};
+	_autoValidate;
+	_validation;
+	_validatedData;
+	constructor(request) {
+		this._request = request ?? HttpContext.getOrFail().request;
+	}
+	getRequest() {
+		return this._request;
+	}
+	all() {
+		return this._request.all();
+	}
+	setRules(rules) {
+		this._rules = rules;
+		return this;
+	}
+	getRules() {
+		return this._rules;
+	}
+	setFilterRules(rules) {
+		this._filterRules = rules;
+		return this;
+	}
+	getFilterRules() {
+		return this._filterRules;
+	}
+	setAutoValidate(autoValidate) {
+		this._autoValidate = autoValidate;
+		return this;
+	}
+	shouldAutoValidate() {
+		return this._autoValidate ?? app.config.get("apiquery.autoValidate", true);
+	}
+	hasValidation() {
+		return this._rules !== void 0 || Object.keys(this._filterRules).length > 0;
+	}
+	async toValidator() {
+		return buildQueryValidator(this._rules, this._filterRules);
+	}
+	/**
+	* Validates the request once (the result is memoized) and returns the validated data.
+	* Returns the raw request data when no rules are configured.
+	*/
+	async validate(rules) {
+		if (rules !== void 0) this.setRules(rules);
+		if (!this.hasValidation()) return this.all();
+		this._validation ??= this.runValidation();
+		return this._validation;
+	}
+	getValidatedData() {
+		return this._validatedData;
+	}
+	isValidated() {
+		return this._validatedData !== void 0;
+	}
+	includes() {
+		return this.getArrayParameterData("apiquery.parameters.include", "include", ApiQueryBuilderRequest.getIncludesArrayValueDelimiter());
+	}
+	appends() {
+		return this.getArrayParameterData("apiquery.parameters.append", "append", ApiQueryBuilderRequest.getAppendsArrayValueDelimiter());
+	}
+	sorts() {
+		return this.getArrayParameterData("apiquery.parameters.sort", "sort", ApiQueryBuilderRequest.getSortsArrayValueDelimiter());
+	}
+	fields() {
+		const fieldsParameterName = app.config.get("apiquery.parameters.fields", "fields");
+		const fieldsDelimiter = ApiQueryBuilderRequest.getFieldsArrayValueDelimiter();
+		const fieldsData = this.getRequestData(fieldsParameterName, {});
+		const fieldsPerTable = typeof fieldsData === "string" ? fieldsData.split(fieldsDelimiter) : fieldsData;
+		if ((Array.isArray(fieldsPerTable) ? fieldsPerTable : Object.keys(fieldsPerTable)).length === 0) return {};
+		const fields = {};
+		const entries = Array.isArray(fieldsPerTable) ? fieldsPerTable.map((item, index) => [String(index), item]) : Object.entries(fieldsPerTable);
+		for (const [rawModel, tableFields] of entries) {
+			const model = Number.isNaN(Number(rawModel)) ? rawModel : typeof tableFields === "string" && tableFields.includes(".") ? strBeforeLast(tableFields, ".") : "_";
+			if (UNSAFE_OBJECT_KEYS.has(model)) continue;
+			if (!Object.hasOwn(fields, model)) fields[model] = [];
+			const currentFields = typeof tableFields === "string" ? tableFields.split(fieldsDelimiter).map((field) => strAfterLast(field, ".")) : tableFields;
+			fields[model].push(...currentFields);
+		}
+		return fields;
+	}
+	filters() {
+		const filterParameterName = app.config.get("apiquery.parameters.filter", "filter");
+		const filterParts = this._validatedData ? this._validatedData[filterParameterName] ?? {} : this.getRequestData(filterParameterName, {});
+		if (!isPlainObject(filterParts)) return {};
+		const filters = {};
+		for (const [key, value] of Object.entries(filterParts)) {
+			if (UNSAFE_OBJECT_KEYS.has(key)) continue;
+			filters[key] = this.getFilterValue(value);
+		}
+		return filters;
+	}
+	getArrayParameterData(configKey, defaultParam, delimiter) {
+		const parameterName = app.config.get(configKey, defaultParam);
+		const rawParts = this.getRequestData(parameterName, []);
+		return (typeof rawParts === "string" ? rawParts.split(delimiter) : Array.isArray(rawParts) ? rawParts : [rawParts]).filter(Boolean);
+	}
+	getFilterValue(value) {
+		if (value === void 0 || value === null) return null;
+		if (value === "" || Array.isArray(value) && value.length === 0 || isPlainObject(value) && Object.keys(value).length === 0) return typeof value === "object" ? [] : value;
+		if (Array.isArray(value)) return value.map((item) => this.getFilterValue(item));
+		if (isPlainObject(value)) {
+			const result = {};
+			for (const [key, val] of Object.entries(value)) {
+				if (UNSAFE_OBJECT_KEYS.has(key)) continue;
+				result[key] = this.getFilterValue(val);
+			}
+			return result;
+		}
+		if (typeof value === "string") {
+			const delimiter = ApiQueryBuilderRequest.getFilterArrayValueDelimiter();
+			if (value.includes(delimiter)) return value.split(delimiter);
+			if (value === "true") return true;
+			if (value === "false") return false;
+		}
+		return value;
+	}
+	getRequestData(key, defaultValue) {
+		return this._request.input(key, defaultValue);
+	}
+	async runValidation() {
+		const validator = await this.toValidator();
+		const request = this._request;
+		const data = typeof request.validateUsing === "function" ? await request.validateUsing(validator) : await validator.validate(this.all());
+		this._validatedData = data;
+		return this._validatedData;
+	}
+	static setArrayValueDelimiter(delimiter) {
+		this.includesArrayValueDelimiter = delimiter;
+		this.appendsArrayValueDelimiter = delimiter;
+		this.fieldsArrayValueDelimiter = delimiter;
+		this.sortsArrayValueDelimiter = delimiter;
+		this.filterArrayValueDelimiter = delimiter;
+	}
+	static setIncludesArrayValueDelimiter(includesArrayValueDelimiter) {
+		this.includesArrayValueDelimiter = includesArrayValueDelimiter;
+	}
+	static setAppendsArrayValueDelimiter(appendsArrayValueDelimiter) {
+		this.appendsArrayValueDelimiter = appendsArrayValueDelimiter;
+	}
+	static setFieldsArrayValueDelimiter(fieldsArrayValueDelimiter) {
+		this.fieldsArrayValueDelimiter = fieldsArrayValueDelimiter;
+	}
+	static setSortsArrayValueDelimiter(sortsArrayValueDelimiter) {
+		this.sortsArrayValueDelimiter = sortsArrayValueDelimiter;
+	}
+	static setFilterArrayValueDelimiter(filterArrayValueDelimiter) {
+		this.filterArrayValueDelimiter = filterArrayValueDelimiter;
+	}
+	static getIncludesArrayValueDelimiter() {
+		return this.includesArrayValueDelimiter;
+	}
+	static getAppendsArrayValueDelimiter() {
+		return this.appendsArrayValueDelimiter;
+	}
+	static getFieldsArrayValueDelimiter() {
+		return this.fieldsArrayValueDelimiter;
+	}
+	static getSortsArrayValueDelimiter() {
+		return this.sortsArrayValueDelimiter;
+	}
+	static getFilterArrayValueDelimiter() {
+		return this.filterArrayValueDelimiter;
+	}
+	static resetDelimiters() {
+		this.includesArrayValueDelimiter = ",";
+		this.appendsArrayValueDelimiter = ",";
+		this.fieldsArrayValueDelimiter = ",";
+		this.sortsArrayValueDelimiter = ",";
+		this.filterArrayValueDelimiter = ",";
+	}
+	static fromRequest(request) {
+		return new ApiQueryBuilderRequest(request);
+	}
+};
+export { ApiQueryBuilderRequest };

package/build/src/base_filterable.d.ts

@@ -0,0 +1,45 @@
+import { ApiQueryBuilderRequest } from "./api_query_builder_request.js";
+import { FilterItem, IncludeItem, QueryValidator, SortItem, ValidationRules } from "../types.js";
+import { HttpRequest } from "@adonisjs/core/http";
+import { LucidModel, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
+export declare abstract class BaseFilterable<Model extends LucidModel = LucidModel> {
+  static model?: LucidModel | (() => LucidModel);
+  request?: HttpRequest | ApiQueryBuilderRequest;
+  filters?: FilterItem<Model>[] | (() => FilterItem<Model>[]);
+  sorts?: SortItem<Model>[] | (() => SortItem<Model>[]);
+  defaultSorts?: SortItem<Model> | SortItem<Model>[] | (() => SortItem<Model> | SortItem<Model>[]);
+  includes?: IncludeItem<Model>[] | (() => IncludeItem<Model>[]);
+  rules?: ValidationRules | (() => ValidationRules);
+  autoValidate?: boolean;
+  constructor(request?: HttpRequest | ApiQueryBuilderRequest);
+  setup?(query: ModelQueryBuilderContract<Model>, request?: HttpRequest | ApiQueryBuilderRequest): void;
+  protected apply(query: ModelQueryBuilderContract<Model>, request?: HttpRequest | ApiQueryBuilderRequest): void;
+  resolveRules(): ValidationRules | undefined;
+  toApiQueryBuilderRequest(request?: HttpRequest | ApiQueryBuilderRequest): ApiQueryBuilderRequest;
+  toValidator(): Promise<QueryValidator>;
+  validate(request?: HttpRequest | ApiQueryBuilderRequest): Promise<Record<string, unknown>>;
+  protected resolvePropertyOrMethod(propertyNames: string[]): unknown;
+  protected resolveFilters(): FilterItem<Model>[];
+  protected resolveSorts(): SortItem<Model>[];
+  protected resolveDefaultSorts(): SortItem<Model> | SortItem<Model>[] | undefined;
+  protected resolveIncludes(): IncludeItem<Model>[];
+  static for<M extends LucidModel>(model: M | (() => M)): {
+    new (request?: HttpRequest | ApiQueryBuilderRequest): BaseFilterable<M>;
+    prototype: BaseFilterable<M>;
+    model: () => M;
+    $query: <R = InstanceType<M>>(request?: HttpRequest | ApiQueryBuilderRequest) => ModelQueryBuilderContract<M, R>;
+    $validateAndQuery: <R = InstanceType<M>>(request?: HttpRequest | ApiQueryBuilderRequest) => Promise<ModelQueryBuilderContract<M, R>>;
+    validator: () => Promise<QueryValidator>;
+    toValidator: () => Promise<QueryValidator>;
+    validate: (request?: HttpRequest | ApiQueryBuilderRequest) => Promise<Record<string, unknown>>;
+  };
+  static toValidator(): Promise<QueryValidator>;
+  static validator(): Promise<QueryValidator>;
+  static validate(request?: HttpRequest | ApiQueryBuilderRequest): Promise<Record<string, unknown>>;
+  static $validateAndQuery<This extends {
+    model?: unknown;
+  }, M extends LucidModel = This['model'] extends (() => infer Model) ? (Model extends LucidModel ? Model : LucidModel) : This['model'] extends LucidModel ? This['model'] : LucidModel, R = InstanceType<M>>(this: This, request?: HttpRequest | ApiQueryBuilderRequest): Promise<ModelQueryBuilderContract<M, R>>;
+  static $query<This extends {
+    model?: unknown;
+  }, M extends LucidModel = This['model'] extends (() => infer Model) ? (Model extends LucidModel ? Model : LucidModel) : This['model'] extends LucidModel ? This['model'] : LucidModel, R = InstanceType<M>>(this: This, request?: HttpRequest | ApiQueryBuilderRequest): ModelQueryBuilderContract<M, R>;
+}

package/build/src/base_filterable.js

@@ -0,0 +1,172 @@
+import { ApiQueryBuilderRequest } from "./api_query_builder_request.js";
+import { AllowedFilter } from "./allowed_filter.js";
+import { AllowedInclude } from "./allowed_include.js";
+import { AllowedSort } from "./allowed_sort.js";
+import { RuntimeException } from "@adonisjs/core/exceptions";
+// src/base_filterable.ts
+const toPascalCase = (str) => {
+	return str.replaceAll(/(^|[-_])(\w)/g, (_, __, c) => c.toUpperCase());
+};
+const RESERVED_PROPERTY_NAMES = /* @__PURE__ */ new Set([
+	"constructor",
+	"setup",
+	"apply",
+	"resolveFilters",
+	"resolveSorts",
+	"resolveDefaultSorts",
+	"resolveIncludes",
+	"resolvePropertyOrMethod",
+	"filters",
+	"sorts",
+	"defaultSorts",
+	"includes",
+	"request",
+	"model",
+	"rules",
+	"autoValidate"
+]);
+var BaseFilterable = class {
+	static model;
+	request;
+	filters;
+	sorts;
+	defaultSorts;
+	includes;
+	rules;
+	autoValidate;
+	constructor(request) {
+		this.request = request;
+	}
+	apply(query, request) {
+		const req = request ?? this.request;
+		if (req) {
+			if (req instanceof ApiQueryBuilderRequest) query.$queryBuilderRequest = req;
+			else query.withRequest(req);
+		}
+		if (typeof this.setup === "function") this.setup(query, req);
+		const filters = this.resolveFilters();
+		if (filters.length > 0) query.allowedFilters(filters);
+		const sorts = this.resolveSorts();
+		if (sorts.length > 0) query.allowedSorts(sorts);
+		const defaultSorts = this.resolveDefaultSorts();
+		if (defaultSorts !== void 0) query.defaultSort(defaultSorts);
+		const includes = this.resolveIncludes();
+		if (includes.length > 0) query.allowedIncludes(includes);
+		const rules = this.resolveRules();
+		const apiRequest = query.$apiQueryBuilderRequest;
+		if (rules !== void 0) apiRequest.setRules(rules);
+		if (this.autoValidate !== void 0) apiRequest.setAutoValidate(this.autoValidate);
+	}
+	resolveRules() {
+		return this.resolvePropertyOrMethod(["rules"]);
+	}
+	toApiQueryBuilderRequest(request) {
+		const req = request ?? this.request;
+		const apiRequest = req instanceof ApiQueryBuilderRequest ? req : new ApiQueryBuilderRequest(req);
+		const rules = this.resolveRules();
+		if (rules !== void 0) apiRequest.setRules(rules);
+		if (this.autoValidate !== void 0) apiRequest.setAutoValidate(this.autoValidate);
+		const filterRules = AllowedFilter.extractRules(this.resolveFilters());
+		if (Object.keys(filterRules).length > 0) apiRequest.setFilterRules(filterRules);
+		return apiRequest;
+	}
+	async toValidator() {
+		return this.toApiQueryBuilderRequest().toValidator();
+	}
+	async validate(request) {
+		return this.toApiQueryBuilderRequest(request).validate();
+	}
+	resolvePropertyOrMethod(propertyNames) {
+		const target = this;
+		for (const name of propertyNames) {
+			if (typeof target[name] === "function") return target[name].call(this);
+			if (target[name] !== void 0) return target[name];
+		}
+	}
+	resolveFilters() {
+		const rawFilters = this.resolvePropertyOrMethod(["filters"]);
+		if (!rawFilters || !Array.isArray(rawFilters)) return [];
+		const target = this;
+		return rawFilters.map((filter) => {
+			if (filter instanceof AllowedFilter) return filter;
+			if (typeof filter === "string") {
+				const filterMethodName = `filter${toPascalCase(filter)}`;
+				if (typeof target[filterMethodName] === "function") return AllowedFilter.callback(filter, (query, value) => {
+					target[filterMethodName].call(this, query, value);
+				});
+				if (!RESERVED_PROPERTY_NAMES.has(filter) && typeof target[filter] === "function") return AllowedFilter.callback(filter, (query, value) => {
+					target[filter].call(this, query, value);
+				});
+			}
+			return filter;
+		});
+	}
+	resolveSorts() {
+		const rawSorts = this.resolvePropertyOrMethod(["sorts"]);
+		if (!rawSorts || !Array.isArray(rawSorts)) return [];
+		const target = this;
+		return rawSorts.map((sort) => {
+			if (sort instanceof AllowedSort) return sort;
+			if (typeof sort === "string") {
+				const cleanName = sort.replaceAll(/^-+/g, "");
+				const sortMethodName = `sort${toPascalCase(cleanName)}`;
+				if (typeof target[sortMethodName] === "function") return AllowedSort.callback(cleanName, (query, isDescending) => {
+					target[sortMethodName].call(this, query, isDescending);
+				});
+				if (!RESERVED_PROPERTY_NAMES.has(cleanName) && typeof target[cleanName] === "function") return AllowedSort.callback(cleanName, (query, isDescending) => {
+					target[cleanName].call(this, query, isDescending);
+				});
+			}
+			return sort;
+		});
+	}
+	resolveDefaultSorts() {
+		return this.resolvePropertyOrMethod(["defaultSorts"]);
+	}
+	resolveIncludes() {
+		const rawIncludes = this.resolvePropertyOrMethod(["includes"]);
+		if (!rawIncludes || !Array.isArray(rawIncludes)) return [];
+		const target = this;
+		return rawIncludes.flatMap((include) => {
+			if (include instanceof AllowedInclude || Array.isArray(include)) return include;
+			if (typeof include === "string") {
+				const includeMethodName = `include${toPascalCase(include)}`;
+				if (typeof target[includeMethodName] === "function") return AllowedInclude.callback(include, (query) => {
+					target[includeMethodName].call(this, query);
+				});
+				if (!RESERVED_PROPERTY_NAMES.has(include) && typeof target[include] === "function") return AllowedInclude.callback(include, (query) => {
+					target[include].call(this, query);
+				});
+			}
+			return include;
+		});
+	}
+	static for(model) {
+		const modelThunk = typeof model === "function" && !("query" in model) ? model : () => model;
+		return class extends this {
+			static model = modelThunk;
+		};
+	}
+	static async toValidator() {
+		return new this().toValidator();
+	}
+	static async validator() {
+		return this.toValidator();
+	}
+	static async validate(request) {
+		return new this(request).validate(request);
+	}
+	static async $validateAndQuery(request) {
+		await this.validate(request);
+		return this.$query(request);
+	}
+	static $query(request) {
+		const rawModel = this.model;
+		if (!rawModel) {
+			const name = this.name ?? "Filterable";
+			throw new RuntimeException(`No model is configured for filterable class "${name}". Define "static model = () => User" on "${name}".`);
+		}
+		return (typeof rawModel.query === "function" ? rawModel : typeof rawModel === "function" ? rawModel() : rawModel).$filter(this, request);
+	}
+};
+export { BaseFilterable };

package/build/src/bindings/api_query_request.js

@@ -0,0 +1,13 @@
+import { ApiQueryBuilderRequest } from "../api_query_builder_request.js";
+// src/bindings/api_query_request.ts
+const extendModelQueryBuilderWithRequest = function(builder) {
+	builder.macro("withRequest", function(request) {
+		this.$queryBuilderRequest = ApiQueryBuilderRequest.fromRequest(request);
+		return this;
+	});
+	builder.getter("$apiQueryBuilderRequest", function() {
+		this.$queryBuilderRequest ??= new ApiQueryBuilderRequest();
+		return this.$queryBuilderRequest;
+	});
+};
+export { extendModelQueryBuilderWithRequest };

package/build/src/bindings/filterable_query.js

@@ -0,0 +1,51 @@
+import { BaseFilterable } from "../base_filterable.js";
+import { FilterableNotConfigured } from "../exceptions/filterable_not_configured.js";
+// src/bindings/filterable_query.ts
+const isFilterableClassOrInstance = (value) => {
+	if (value instanceof BaseFilterable) return true;
+	if (typeof value === "function") {
+		const fn = value;
+		if (fn.prototype instanceof BaseFilterable) return true;
+		if (fn.prototype && typeof fn.prototype.apply === "function" && typeof fn.prototype.setup === "function") return true;
+	}
+	return false;
+};
+const resolveFilterable = (raw) => {
+	if (!raw) return;
+	if (raw instanceof BaseFilterable) return raw;
+	if (typeof raw === "function") {
+		const fn = raw;
+		if (fn.prototype instanceof BaseFilterable) return raw;
+		if (fn.prototype && typeof fn.prototype.apply === "function") return raw;
+		try {
+			const resolved = raw();
+			return resolveFilterable(resolved);
+		} catch {
+			return raw;
+		}
+	}
+};
+const extendLucidWithFilterable = function(baseModel, builder) {
+	const modelWithFilter = baseModel;
+	modelWithFilter.$filter ??= function(filterableOrRequest, maybeRequest) {
+		return this.query().filter(filterableOrRequest, maybeRequest);
+	};
+	const filterMacro = function(filterableOrRequest, maybeRequest) {
+		let filterable;
+		let request;
+		if (isFilterableClassOrInstance(filterableOrRequest)) {
+			filterable = filterableOrRequest;
+			request = maybeRequest;
+		} else {
+			const model = this.model;
+			filterable = resolveFilterable(model.$filterable);
+			request = filterableOrRequest;
+		}
+		if (!filterable) throw new FilterableNotConfigured(this.model.name);
+		const FilterableClass = filterable;
+		(filterable instanceof BaseFilterable ? filterable : new FilterableClass(request)).apply(this, request);
+		return this;
+	};
+	builder.macro("filter", filterMacro);
+};
+export { extendLucidWithFilterable };

package/build/src/bindings/filters_query.js

@@ -0,0 +1,38 @@
+import { AllowedFilter } from "../allowed_filter.js";
+import { InvalidFilterQuery } from "../exceptions/invalid_filter_query.js";
+// src/bindings/filters_query.ts
+const extendModelQueryBuilderWithFiltersQuery = function(builder, config) {
+	const ensureAllFiltersExist = (self, requestedFilters) => {
+		if (config.disableInvalidFilterQueryException) return;
+		const filterNames = Object.keys(requestedFilters);
+		if (filterNames.length === 0) return;
+		const allowedFilterNames = self._allowedFilters.map((allowedFilter) => allowedFilter.getName());
+		const allowedSet = new Set(allowedFilterNames);
+		const diff = filterNames.filter((filterName) => !allowedSet.has(filterName));
+		if (diff.length > 0) throw InvalidFilterQuery.filtersNotAllowed(diff, allowedFilterNames);
+	};
+	const addRequestedFiltersToQuery = (query, requestedFilters) => {
+		for (const allowedFilter of query._allowedFilters) {
+			const name = allowedFilter.getName();
+			if (Object.hasOwn(requestedFilters, name)) {
+				allowedFilter.filter(query, requestedFilters[name]);
+				continue;
+			}
+			if (allowedFilter.hasDefault()) allowedFilter.filter(query, allowedFilter.getDefault());
+		}
+	};
+	builder.macro("allowedFilters", function(...filters) {
+		const arrayFilters = Array.isArray(filters.at(0)) ? filters.at(0) : filters;
+		this._allowedFilters = arrayFilters.map((filter) => {
+			if (filter instanceof AllowedFilter) return filter;
+			return AllowedFilter.partial(filter);
+		});
+		const filterRules = AllowedFilter.extractRules(this._allowedFilters);
+		if (Object.keys(filterRules).length > 0) this.$apiQueryBuilderRequest.setFilterRules(filterRules);
+		const requestedFilters = this.$apiQueryBuilderRequest.filters();
+		ensureAllFiltersExist(this, requestedFilters);
+		addRequestedFiltersToQuery(this, requestedFilters);
+		return this;
+	});
+};
+export { extendModelQueryBuilderWithFiltersQuery };

package/build/src/bindings/includes_query.js

@@ -0,0 +1,50 @@
+import { AllowedInclude } from "../allowed_include.js";
+import { InvalidIncludeQuery } from "../exceptions/invalid_include_query.js";
+// src/bindings/includes_query.ts
+const extendModelQueryBuilderWithIncludesQuery = function(builder, config) {
+	const ensureAllIncludesExist = (self, requestedIncludes) => {
+		if (config.disableInvalidIncludesQueryException || requestedIncludes.length === 0) return;
+		const allowedIncludeNames = self._allowedIncludes.map((allowedInclude) => allowedInclude.getName());
+		const allowedSet = new Set(allowedIncludeNames);
+		const diff = requestedIncludes.filter((include) => !allowedSet.has(include));
+		if (diff.length > 0) throw InvalidIncludeQuery.includesNotAllowed(diff, allowedIncludeNames);
+	};
+	const findInclude = (self, include) => {
+		return self._allowedIncludes.find((included) => included.isForInclude(include));
+	};
+	const addIncludesToQuery = (self, includes) => {
+		for (const include of includes) findInclude(self, include)?.include(self);
+	};
+	builder.macro("allowedIncludes", function(...includes) {
+		const arrayIncludes = Array.isArray(includes.at(0)) ? includes.at(0) : includes;
+		const reduced = [];
+		for (const include of arrayIncludes) {
+			if (typeof include === "string" && include.length === 0) continue;
+			if (Array.isArray(include)) {
+				reduced.push(...include);
+				continue;
+			}
+			if (include instanceof AllowedInclude) {
+				reduced.push(include);
+				continue;
+			}
+			if (include.endsWith(config.countSuffix)) {
+				reduced.push(...AllowedInclude.count(include));
+				continue;
+			}
+			reduced.push(...AllowedInclude.relationship(include));
+		}
+		const seen = /* @__PURE__ */ new Set();
+		this._allowedIncludes = reduced.filter((allowedInclude) => {
+			const name = allowedInclude.getName();
+			if (seen.has(name)) return false;
+			seen.add(name);
+			return true;
+		});
+		const requestedIncludes = this.$apiQueryBuilderRequest.includes();
+		ensureAllIncludesExist(this, requestedIncludes);
+		addIncludesToQuery(this, requestedIncludes);
+		return this;
+	});
+};
+export { extendModelQueryBuilderWithIncludesQuery };

package/build/src/bindings/sorts_query.js

@@ -0,0 +1,42 @@
+import { AllowedSort } from "../allowed_sort.js";
+import { InvalidSortQuery } from "../exceptions/invalid_sort_query.js";
+// src/bindings/sorts_query.ts
+const DESCENDING_ORDER_PREFIX = /^-+/;
+const extendModelQueryBuilderWithSortsQuery = function(builder, config) {
+	const ensureAllSortsExist = (self, requestedSorts) => {
+		if (config.disableInvalidSortQueryException || requestedSorts.length === 0) return;
+		const requestedSortNames = requestedSorts.map((sort) => sort.replace(DESCENDING_ORDER_PREFIX, ""));
+		const allowedSortNames = self._allowedSorts.map((sort) => sort.getName());
+		const allowedSet = new Set(allowedSortNames);
+		const unknownSort = requestedSortNames.filter((sort) => !allowedSet.has(sort));
+		if (unknownSort.length > 0) throw InvalidSortQuery.sortsNotAllowed(unknownSort, allowedSortNames);
+	};
+	const findSort = (self, property) => {
+		return self._allowedSorts.find((sort) => sort.isSort(property));
+	};
+	const addRequestedSortsToQuery = (self, requestedSorts) => {
+		for (const property of requestedSorts) {
+			const isDescending = property.startsWith("-");
+			const key = property.replace(DESCENDING_ORDER_PREFIX, "");
+			findSort(self, key)?.sort(self, isDescending);
+		}
+	};
+	builder.macro("allowedSorts", function(...sorts) {
+		const arraySorts = Array.isArray(sorts.at(0)) ? sorts.at(0) : sorts;
+		this._allowedSorts = arraySorts.map((sort) => {
+			if (sort instanceof AllowedSort) return sort;
+			return AllowedSort.field(sort.replace(DESCENDING_ORDER_PREFIX, ""));
+		});
+		const requestedSorts = this.$apiQueryBuilderRequest.sorts();
+		ensureAllSortsExist(this, requestedSorts);
+		addRequestedSortsToQuery(this, requestedSorts);
+		return this;
+	});
+	builder.macro("defaultSort", function(...sorts) {
+		if (this.$apiQueryBuilderRequest.sorts().length > 0) return this;
+		const arraySorts = Array.isArray(sorts.at(0)) ? sorts.at(0) : sorts;
+		for (const rawSort of arraySorts) (rawSort instanceof AllowedSort ? rawSort : AllowedSort.field(rawSort)).sort(this);
+		return this;
+	});
+};
+export { extendModelQueryBuilderWithSortsQuery };

package/build/src/bindings/validation_query.js

@@ -0,0 +1,27 @@
+// src/bindings/validation_query.ts
+let isPatched = false;
+const extendModelQueryBuilderWithValidation = function(builder) {
+	builder.macro("validate", async function() {
+		return this.$apiQueryBuilderRequest.validate();
+	});
+	if (isPatched) return;
+	const proto = builder.prototype;
+	const originalExecQuery = proto.execQuery;
+	proto.execQuery = async function(...args) {
+		const query = this;
+		if (query.$queryBuilderRequest) {
+			const apiRequest = query.$queryBuilderRequest;
+			if (apiRequest.shouldAutoValidate() && apiRequest.hasValidation()) await apiRequest.validate();
+		}
+		return originalExecQuery.apply(this, args);
+	};
+	const originalClone = proto.clone;
+	proto.clone = function() {
+		const cloned = originalClone.call(this);
+		const query = this;
+		if (query.$queryBuilderRequest) cloned.$queryBuilderRequest = query.$queryBuilderRequest;
+		return cloned;
+	};
+	isPatched = true;
+};
+export { extendModelQueryBuilderWithValidation };

package/build/src/decorators/filterable.d.ts

@@ -0,0 +1,20 @@
+import { ApiQueryBuilderRequest } from "../api_query_builder_request.js";
+import { BaseFilterable } from "../base_filterable.js";
+import { FilterableConstructor, FilterableTarget } from "../../types.js";
+import { HttpRequest } from "@adonisjs/core/http";
+import { BaseModel } from "@adonisjs/lucid/orm";
+import { LucidModel, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
+import { NormalizeConstructor } from "@adonisjs/core/types/helpers";
+export type FilterableModel<T extends NormalizeConstructor<typeof BaseModel>> = (new (...args: unknown[]) => InstanceType<T>) & { [K in keyof T]: T[K]; } & {
+  $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>>;
+};
+/**
+ * Decorator to assign a filterable class to a Lucid Model
+ */
+export declare function filterable<Model extends LucidModel = LucidModel>(target: FilterableTarget<Model>): (model: unknown) => void;
+/**
+ * Mixin that adds filterable capabilities to a Lucid Model
+ */
+export declare function Filterable<T extends NormalizeConstructor<typeof BaseModel>, Model extends LucidModel = LucidModel>(filterableTarget?: FilterableTarget<Model>): (superclass: T) => FilterableModel<T>;