cascading-column-filter

Headless, Excel-style cascading column filtering engine for JavaScript and TypeScript.

This library provides only the filtering logic — no UI — so you can integrate it with React, Vue, Angular, Next.js, or plain JavaScript tables and dropdowns.

Why use this

• Decoupled logic: Implement UI however you like; the engine handles filter logic.
• Cascading filters: Filtering a column updates available options for downstream columns.
• Type-safe: Built with TypeScript-first APIs.

Contents

• Installation: add to your project
• Quick Start: small example showing typical usage
• API: methods and behavior
• Development & Tests: how to run the test suite

Installation

• npm: npm install cascading-column-filter
• yarn: yarn add cascading-column-filter
• pnpm: pnpm add cascading-column-filter

Quick Start (TypeScript)

import { createFilterEngine } from "cascading-column-filter";

type Row = { country: string; city: string; population: number };

const data: Row[] = [
  { country: "USA", city: "New York", population: 8_000_000 },
  { country: "USA", city: "Los Angeles", population: 4_000_000 },
  { country: "Canada", city: "Toronto", population: 2_700_000 },
];

const engine = createFilterEngine<Row>(data, ["country", "city"]);

// Set a filter on `country`
engine.setFilter("country", ["USA"]);

// Then get available options for `city` (only cities in USA remain)
const cityOptions = engine.getOptions("city");

// Get the filtered rows
const filtered = engine.getFilteredData();

API Reference

• createFilterEngine<T>(data: T[], columns: (keyof T)[]) — Create a new engine instance for the provided data and column order.

The returned engine exposes these methods:

• setFilter(column: keyof T, values: string[]) — Apply a filter on column using the provided list of string-selected values. Setting a filter for a column will drop filters for any columns that were applied after it (to preserve cascading correctness).

• clearFilter(column: keyof T) — Remove the filter on column. This also clears any cached downstream options.

• getOptions(column: keyof T): string[] — Compute and return the available option values for column given the current filters. If column itself is filtered, it returns the cached/original options.

• getFilteredData(): T[] — Return the dataset after applying the current filters.

Notes on behavior:

• Filters are stored and enforced in the order they are applied. Refiltering an earlier column automatically invalidates later filters.
• All option values and filter comparisons use string coercion (values are handled as string) to keep the engine simple and predictable.

Development & Tests

Install dependencies and run tests:

npm install
npm test

Build (if available):

npm run build

Contributing

• Please open issues for bugs or feature requests.
• Pull requests are welcome — keep changes focused and add tests for new behavior.

README for the excel-filter-engine package. See source in src/createFilteringEngine.ts for the implementation details.