Registry / database / adonis-lucid-filter

adonis-lucid-filter

library5.2.0jsnpmunverified

Adonis Lucid Filter (v5.2.0) is a Lucid ORM addon for AdonisJS v6 that simplifies query filtering by automatically mapping HTTP query parameters to model filter methods. It reduces boilerplate code, supports CamelCase-to-snake_case conversion, ignores empty strings and unmatched inputs, and provides a `setup()` method for global query modifications. The package is actively maintained, with ~monthly releases, and ships TypeScript types. It requires @adonisjs/core ^6.2.3, @adonisjs/lucid ^21.1.0, and lodash. Compared to manual filtering, it offers a declarative, convention-driven approach inspired by EloquentFilter.

database devops

npm install adonis-lucid-filter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ADONIS-LUCID-FILTE

adonis-lucid-filter

databasejavascriptv5.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

filter

✓ import { filter } from 'adonis-lucid-filter'

✗ import { filter } from 'adonis-lucid-filter' is correct; do not use default import or require

Named export only. Used as a mixin for Lucid models.

BaseModelFilter

✓ import { BaseModelFilter } from 'adonis-lucid-filter'

✗ const BaseModelFilter = require('adonis-lucid-filter').BaseModelFilter

ESM-only; require() will fail. Base class for filter definitions.

provider

✓ import 'adonis-lucid-filter/provider'

✗ import { provider } from 'adonis-lucid-filter/provider'

Side-effect import to register provider in adonisrc.ts.

Complete setup flow: install, configure, generate filter, define filter methods, and apply in controller.

// 1. Install: npm i adonis-lucid-filter // 2. Configure: node ace configure adonis-lucid-filter // 3. In adonisrc.ts: providers: [ () => import('adonis-lucid-filter/provider'), ], commands: [ () => import('adonis-lucid-filter/commands'), ] // 4. Generate a filter: node ace make:filter user // 5. Define filter in app/Models/Filters/UserFilter.ts: import { BaseModelFilter } from 'adonis-lucid-filter' import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model' export default class UserFilter extends BaseModelFilter { public static $blacklist: string[] = ['admin'] public $query: ModelQueryBuilderContract<any> name(name: string): void { this.$query.where(function () { this.where('first_name', 'LIKE', `%${name}%`) .orWhere('last_name', 'LIKE', `%${name}%`) }) } companyId(companyId: number): void { this.$query.where('company_id', companyId) } } // 6. Use in controller: import User from '#models/user' export default class UsersController { async index({ request }: HttpContext) { return User.filter(request.qs()).exec() } }

Debug

Known issues

breakingv5 requires @adonisjs/lucid ^21.1.0 and @adonisjs/core ^6.2.3; incompatible with older AdonisJS versions

fix

Update AdonisJS to v6.2.3+ and Lucid to v21.1.0+

affects: >=5.0.0

breakingv4 used decorator @filterable() which was removed in v5

fix

For v5, do not use @filterable(); extend BaseModelFilter instead

affects: >=3.0.0 <5.0.0

deprecatedv4 and below are deprecated; AdonisJS v5 users should stay on v4 branch

fix

Stay on v4 for AdonisJS v5; no migration needed unless moving to v6

affects: 4.x

gotchaFilter methods must be camelCase of query param; underscores are dropped for _id suffix

fix

Name methods like: param 'company_id' => method companyId() (without '_id')

affects: >=1.0.0

gotchaEmpty string values are ignored; a filter method won't be called for empty input

fix

If you need to handle empty strings, check this.$input[key] manually in setup()

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'adonis-lucid-filter/provider'

Provider path misspelled or not configured in adonisrc.ts

fix

Ensure adonisrc.ts imports 'adonis-lucid-filter/provider' and not 'adonis-lucid-filter/providers'

User.filter is not a function

Model does not have filter mixin applied; or filter decorator not added

fix

In your model: import { filter } from 'adonis-lucid-filter' and apply @filter() decorator or use static mixin

Cannot find module 'adonis-lucid-filter/commands'

Commands path not added to commands array in adonisrc.ts

fix

Add () => import('adonis-lucid-filter/commands') to commands array in adonisrc.ts

Property '$query' is used before its initialization in BaseModelFilter

TypeScript strict mode; $query is assigned at runtime by the mixin

fix

Add !: (non-null assertion) to $query declaration in filter class, or use 'as any'

Upgrade

Version history

5.2.0latest on npm

Audit

Dependencies

@adonisjs/corerequiredCore dependency for AdonisJS v6 framework features (HTTP context, IoC container)

@adonisjs/lucidrequiredRequired for Lucid ORM model queries and QueryBuilder

lodashrequiredUsed internally for object manipulation and string conversion

Agent activity

51 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/lookinlab/adonis-lucid-filter ↗

packageadonis-lucid-filter ↗

homepagehttps://github.com/lookinlab/adonis-lucid-filter#readme ↗