ig-types 6.11.3 → 6.13.2

package/Promise.js

@@ -65,6 +65,62 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	__list: null,
 
+	// low-level .__list handlers/helpers...
+	// NOTE: these can be useful for debugging and extending...
+	__normalize: function(list, handler){
+		// handle promise list...
+		if(list instanceof Promise){
+			var that = this
+			return list.then(function(list){
+				return that.__normalize(list, handler) }) }
+
+		var handle = !!handler
+		handler = handler 
+			?? function(elem){ 
+				return [elem] }
+		return [list].flat()
+			.map(function(elem){
+				return elem instanceof Array ?
+						handler(elem)
+					: elem && elem.then ?
+						elem.then(handler)
+					: !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) }) }
+
+		return list.map(function(elem){
+			return elem instanceof Array ?
+					that.__normalize(elem, handler)
+				: elem instanceof Promise ?
+					that.__normalize([elem], handler).pop()
+						.then(function(elem){
+							return elem.flat() })
+				: handler(elem) })
+   			.flat() },
+	__denormalize: function(list){
+		list = list 
+			?? this.__list
+		// handle promise list...
+		if(list instanceof Promise){
+			var that = this
+			return list.then(function(list){
+				return that.__denormalize(list) }) }
+
+		return Promise.all(list)
+			.then(function(list){
+				return list.flat() }) },
+
 
 	// iterator methods...
 	//
