transducers

Groups the elements of the input collection into arrays of length n in the output collection.

Whatever the type of input collection, the groups inside the output collection will always be arrays (the output collection itself will still be definable as normal). Because of this, chunk doesn't do anything meaningful to collection types that cannot contain arrays (strings and objects, for instance).

If there are not enough remaining elements in the input collection to create a chunk of the proper size in the output collection, the last chunk in the output will only be large enough to contain those remaining elements.

chunk works on iterators (it returns a new iterator whose values are arrays), but because of technical reasons, the function has no way of knowing when the end of an iterator comes unless it happens to be at the same place as the last element of a chunk. For example, if an iterator has six values and it gets chunked into groups of three, the function will terminate correctly (because the last value of the iterator coincides with the last element of one of the chunks). However, if the same iterator had only five values, chunk would not terminate properly. It would return [1, 2, 3] for the first chunk, [4, 5] for the second chunk, and then [4, 5] over and over ad infinitum.

A workaround is to compose chunk with a previous take with the same n as the length of the iterator. Since take knows when it's reached the right number of elements, it can communicate that to chunk.

Another is to check the length of the chunk after each call to next on the iterator. If it's less than the size of the chunk, then it must be the last one.

chunk works as expected on infinite iterators.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = chunk([1, 2, 3, 4, 5], 3);
// result = [[1, 2, 3], [4, 5]]

Breaks the elements of an input collection into arrays of consecutive elements that return the same value from a predicate function.

Whatever the type of input collection, the groups inside the output collection will always be arrays (the output collection itself will still be of the same type as the input collection). Because of this, chunkBy doesn't do anything meaningful to collection types that cannot contain arrays (strings and objects, for instance).

Unlike chunk, this function does not know how many elements will be in each array until the first one that turns out to be part of the next array. Therefore, for the same reasons as in chunk above, an iterator result is never terminated. This works fine for infinite iterators, but finite iterators should be treated with care. The same chunk workaround with take works with chunkBy as well.

const result = chunkBy([0, 1, 1, 2, 3, 5, 8, 13, 21, 34], x => x % 2 === 0);
// result = [[0], [1, 1], [2], [3, 5], [8], [13, 21], [34]]

Removes any 'falsey' elements from the collection.

'Falsey' means any value in JavaScript that is considered to be false. These values are false, null, undefined, the empty string, and 0. This function is good for removing empy elements from a collection.

If the semantics don't suit - for example, if you want to remove empty elements but retain 0s - then use an appropriate function with either filter or reject.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = compact([1, 0, 2, null, 3, undefined, 4, '', 5]);
// result = [1, 2, 3, 4, 5]

Removes consecutive duplicate elements from a collection.

This differs from unique in that an element is removed only if it equals the element immediately preceeding it. Comparisons between elements are done with SameValueZero.

If no collection is provided, a function is returned that can be passed to sequence, et al.

let result = distinct([1, 1, 2, 3, 3, 3, 4, 5, 3, 1, 5]);
// result = [1, 2, 3, 4, 5, 3, 1, 5];

// Compare to unique with the same input
result = unique([1, 1, 2, 3, 3, 3, 4, 5, 3, 1, 5]);
// result = [1, 2, 3, 4, 5];

Applies a function each element of a collection and removes consecutive elements that create duplicate return values.

Once the function is applied to the collection elements, a comparison is made using SameValueZero. If a comparison indicates that the return value from the function for one element is the same as the return value for the element that comes right before it, only the first element is retained in the output collection.

Also note that even though the function can cause a completely different value to be compared, the element (not the return value of the function) is what is added to the output collection.

A very common use for distinctBy is to refer to a particular property in an array of objects. Another is to do a case-insensitive comparison by passing a function that turns every letter in a string to the same case. However, it can be used in any number of different ways, depending on the function used.

This is different from uniqueBy in that this transform only eliminates consecutive duplicate elements, not all duplicate elements.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const array = [{x: 1}, {x: 1}, {x: 2}, {x: 3}, {x: 3}, {x: 3},
               {x: 4}, {x: 5}, {x: 3}, {x: 1}, {x: 5}];

let result = distinctBy(array, obj => obj.x);
// result = [{x: 1}, {x: 2}, {x: 3}, {x: 4}, {x: 5}, {x: 3}, {x: 1}, {x: 5}]

// Compare to uniqueBy for the same parameters
result = uniqueBy(array, obj => obj.x);
// result = [{x: 1}, {x: 2}, {x: 3}, {x: 4}, {x: 5}]

