Skip to main content

​
Choose Your Adapter

filter-def is split into multiple packages. Install only the adapters you need for your project:

@filter-def/in-memory

For filtering JavaScript arrays with native methods

@filter-def/drizzle

For generating SQL WHERE clauses with Drizzle ORM

@filter-def/bigquery

For creating parameterized BigQuery SQL queries

@filter-def/core

Core types only (usually not needed directly)

​
Installation Commands

​
In-Memory Filtering

For filtering arrays in JavaScript/TypeScript applications: 
npm install @filter-def/in-memory
@filter-def/in-memory has zero runtime dependencies except for @filter-def/core (bundled automatically).

​
Drizzle ORM Adapter

For SQL databases using Drizzle ORM: 
npm install @filter-def/drizzle drizzle-orm
Requires drizzle-orm@>=0.30.0 as a peer dependency. You’ll also need a database driver (e.g., pg for PostgreSQL, better-sqlite3 for SQLite).

​
BigQuery Adapter

For Google BigQuery parameterized SQL queries: 
npm install @filter-def/bigquery @google-cloud/bigquery
@google-cloud/bigquery@>=7.0.0 is an optional peer dependency. The adapter can generate SQL without it, but you’ll need it to execute queries.

​
Core Package (Optional)

The core package contains TypeScript types and utilities. It’s automatically included when you install any adapter, but you can install it directly if you’re building a custom adapter: 
npm install @filter-def/core

​
Package Versions

All packages use semantic versioning. Check npm for the latest versions:

@filter-def/core

npm

@filter-def/in-memory

npm

@filter-def/drizzle

npm

@filter-def/bigquery

npm

​
TypeScript Configuration

filter-def requires TypeScript 5.0 or later with strict mode enabled. Add these settings to your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
The library is built with ES modules. If you’re using CommonJS, the packages provide both ESM and CJS builds automatically.

​
Installing Multiple Adapters

You can install multiple adapters in the same project. This is useful for:
  • Using different backends for different features
  • Testing in-memory before deploying to a database
  • Supporting multiple data sources (e.g., PostgreSQL + BigQuery)
npm install @filter-def/in-memory @filter-def/drizzle drizzle-orm

​
Verify Installation

Test your installation with a simple example:
index.ts
import { inMemoryFilter } from "@filter-def/in-memory";

interface User {
    name: string;
    age: number;
}

const userFilter = inMemoryFilter<User>().def({
    name: { kind: "eq" },
    minAge: { kind: "gte", field: "age" },
});

const users: User[] = [
    { name: "Alice", age: 30 },
    { name: "Bob", age: 25 },
    { name: "Charlie", age: 35 },
];

const results = users.filter(
    userFilter({ minAge: 30 })
);

console.log(results);
// Output: [{ name: "Alice", age: 30 }, { name: "Charlie", age: 35 }]
Run the file: 
npx tsx index.ts

​
Peer Dependencies

Each adapter has specific peer dependency requirements:
No peer dependenciesWorks out of the box with no additional packages required.
Required:
  • drizzle-orm@>=0.30.0
Also needed (depending on your database):
  • PostgreSQL: pg or postgres
  • MySQL: mysql2
  • SQLite: better-sqlite3
Example for PostgreSQL:
npm install @filter-def/drizzle drizzle-orm pg
npm install -D @types/pg
Optional:
  • @google-cloud/bigquery@>=7.0.0
The adapter generates SQL without BigQuery installed, but you’ll need it to execute queries:
npm install @filter-def/bigquery @google-cloud/bigquery

​
Troubleshooting

Ensure you’re using TypeScript 5.0+ with strict mode:
tsconfig.json
{
  "compilerOptions": {
    "strict": true
  }
}
If you see errors about missing types, install the corresponding @types packages:
npm install -D @types/node
If you see “Cannot find module” errors:
  1. Check that you installed the package: 
    npm list @filter-def/in-memory
  2. Verify your moduleResolution setting in tsconfig.json: 
    {
  "compilerOptions": {
    "moduleResolution": "bundler" // or "node16"
  }
}
  3. Clear your package manager cache: 
    npm cache clean --force
rm -rf node_modules package-lock.json
npm install
Peer dependency warnings indicate missing or incompatible versions of required packages.For Drizzle:
npm install drizzle-orm@latest
For BigQuery:
npm install @google-cloud/bigquery@latest
If you’re not using a particular adapter, you can safely ignore its peer dependency warnings.

​
Next Steps

Quick Start Guide

Build your first filter in 5 minutes

API Reference

Explore all available filter types

Build docs developers (and LLMs) love

Get started for freeTalk to us