Array Ninja 🥷🏻

Overview

Array Ninja is a powerful and easy-to-use NPM package for manipulating arrays in JavaScript. With Array Ninja, you can perform a wide range of operations on arrays, such as sorting, filtering, mapping, and more. It provides a clean and efficient way to work with arrays, making it a valuable tool for any JavaScript developer.

Features

Array Ninja exposes a const Arr for the class called ArrayNinja which includes the following features:

| # | Function | Description | |----|--------------------------------|-------------------------------------------------------------------------------------------------| | 1 | findIndex(arr, value) | Find the index of the first item in the array that matches the given value. Returns -1 if no match is found. | | 2 | contains(arr, value) | Check if an array contains a value. Returns a boolean. | | 3 | append(arr, data) | Append an element to the end of an array. Returns the modified array. | | 4 | flatten(arr) | Flatten a nested array. Returns a new array. | | 5 | crossJoin(...arrays) | Cross join multiple arrays. Returns a new array. | | 6 | extract(arr, keys) | Extract specific keys from an array of objects. Returns a new array with the extracted keys. | | 7 | extractFromKey(arr, key) | Extracts the values of a specific key from each object present in the array | | 8 | removeKeys(arr, keys) | Remove specific keys from an array of objects. Returns the modified array. | | 9 | findFirst(arr, key, comparisonOperator, value) | Find the first object in the array that matches the given key, comparison operator, and value. Returns the object or null. | | 10 | findAll(arr, key, comparisonOperator, value) | Find all objects in the array that match the given key, comparison operator, and value. Returns an array of objects. | | 11 | isSequentialArray(arr) | Check if an array is a sequential array (an array of numbers starting from 0). Returns a boolean.| | 12 | joinArrayElements(arr, intermediateJoiner, finalElementJoiner) | Join elements in an array with a separator. Returns a string. | | 13 | groupArrayByKey(arr, key) | Group objects in an array by a specific key. Returns a new array. | | 14 | getLastElement(arr) | Get the last element of an array. | | 15 | mapKeyValues(arr, key1, key2)| Map specific keys of an array of objects into a new array. Returns a new array. | | 16 | prepend(arr, item) | Prepend an element to the beginning of an array. Returns the modified array. | | 17 | removeNestedKey(arr, path) | Remove a nested key from objects in an array. Returns the modified array. | | 18 | sortByKey(arr, key, sortOrder)| Sort an array of objects by a specific key. Returns the modified array. | | 19 | sumOfKey(arr, key) | Calculate the sum of a specific key across all objects in the array. Returns a number. | | 20 | countOccurence(arr, key, value, isStrict) | Count the number of occurrences of a specific key-value pair in an array of objects. Returns a number. | | 21 | sum(arr, decimalPlaces) | Sum elements in an array. Returns a number. | | 22 | unique(arr) | Get a unique set of values in an array. Returns a new array. | | 23 | clean(arr) | Remove null or undefined elements from an array. Returns a new array. | | 24 | min(arr) | Get the minimum value in an array of numbers. Returns a number or null. | | 25 | max(arr) | Get the maximum value in an array of numbers. Returns a number or null. | | 26 | sort(arr, sortOrder) | Sort an array. Returns the modified array.

Installation

To install Array Ninja, simply run the following command in your terminal:

npm install array-ninja

Usage

Here's a quick example of how to use Array Ninja methods:

1. findIndex(arr, value)

This method finds the index of the first item in the array that matches the given value. It returns -1 if no match is found.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [5, 7, 2, 4, 1, 8];
const index1 = Arr.findIndex(arr1, 2); // Output: 2

// Example 2
const arr2 = ['apple', 'banana', 'orange', 'strawberry'];
const index2 = Arr.findIndex(arr2, 'orange'); // Output: 2

2. contains(arr, value)

This method checks if an array contains a specific value and returns a boolean.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [5, 7, 2, 4, 1, 8];
const hasValue1 = Arr.contains(arr1, 2); // Output: true

// Example 2
const arr2 = ['apple', 'banana', 'orange', 'strawberry'];
const hasValue2 = Arr.contains(arr2, 'grape'); // Output: false

3. append(arr, data)

This method appends an element to the end of an array and returns the modified array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, 2, 3];
const newArr1 = Arr.append(arr1, 4); // Output: [1, 2, 3, 4]

// Example 2
const arr2 = ['apple', 'banana'];
const newArr2 = Arr.append(arr2, 'orange'); // Output: ['apple', 'banana', 'orange']

