A modular, fully typed, and reusable filtering library for JavaScript and TypeScript projects, designed to handle multi-criteria filtering on arrays of objects with ease.

Built with TypeScript and optimized for React, this library provides a clean API for dynamic filtering without configuration.

Features

• ✅ Fully typed (TypeScript-first)
• ✅ Multiple filter criteria support
• ✅ AND / OR combinators
• ✅ Optional duplicate removal
• ✅ Framework-agnostic core logic
• ✅ React Hook included
• ✅ Zero configuration required

Installation

npm install @leo95/multi-criteria-filter

Usage in React

import { useDynamicFilterHook } from "@leo95/multi-criteria-filter";
import type { FilterCriteria } from "@leo95/multi-criteria-filter";

type Person = {
  id: number;
  name: string;
  age: number;
};

const data: Person[] = [
  { id: 1, name: "Alice", age: 25 },
  { id: 2, name: "Bob", age: 40 },
  { id: 3, name: "Charlie", age: 30 },
];

const initialCriteria: FilterCriteria<Person>[] = [
  { key: "age", operator: "greaterThan", value: 30 },
];

export const ExampleComponent = () => {
  const {
    results,
    criterias,
    updateFilters,
    resetFilters,
    setCombinator,
    removeDuplicate,
  } = useDynamicFilterHook({ data, initialCriteria });

  return (
    <>
      <button onClick={() => setCombinator("AND")}>AND</button>
      <button onClick={() => setCombinator("OR")}>OR</button>

      <button
        onClick={() =>
          updateFilters([{ key: "age", operator: "lesserThan", value: 35 }])
        }
      >
        Update Filters
      </button>

      <button onClick={resetFilters}>Reset</button>
      <button onClick={() => removeDuplicate(true)}>Remove Duplicates</button>

      <pre>{JSON.stringify(results, null, 2)}</pre>
    </>
  );
};

General Purpose usage (Without React)

import { createFilterManager } from "@leo95/multi-criteria-filter";
import type { FilterCriteria } from "@leo95/multi-criteria-filter";

type Person = {
  id: number;
  name: string;
  age: number;
};

const people: Person[] = [
  { id: 1, name: "Alice", age: 25 },
  { id: 2, name: "Bob", age: 40 },
  { id: 3, name: "Charlie", age: 30 },
];

const criteria: FilterCriteria<Person>[] = [
  { key: "age", operator: "greaterThan", value: 30 },
];

const manager = createFilterManager(people, criteria);

console.log(manager.getFilteredData()); // [{ id: 2, name: "Bob", age: 40 }]

API Reference

// Creates a new filter manager instance.
createFilterManager<T>(data: T[], initialCriteria?: FilterCriteria<T>[])

Methods:

getFilteredData(options?: { removeDuplicates?: boolean }): T[] // Returns filtered results.

updateFilter(newCriterias: FilterCriteria<T>[]): void //Updates active filter criteria.

resetFilters(): void // Resets all criteria to initial state.

setCombinator(combinator: "AND" | "OR"): void // Sets the logical combinator.

React Hook wrapper around createFilterManager.

useDynamicFilterHook<T>({ data, initialCriteria }) // React Hook

// Returned Values:

results // Current filtered results

criterias // Current active filter criteria

updateFilters(newCriterias) // Updates criteria

resetFilters()  // Resets criteria

setCombinator("AND" | "OR") // Sets combinator

removeDuplicate(status?: boolean) // Toggles duplicate removal

refreshResults() // Refreshes the filtered results

Tips & Tricks

Use AND for restrictive filtering and OR for inclusive filtering.

Call removeDuplicate(true) when you want a unique set of results.

You can dynamically update criteria without re-creating the filter manager.

Works well for large arrays of objects, optimized for performance.

Current Limitations

⚠️ Only works with arrays of objects (does not currently support primitive arrays like string[] or number[]).

Contributing

Contributions, issues, and feature requests are welcome!

Fork the repo

Create your branch (git checkout -b feature-name)

Commit your changes (git commit -m 'Add feature')

Push to the branch (git push origin feature-name)

Open a Pull Request

License

This project is licensed under the MIT License.

Links & Resources

• GitHub Repository – @leo95995/multi-criteria-filter
• GitHub Profile – Leonardo Malvolti
• npm Package – @leo95/multi-criteria-filter
• LinkedIn Profile – Leonardo Malvolti