Array-Querier is a TS/JS NPM Package to Filter an Array of objects with multiple match-criteria.
- 🟢 Array Querier 🔎
- 📚 Table Of Contents 📑
- 💨 What is this Library for? 🤔
- ✨ Key Features 🎯
- 📥 Installation 🔰
- 🤔 One-Level vs Multi-Level Depth JSON ? 🤔
- ⚙ Usage: One-Level Depth Arrays (Simple Arrays) 🎚
- ⚙ Usage: Multi-Level Depth Arrays (Complex Arrays) 🎛
- Configuration Options
- Contributing ❤
- Issue Reporting
- GREETINGS
- Author
- License
array-querier is a small library that is useful for filtering a One Level or Multi Level Depth array of objects with multiple match-criteria. The exposed methods receives an array as the first argument, and a plain object describing the fields to filter as the last argument.
Note: This library can only be used with typescript or js but you already know that 🤦🏿♂️.
- Use it without
Instanciationbecause all the methods areStatic. - Multi Level Depth Filtering with complex filtering condition.
- Optimized for Great Performance even with Big Fat @/@ Arrays of Objects.
- ✅ TOO EASY TO USE !! 🥳🥳
# installation with npm
npm install array-querier
# or you may prefer
npm i --save array-querier
# installation with yarn
yarn add array-querierThis HELPER relies on NOTHING SO YOU DON'T NEED ADDITIONNAL PACKAGES.
A JSON depth level is just an nesting of another object within a current JSON object. For example : If you have a User object as follows ->
// Nested Object Planet in User
User = {
"name": "Orbit",
"age": 21,
"planet": {
"id": 4,
"codename" : "Shadow-Coders",
"galaxyName" : "Turner"
}
}Then User is an Array of two level Depth.
Of course if you don't have any nested object then you got an One level Depth.
If you are only interested in filtering an simple array of JSON objects directly:
import {Querier} from 'array-querier/lib/orbiter';
/**
* Your array of JSON Objects.
* This can be pulled directly from your Backend Rest API.
*/
const products = [
{ name: 'A', color: 'Blue', size: 50 },
{ name: 'B', color: 'Blue', size: 60 },
{ name: 'C', color: 'Black', size: 70 },
{ name: 'D', color: 'Green', size: 50 },
];
// ⚠ You need a Filter Object to make your condition ⚠
const filters = {
color: ['BLUE', 'black'],
size: [70, 50],
};
/**
* Calling Simple Array Filterer In Query.
* Filters an array of objects (one level-depth) with multiple criteria.
* The function returns an array of the same type as the input array.
*/
const MyFilteredResult = Querier.filterSimpleArray(products, filters);
console.table(MyFilteredResult);
/* 🟢 The Result Will Be :🟢
{ name: 'A', color: 'Blue', size: 50 },
{ name: 'C', color: 'Black', size: 70 },
*/⚠ Note: ⚠ The
filterSimpleArraymethod IS NOT Case-Sensitive 🚨.
In everyday life, as developers, our JSON arrays are often very complex because of foreign keys and / or the nesting of objects that allow us to better describe our entities.
In this case this Method is the most appropriate because it allows to apply very advanced filters to our Array regardless of the depth level.
import {Querier} from 'array-querier/lib/orbiter';
/**
* Your Complex array of JSON Objects.
* This can be pulled directly from your Backend Rest API.
*/
const products = [
{ name: 'Orbit', color: 'Blue', size: 50, locations: ['USA', 'Europe'], details: { length: 20, width: 70 } },
{ name: 'Galsen', color: 'Blue', size: 60, locations: [], details: { length: 20, width: 70 } },
{ name: 'DaoudaBa', color: 'Black', size: 70, locations: ['Japan'], details: { length: 20, width: 71 } },
{ name: 'Mmnl', color: 'Green', size: 50, locations: ['USA'], details: { length: 20, width: 71 } },
];
// ⚠ Filter Object with complex conditions ⚠
const filters = {
size: (size: number) => size === 50 || size === 70,
color: (color: string) => ['blue', 'black'].includes(color.toLowerCase()),
locations: (locations: any[]) => locations.find(x => ['JAPAN', 'USA'].includes(x.toUpperCase())),
details: (details: { length: number; width: number; }) => details.length < 30 && details.width >= 70,
};
/**
* Calling Simple Array Filterer In Query.
* Filters an array of objects (one level-depth) with multiple criteria.
* The function returns an array of the same type as the input array.
*/
const MyFilteredResult = Querier.filterComplexArray(products, filters);
console.table(MyFilteredResult);
/* 🟢 The Result Will Be :🟢
{ name: 'A', color: 'Blue', size: 50, locations: ['USA', 'Europe'], details: { length: 20, width: 70 } },
{ name: 'C', color: 'Black', size: 70, locations: ['Japan'], details: { length: 20, width: 71 } },
*/The Filter can be more complex and advance like the following use case case :
...
// ⚠ Filter Object with VERY Complex Conditions 🏃🏾♂️🏃🏾♂️⚠
const filters = {
size: (size: number) => size === 50 || size === 70,
color: (color: string) => ['blue', 'black'].includes(color.toLowerCase()),
details: (details: { length: number; width: number; }) => details.length < 30 && details.width >= 70,
locations: (locations: string | string[]) => {
if (locations.includes('USA')) { return true; } // case sensitive
if (locations.includes('Japan')) { return true; } // case sensitive
const url = window.location.pathname.toLowerCase();
if (url.includes('/en-us/')) { return true; } // not case sensitive
if (url.includes('/es/')) { return true; } // not case sensitive
return false;
}
};
const MyFilteredResult = Querier.filterComplexArray(products, filters);✨🤗 AS I SAID BEFORE : EASYYY 🤗✨
Coming Soon !
👋🏾 Pull requests are welcome!
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
❤❤ Coming Soon ! ❤❤
This project is licensed under the MIT license. See the LICENSE file for more info.
❤ MADE WITH LOVE ❤
