adonis-lucid-filter

Create a class that extends BaseModelFilter. The filter logic is driven by the keys provided in the input object (e.g., from request.qs()).

Key Concepts:

• Method Mapping: Input keys are mapped to methods in the class. For example, an input key companyId will call the company(id: number) method.
• $query: Access the Lucid QueryBuilder via this.$query.
• $input: Access the full input object via this.$input.
• setup(): A method called on every filter execution. Use it for mandatory filters (e.g., this.$query.where('is_active', true)).
• Empty Strings: Input values that are empty strings are automatically ignored.
• _id Suffix: If static dropId = true is set, user_id in the input will call the user() method.
• camelCase: If static camelCase = true is set, mobile_phone or mobilePhone will both call the mobilePhone() method.

import { BaseModelFilter } from 'adonis-lucid-filter'
import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
import User from '#models/user'

export default class UserFilter extends BaseModelFilter {
  declare $query: ModelQueryBuilderContract<typeof User>
  
  static blacklist: string[] = ['secretMethod']
  static dropId: boolean = true
  static camelCase: boolean = true

  // Filters 'companyId', 'company_id', or 'company'
  company(id: number) {
    this.$query.where('company_id', id)
  }

  name(name: string) {
    this.$query.where((builder) => {
      builder
        .where('first_name', 'LIKE', `%${name}%`)
        .orWhere('last_name', `%${name}%`)
    })
  }

  mobilePhone(phone: string) {
    this.$query.where('mobile_phone', 'LIKE', `${phone}%`)
  }

  secretMethod(secretParameter: any) {
    this.$query.where('some_column', true)
  }
}

To enable filtering on a model, extend it using compose(BaseModel, Filterable) and define the $filter static property to return your filter class.

Once applied, you can call .filter(input) on the model to execute the query.

import UserFilter from '#models/filters/user_filter'
import { compose } from '@adonisjs/core/helpers'
import { Filterable } from 'adonis-lucid-filter'
import { BaseModel } from '@adonisjs/lucid/orm'

export default class User extends compose(BaseModel, Filterable) {
  static $filter = () => UserFilter
}

// Usage in a Controller
export default class UsersController {
  async index({ request }: HttpContext): Promise<User[]> {
    // Standard filtering
    return User.filter(request.qs()).exec()
  }

  async paginate({ request }: HttpContext): Promise<ModelPaginatorContract<User>> {
    const { page = 1, ...input } = request.qs()
    return User.filter(input).paginate(page, 15)
  }
}

The LucidFilterContract defines the static configuration and constructor requirements for a filter class. When implementing a filter, your class must adhere to this contract to be compatible with the library's automation.

Configuration options:

• blacklist: An array of strings representing method names that should not be used for filtering.
• dropId: A boolean indicating whether the id field should be excluded from the filterable input.
• camelCase: A boolean indicating whether input keys should be automatically converted to camelCase.
• removeEmptyInput(input): A method to clean the input object (e.g., removing null or empty values).

The constructor must accept a ModelQueryBuilderContract and an object representing the input.

export interface LucidFilterContract {
  blacklist: string[]
  dropId: boolean
  camelCase: boolean
  removeEmptyInput(input: object): object
  new ($query: ModelQueryBuilderContract<LucidModel, LucidRow>, $input: object): LucidFilter
}

To create a custom filter for an AdonisJS Lucid model, extend the BaseModelFilter class. This class provides the core engine for mapping input keys to specific filtering methods on your class.

Key Behaviors:

• Input Cleaning: The constructor automatically removes empty values ('', null, or undefined) from the $input object.
• Method Mapping: Input keys are automatically transformed into method names based on static configuration:
  • If static camelCase is true (default), a key like user_name becomes the method userName.
  • If static dropId is true (default), keys ending in _id or Id have that suffix removed before camelCasing (e.g., user_id becomes user).
• Lifecycle: When calling .handle(), the class first executes the setup($query) method (if defined) and then iterates through the $input to call matching methods.
• Blacklisting: You can prevent certain methods from being called by input keys by defining a static blacklist: string[].

import BaseModelFilter from 'adonis-lucid-filter/base_model'

export default class UserFilter extends BaseModelFilter {
  // Prevent specific methods from being triggered by input keys
  static blacklist = ['someInternalMethod']

  // Optional: Run logic before input-based filtering
  setup($query: any) {
    $query.where('is_active', true)
  }

  // This method will be called if the input contains { name: '...' }
  name(value: string) {
    this.$query.where('name', 'like', `%${value}%`)
  }

  // This method will be called if the input contains { user_id: 123 }
  // because dropId is true by default
  user(value: number) {
    this.$query.where('user_id', value)
  }
}