Applies a comparator function to consecutive elements of a collection and removes the second if the comparator indicates they're equal.

Comparisons are made by passing each pair of elements to the function, which must take two parameters and return a boolean indicating whether or not the values are equal. As an example, the distinct transducer could be regarded as the same as this transformer, with a SameValueZero function serving as the comparator.

This is different from uniqueWith in that this transform only eliminates consecutive duplicate elements, not all duplicate elements.

If no collection is provided, a function is returned that can be passed to sequence, et al.

// magnitude returns the number of digits in a number
function magnitude(x) {
  return Math.floor(Math.log(x) / Math.LN10 + 0.000000001);
}
function comparator(a, b) {
  return magnitude(a) === magnitude(b);
}

let result = distinctWith([1, 10, 100, 42, 56, 893, 1111, 1000], comparator);
// result = [1, 10, 100, 42, 893, 1111]

// Compare to uniueqWith with the same parameters
result = uniqueWith([1, 10, 100, 42, 56, 893, 1111, 1000], comparator);
// result = [1, 10, 100, 1111]

Creates a new collection consisting of all of the elements of the input collection except for the first n elements.

While this could be considered an opposite of take, there is one difference: drop cannot return a finite collection when provided an infinite one.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = drop([1, 2, 3, 4, 5], 3);
// result = [4, 5]

Creates a new collection containing the elements of the input collection including the first one that causes a predicate function to return false and all elements thereafter.

This is rather the opposite of takeWhile, though unlike that function, this one cannot return a finite collection when given an infinite one. It's also related to reject, except that once the first element is not rejected, every element after that is also not rejected (even if they would make the predicate return true).

If no collection is provided, a function is returned that can be passed to sequence, et al.

const array = [2, 4, 6, 8, 1, 3, 5, 7, 9, 10];
const even = x => x % 2 === 0;

let result = dropWhile(array, even);
// result = [1, 3, 5, 7, 9, 10];

// This shows the difference between `dropWhile` and `reject` with the same parameters
result = reject(array, even);
// result = [1, 3, 5, 7, 9];

Creates a collection containing only the elements from the input collection that pass a predicate function.

The elements are not in any way modified. Quite simply, if the predicate returns true for an element, it's included in the output collection, and if it returns false, that element is not included.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const even = x => x % 2 === 0; *
const result = filter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], even);
// result = [2, 4, 6, 8, 10]

A map function that flattens any collections among the return values.

This is a composition of map and flatten. In fact it could be defined by the user by using those two functions with compose, but the concept of a flatmap is so fundamental that it's included separately.

Because the map is followed by flattening, there are the same notes as with flatten; this function doesn't make a lot of sense with functions that return objects, strings, or iterators.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const duplicate = x => [x, x];

let result = flatMap([1, 2, 3, 4, 5], duplicate);
// result = [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]

// The following is equivalent
const fn = compose(map(duplicate), flatten());
result = sequence([1, 2, 3, 4, 5], fn);
// result = [1, 1, 2, 2, 3, 3, 4, 4, 5, 5]

// To illustrate the difference from `map`, here's what `map` would do with
// the same parameters
result = map([1, 2, 3, 4, 5], duplicate);
// result = [[1, 1], [2, 2], [3, 3], [4, 4], [5, 5]]

Flattens a collection by merging elements in any sub-collection into the main collection.

Elements of the main collection that are not collections themselves are not changed. It's fine to have a combination of the two, some elements that are collections and some that are not.

Since there aren't sub-collections in objects, strings, or iterators, flatten doesn't make sense with those types of collections.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = flatten([[1, 2], [3, 4, 5], 6, [7]]);
// result = [1, 2, 3, 4, 5, 6, 7]

Returns exactly the same collection sent to it.

This is generally a function used when a transducer function is required but there is no desire to do an actual transformation. The "transformation" implemented here is to pass each element through exactly as it is.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = identity([1, 2, 3, 4, 5]);
// result = [1, 2, 3, 4, 5]

Creates a new collection whose values are the results of mapping input collection elements over a function.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = map([1, 2, 3, 4, 5], x => x * x);
// result = [1, 4, 9, 16, 25]

Creates a collection containing only the elements from the input collection that do not pass a predicate function.

This is the opposite of filter. None of the elements of the input collection are modified, and only those for which the predicate returns false are included in the output collection.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const even = x => x % 2 === 0;
const result = reject([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], even);
// result = [1, 3, 5, 7, 9]

