Advanced Usage
Exceptions
Handle exceptions thrown by @eienjs/adonisjs-api-query when invalid query parameters are requested.
By default, @eienjs/adonisjs-api-query validates that any requested filter, sort, or include parameter in the URL has been explicitly allowed on the query. When a disallowed parameter is encountered, an exception extending AdonisJS Exception is thrown.
Exception Reference
| Exception Class | HTTP Status | Code / Base Class | When It Is Thrown |
|---|---|---|---|
InvalidFilterQuery | 400 Bad Request | E_INVALID_QUERY_EXCEPTION (InvalidQuery) | A requested filter[...] is not in .allowedFilters(). Exposes unknownFilters and allowedFilters. |
InvalidSortQuery | 400 Bad Request | E_INVALID_QUERY_EXCEPTION (InvalidQuery) | A requested sort is not in .allowedSorts(). Exposes unknownSorts and allowedSorts. |
InvalidIncludeQuery | 400 Bad Request | E_INVALID_QUERY_EXCEPTION (InvalidQuery) | A requested include is not in .allowedIncludes(). Exposes unknownIncludes and allowedIncludes. |
InvalidDirection | 500 Internal Server Error | Exception | An invalid default sort direction (not 'asc' or 'desc') is passed to AllowedSort.setDefaultDirection(). |
FilterableNotConfigured | 500 Internal Server Error | E_FILTERABLE_NOT_CONFIGURED | Model.$filter() or query.filter() is called on a model that has no $filterable configured and no filterable class argument was provided. |
VineNotInstalledException | 500 Internal Server Error | E_VINE_NOT_INSTALLED | Validation rules are executed when @vinejs/vine is not installed in the project. |
All invalid query exceptions (
InvalidFilterQuery, InvalidSortQuery, InvalidIncludeQuery, InvalidFieldQuery, InvalidAppendQuery, UnknownIncludedFieldsQuery) inherit from the abstract InvalidQuery class, making it easy to catch all client query errors in a single instanceof InvalidQuery check.Custom Exception Handling
In your AdonisJS global exception handler (app/exceptions/handler.ts), you can customize the JSON response for InvalidQuery exceptions:
app/exceptions/handler.ts
import type { HttpContext } from '@adonisjs/core/http';
import { ExceptionHandler } from '@adonisjs/core/http';
import {
InvalidFilterQuery,
InvalidIncludeQuery,
InvalidQuery,
InvalidSortQuery,
} from '@eienjs/adonisjs-api-query';
export default class HttpExceptionHandler extends ExceptionHandler {
public async handle(error: unknown, ctx: HttpContext) {
if (error instanceof InvalidFilterQuery) {
return ctx.response.badRequest({
code: 'E_INVALID_FILTER',
message: error.message,
unknownFilters: error.unknownFilters,
allowedFilters: error.allowedFilters,
});
}
if (error instanceof InvalidSortQuery) {
return ctx.response.badRequest({
code: 'E_INVALID_SORT',
message: error.message,
unknownSorts: error.unknownSorts,
allowedSorts: error.allowedSorts,
});
}
if (error instanceof InvalidIncludeQuery) {
return ctx.response.badRequest({
code: 'E_INVALID_INCLUDE',
message: error.message,
unknownIncludes: error.unknownIncludes,
allowedIncludes: error.allowedIncludes,
});
}
if (error instanceof InvalidQuery) {
return ctx.response.badRequest({
code: InvalidQuery.code,
message: error.message,
});
}
return super.handle(error, ctx);
}
}
Disabling Invalid Query Exceptions
If you prefer to silently ignore disallowed filters, sorts, or includes instead of throwing 400 Bad Request exceptions, update your Configuration in config/apiquery.ts:
config/apiquery.ts
import { defineConfig } from '@eienjs/adonisjs-api-query';
export default defineConfig({
disableInvalidFilterQueryException: true,
disableInvalidSortQueryException: true,
disableInvalidIncludesQueryException: true,
});