feat: 🎸 add mapSpread operator

to allow tranformation output tuples to tuples

Author: dmitriz

index.js

@@ -160,18 +160,19 @@ const chain = (...fns) => cpsFn => {
  *    If `fj` is undefined or null, the output is passed unchanged.
  *
  * @example
- * const cpsFn = (cb1, cb2) => {cb1(2, 3); cb2(7)}
- *   // 2 callbacks receive corresponding outputs (2, 3) and (7)
- * map(f1, f2)(cpsFn)
+ *   // 2 callbacks receive respective outputs (2,3) and (7)
+ * const cpsFn = (cb0,cb1) => {cb0(2,3); cb1(7)}
+ * const f0 = (x,y) => x+y
+ * const f1 = z => z*6
+ * map(f0,f1)(cpsFn)
  *   // is equivalent to the CPS function
- * (cb1, cb2) => {cb1(f1(2, 3));  cb2(f2(7))}
- *   // where f1 and f2 transform respective outputs.
+ * (cb0,cb1) => {cb0(2+3); cb1(f1(7*6))}
  *
  * @example
- * const cpsFromPromise = promise => (onRes, onErr) => promise.then(onRes, onErr)
- * map(f1, f2)(cpsFromPromise(promise))
+ * const cpsFromPromise = promise => (onRes,onErr) => promise.then(onRes,onErr)
+ * map(f0,f1)(cpsFromPromise(promise))
  *   // is equivalent to
- * cpsFromPromise(promise.then(f1).catch(f2))
+ * cpsFromPromise(promise.then(f0).catch(f1))
  */
 // precompose every callback with fn from array matched by index
 // if no function provided, default to the identity
@@ -180,6 +181,25 @@ const map = (...fns) => chain(...fns.map((f, idx) =>
 ))
 
 
+/**
+ * Same as `map` but spread return values of transforming functions.
+ * This allows to transform output tuples into tuples rather than single values as `map` does.
+ * As JavaScript has no tuples, use arrays instead.
+ * 
+ * @example
+ *   // 1 callback receives output `(2,3)`
+ * const cpsFn = cb => cb(2,3)
+ *   // `f` transforms `(x,y)` to `(x+y,x-y)` (written as array)
+ * const f = (x,y) => [x+y,x-y]
+ * map(f)(cpsFn)
+ *   // is equivalent to the CPS function
+ * cb => cb(2+3,2-3)
+ */
+exports.mapSpread = (...fns) => chain(...fns.map((f, idx) =>
+  (...args) => ofN(idx)(...f(...args))
+))
+
+
 
 /**
  * Filter outputs making predicates `(pred0,...,predn)` truthy.

test/filter.test.js

@@ -24,7 +24,7 @@ test('filter tuples', t => {
 	const cpsFun = cb => cb(1,2) + cb(3,4)
 	t.plan(1)
 	const cpsNew = filter(a => a > 1)(cpsFun)
-	cpsNew(t.cis(3))
+	cpsNew(t.cis(3,4))
 })
 
 test('filter multiple outputs', t => {

test/helpers/ava-patched.js

@@ -8,7 +8,7 @@ Usage: t.cis(a)(b) instead of t.is(a, b)
 */
 module.exports = (title, fn) =>	
 	test(title, t => {
-		t.cis = a => b => t.is(a, b)
-		t.cDeepEqual = a => b => t.deepEqual(a, b)
+		t.cis = (...a) => (...b) => t.deepEqual(a, b)
+		t.cDeepEqual = (...a) => (...b) => t.deepEqual(a, b)
 		return fn(t)
 	})

test/map.test.js

@@ -16,7 +16,7 @@ test('map over single function with no arguments', t => {
 	map(() => 30)(cpsFun)(t.cis(30))	
 })
 
-test('further callbacks are unaffected when map over single function', t => {
+test('mapSpread preserves outputs for missing transforms', t => {
 	const cpsFun = (cb1, cb2) => {cb1(42); cb2(23)}
 	map(x => x*2)(cpsFun)(x => x, t.cis(23))	
 })
@@ -32,8 +32,8 @@ test('map over more functions than callbacks, the extra functions are ignored',
 	map(x => x*2, x => x+10)(cpsFun)(t.cis(84))	
 })
 
-test('map over nested arrays', t => {
-	const cf0 = cb => cb([1,2])
-	map(arr => arr.map(a => a + 1))(cf0)(t.cDeepEqual([2,3]))
+test('map over arrays', t => {
+	const F = cb => cb([1,2])
+	map(arr => arr.map(a => a + 1))(F)(t.cDeepEqual([2,3]))
 })
 

test/mapSpread.test.js

@@ -0,0 +1,45 @@
+const test = require('./config')
+const { mapSpread } = require('..')
+
+test('mapSpread transforms output 1-tuples to m-tuples', t => {
+	const cpsFun = cb => cb(42)
+	mapSpread(x => [])(cpsFun)(t.cis())
+	mapSpread(x => [x*2])(cpsFun)(t.cis(84))
+	mapSpread(x => [x,x*2])(cpsFun)(t.cis(42,84))
+	mapSpread(x => [x,x*2,5])(cpsFun)(t.cis(42,84,5))
+})
+
+test('mapSpread transforms output 2-tuples to m-tuples', t => {
+	const cpsFun = cb => cb(42, 24)
+	mapSpread((a,b)=>[])(cpsFun)(t.cis())	
+	mapSpread((a,b)=>[a-b])(cpsFun)(t.cis(18))	
+	mapSpread((a,b)=>[a,a-b,b,1])(cpsFun)(t.cis(42,18,24,1))	
+})
+
+test('mapSpread over single function with no arguments', t => {
+	const cpsFun = cb => cb()
+	mapSpread(() => [])(cpsFun)(t.cis())	
+	mapSpread(() => [30])(cpsFun)(t.cis(30))	
+})
+
+test('mapSpread preserves outputs for missing transforms', t => {
+	const cpsFun = (cb1, cb2) => {cb1(42); cb2(23)}
+	mapSpread(x => [x*2,1,4])(cpsFun)(_ => null, t.cis(23))	
+})
+
+test('mapSpread over multiple functions', t => {
+	t.plan(4)
+	const cpsFun = (cb1, cb2) => {cb1(42); cb2(23)}
+	mapSpread(x => [x/2], x => [x*2])(cpsFun)(t.cis(21), t.cis(46))	
+	mapSpread(x => [x/2,x], x => [x*2,-x])(cpsFun)(t.cis(21,42), t.cis(46,-23))	
+})
+
+test('mapSpread over more functions than callbacks, the extra functions are ignored', t => {
+	const cpsFun = cb => cb(42)
+	mapSpread(x => [x*2], x => [x+10])(cpsFun)(t.cis(84))	
+})
+
+test('mapSpread transforms tuples via arrays', t => {
+	const F = cb => cb(1,2)
+	mapSpread((...arr) => arr.map(a => a + 1))(F)(t.cDeepEqual(2,3))
+})