npm package: @leo95/multi-criteria-filter
Description: A modular, fully typed, and reusable library that allows frontend developers (React/TypeScript) to dynamically filter arrays of objects.
Author: Leonardo Malvolti
Latest version: 0.1.3

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

```bash
npm install @leo95/multi-criteria-filter
```

### Usage in React 

```tsx
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)

```typescript
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
```typescript
// Creates a new filter manager instance.
createFilterManager<T>(data: T[], initialCriteria?: FilterCriteria<T>[])

```
#### Methods:
```typescript
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.

```tsx

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](https://github.com/Leo95995/multi-criteria-filter)  
- **GitHub Profile** – [Leonardo Malvolti](https://github.com/Leo95995)  
- **npm Package** – [@leo95/multi-criteria-filter](https://www.npmjs.com/package/@leo95/multi-criteria-filter)  
- **LinkedIn Profile** – [Leonardo Malvolti](https://www.linkedin.com/in/leonardo-malvolti/)