@sirzag/filter-ast

Turns a declarative filter object with operator strings into a database-agnostic filter tree.

npm install @sirzag/filter-ast

bun add @sirzag/filter-ast

import { buildAbstractFilterTree } from "@sirzag/filter-ast";

buildAbstractFilterTree({
  status: "$in(active,pending)",
  age: "$gte(18)",
  name: "John",
});

[
  {
    joinLogic: 'and',
    conditions: [
      { field: 'status', operator: 'in', value: [ 'active', 'pending' ] },
      { field: 'age', operator: 'gte', value: 18 },
      { field: 'name', operator: 'eq', value: 'John' }
    ]
  }
]

The package has named exports only: buildAbstractFilterTree, $and, $or, joinOr, isFilterGroup, QueryHelpers, FilterError, and the types FilterGroup, FilterCondition, FilterExpression, FilterValue, FilterFieldValue, FilterInput, LogicalOperator, Operator, ParsedOperator.

A value that is not an operator string becomes an eq condition and is passed through as is. undefined fields are dropped.

buildAbstractFilterTree({ name: "John", age: 30, deletedAt: null, archived: undefined });

[
  {
    joinLogic: 'and',
    conditions: [
      { field: 'name', operator: 'eq', value: 'John' },
      { field: 'age', operator: 'eq', value: 30 },
      { field: 'deletedAt', operator: 'eq', value: null }
    ]
  }
]

A string that starts with $ but is not a known $operator(payload) is also matched literally ("$100" → eq "$100").

An operator string has the form $operator(payload). An empty or whitespace-only payload ($eq(), $eq( )) drops the condition, except for $in and $not_in, where $in() and $in( ) are kept as an empty list. A quoted blank is a value: $eq(" ") → ' '.

