FlowPipe

FlowPipe works somewhat like the pipeline operator |>. To make a value flowable, call flow() passing the value as the first argument. Then, to indicate a value being processed, use flow.$ as an argument of pipe() method. Final value can be accessed by the call of get().

function uppercase(str) {
	return str.toUpperCase();
}

var str = flow('john').pipe(uppercase).pipe(flow.$ + '!');
console.log(str.get());    // JOHN!

pipe() method

The method can take following combinations of arguments:

• (expression) - modifies the current value, for example, concatenates strings
• (function) - calls a function and passes to this function the current value as a first argument
• (function, extraArg1, ..., extraArgN) - similar to the previous + passes extra arguments to the function
• (function, callSpec) - callSpec is a object that can have this, args or both properties to define a context for the function call and an array of the arguments to pass (the current value can be passed by flow.$)
• (..., flow.$orig) - to any of the above, flow.$orig can be passed as a last argument to return the processed value instead of a result of an operation on it
• (..., flow.$both) - similar to flow.$orig, but returns an array containing both modified and original value

Let's take a look at a couple of examples:

processing a number

var num = flow(-3)
	.pipe(flow.$ + 1)
	// -2
	.pipe(Math.abs)
	// 2
	.pipe(Math.pow, 2)
	// 4
	.pipe(
		Math.pow, {
			args: [2, flow.$]
		}
	);
	// 16

console.log(num.get());
// 256

processing an array

var arr = flow(['a', 'b', 'c', 'd'])
	.pipe(
		Array.prototype.pop,
		{ this: flow.$ },
		flow.$orig
	)
	.pipe(
		Array.prototype.reverse,
		{ this: flow.$ }
	);

console.log(arr.get());
// ['c', 'b', 'a']

Here, if we would not use flow.$orig, we would get the value d. It is because pop() method returns a deleted item of an array. We want to get the original value passed to pipe() (after it has been processed).

processing an object

var obj = flow({a: 1})
	.pipe(
		Object.assign,
		{ b: 2}
	)
	.pipe(
		delete flow.$.a,
		flow.$orig
	);

console.log(obj.get());
// {b: 2}

flow.$orig has been used because of the same reason as in the case of the above array - delete operator returns true, but we want to process the original value, i.e., the object.

Throwing an exception when processing

Let's throw error if a first letter does not equal A. In the first example everything is ok:

var res = flow('ABC')
	.pipe((_) => {
		if (_.charAt(0) != 'A') throw new Error('Wrong first letter');
	}, flow.$orig)
	.get();
// res = 'ABC'

When it comes to the other, it can't be said so:

var res = flow('CBA')
	.pipe((_) => {
		if (_.charAt(0) != 'A') throw new Error('Wrong first letter');
	}, flow.$orig)
	.get();
// res = 'ABC'
// + error thrown

Passing the promises

Promises can be passed to pipe() with await keyword.

flow('/api/url')
	.pipe(await $.ajax({
		url: flow.$,
		data: someData
	}))
	.pipe(flow.$ + 1)
	.pipe(new Item(flow.$))
	.pipe(flow.$.id)
	.get();

flow(promise)
	.pipe(await flow.$)
	.pipe(flow.$.id + ': ' + flow.$.name)
	.get();

Getting both original and modified value

In the examples above, we have used $.orig to get the original value rather than the processed one. We may want to get both. Then, the last argument of pipe() method should be $.both. What will be returned is an array [modifiedValue, originalValue].

var res = flow([1, 2, 3])
	.pipe(
		Array.prototype.reduce,
		{
			this: flow.$,
			args: [
				(a, b) => a + b,
				0
			]
		},
		flow.$both
	)
	.pipe({
		items: flow.$[1],
		sum: flow.$[0]
	})
	.get();

console.log(res);
// {items: [1, 2, 3], sum: 6}