4. flatten(arr)

This method flattens a nested array and returns a new array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, [2, [3, [4]], 5]];
const flatArr1 = Arr.flatten(arr1); // Output: [1, 2, 3, 4, 5]

// Example 2
const arr2 = [[1, 2], [3, 4], [5, 6]];
const flatArr2 = Arr.flatten(arr2); // Output: [1, 2, 3, 4, 5, 6]

5. crossJoin(...arrays)

This method cross joins multiple arrays and returns a new array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, 2];
const arr2 = ['a', 'b'];
const result1 = Arr.crossJoin(arr1, arr2); // Output: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]

// Example 2
const arr3 = ['x', 'y'];
const arr4 = [true, false];
const result2 = Arr.crossJoin(arr3, arr4); // Output: [['x', true], ['x', false], ['y', true], ['y', false]]

6. extract(arr, keys)

This method extracts specific keys from an array of objects and returns a new array with the extracted keys.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
const extractedData1 = Arr.extract(arr1, ['name']); // Output: [{ name: 'Alice' }, { name: 'Bob' }]

// Example 2
const arr2 = [{ title: 'Task 1', priority: 'high' }, { title: 'Task 2', priority: 'low' }];
const extractedData2 = Arr.extract(arr2, ['priority']); // Output: [{ priority: 'high' }, { priority: 'low' }]

7. extractFromKey(arr, key)

This method extracts the values of a specified key from each object present in the array, returning a new array with the extracted values.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
const extractedNames = Arr.extractFromKey(arr1, 'name'); // Output: ['Alice', 'Bob']

// Example 2
const arr2 = [{ title: 'Task 1', priority: 'high' }, { title: 'Task 2', priority: 'low' }];
const extractedPriorities = Arr.extractFromKey(arr2, 'priority'); // Output: ['high', 'low']

8. removeKeys(arr, keys)

This method removes specific keys from an array of objects and returns the modified array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
const modifiedArr1 = Arr.removeKeys(arr1, ['age']);
// Output: [{ name: 'Alice' }, { name: 'Bob' }]

// Example 2
const arr2 = [{ title: 'Task 1', priority: 'high' }, { title: 'Task 2', priority: 'low' }];
const modifiedArr2 = Arr.removeKeys(arr2, ['priority']);
// Output: [{ title: 'Task 1' }, { title: 'Task 2' }]

9. findFirst(arr, key, comparisonOperator, value)

This method finds the first object in the array that matches the given key, comparison operator, and value. It returns the object or null.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
const result1 = Arr.findFirst(arr1, 'age', Arr.Compare.GREATER_THAN, 28);
// Output: { name: 'Bob', age: 30 }

// Example 2
const arr2 = [{ name: 'Alice', role: 'admin' }, { name: 'Bob', role: 'user' }, { name: 'Charlie', role: 'admin' }];
const result2 = Arr.findFirst(arr2, 'role', Arr.Compare.EQUALS, 'admin');
// Output: { name: 'Alice', role: 'admin' }

All Comparison Operators Available For Use

| Comparison Operator | Description | | --- | --- | | Arr.Compare.EQUALS | Equals | | Arr.Compare.EQUALS_STRICT | Equals (Strict) | | Arr.Compare.NOT_EQUALS | Not Equals | | Arr.Compare.NOT_EQUALS_STRICT | Not Equals (Strict) | | Arr.Compare.GREATER_THAN | Greater Than | | Arr.Compare.GREATER_THAN_OR_EQUAL | Greater Than or Equal | | Arr.Compare.LESS_THAN | Less Than | | Arr.Compare.LESS_THAN_OR_EQUAL | Less Than or Equal |

10. findAll(arr, key, comparisonOperator, value)

This method finds all objects in the array that match the given key, comparison operator, and value. It returns an array of objects.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 },
  { name: 'Charlie', age: 25 }
];
const result1 = Arr.findAll(arr1, 'age', Arr.Compare.EQUALS, 25);
// Output: [{ name: 'Alice', age: 25 }, { name: 'Charlie', age: 25 }]

// Example 2
const arr2 = [
  { department: 'Sales', job: 'Salesperson', age: 25 },
  { department: 'Sales', job: 'Manager', age: 30 },
  { department: 'Marketing', job: 'Marketer', age: 25 }
];
const result2 = Arr.findAll(arr2, 'department', Arr.Compare.EQUALS, 'Sales');
// Output: [
//   { department: 'Sales', job: 'Salesperson', age: 25 },
//   { department: 'Sales', job: 'Manager', age: 30 }
// ]

