ig-types 6.12.0 → 6.13.4

package/Promise.js

@@ -58,6 +58,7 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	// Format:
 	// 	[
+	//		<non-array-value>,
 	//		[ <value> ],
 	//		<promise>,
 	//		...
@@ -65,6 +66,74 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	__list: null,
 
+	// low-level .__list handlers/helpers...
+	//
+	// NOTE: these can be useful for debugging and extending...
+	__pack: function(list, handler){
+		var that = this
+		// handle iterable promise list...
+		if(list instanceof IterablePromise){
+			return this.__handle(list.__list, handler) }
+		// handle promise list...
+		if(list instanceof Promise){
+			return list.then(function(list){
+				return that.__pack(list, handler) }) }
+		// do the work...
+		// NOTE: packing and handling are mixed here because it's faster
+		// 		to do them both on a single list traverse...
+		var handle = !!handler
+		handler = handler 
+			?? function(elem){ 
+				return [elem] }
+		return [list].flat()
+			.map(function(elem){
+				return elem && elem.then ?
+						//that.__pack(elem, handler)
+						elem.then(handler)
+					: elem instanceof Array ?
+						handler(elem)
+					// NOTE: we keep things that do not need protecting 
+					// 		from .flat() as-is...
+					: !handle ?
+						elem
+					: handler(elem) }) },
+	__handle: function(list, handler){
+		var that = this
+		if(typeof(list) == 'function'){
+			handler = list
+			list = this.__list }
+		if(!handler){
+			return list }
+		// handle promise list...
+		if(list instanceof Promise){
+			return list.then(function(list){
+				return that.__handle(list, handler) }) }
+		// do the work...
+		// NOTE: since each section of the packed .__array is the same 
+		// 		structure as the input we'll use .__pack(..) to handle 
+		// 		them, this also keeps all the handling code in one place.
+		return list.map(function(elem){
+			return elem instanceof Array ?
+					that.__pack(elem, handler)
+				: elem instanceof Promise ?
+					that.__pack(elem, handler)
+						.then(function(elem){
+							return elem.flat() })
+				: [handler(elem)] })
+   			.flat() },
+	__unpack: function(list){
+		list = list 
+			?? this.__list
+		// handle promise list...
+		if(list instanceof Promise){
+			var that = this
+			return list.then(function(list){
+				return that.__unpack(list) }) }
+		// do the work...
+		return Promise.all(list)
+			.then(function(list){
+				return list.flat() }) },
+
 
 	// iterator methods...
 	//
@@ -99,21 +168,31 @@ object.Constructor('IterablePromise', Promise, {
 	map: function(func){
 		return this.constructor(this, 
 			function(e){
-				return [func(e)] }) },
+				var res = func(e)
+				return res instanceof Promise ?
+		   			res.then(function(e){ 
+						return [e] })
+					: [res] }) },
 	filter: function(func){
 		return this.constructor(this, 
 			function(e){
-				return func(e) ? 
-					[e] 
-					: [] }) },
+				var res = func(e)
+				var _filter = function(elem){
+					return res ?
+						[elem]
+						: [] }
+				return res instanceof Promise ?
+					res.then(_filter)
+					: _filter(e) }) },
 	// NOTE: this does not return an iterable promise as we can't know 
 	// 		what the user reduces to...
 	// 		XXX we could look at the initial state though...
 	// NOTE: the items can be handled out of order because the nested 
 	// 		promises can resolve in any order.
-	//		XXX write how to go around this...
+	//		XXX doc how to go around this...
 	// NOTE: since order of execution can not be guaranteed there is no
 	// 		point in implementing .reduceRight(..)