Repeats each element from the input collection n times in the output collection.

These elements are put into the main output collection, not into subcollections. In other words, each input element creates n output elements.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = repeat([1, 2, 3, 4, 5], 3);
// result = [1, 1, 1, 2, 2, 2, 3, 3, 3, 4, 4, 4, 5, 5, 5]

Creates a new collection containing only the first n elements of the input collection.

Note that this is an excellent way to turn an 'infinite' collection - one that doesn't have a well-defined end, like a stream, channel, or infinite generator - into a finite collection.

If no collection is provided, a function is returned that can be passed to sequence, et al.

// An iterator that will return every positive integer, one at a time per next() call
function* naturals() {
  let x = 1;
  while (true) {
    yield x++;
  }
}

const result = take(naturals(), 3);
// result is now an iterator that has only three values in it
result.next().value === 1;  // true
result.next().value === 2;  // true
result.next().value === 3;  // true
result.next().done;         // true

Creates a new collection consisting of the first element of the input collection, and then every nth element after that.

Note that unlike take and takeWhile, this function is not capable of returning a finite collection when given an infinite collection.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const result = takeNth([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 3);
// result = [1, 4, 7, 10]

Creates a new collection containing the elements of the input collection up until the first one that causes a predicate function to return false.

While this is similar to filter, there is one key difference. takeWhile will not add any further elements to a collection once the first fails the predicate, including later elements that might pass the predicate. filter, on the other hand, will continue to add those later elements. Therefore takeWhile will convert an infinite collection to a finite one while filter cannot.

If no collection is provided, a function is returned that can be passed to sequence, et al.

const array = [2, 4, 6, 8, 1, 3, 5, 7, 9, 10];
const even = x => x % 2 === 0;

let result = takeWhile(array, even);
// result = [2, 4, 6, 8];

// This shows the difference between takeWhile and filter with the same parameters
result = filter(array, even);
// result = [2, 4, 6, 8, 10];

Removes all duplicates from a collection.

Once an element is added to the output collection, an equal element will never be added to the output collection again. 'Equal' according to this transformer is a SameValueZero comparison.

If no collection is provided, a function is returned that can be passed to sequence, et al.

var result = unique([1, 1, 2, 3, 3, 3, 4, 5, 3, 1, 5]);
// result = [1, 2, 3, 4, 5];

Applies a function each element of a collection and removes elements that create duplicate return values.

Once the function is applied to the collection elements, a comparison is made using SameValueZero. If a comparison indicates that the return value from the function for one element is the same as the return value for another element, only the first element is retained in the output collection.

Also note that even though the function can cause a completely different value to be compared, the element (not the return value of the function) is what is added to the output collection.

A very common use for uniqueBy is to refer to a particular property in an array of objects. Another is to do a case-insensitive comparison by passing a function that turns every letter in a string to the same case. However, it can be used in any number of different ways, depending on the function used.

If no collection is provided, a function is returned that can be passed to sequence, et al.

var array = [{x: 1}, {x: 1}, {x: 2}, {x: 3}, {x: 3}, {x: 3},
             {x: 4}, {x: 5}, {x: 3}, {x: 1}, {x: 5}];

var result = uniqueBy(array, obj => obj.x);
// result = [{x: 1}, {x: 2}, {x: 3}, {x: 4}, {x: 5}]

// Comparison is case-insensitive, the duplicate letter retained is the first one that appears
// This is why 'N' is present in the output, not 'n', for example
result = uniqueBy('aNtidiseSTablIshmENtaRianiSM', x => x.toLowerCase());
// result = 'aNtidseblhmR'

Removes all duplicates from a collection, using a comparator function to determine what's unique.

Comparisons are made by passing each pair of elements to the function, which must take two parameters and return a boolean indicating whether or not the values are equal. As an example, the unique transducer could be regarded as the same as this transducer, with a SameValueZero function serving as the comparator.

If no collection is provided, a function is returned that can be passed to sequence, et al.

Example:

// magnitude returns the number of digits in a number
function magnitude(x) {
  return Math.floor(Math.log(x) / Math.LN10 + 0.000000001);
}
function comparator(a, b) {
  return magnitude(a) === magnitude(b);
}

// Returns only the first value of each magnitude
const result = uniqueWith([1, 10, 100, 42, 56, 893, 1111, 1000], comparator);
// result = [1, 10, 100, 1111]