Request & Delimiters
Under the hood, @eienjs/adonisjs-api-query wraps the AdonisJS HttpRequest in an ApiQueryBuilderRequest instance to parse filter, sort, include, fields, and append parameters consistently.
Accessing ApiQueryBuilderRequest
You can create an ApiQueryBuilderRequest directly from an HttpRequest or access it on any ModelQueryBuilder instance via the $apiQueryBuilderRequest getter:
import { ApiQueryBuilderRequest } from '@eienjs/adonisjs-api-query';
// Directly from HttpRequest:
const apiRequest = ApiQueryBuilderRequest.fromRequest(request);
// or: new ApiQueryBuilderRequest(request)
const filters = apiRequest.filters(); // Record<string, unknown>
const sorts = apiRequest.sorts(); // string[]
const includes = apiRequest.includes(); // string[]
const fields = apiRequest.fields(); // Record<string, string[]>
const appends = apiRequest.appends(); // string[]
// Or from a ModelQueryBuilder:
const query = User.query().withRequest(request);
const parsedFilters = query.$apiQueryBuilderRequest.filters();
Automatic Value Parsing in filters()
When ApiQueryBuilderRequest parses filter values from the query string:
- String
'true'and'false'are converted to booleantrueandfalse. - Strings containing the filter array delimiter (
,by default) are split into string arrays (e.g.,?filter[status]=active,pendingbecomes['active', 'pending']). undefinedandnullbecomenull.- Unsafe object prototype keys (
__proto__,constructor,prototype) are automatically stripped to prevent prototype pollution.
Customizing Array Value Delimiters
By default, comma (,) is used to split multiple values in filter, sort, include, fields, and append parameters (for example, ?filter[id]=1,2,3 or ?include=posts,profile).
If your filter values naturally contain commas (such as addresses or titles), you can change the delimiter globally or for specific parameter types.
Per-Filter Array Delimiter
All AllowedFilter factory methods (exact, partial, beginsWithStrict, endsWithStrict, callback, scope, custom, operator) accept an optional arrayValueDelimiter parameter:
import { AllowedFilter } from '@eienjs/adonisjs-api-query';
// GET /users?filter[location]=New York, NY;Los Angeles, CA
const users = await User.query()
.withRequest(request)
.allowedFilters([
AllowedFilter.exact('location', undefined, true, ';'),
]);
Global Delimiter Methods on ApiQueryBuilderRequest
You can also configure delimiters via static methods on ApiQueryBuilderRequest (or AllowedFilter.setFilterArrayValueDelimiter()):
import { ApiQueryBuilderRequest } from '@eienjs/adonisjs-api-query';
// Set delimiter for all parameter types at once (includes, appends, fields, sorts, filters)
ApiQueryBuilderRequest.setArrayValueDelimiter(';');
// Or configure each parameter type individually:
ApiQueryBuilderRequest.setFilterArrayValueDelimiter('|');
ApiQueryBuilderRequest.setIncludesArrayValueDelimiter(',');
ApiQueryBuilderRequest.setSortsArrayValueDelimiter(',');
ApiQueryBuilderRequest.setFieldsArrayValueDelimiter(',');
ApiQueryBuilderRequest.setAppendsArrayValueDelimiter(',');
// Reset all delimiters back to ','
ApiQueryBuilderRequest.resetDelimiters();