+	// XXX should func be able to return a promise???
 	reduce: function(func, res){
 		return this.constructor(this, 
 				function(e){
@@ -160,32 +239,29 @@ object.Constructor('IterablePromise', Promise, {
 				.reverse(),
 			'raw') },
 
-	// NOTE: these can create an unresolved promise from a resolved 
-	// 		promise...
-	// XXX EXPEREMENTAL...
-	// 		....can we remove a level of indirection here???
-	// 		would be better to use the raw mode...
+	// NOTE: the following methods can create an unresolved promise from 
+	// 		a resolved promise...
 	concat: function(other){
-		var lst = this.__list
-		return lst instanceof Promise ?
-				this.constructor([this, other])
-					.flat()
-			: other instanceof IterablePromise ?
-				this.constructor(
-					lst.concat(other.__list),
-					'raw')
+		var that = this
+		var cur = this.__pack(this)
+		var other = this.__pack(other)
+		return this.constructor(
+			// NOTE: we are not using only the first branch to keep the 
+			// 		lists as exposed as possible thus avoiding blocking 
+			// 		until the whole ting is resolved...
+			(cur instanceof Promise 
+					&& other instanceof Promise) ?
+				Promise.all([cur, other])
+					.then(function(list){
+						return list[0].concat(list[1]) })
+			: cur instanceof Promise ?
+				cur.then(function(list){
+					return list.concat(other) })
 			: other instanceof Promise ?
-				this.constructor(
-					lst.concat(other
-						.then(function(res){ 
-							return res instanceof Array ?
-					   			res
-								: [res] })),
-					'raw')
-			: this.constructor(
-				// XXX this is cheating -- need a more direct way to form the array...
-				lst.concat(this.constructor(other).__list),
-				'raw') },
+				other.then(function(list){
+					return cur.concat(list) })
+			: cur.concat(other),
+			'raw') },
 	push: function(elem){
 		return this.concat([elem]) },
 	unshift: function(elem){
@@ -196,6 +272,7 @@ object.Constructor('IterablePromise', Promise, {
 	// 			.pop()
 	// 			.shift()
 	// 			.first() / .last()
+	// 			.at(..)
 	// 		...would be nice if these could stop everything that's not
 	// 		needed to execute...
 	
@@ -268,6 +345,26 @@ object.Constructor('IterablePromise', Promise, {
 	// 			manually handle the stop...
 	// 		- another issue here is that the stop would happen in order of 
 	// 			execution and not order of elements...
+	// XXX DOC:
+	// 		inputs:
+	// 			- Chaining -- list instanceof IterablePromise
+	// 				After all the promises resolve .flat() should 
+	// 				turn this into the input list.
+	// 				For this to work we'll need to at least wrap all 
+	// 				arrays and promise results in arrays.
+	// 				(currently each value is wrapped)
+	// 				-> __list
+	// 					- promise (value | array)
+	// 					- array of:
+	// 						- array
+	// 							- value
+	// 						- promise (value | array)
+	// 			- New
+	// 				- promise (value | array)
+	// 				- value (non-array)
+	// 				- array of:
+	// 					- value
+	// 					- promise (value)
 	__new__: function(_, list, handler){
 		// instance...
 		var promise
@@ -284,47 +381,10 @@ object.Constructor('IterablePromise', Promise, {
 			IterablePromise)
 
 		if(promise){
-
 			if(handler != 'raw'){
-				handler = handler
-					?? function(e){ 
-						return [e] }
-
-				// NOTE: this is recursive to handle expanding nested promises...
-				var handle = function(elem){
-					// call the handler...
-					return (elem && elem.then) ?
-						//elem.then(function(elem){
-						//	return handler(elem) })
-						elem.then(handler)
-						: handler(elem) }
-
-				// handle the list...
-				// NOTE: we can't .flat() the results here as we need to 
-				// 		wait till all the promises resolve...
-				list =
-					(list instanceof IterablePromise 
-							&& !(list.__list instanceof Promise)) ?
-						// NOTE: this is essentially the same as below but 
-						// 		with a normalized list as input...
-						// 		XXX can we merge the two???
-						list.__list
-							.map(function(elems){
-								return elems instanceof Promise ?
-									elems.then(function(elems){
-										return elems
-											.map(handle) 
-											.flat() })
-									: elems
-										.map(handle)
-										.flat() })
-					: list instanceof Promise ?
-						// special case: promised list...
-						list.then(function(list){
-							return [list].flat()
-								.map(handle) })	
-					: [list].flat()
-						.map(handle) }
+				list = list instanceof IterablePromise ?
+					this.__handle(list.__list, handler)
+					: this.__pack(list, handler) }
 
 			Object.defineProperty(obj, '__list', {
 				value: list,
@@ -332,14 +392,9 @@ object.Constructor('IterablePromise', Promise, {
 			})
 
 			// handle promise state...
-			;(list instanceof Promise ?
-					// special case: promised list...
-					list
-					: Promise.all([list].flat()))
-				.then(function(res){
-					promise.resolve(handler ?
-						res.flat()
-						: res) })
+			this.__unpack(list)
+				.then(function(list){
+					promise.resolve(list) })
 				.catch(promise.reject) }
 
 		return obj },
@@ -547,8 +602,8 @@ object.Mixin('PromiseProtoMixin', 'soft', {
 	as: ProxyPromise,
 
 	// XXX
-	iter: function(){
-		return IterablePromise(this) },
+	iter: function(handler){
+		return IterablePromise(this, handler) },
 })
 
 PromiseProtoMixin(Promise.prototype)

package/README.md

@@ -1389,7 +1389,7 @@ controlled(t.then())
 // ...
 ```
 
-Note that functionally this can be considered a special-case of an 
+Note that this functionally can be considered a special-case of an 
 [interactive promise](#interactive-promises), but in reality they are two 
 different implementations, the main differences are:
 - _Cooperative promise_ constructor does not need a resolver function,
@@ -1485,8 +1485,6 @@ var p = Promise.iter([ .. ])
         // ...
     })
     // items reach here as soon as they are returned by the filter stage handler...
-    // NOTE: the filter handler may return promises, those will not be processed
-    //    until they are resolved...
     .map(function(e){
         // ...
     })
@@ -1504,6 +1502,12 @@ This approach has a number of advantages:
 And some disadvantages:
 - item indexes are unknowable until all the promises resolve.
 
+Calling each of the `<promise-iter>` methods will return a new and unresolved 
+promise, even if the original is resolved.
+
+If all values are resolved the `<promise-iter>` will resolve on the next 
+execution frame.
+
 <!-- 
 XXX should we support generators as input?
     ...not sure about the control flow direction here, on one hand the generator
@@ -1582,19 +1586,21 @@ and [`.reduce(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe
 
 Note that these are different to `Array`'s equivalents in some details: 
 - `<handler>` is _not_ called in the order of element occurrence but rather 
-  in the order of elements are resolved/ready.
+    in the order of elements are resolved/ready.
 - `<handler>` does not get either the element _index_ or the _container_.  
-    this is because the index with _out-of-order_ and _depth-first_ execution the 
-    index is unknowable and the container is a promise/black-box.
+    this is because in _out-of-order_ and _depth-first_ execution the 
+    index is _unknowable_ and the container is a promise/black-box.
 
-This is especially critical for `.reduce(..)` as iteration in an order different 
-from the order of elements _can_ affect actual result if this is not expected.
+This is especially critical for `.reduce(..)` as the iteration in an order
+different from the order of elements _can_ affect actual result if this is 
+not expected.
 
 `.reduce(..)` is also a bit different here in that it will return a basic 
-`<promise>` object as we can't know what will it will reduce to.
+`<promise>` rather than an iterable promise object as we can't know what 
+will it will reduce to.
 
-Note that since `.reduce(..)` order can not be guaranteed there is no point 
-in implementing `.reduceRigth(..)`.
+Note that since `.reduce(..)` handler's execution order can not be known,
+there is no point in implementing `.reduceRigth(..)`.
 
 
 #### `<promise-iter>.flat(..)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ig-types",
-  "version": "6.12.0",
+  "version": "6.13.4",
   "description": "Generic JavaScript types and type extensions...",
   "main": "main.js",
   "scripts": {

package/test.js

@@ -111,45 +111,160 @@ var cases = test.Cases({
 	RegExp: function(assert){
 	},
 
-	Promise: function(assert){
+	IterablePromise: test.TestSet(function(){
+		var create = function(assert, value){
+			return {
+				input: value, 
+				output: assert(Promise.iter(value), 'Promise.iter(', value, ')'),
+			} }
+
+		this.Setup({
+			empty: function(assert){
+				return create(assert, []) },
+			value: function(assert){
+				return create(assert, 123) },
+			array: function(assert){
+				return create(assert, [1, 2, 3]) },
+			nested_array: function(assert){
+				return create(assert, [1, 2, [3]]) },
+			promise_value: function(assert){
+				return create(assert, Promise.resolve(123)) },
+			promise_array: function(assert){
+				return create(assert, Promise.resolve([1, 2, 3])) },
+			promise_nested_array: function(assert){
+				return create(assert, Promise.resolve([1, 2, [3]])) },
+			array_mixed: function(assert){
+				return create(assert, [1, Promise.resolve(2), 3]) },
+			nested_array_mixed: function(assert){
+				return create(assert, [
+					1, 
+					Promise.resolve(2), 
+					[3], 
+					Promise.resolve([4]),
+				]) },
+			promise_array_mixed: function(assert){
+				return create(assert, Promise.resolve([1, Promise.resolve(2), 3])) },
+			promise_nested_array_mixed: function(assert){
+				return create(assert, Promise.resolve([
+					1, 
+					Promise.resolve(2), 
+					[3], 
+					Promise.resolve([4]),
+				])) },
+		})
+		this.Modifier({
+			nest: function(assert, setup){
+				setup.output = Promise.iter(setup.output)
+				return setup },
+			iter: function(assert, setup){
+				setup.output = setup.output.iter()
+				return setup },
+
+			map_asis: function(assert, setup){
+				setup.output = setup.output
+					.map(function(e){ 
+						return e }) 
+				return setup },
+			map_promise: function(assert, setup){
+				setup.output = setup.output
+					.map(function(e){ 
+						return Promise.resolve(e) }) 
+				return setup },
+
+			filter_all: function(assert, setup){
+				setup.output = setup.output
+					.filter(function(e){ return true }) 
+				return setup },
+			// XXX either the test is worng or something is broken...
+			filter_none: function(assert, setup){
+				return {
+					input: [],
+					output: setup.output
+						.filter(function(e){ return false }),
+				} },
+
+			/* XXX need tuning...
+			concat_basic: function(assert, {input, output}){
+				return {
+					input: [input].flat()
+						.concat(['a', 'b', 'c']),
+					output: output
+						.concat(['a', 'b', 'c']),
+				} },
+			concat_nested_array: function(assert, {input, output}){
+				return {
+					input: [input].flat()
+						.concat(['a', ['b'], 'c']),
+					output: output
+						.concat(['a', ['b'], 'c']),
+				} },
+			//*/
+
+		})
+		this.Test({
+			value: async function(assert, {input, output}){
+
+				var res = await output
+
+				assert(res instanceof Array, 'result is array')
+
+				input instanceof Array ?
+					// XXX this does not catch some errors -- map_promise specifically...
+					assert.array(res, 
+						await Promise.all(input), 
+							'array -> array')
+				: (input instanceof Promise && await input instanceof Array) ?
+					assert.array(res, 
+						await input, 
+							'promise array -> array')
+				: input instanceof Promise ?
+					assert.array(res, 
+						[await input], 
+							'promise value -> array')
+				: assert.array(res, 
+					[input], 
+					'value -> array') },
+		})
+	}),
+	Promise: async function(assert){
 		var p = assert(Promise.cooperative(), '.cooperative()')
-		//var p = assert(promise._CooperativePromise())
 		
-		assert(!p.isSet, '.isSet is false')
-
+		assert(!p.isSet, 'promise unset')
+		
 		var RESOLVE = 123
+		var then = false
+		var done = false
 
-		var then
 		p.then(function(v){
-			// XXX this does not get printed for some reason...
-			console.log('!!!!!!!!!!! then')
-			// XXX this seems not to work/print/count a fail...
-			assert(false, 'test fail')
-
-			then = v })
+			then = assert(v == RESOLVE, '.then(..) handled') })
 
-		assert(!p.isSet, '.isSet is false')
-
-		var fin
 		p.finally(function(){
-			fin = true })
+			done = assert(true, '.finally(..) handled') })
 
-		assert(!p.isSet, '.isSet is false')
+		assert(!p.isSet, 'promise unset')
 
 		p.set(RESOLVE)
 
-		assert(p.isSet, '.isSet')
-
-		// XXX without setTimeout(..) these are run before the 
-		// 		.then(..) / .finally(..) have a chance to run...
-		// 		...not yet sure how I feel about this...
-		// XXX with setTimeout(..) these appear not to have ANY effect, 
-		// 		as if setTimeout(..) did not run...
-		setTimeout(function(){
-			assert(false, 'test fail')
-			assert(then == RESOLVE, '.then(..)')
-			assert(fin, '.finally(..)')
-		}, 0)
+		assert(p.isSet, 'promise set')
+
+		// allow the promise to finalize...
+		await p
+
+		assert(then, '.then(..): confirmed')
+		assert(done, '.done(..): confirmed')
+
+		// XXX
+
+		assert(await Promise.iter([1, Promise.resolve(2), [3]]), '.iter(..)')
+
+		assert.array(
+			await Promise.iter([1, 2, 3]), 
+			[1, 2, 3], 
+				'basic array')
+		assert.array(
+			await Promise.iter([1, Promise.resolve(2), 3]), 
+			[1, 2, 3], 
+				'promises as elements')
 	},
 
 	// Date.js