You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# split-filter-n
|
|
|
|
Like `Array#filter`, but lets you categorize an array of items into *many* arrays, based on a predicate function.
|
|
|
|
If you just want to split an array into two parts (eg. based on a `true`/`false` result), you'll probably want to use [`split-filter`](https://www.npmjs.com/package/split-filter) instead.
|
|
|
|
## Example
|
|
|
|
```js
|
|
"use strict";
|
|
|
|
const splitFilterN = require("split-filter-n");
|
|
|
|
let words = [
|
|
"apple",
|
|
"Banana",
|
|
"strawberry",
|
|
"Avocado"
|
|
];
|
|
|
|
let letterIndex = splitFilterN(words, ["A", "B", "C"], (word) => word[0].toUpperCase());
|
|
|
|
console.log(letterIndex);
|
|
|
|
/*
|
|
{
|
|
A: [ 'apple', 'Avocado' ]
|
|
B: [ 'Banana' ],
|
|
C: [],
|
|
S: [ 'strawberry' ]
|
|
}
|
|
*/
|
|
```
|
|
|
|
## API
|
|
|
|
### splitFilterN(array, ensureCategories, predicate)
|
|
|
|
Splits the `array` into an object of arrays, keyed by whatever the `predicate` function returned for each value.
|
|
|
|
- __array:__ The array to split.
|
|
- __ensureCategories:__ An array of strings, indicating which categories should always exist on the result object (explained further below). Set this to an empty array (`[]`) if you don't need this feature.
|
|
- __predicate:__ The function that determines which category to sort the value into. This function should return a string, indicating the desired category for the value. This predicate function receives two arguments, of which you'll usually only need the first one:
|
|
- __value:__ The value itself.
|
|
- __index:__ The index of the value in the array you've provided.
|
|
|
|
Returns an object - one key for each category, with the corresponding value being an array of items that were sorted into that category.
|
|
|
|
Note that the keys on the object come from two sources:
|
|
- Each unique string returned from the `predicate` function will become a category key.
|
|
- Each string in the `ensureCategories` array will also become a category key.
|
|
|
|
The reason for the `ensureCategories` option is that you'll often want to use [object destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Object_destructuring), like so:
|
|
|
|
```js
|
|
let { low, medium, high } = splitFilterN(values, [], predicate);
|
|
|
|
for (let mediumValue of medium) {
|
|
// some more logic...
|
|
}
|
|
```
|
|
|
|
Now, what if there *were* no values in `values` that returned `"medium"` from the `predicate` function? The `medium` variable would be set to `undefined`, and the `for` statement would produce an error, as you can't iterate over `undefined`. This is of course very impractical if you can't predict what values you're going to encounter.
|
|
|
|
Since it's not possible in JS for a function to detect what variables it will be destructured into, you'll have to explicitly *tell* the `splitFilterN` function what categories you want to always exist - and you do that through the `ensureCategories` argument. Whatever categories are listed in that argument, will *always* be an array in the result object, even if no items matched it.
|
|
|
|
Using the `ensureCategories` argument still lets you create undeclared categories through the `predicate` return value, of course - it just ensures that a particular set of categories is always there no matter what, so that you can safely destructure the result.
|
|
|
|
Example:
|
|
|
|
```js
|
|
let { low, medium, high } = splitFilterN(values, [ "low", "medium", "high" ], predicate);
|
|
|
|
for (let mediumValue of medium) {
|
|
// some more logic...
|
|
}
|
|
```
|
|
|
|
Now the `for` statement will always work.
|
|
|
|
__If it's an optional feature, why does it come before the required `predicate`?__ Because a predicate function will very often need to be more than one line, and having it at the end makes it easier to format your code well, regardless of what code style you use. Setting it to `[]` if you don't need it is pretty unobtrusive, and means that this library doesn't need to support overloaded syntax (which would make it unnecessarily fragile).
|
|
|
|
## Changelog
|
|
|
|
### 1.1.3 (March 20, 2022)
|
|
|
|
- Return a null-prototype object instead.
|
|
|
|
### 1.1.2 (February 17, 2020)
|
|
|
|
- Fixed repository URL in package.json
|
|
|
|
### 1.1.1 (August 25, 2019)
|
|
|
|
- Fixed `require` in documentation example.
|
|
- Fixed changelog formatting.
|
|
|
|
### 1.1.0 (August 19, 2019)
|
|
|
|
- __New:__ Predicate function now also receives the index of the value as an argument, not just the value itself.
|
|
|
|
### 1.0.1 (August 19, 2019)
|
|
|
|
- Clarified `ensureCategories` documentation with additional example.
|
|
|
|
### 1.0.0 (August 19, 2019)
|
|
|
|
Initial release.
|