Getting Started

Configuration

Customize query parameter names, suffixes, and exception behavior in config/apiquery.ts.

When you configure the package, a config/apiquery.ts file is created in your project. It uses the defineConfig helper from @eienjs/adonisjs-api-query.

Default Configuration

config/apiquery.ts

import { defineConfig } from '@eienjs/adonisjs-api-query';

const apiQueryConfig = defineConfig({
  parameters: {
    include: 'include',
    filter: 'filter',
    sort: 'sort',
    fields: 'fields',
    append: 'append',
  },

  countSuffix: 'Count',
  existsSuffix: 'Exists',

  disableInvalidFilterQueryException: false,
  disableInvalidSortQueryException: false,
  disableInvalidIncludesQueryException: false,

  convertRelationNamesToSnakeCasePlural: false,
  convertRelationTableNameStrategy: false,
  convertFieldNamesToSnakeCase: false,

  autoValidate: true,
});

export default apiQueryConfig;

Configuration Options

`parameters`

Customizes the query string parameter names inspected by ApiQueryBuilderRequest.

Option	Default	Example URL
`parameters.include`	`'include'`	`GET /users?include=posts,profile`
`parameters.filter`	`'filter'`	`GET /users?filter[name]=john`
`parameters.sort`	`'sort'`	`GET /users?sort=-createdAt`
`parameters.fields`	`'fields'`	`GET /users?fields[users]=id,name`
`parameters.append`	`'append'`	`GET /users?append=fullName`

For example, if you set filter: 'filters' and sort: 'order_by', the package will read ?filters[name]=john&order_by=-createdAt.

`countSuffix`

Type: string
Default: 'Count'

Suffix used when requesting relationship counts via include. With the default value 'Count', allowing 'posts' or 'postsCount' lets clients request GET /users?include=postsCount to execute query.withCount('posts').

`existsSuffix`

Type: string
Default: 'Exists'

Suffix configuration for existence includes.

Disabling Invalid Query Exceptions

By default, when a client requests a filter, sort, or include that is not listed in .allowedFilters(), .allowedSorts(), or .allowedIncludes(), the package throws an HTTP 400 Bad Request exception (InvalidFilterQuery, InvalidSortQuery, or InvalidIncludeQuery).

You can silence these exceptions so disallowed parameters are simply ignored:

Option	Default	Description
`disableInvalidFilterQueryException`	`false`	When `true`, unknown filters in the URL are ignored instead of throwing `InvalidFilterQuery`.
`disableInvalidSortQueryException`	`false`	When `true`, unknown sorts in the URL are ignored instead of throwing `InvalidSortQuery`.
`disableInvalidIncludesQueryException`	`false`	When `true`, unknown includes in the URL are ignored instead of throwing `InvalidIncludeQuery`.

`autoValidate`

Type: boolean
Default: true

Controls whether queries with validation rules defined (via Filterable Classes or AllowedFilter.rule()) automatically validate the incoming request before executing the database query. Set to false if you prefer to trigger validation manually via .validate(). See Validation for full details.

Field & Relation Naming Options

Option	Type	Default	Description
`convertRelationNamesToSnakeCasePlural`	`boolean`	`false`	Keep relationship names in `fields[relation]` as-is instead of converting to camelCase plural.
`convertRelationTableNameStrategy`	`'snake_case' \| 'camelCase' \| 'none' \| false`	`false`	Strategy for resolving table names in `fields[table]`.
`convertFieldNamesToSnakeCase`	`boolean`	`false`	Convert requested field names (e.g., `firstName`) to `snake_case` (`first_name`).

Installation

Install and configure @eienjs/adonisjs-api-query in your AdonisJS application.

Filtering

Filter Lucid queries using partial, exact, operator, scope, trashed, and callback filters.