11. isSequentialArray(arr)

This method checks if an array is a sequential array (an array of numbers starting from 0). It returns a boolean.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [0, 1, 2, 3, 4];
const result1 = Arr.isSequentialArray(arr1);
// Output: true

// Example 2
const arr2 = [5, 6, 8, 7, 9];
const result2 = Arr.isSequentialArray(arr2);
// Output: false

12. joinArrayElements(arr, intermediateJoiner, finalElementJoiner)

This method joins elements in an array with a separator and returns a string.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = ['apple', 'banana', 'orange'];
const result1 = Arr.joinArrayElements(arr1, ', ', 'and');
// Output: 'apple, banana, and orange'

// Example 2
const arr2 = [10, 20, 30, 40];
const result2 = Arr.joinArrayElements(arr2, ' > ', 'end');
// Output: '10 > 20 > 30 > end 40'

13. groupArrayByKey(arr, key)

This method groups objects in an array by a specific key and returns a new array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { department: 'Sales', sales: 100 },
  { department: 'IT', sales: 200 },
  { department: 'HR', sales: 150 },
  { department: 'Sales', sales: 120 }
];
const result1 = Arr.groupArrayByKey(arr1, 'department');
// Output: [
//   { 'Sales': [{ department: 'Sales', sales: 100 }, { department: 'Sales', sales: 120 }] },
//   { 'IT': [{ department: 'IT', sales: 200 }] },
//   { 'HR': [{ department: 'HR', sales: 150 }] }
// ]

// Example 2
const arr2 = [
  { category: 'A', value: 10 },
  { category: 'B', value: 20 },
  { category: 'A', value: 30 },
  { category: 'B', value: 40 }
];
const result2 = Arr.groupArrayByKey(arr2, 'category');
// Output: [
//   { 'A': [{ category: 'A', value: 10 }, { category: 'A', value: 30 }] },
//   { 'B': [{ category: 'B', value: 20 }, { category: 'B', value: 40 }] }
// ]

14. getLastElement(arr)

This method gets the last element of an array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, 2, 3, 4];
const lastElement1 = Arr.getLastElement(arr1);
// Output: 4

// Example 2
const arr2 = ['apple', 'banana', 'orange'];
const lastElement2 = Arr.getLastElement(arr2);
// Output: 'orange'

15. mapKeyValues(arr, key1, key2)

This method maps the key1 values with key2 values from an array of objects.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 }
];
const mappedArray1 = Arr.mapKeyValues(arr1, 'name', 'age');
// Output: [{ 'Alice': 25 }, { 'Bob': 30 }]

// Example 2
const arr2 = [
  { city: 'New York', population: 8000000 },
  { city: 'Los Angeles', population: 4000000 }
];
const mappedArray2 = Arr.mapKeyValues(arr2, 'city', 'population');
// Output: [{ 'New York': 8000000 }, { 'Los Angeles': 4000000 }]

16. prepend(arr, item)

This method prepends an element to the beginning of an array and returns the modified array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [2, 3, 4];
const newArr1 = Arr.prepend(arr1, 1);
// Output: [1, 2, 3, 4]

// Example 2
const arr2 = ['banana', 'orange'];
const newArr2 = Arr.prepend(arr2, 'apple');
// Output: ['apple', 'banana', 'orange']

17. removeNestedKey(arr, path)

This method removes a nested key from objects in an array and returns the modified array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { details: { id: 1, name: 'Alice' } },
  { details: { id: 2, name: 'Bob' } }
];
const modifiedArr1 = Arr.removeNestedKey(arr1, 'details.id');
// Output: [ { details: { name: 'Alice' } }, { details: { name: 'Bob' } } ]

// Example 2
const arr2 = [
  { info: { address: { city: 'New York' } } },
  { info: { address: { city: 'Los Angeles' } } }
];
const modifiedArr2 = Arr.removeNestedKey(arr2, 'info.address.city');
// Output: [ { info: { address: {} } }, { info: { address: {} } } ]

18. sortByKey(arr, key, sortOrder)

