tsfiltor

A composable TypeScript filter system for querying and evaluating in-memory data. Provides a structured way to build complex query conditions that can be evaluated against entities.

🎯 Composable filters Build complex conditions with simple builder functions

🔍 Rich operators Equality, comparison, string matching, regex, type checking, and more

🧩 Logical operations AND, OR, NOT with nested conditions

🚀 Array extensions Optional prototype extensions for fluent API

🔧 Extensible Register custom operators easily

📦 Type-safe Full TypeScript support

Installation

npm install tsfiltor

Universal Compatibility

This package is built with dual module support (ESM + CommonJS) for maximum compatibility:

✅ Node.js (ESM and CommonJS) - Node 18+
✅ Browsers (ESM via CDN or bundlers)
✅ React Native (CommonJS) - Full support
✅ Bundlers (Webpack, Vite, Rollup, etc.) - Auto-detects format
✅ TypeScript (full type support)

The package automatically serves the correct format:

import { ... } from 'tsfiltor' → ESM (browsers, modern Node.js, bundlers)
const { ... } = require('tsfiltor') → CommonJS (React Native, older tools)

Browser Usage

The package works in browsers via CDN. Use esm.sh or similar CDN:

<script type="module">
  import { eq, gt, filterEntities } from 'https://esm.sh/tsfiltor@latest';
  // Use the library...
</script>

Try It Live

Edit the code below and click "Run" to see the results. The package is loaded from npm via esm.sh CDN.

Editor

Ready

// Import types and functions - this activates TypeScript support for Array extensions
import 'https://esm.sh/tsfiltor@latest/extensions';
import { enableArrayExtensions } from 'https://esm.sh/tsfiltor@latest/extensions';
import { eq, gt, contains } from 'https://esm.sh/tsfiltor@latest';

// Enable extensions (opt-in)
enableArrayExtensions();

const users = [
    { id: 1, name: 'John Doe', age: 30, email: 'john@example.com', status: 'active', tags: ['vip', 'premium'] },
    { id: 2, name: 'Jane Smith', age: 25, email: 'jane@example.com', status: 'active', tags: ['premium'] },
    { id: 3, name: 'Bob Johnson', age: 18, email: 'bob@test.com', status: 'inactive', tags: [] },
    { id: 4, name: 'Alice Brown', age: 35, email: 'alice@example.com', status: 'pending', tags: ['vip'] },
];

// Now arrays have .where(), .first(), .exists(), .count(), and .findWhere()
const activeUsers = users.where(eq('status', 'active'));
console.log('Active users:', activeUsers);

const john = users.first(eq('name', 'John'));
console.log('John:', john);

const hasVip = users.exists(contains('tags', 'vip'));
console.log('Has VIP users:', hasVip);

const count = users.count(gt('age', 25));
console.log('Users over 25:', count);

// Chain with native array methods
const names = users
  .where(gt('age', 20))
  .map(u => u.name)
  .sort();
console.log('Names of users over 20 (sorted):', names);

Output

Available Operators

Comparison

eq(field, value) - Equality

ne(field, value) - Not equal

lt(field, value) - Less than

lte(field, value) - Less than or equal

gt(field, value) - Greater than

gte(field, value) - Greater than or equal

String Operations

contains(field, value) - String/array contains

startsWith(field, value) - String starts with

endsWith(field, value) - String ends with

matches(field, pattern) - Regex pattern match

Array Operations

anyOf(field, values[]) - Value is in array

minLength(field, n) - Minimum length

maxLength(field, n) - Maximum length

Type Checking

isRecord(field) - Is plain object/Record

matchesZodSchema(field, schema) - Matches Zod schema

Logical

and(...conditions) - All conditions must match

or(...conditions) - Any condition must match

not(condition) - Negate condition

API Reference

Core Functions

evaluateCondition(entity, condition) - Evaluate condition against entity
filterEntities(entities, filter?) - Filter array of entities
findFirst(entities, filter?) - Find first matching entity
matchExists(entities, filter?) - Check if any entity matches
countWhere(entities, filter?) - Count matching entities
findWhere(entities, options?) - Find with pagination support

Extension Functions

enableArrayExtensions(options?) - Enable Array prototype extensions
disableArrayExtensions() - Disable Array prototype extensions
registerOperator(operator, evaluator) - Register custom operator

License

Unlicense - This is free and unencumbered software released into the public domain.

For more information, see unlicense.org