xduce

The mapping of protocol names to their respective property key names.

The values of this map will depend on whether symbols are available, whatever is present here will be used as key names for protocol properties throughout the library.

Transforms the elements of the input collection and reduces them into a new array.

The transformer is optional. If it isn't present, this function just converts the input collection into an array.

const xform = map(x => x + 1);

let result = asArray([1, 2, 3, 4, 5], xform);
// result = [2, 3, 4, 5, 6]

result = asArray('12345', xform);
// result = [2, 3, 4, 5, 6]

result = asArray('12345');
// result = [1, 2, 3, 4, 5]

result = asArray({a: 1, b: 2});
// result = [{a: 1}, {b: 2}]

Transforms the elements of the input collection and reduces them into a new iterator.

The transformer is optional. If it isn't present, this function just converts the input collection into an iterator.

(The results here are shown passed through asArray because there's no literal interpretation of an iterator to show. The asArray calls are for demonstration purposes only.)

const xform = map(x => x + 1);
function* five() {
  for (let i = 1; i <= 5; ++i) {
    yield i;
  }
};

let result = asIterator(five(), xform);
// asArray(result) = [2, 3, 4, 5, 6]

result = asIterator([1, 2, 3, 4, 5], xform);
// asArray(result) = [2, 3, 4, 5, 6]

result = asIterator([1, 2, 3, 4, 5]);
// asArray(result) = [1, 2, 3, 4, 5]

result = asIterator({a: 1, b: 2});
// asArray(result) = [{a: 1}, {b: 2}]

Transforms the elements of the input collection and reduces them into a new object.

The transformer is optional. If it isn't present, this function just converts the input collection into an object.

const xform = map(({ k, v }) => ({ [k]: v + 1 }));

let result = asObject({a: 1, b: 2}, xform);
// result = {a: 2, b: 3}

result = asObject([{a: 1}, {b: 2}], xform);
// result = {a: 2, b: 3}

result = asObject([1, 2, 3, 4, 5]);
// result = {0: 1, 1: 2, 2: 3, 3: 4, 4: 5}

result = asObject('hello');
// result = {0: 'h', 1: 'e', 2: 'l', 3: 'l', 4: 'o'}

Transforms the elements of the input collection and reduces them into a new string.

The transformer is optional. If it isn't present, this function just converts the input collection into an string.

const xform = map(x => x.toUpperCase());

let result = asString('hello', xform);
// result = 'HELLO'

result = asString(['h', 'e', 'l', 'l', 'o'], xform);
// result = 'HELLO'

result = asString([1, 2, 3, 4, 5]);
// result = '12345'

result = asString({a: 1, b: 2});
// result = '12'

Composes two or more transducer functions into a single transducer function.

Each function that takes a transducer function (sequence, into, etc.) is only capable of accepting one of them. If there is a need to have several transducers chained together, then use compose to create a transducer function that does what all of them do.

This operates only on transducer functions, not on transducers themselves. There is no option for a shortcut form on a composed transducer function. They must be passed to functions that operate on them (sequence and the like).

NOTE: In functional programming, a compose function is generally ordered so that the first-executed function is listed last. This is done in the opposite way, with the first transducer executing first, etc. This is more sensible for transducer functions.

const add1 = x => x + 1;
const odd = x => x % 2 !== 0;

const xform = compose(map(add1), filter(odd), take(3));

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

Transforms the elements of the input collection and reduces them into the target collection.

This is much like transduce, except that instead of explicitly providing a reducer (and perhaps an initial collection), the target collection acts as a reducer itself. This requires that the collection implement the init, result, and step transducer protocol functions.

If no transducer function is provided, the input collection elements are reduced into the target collection without being transformed. This can be used to convert one kind of collection into another.

const xform = map(x => x + 1);

let result = into([], [1, 2, 3, 4, 5], xform);
// result = [2, 3, 4, 5, 6]

result = into('', [1, 2, 3, 4, 5], xform);
// result = '23456'

result = into([], '12345', xform);
// result = [2, 3, 4, 5, 6]

result = into('', '12345', xform);
// result = '23456'

These examples are exactly equivalent to the four examples under transduce, but using into instead.

Creates an iterator over the provided collection.

For collections that are not objects, it's as simple as that. Pass in the collection, get an iterator over that collection.

const iter = iterator([1, 2, 3]);
iter.next().value === 1;     // true
iter.next().value === 2;     // true
iter.next().value === 3;     // true
iter.next().done === true;   // true

Objects get special support though, as noted in the section above on iterating over objects. Objects are iterated in alphabetical order by key, unless a second parameter is passed to iterator. This must be a function that takes two parameters (which will be object keys) and returns -1 if the first is less than the second, 1 if the second is less than the first, and 0 if they're equal.

Also, iterator by default iterates objects into key/value form. However, if a third parameter of true is passed, it will instead render the object in kv-form. This is the form used internally when a transducer is invoked.

The second and third parameters are ignored if the input collection is not an object.

const iter = iterator({ b: 2, a: 4 });
iter.next().value.a === 4;     // true
iter.next().value.b === 2;     // true
iter.next().done === true;     // true

const kvIter = iterator({ b: 2, a: 4 }, null, true);
const { k: k1, v: v1 } = kvIter.next().value;
k1 === 'a' && v1 === 4;        // true
const { k: k2, v: v2 } = kvIter.next().value;
k2 === 'b' && v2 === 2;        // true
iter.next().done === true;     // true

Note that if this function is passed an object that looks like an iterator (an object that has a next function), the object itself is returned. It is assumed that a function called next conforms to the iteration protocol.

If this function is provided a function as its first argument, an iterator is returned which runs that function one time for each call to next. That function is provided two arguments: the index of the call (starting at 0 for the first time it's called and increasing by 1 per invocation after that) and the return value of the previous call to the function (starting at undefined for the first run before the function is ever called). If the function ever returns undefined, the iterator will terminate and set the done property of its return value to true at that point.

Note that since the initial value of the second argument is undefined, using default arguments is an excellent way of providing the function an initial value.

const constIter = iterator(() => 6);  // Bert's favorite number
constIter.next().value === 6;   // true
constIter.next().value === 6;   // true;
// This will go on forever, as long as `next` keeps getting called

const indexIter = iterator(x => x * x);
indexIter.next().value === 0;   // true
indexIter.next().value === 1;   // true
indexIter.next().value === 4;   // true
indexIter.next().value === 9;   // true
// Again, this will go on forever, or until the numbers get to big JS to handle

// Using default value on `last` parameter for initial value
const lastIter = iterator((index, last = 1) => last * (index + 1));  // Factorial
lastIter.next().value === 1;    // true
lastIter.next().value === 2;    // true
lastIter.next().value === 6;    // true
lastIter.next().value === 24;   // true
// Again, forever, though factorials get big quickly

// This iterator will terminate when the function returns `undefined`
const stopIter = iterator(x => x < 2 ? x : undefined);
stopIter.next().value === 0;    // true
stopIter.next().value === 1;    // true
stopIter.next().done === true;  // true

Reduces the elements of the input collection through a reducer into an output collection.

This is the lowest-level of the transduction functions. In fact, this one is so low-level that it doesn't have a lot of use in normal operation. It's more useful for writing your own transformation functions.

reduce doesn't assume that there's even a transformation. It requires an initial collection and a reducer object that is matched to that initial collection. The reducer object must implement the step and result protocols, which instruct reduce on how to build up the collection. The reducer may implement a transformation as well, but all that's important here is that it can do the reduction.

The input collection need only implement iterator. It is not necessary for the input and output collections to be of the same type; as long as the input implements iterator and the reducer implements step and result appropriate to the type of the init collection, then any translation between collection types can occur.

The normal course of operation will be to call transduce instead, as that function makes it easy to combine transformations with reductions and can optionally figure out the initial collection itself.

Transforms the elements of the input collection and reduces them into a new collection of the same type.

This is the highest level of the three main transduction functions (sequence, into, and transduce). It creates a new collection of the same type as the input collection and reduces the transformed elements into it. Additionally, unlike into and transduce, this function is capable of producing an iterator (as long as the input is an iterator).

The input collection must not only implement the iterator protocol (as in the last two functions) but also the init, result, and step transducer protocols. Special support is provided for arrays, strings, objects, and iterators, so they need not implement any protocol.

The obvious limitation of this function is that the type of output collection cannot be chosen. Since it is always the same as the input collection, this function cannot be used to convert a collection into a different type.

const xform = map(x => x + 1);

let result = sequence([1, 2, 3, 4, 5], xform);
// result = [2, 3, 4, 5, 6]

result = sequence('12345', xform);
// result = '23456'

These examples are identical to two of the four examples from the asX functions. The other two examples are not possible with sequence because they have different input and output collection types.

Creates a reduction function from a transducer and a reducer.

This produces a function that's suitable for being passed into other libraries' reduce functions, such as JavaScript's Array.prototype.reduce or Lodash's _.reduce. It requires both a transformer and a reducer because reduction functions for those libraries must know how to do both. The reducer can be a standard reducer object like the ones sent totransduce or reduce, or it can be a plain function that takes two parameters and returns the result of reducing the second parameter into the first.

If there is no need for a transformation, then pass in the identity transducer.

Creates a reducer object from a function or from a built-in reducible type (array, object, or string).

To create a reducer for arrays, objects, or strings, simply pass an empty version of that collection to this function (e.g., toReducer([])). These reducers support the kv-form for objects.

The notable use for this function though is to turn a reduction function into a reducer object. The function is a function oftwo parameters, an accumulator and a value, and returns the accumulator with the value in it. This is exactly the same kind of function that is passed to reduction functions like JavaScript's Array.prototype.reduce and Lodash's _.reduce.

Note in particular that the output of this reducer does not need to be a collection. It can be anything. While transducing normally involves transforming one collection into another, it need not be so. For example, here is a reducer that will result in summing of the collection values.

const { toReducer, reduce } = xduce;

const sumReducer = toReducer((acc, input) => acc + input);
const sum = reduce([1, 2, 3, 4, 5], sumReducer, 0);
// sum = 15

This can be combined with transducers as well, as in this calculation of the sum of the squares of the collection values.

const { toReducer, transduce } = xduce;
const { map } = xduce.transducers;

const sumReducer = toReducer((acc, input) => acc + input);
const sum = transduce([1, 2, 3, 4, 5], map(x => x * x), sumReducer, 0);
// sum = 55

Transforms the elements of the input collection and reduces them into an output collection.

This is the lowest-level of the transduction functions that is likely to see regular use. It does not assume anything about the reducer, as it asks for it to be passed explicitly. This means that any kind of collection can be produced, since the reducer is not tied to the input collection in any way.

transduce also will accept an initial value for the resulting collection as the optional last parameter. If this parameter isn't present, then the initial value is determined from the transducer init protocol property on the reducer. Note however that many reducers may not provide an initial value, and in those cases it will have to be passed as a parameter.

const xform = map(x => x + 1);

const arrayReducer = {
  [protocols.init]() { return []; },
  [protocols.result](x) { return x; },
  [protocols.step](acc, x) {
    acc.push(x);
    return acc;
  }
};

const stringReducer = {
  [protocols.init]() { return ''; },
  [protocols.result](x) { return x; },
  [protocols.step](acc, x) { return acc + x; }
};

let result = transduce([1, 2, 3, 4, 5], xform, arrayReducer);
// result = [2, 3, 4, 5, 6]

result = transduce([1, 2, 3, 4, 5], xform, stringReducer);
// result = '23456'

result = transduce('12345', xform, arrayReducer);
// result = [2, 3, 4, 5, 6]

result = transduce('12345', xform, stringReducer);
// result = '23456'

These examples illustrate a number of important concepts. First of all, the transducer function is independent of the type of the collection; the same transducer function is used no matter the type of input or output collections. Secondly, two reducers are defined. These are objects that conform to the transducer protocol (see the documentation on module:xduce.protocols) and that know how to produce the output collection of choice. In this case, the reducers know how to create new arrays and strings (the init protocol) and how to add elements to arrays and strings (the step protocol). Because these reducers do have init protocol properties, the transduce calls do not require explicit initial collections.

The final point is that transduce can accept any kind of iterable collection, and by passing in the proper reducer, it can produce any kind of output collection. The same transduce function and the same map transformer is used in all four examples, despite the input/output combination being different in all four.

The init collection doesn't have to be empty. If it isn't, the elements that are already in it are retained and the transformed input elements are reduced into the collection normally.

Of course, the examples are not really necessary - the same thing could be accomplished using into without having to create the reducers (strings and arrays passed to into as targets know how to reduce themselves already).

Returns a new, blank, empty instance of the target collection.

A generic iterator. This conforms to the iterator protocol in that it has a next function that produces iterator-compatible objects.

The function that makes an object an iterator. This can be called repeatedly, with each call returning one iterator value, in order. This function must therefore keep state to know which of the values is the one to return next, based on the values that have already been returned by prior calls.

An object returned by an iterator's next function. It has two properties so one can be used as a flag, since values like false and undefined can be legitimate iterator values.

The mapping of protocol names to their respective property key names. The values of this map will depend on whether symbols are available.

Performs any post-processing on the completely reduced target collection. This lets a transducer make a final, whole-collection transformation, particularly useful when the step function has been used on an intermediate form of the collection which is not meant to be the output.

A function used for sorting a collection.

Performs a transformation on a single element of a collection, adding it to the target collection at the end. Thus, this function performs both the transformation and the reduction steps.

A function that is responsible for performing transductions on collections.

These functions have two forms. If no input collection is supplied, then this takes a set of configuration parameters and returns a transducer function configured to handle that specific transformation.

There is also a shortcut form, where an input collection is supplied. In this case, a transducer function is still configured and created, but then it is immediately applied as though sequence was called with that collection and transducer function. The transformed collection is then returned.

A function that creates a transducer object and links it to the next one in the chain.

An object implementing all three transduction protocols (init, step, and result) which is used by the engine to define transduction.

Transducer objects can (and must) be chained together. For instance, none of the transducer functions defined in module:xduce.transducers produces objects that know how to reduce transformed values into an output collection. This is the entire point; reduction is separate from transformation, which allows transformations to be used no matter the type of the output collection. So the engine automatically chains transducer objects to a reducer object (which is basically a specialized transducer objects whose step function transforms its inputs by adding them to a collection) that does know how to create an output collection. Thus, the protocol methods need to call the protocol methods of the next transducer object in the chain.

For that reason, transducer objects are not created manually. They are instead created by transducer functions that automatically create transducer objects and link them to the next transducer object in the chain.