This method sorts an array of objects by a specific key and returns the modified array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 },
  { name: 'Charlie', age: 20 }
];
const sortedArr1 = Arr.sortByKey(arr1, 'age', Arr.Sort.ASC);
// Output: [
//   { name: 'Charlie', age: 20 },
//   { name: 'Alice', age: 25 },
//   { name: 'Bob', age: 30 }
// ]

// Example 2
const arr2 = [
  { category: 'Fruit', name: 'Apple' },
  { category: 'Vegetable', name: 'Carrot' },
  { category: 'Fruit', name: 'Banana' }
];
const sortedArr2 = Arr.sortByKey(arr2, 'category', Arr.Sort.DESC);
// Output: [
//   { category: 'Vegetable', name: 'Carrot' },
//   { category: 'Fruit', name: 'Apple' },
//   { category: 'Fruit', name: 'Banana' }
// ]

19. sumOfKey(arr, key)

This method calculates the sum of a specific key across all objects in the array and returns a number.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { price: 10 },
  { price: 20 },
  { price: 30 }
];
const total1 = Arr.sumOfKey(arr1, 'price');
// Output: 60

// Example 2
const arr2 = [
  { count: 5 },
  { count: 10 },
  { count: 15 }
];
const total2 = Arr.sumOfKey(arr2, 'count');
// Output: 30

20. countOccurence(arr, key, value, isStrict)

This method counts the number of occurrences of a specific key-value pair in an array of objects and returns a number.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [
  { color: 'red' },
  { color: 'blue' },
  { color: 'red' }
];
const count1 = Arr.countOccurence(arr1, 'color', 'red', true);
// Output: 2

// Example 2
const arr2 = [
  { code: 1 },
  { code: '1' },
  { code: 1 }
];
const count2 = Arr.countOccurence(arr2, 'code', 1, false);
// Output: 3

21. sum(arr, decimalPlaces)

This method calculates the sum of elements in an array and returns a number. The decimalPlaces defaults to 4 digits after dot(.), however you can change it as per your need.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, 2, 3, 4, 5];
const total1 = Arr.sum(arr1);
// Output: 15

// Example 2
const arr2 = [0.1, 0.2, 0.3];
const total2 = Arr.sum(arr2);
// Output: 0.6000

22. unique(arr)

This method gets a unique set of values in an array and returns a new array. It also removes the duplicate, null, and undefined values.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, 2, 3, 1, 2, 4, 5];
const uniqueValues1 = Arr.unique(arr1);
// Output: [1, 2, 3, 4, 5]

// Example 2
const arr2 = ['apple', 'orange', 'banana', 'apple'];
const uniqueValues2 = Arr.unique(arr2);
// Output: ['apple', 'orange', 'banana']

23. clean(arr)

This method removes null or undefined elements from an array and returns a new array.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [1, 2, null, 4, undefined, 6];
const cleanedArr1 = Arr.clean(arr1);
// Output: [1, 2, 4, 6]

// Example 2
const arr2 = [null, 'apple', 'orange', undefined, 'banana'];
const cleanedArr2 = Arr.clean(arr2);
// Output: ['apple', 'orange', 'banana']

24. min(arr)

This method gets the minimum value in an array of numbers and returns a number, or null if the array is empty.

import { Arr } from 'array-ninja';

// Example 1
const arr = [25, 10, 60, 5];
const minValue = Arr.min(arr);
// Output: 5

25. max(arr)

This method gets the maximum value in an array of numbers and returns a number, or null if the array is empty.

import { Arr } from 'array-ninja';

// Example
const arr = [25, 10, 60, 5];
const maxValue = Arr.max(arr);
// Output: 60

26. sort(arr, sortOrder)

This method sorts an array and returns the modified array. The sortOrder parameter can be 'asc' for ascending order or 'desc' for descending order.

import { Arr } from 'array-ninja';

// Example 1
const arr1 = [3, 1, 4, 1, 5, 9, 2];
const sortedArr1 = Arr.sort(arr1, Arr.Sort.ASC);
// Output: [1, 1, 2, 3, 4, 5, 9]

// Example 2
const arr2 = ['peach', 'apple', 'banana', 'orange'];
const sortedArr2 = Arr.sort(arr2, Arr.Sort.DESC);
// Output: ['peach', 'orange', 'banana', 'apple']

For more detailed usage instructions and documentation, please refer to the official documentation.

License

Array Ninja is licensed under the MIT license.

Contact

If you have any questions or inquiries about Array Ninja, please feel free to contact me at Contact Page - Official Website.

Happy array manipulation! 🥷🏼