@@ -99,21 +155,36 @@ object.Constructor('IterablePromise', Promise, {
 	map: function(func){
 		return this.constructor(this, 
 			function(e){
-				return [func(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] 
+				//return func(e) ? 
+				//	[e] 
+				//	: [] }) },
+				var res = func(e)
+				return res instanceof Promise ?
+						res.then(function(res){
+							return res ?
+								[e]
+								: [] })
+					: res ?
+						[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){
@@ -121,6 +192,14 @@ object.Constructor('IterablePromise', Promise, {
 					return [] })
 			.then(function(){ 
 				return res }) },
+	/* // XXX since order of execution is not fixed there is no point in 
+	//		adding this.
+	reduceRight: function(func, res){
+		return this
+			.reverse()
+			.reduce(...arguments)
+			.reverse() },
+	//*/
 	flat: function(depth=1){
 		return this.constructor(this, 
 			function(e){ 
@@ -152,18 +231,26 @@ object.Constructor('IterablePromise', Promise, {
 				.reverse(),
 			'raw') },
 
+	// NOTE: these can create an unresolved promise from a resolved 
+	// 		promise...
+	concat: function(other){
+		return this.constructor(
+				this.__list
+					.concat(this.__normalize(other)),
+				'raw') },
+	push: function(elem){
+		return this.concat([elem]) },
+	unshift: function(elem){
+		return this.constructor([elem])
+			.concat(this) },
+
 	// XXX do we need these?
 	// 			.pop()
 	// 			.shift()
 	// 			.first() / .last()
-	// XXX these can change the "resolved" state...
-	// 		...i.e. return a pending promise when called from a fulfilled 
-	// 		promise....
-	// 			.concat(..)
-	// 			.push(..)
-	// 			.unshift(..)
-	// 			.first(..) / .last(..)
-
+	// 		...would be nice if these could stop everything that's not
+	// 		needed to execute...
+	
 
 	// Overload .then(..), .catch(..) and .finally(..) to return a plain 
 	// Promise instnace...
@@ -233,6 +320,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
@@ -249,47 +356,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.__normalize(list, handler) }
 
 			Object.defineProperty(obj, '__list', {
 				value: list,
@@ -297,14 +367,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.__denormalize(list)
+				.then(function(list){
+					promise.resolve(list) })
 				.catch(promise.reject) }
 
 		return obj },

package/README.md

@@ -75,6 +75,8 @@ Library of JavaScript type extensions, types and utilities.
       - [`<promise-iter>.map(..)` / `<promise-iter>.filter(..)` / `<promise-iter>.reduce(..)`](#promise-itermap--promise-iterfilter--promise-iterreduce)
       - [`<promise-iter>.flat(..)`](#promise-iterflat)
       - [`<promise-iter>.reverse()`](#promise-iterreverse)
+      - [`<promise-iter>.concat(..)`](#promise-iterconcat)
+      - [`<promise-iter>.push(..)` / `<promise-iter>.unshift(..)`](#promise-iterpush--promise-iterunshift)
       - [`<promise-iter>.then(..)` / `<promise-iter>.catch(..)` / `<promise-iter>.finally(..)`](#promise-iterthen--promise-itercatch--promise-iterfinally)
       - [Advanced handler](#advanced-handler)
     - [Promise proxies](#promise-proxies)
@@ -1387,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,
@@ -1483,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){
         // ...
     })
@@ -1502,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
@@ -1580,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(..)`
@@ -1613,7 +1621,35 @@ This is similar to [`<array>.flat(..)`](https://developer.mozilla.org/en-US/docs
     -> <promise-iter>
 ```
 
-This is similar to [`<array>.reverse(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) see it for more info.
+This is deferent from `<array>.reverse()` in that it will _not_ reverse in-place, 
+but rather a _reversed copy_ will be created.
+
+This is similar to [`<array>.reverse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) see it for more info.
+
+
+#### `<promise-iter>.concat(..)`
+
+```bnf
+<promise-iter>.concat(<other>)
+    -> <promise-iter>
+```
+
+This is similar to [`<array>.concat(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) see it for more info.
+
+
+#### `<promise-iter>.push(..)` / `<promise-iter>.unshift(..)`
+
+```bnf
+<promise-iter>.push(<elem>)
+    -> <promise-iter>
+
+<promise-iter>.unshift(<elem>)
+    -> <promise-iter>
+```
+
+These are similar to [`<array>.push(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) 
+and [`<array>.unshift(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) 
+see them for more info.
 
 
 #### `<promise-iter>.then(..)` / `<promise-iter>.catch(..)` / `<promise-iter>.finally(..)`
@@ -1633,40 +1669,51 @@ can be useful to hide the extended promise API from further code.
 #### Advanced handler
 
 ```bnf
-Promise.iter(<block-array>, <handler>)
+Promise.iter(<block>, <handler>)
     -> <iterable-promise>
+```
 
-<handler>(<elem>)
-    -> [ <elems> ]
+The `<handler>` will get passed each resolved `<value>` of the input `<block>` 
+as soon as it's available/resolved.
+
+The `<handler>` return value is unwrapped into the resulting array, allowing
+each call to both remove elements (i.e. returning `[]`) from the resulting 
+`<block>` as well as insert multiple items (by returning an array of items).
+
+<!-- XXX returning promises from handler needs to be documented/tested... -->
+
+```bnf
+<handler>(<value>)
+    -> []
+    -> [ <elem>, .. ]
+    -> <non-array>
 ```
 
 ```bnf
-<block-array> ::= 
+<block> ::= 
     []
-    | [ <block-elem>, .. ]
+    | [ <elem>, .. ]
 
-<block-elem> ::=
-    []
-    | [ <value>, .. ]
-    | <promise>
-    | <non-array>
+<elem> ::= 
+    <value>
+    | <promise>(<value>)
 ```
 
 Example:
 ```javascript
 var p = Promise.iter(
-        // NOTE: if you want an element to explicitly be an array wrap it in 
-        //    an array -- like the last element here...
-        [[1, 2], 3, Promise.resolve(4), [[5, 6]]], 
+        [1, 2, 3, Promise.resolve(4), [5, 6]], 
         function(elem){
+            // duplicate even numbers...
             return elem % 2 == 0 ?
                     [elem, elem]
+                // return arrays as-is...
                 : elem instanceof Array ?
-                  [elem]
+                    [elem]
+                // remove other elements...
                 : [] })
     .then(function(lst){
-        console.log(lst) // -> [2, 2, 4, 4, [5, 6]]
-    })
+        console.log(lst) }) // -> [2, 2, 4, 4, [5, 6]]
 ```
 
 

package/package.json

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

package/test.js

@@ -111,45 +111,143 @@ 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 }),
+				} },
+
+		})
+		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