$in, $not_in and $between split the payload on ,; every other operator keeps commas as part of the value. An item that starts with " keeps its commas up to the next " not preceded by \: $in("a,b",c) → [ 'a,b', 'c' ]. Escaped quotes do not protect commas ($in(\"a,b\") → [ '\\"a', 'b\\"' ]), and an unterminated " is ordinary text ($in("a,b) → [ '"a', 'b' ]).

Every operator payload, and every element of $in/$not_in/$between, is coerced with one rule. This includes $like, $contains and $has. The first matching step wins:

1. Wrapped in double quotes → the inner string, verbatim. \"...\" keeps the quotes.
2. Starts with 0x, 0b or 0o (any case) → the string, untouched.
3. Starts with a digit, or with - followed by a digit, and is -?digits followed by n → bigint.
4. Starts with a digit, or with - followed by a digit, and is a complete, finite decimal number → number. Integers outside Number.MAX_SAFE_INTEGER keep their original text.
5. true, false, null → the literal. undefined is not a literal and stays a string.
6. Anything else → the trimmed string.

There is no Date coercion. Date-like text stays a string.

Leading-zero text such as phone numbers or ZIP codes is coerced to a number unless quoted:

Text ending in digits plus n (123n) must also be quoted to stay a string.

Radix-prefixed text is never converted, so crypto addresses and hex-encoded values reach the database as written:

Convert the value yourself when you need the number: Number(value) or BigInt(value).

$between on these strings compares text, not magnitude: $between(0xf,0x10) throws because '0xf' > '0x10'. Use equal-length, zero-padded values or convert them first.

• Use the n suffix for integers beyond Number.MAX_SAFE_INTEGER: $eq(9007199254740993n) → 9007199254740993n.
• Without the suffix they stay strings: $eq(9007199254740993) → '9007199254740993'.
• bigint values are not JSON-serializable. JSON.stringify throws a TypeError on a tree that contains one, so serialize them yourself.

$between takes exactly two values of the same type, and the first must be less than or equal to the second.

• When either side is a bigint, an integer number on the other side is converted to bigint.
• Strings are ordered with JavaScript string comparison. ISO dates in one format order correctly: $between(2024-09-01,2024-10-01) → [ '2024-09-01', '2024-10-01' ]. Mixed or non-ISO formats can throw on a valid range: $between(9/1/2024,10/1/2024) throws First value in $between must be less than or equal to second value. Date.prototype.toString() output also orders incorrectly.

import { buildAbstractFilterTree, $and } from "@sirzag/filter-ast";

buildAbstractFilterTree({ name: "John", [$and]: { age: "$gte(18)", country: "UA" } });

[
  {
    joinLogic: 'and',
    conditions: [
      { field: 'name', operator: 'eq', value: 'John' },
      {
        joinLogic: 'and',
        conditions: [
          { field: 'age', operator: 'gte', value: 18 },
          { field: 'country', operator: 'eq', value: 'UA' }
        ]
      }
    ]
  }
]

One object can hold several [$or] branches. The remaining fields of that object become the first branch.

import { buildAbstractFilterTree, $or } from "@sirzag/filter-ast";

buildAbstractFilterTree({
  status: "active",
  [$or]: { role: "admin" },
  [$or]: { role: "owner", verified: true },
});

[
  {
    joinLogic: 'or',
    conditions: [
      {
        joinLogic: 'and',
        conditions: [ { field: 'status', operator: 'eq', value: 'active' } ]
      },
      {
        joinLogic: 'and',
        conditions: [ { field: 'role', operator: 'eq', value: 'admin' } ]
      },
      {
        joinLogic: 'and',
        conditions: [
          { field: 'role', operator: 'eq', value: 'owner' },
          { field: 'verified', operator: 'eq', value: true }
        ]
      }
    ]
  }
]

joinOr joins the fields of one level with OR, without creating a nested group.

import { buildAbstractFilterTree, $and, joinOr } from "@sirzag/filter-ast";

buildAbstractFilterTree({
  name: "John",
  [$and]: joinOr({ createdAt: "$lte(2020-01-04)", twoFactorEnabled: true }),
});

[
  {
    joinLogic: 'and',
    conditions: [
      { field: 'name', operator: 'eq', value: 'John' },
      {
        joinLogic: 'or',
        conditions: [
          { field: 'createdAt', operator: 'lte', value: '2020-01-04' },
          { field: 'twoFactorEnabled', operator: 'eq', value: true }
        ]
      }
    ]
  }
]

At the root, buildAbstractFilterTree(joinOr({ a: 1, b: 2 })) returns:

[
  {
    joinLogic: 'or',
    conditions: [ { field: 'a', operator: 'eq', value: 1 }, { field: 'b', operator: 'eq', value: 2 } ]
  }
]

buildAbstractFilterTree returns FilterGroup[]: an empty array for undefined, null, or a filter with no conditions left, otherwise one root group. A group whose conditions were all dropped (undefined fields, empty payloads, empty nested groups) is dropped at every depth, so { x: 1, [$or]: { a: undefined } } matches x = 1, never everything. Any other non-object root, and any array, throws TypeError: Filter must be a non-array object.

type ParsedOperator =
  | "eq" | "ne" | "not" | "gt" | "gte" | "lt" | "lte"
  | "in" | "not_in" | "contains" | "has" | "like" | "between";

interface FilterCondition {
  field: string;
  operator: ParsedOperator;
  value: unknown;
}

interface FilterGroup {
  joinLogic: "or" | "and";
  conditions: Array<FilterCondition | FilterGroup>;
}

isFilterGroup tells groups and conditions apart:

import { buildAbstractFilterTree, $and, isFilterGroup } from "@sirzag/filter-ast";

const [root] = buildAbstractFilterTree({ a: 1, [$and]: { b: 2 } });
root.conditions.map((c) => isFilterGroup(c)); // [ false, true ]

The package stops at the tree. What an operator means, how null compares and which SQL comes out are the consumer's decisions. One possible mapping onto a Kysely where clause, db being a Kysely instance:

import { buildAbstractFilterTree, isFilterGroup, $and, joinOr } from "@sirzag/filter-ast";
import type { FilterExpression } from "@sirzag/filter-ast";
import type { Expression, ExpressionBuilder, SqlBool } from "kysely";

function toKysely(eb: ExpressionBuilder<any, any>, expr: FilterExpression): Expression<SqlBool> {
  if (isFilterGroup(expr)) {
    const parts = expr.conditions.map((c) => toKysely(eb, c));
    return expr.joinLogic === "and" ? eb.and(parts) : eb.or(parts);
  }
  const { field, operator, value } = expr;
  switch (operator) {
    case "eq": return eb(field, value === null ? "is" : "=", value);
    case "not": return eb(field, value === null ? "is not" : "!=", value);
    case "in": return eb(field, "in", value);
    case "between": return eb.between(field, (value as unknown[])[0], (value as unknown[])[1]);
    case "has": return eb(field, "@>", eb.val([value]));
    default: throw new Error(`Unsupported operator: ${operator}`);
  }
}

const tree = buildAbstractFilterTree({
  deletedAt: null,
  role: "$not(guest)",
  tags: "$has(vip)",
  [$and]: joinOr({ status: "$in(active,pending)", age: "$between(18,30)" }),
});

db.selectFrom("users").selectAll().where((eb) => eb.and(tree.map((g) => toKysely(eb, g))));

select * from "users"
where ("deletedAt" is null and "role" != $1 and "tags" @> $2 and ("status" in ($3, $4) or "age" between $5 and $6))
-- [ 'guest', [ 'vip' ], 'active', 'pending', 18, 30 ]

has is mapped to the Postgres array operator @> here; the remaining operators follow the same pattern. An empty tree compiles to 1 = 1. $in() compiles to in (), which Postgres rejects, so decide what an empty list means before this point. Validate field against the columns you expose before it reaches the query builder. Checked against Kysely 0.29.6.

Every $between validation error is a FilterError. It extends Error and carries the field and the raw operator string:

import { buildAbstractFilterTree, FilterError } from "@sirzag/filter-ast";

try {
  buildAbstractFilterTree({ age: "$between(30,18)" });
} catch (error) {
  if (error instanceof FilterError) {
    error.name;    // 'FilterError'
    error.field;   // 'age'
    error.value;   // '$between(30,18)'
    error.message; // 'First value in $between must be less than or equal to second value'
  }
}

A non-object root throws a plain TypeError, not a FilterError.

Cost of one buildAbstractFilterTree call, including allocation of the returned tree. Median of 11 rounds × 100 000 calls; each cell runs in its own process after a 20 000-call warm-up. Hot reuses one filter object. Fresh cycles through 4 096 distinct pre-built objects: construction is excluded, but every call sees a new object and new $and/$or symbols. Apple M4.

Bun 1.4.2

Node v24.10.0

Reproduce with bun run bench: builds dist, prints the table on Bun, then on Node. Workloads are defined in bench/bench.mjs.

• $and and $or work only as computed keys in object literals. They are not reusable symbols: each use creates a new key, so obj[$and] = { a: 1 } followed by obj[$and] returns undefined.
• Any symbol key whose description is "or" is treated as an OR branch. { a: 1, [Symbol("or")]: { b: 2 } } builds an OR of a and b.
• Input types are compile-time only. FilterInput rejects functions, symbols and plain objects as field values, but field values are not checked at runtime.
• There are no adapters and no SQL generation. Field names are passed through unsanitized ({ "name; DROP TABLE users": "x" } → field: 'name; DROP TABLE users'). Never concatenate them into SQL.

MIT