ig-types 6.11.1 → 6.12.0

package/Promise.js

@@ -94,46 +94,43 @@ object.Constructor('IterablePromise', Promise, {
 	// 			.includes(..)
 	// 			.some(..) / .every(..)
 	// 			.sort(..)
-	// XXX BUG:
-	// 			Promise.iter([1,2,3])
-	// 				.map(e => e)
-	// 		is not the same as:
-	// 			Promise.iter([1,2,3])
-	// 				.map(e => e)
-	// 				.map(e => e)
+	//
 	// XXX should these support STOP???
 	map: function(func){
-		return this.constructor(this.__list.flat(), 
+		return this.constructor(this, 
 			function(e){
 				return [func(e)] }) },
 	filter: function(func){
-		return this.constructor(this.__list.flat(), 
+		return this.constructor(this, 
 			function(e){
 				return func(e) ? 
 					[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...
+	// NOTE: since order of execution can not be guaranteed there is no
+	// 		point in implementing .reduceRight(..)
 	reduce: function(func, res){
-		return this.constructor(this.__list.flat(), 
+		return this.constructor(this, 
 				function(e){
 					res = func(res, e)
 					return [] })
 			.then(function(){ 
 				return res }) },
-	/*/ XXX this is wrong...
+	/* // XXX since order of execution is not fixed there is no point in 
+	//		adding this.
 	reduceRight: function(func, res){
-		return this.constructor(this.__list.flat().reverse(), 
-				function(e){
-					res = func(res, e)
-					return [] })
-			.then(function(){ 
-				return res }) },
-	// XXX this is wrong...
-	reverse: function(){
-		return this.constructor(this.__list.flat().reverse()) },
+		return this
+			.reverse()
+			.reduce(...arguments)
+			.reverse() },
+	//*/
 	flat: function(depth=1){
-		return this.constructor(this.__list.flat(), 
+		return this.constructor(this, 
 			function(e){ 
 				return (depth > 1 
 							&& e != null 
@@ -142,24 +139,66 @@ object.Constructor('IterablePromise', Promise, {
 					: depth != 0 ?
 						e
 					: [e] }) },
+	reverse: function(){
+		var lst = this.__list
+		return this.constructor(
+			lst instanceof Promise ?
+				lst.then(function(elems){
+					return elems instanceof Array ?
+						elems.slice()
+							.reverse()
+						: elems })
+			: lst
+				.map(function(elems){
+					return elems instanceof Array ?
+							elems.slice()
+								.reverse()
+						: elems instanceof Promise ?
+							elems.then(function(elems){
+								return elems.reverse() })
+						: elems })
+				.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...
+	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')
+			: 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') },
+	push: function(elem){
+		return this.concat([elem]) },
+	unshift: function(elem){
+		return this.constructor([elem])
+			.concat(this) },
 
-	// compatibility with root promise...
-	iter: function(){
-		return this.constructor(this.__list.flat()) },
-	//*/
-	
 	// 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...
@@ -208,8 +247,8 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	// Spectial cases usefull for extending this constructor...
 	//
-	//	Clone the iterator...
-	//	Promise.iter([ .. ], false)
+	//	Set raw .__list without any pre-processing...
+	//	Promise.iter([ .. ], 'raw')
 	//		-> iterable-promise
 	//
 	//	Create a rejected iterator...
@@ -245,29 +284,47 @@ object.Constructor('IterablePromise', Promise, {
 			IterablePromise)
 
 		if(promise){
-			// clone/normalize...
-			list = list
-				.map(function(e){
-					return (e && e.then) ?
-						e.then(function(e){ 
-							return [e] })
-						: [e] })
-
-			if(handler){
+
+			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(elems){
-							return elems
-								.map(handle)
-								.flat() })
-						: elem
-							.map(handler)
-							.flat() }
+						//elem.then(function(elem){
+						//	return handler(elem) })
+						elem.then(handler)
+						: handler(elem) }
 
 				// handle the list...
-				list = list.map(handle) }
+				// 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) }
 
 			Object.defineProperty(obj, '__list', {
 				value: list,
@@ -275,9 +332,14 @@ object.Constructor('IterablePromise', Promise, {
 			})
 
 			// handle promise state...
-			Promise.all(list)
+			;(list instanceof Promise ?
+					// special case: promised list...
+					list
+					: Promise.all([list].flat()))
 				.then(function(res){
-					promise.resolve(res.flat()) })
+					promise.resolve(handler ?
+						res.flat()
+						: res) })
 				.catch(promise.reject) }
 
 		return obj },
@@ -483,6 +545,10 @@ var PromiseProtoMixin =
 module.PromiseProtoMixin =
 object.Mixin('PromiseProtoMixin', 'soft', {
 	as: ProxyPromise,
+
+	// XXX
+	iter: function(){
+		return IterablePromise(this) },
 })
 
 PromiseProtoMixin(Promise.prototype)

package/README.md

@@ -70,8 +70,13 @@ Library of JavaScript type extensions, types and utilities.
       - [`<promise-coop>.then(..)`](#promise-coopthen)
     - [Promise iteration](#promise-iteration)
       - [`Promise.iter(..)` / `promise.IterablePromise(..)`](#promiseiter--promiseiterablepromise)
+      - [`<promise>.iter()`](#promiseiter)
+      - [`<promise-iter>.iter()`](#promise-iteriter)
       - [`<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)
@@ -1452,8 +1457,8 @@ promise, and it is similar to a _generator_ in that it allows iteration over the
 contained values and chaining of operations but unlike `Promise.all(..)` this 
 iteration occurs depth-first instead of breadth first.
 
-Essentially one can think of _promise iterators_ vs. _generators_ as the former
-being internally controlled and asynchronous while the later being externally
+One can think of _promise iterators_ vs. _generators_ as the former being 
+internally controlled and asynchronous while the later being externally
 controlled and synchronous.
 
 Here is a traditional example using `Promise.all(..)`:
@@ -1515,8 +1520,32 @@ XXX should we support infinite generators as input?
 #### `Promise.iter(..)` / `promise.IterablePromise(..)`
 
 Create an _iterable promise_
+
 ```bnf
 Promise.iter(<array>)
+Promise.iter(<promise>)
+    -> <promise-iter>
+```
+
+#### `<promise>.iter()`
+
+Wrap a promise in an promise iterator. 
+
+```bnf
+<promise>.iter()
+    -> <promise-iter>
+```
+
+If `<promise>` resolves to a non-array value it will be treated as a single 
+element, otherwise the array will be iterated over.
+
+
+#### `<promise-iter>.iter()`
+
+Return a shallow copy of the current promise iterator.
+
+```bnf
+<promise-iter>.iter()
     -> <promise-iter>
 ```
 
@@ -1545,7 +1574,7 @@ and [`.reduce(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe
 
 ```bnf
 <promise-iter>.reduce(<handler>, <state>)
-    -> <promise-iter>
+    -> <promise>
 
 <handler>(<state>, <elem>)
     -> <state>
@@ -1558,6 +1587,15 @@ Note that these are different to `Array`'s equivalents in some details:
     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 especially critical for `.reduce(..)` as 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.
+
+Note that since `.reduce(..)` order can not be guaranteed there is no point 
+in implementing `.reduceRigth(..)`.
+
 
 #### `<promise-iter>.flat(..)`
 
@@ -1570,6 +1608,44 @@ Note that these are different to `Array`'s equivalents in some details:
 This is similar to [`<array>.flat(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) see it for more info.
 
 
+#### `<promise-iter>.reverse()`
+
+```bnf
+<promise-iter>.reverse()
+    -> <promise-iter>
+```
+
+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(..)`
 
 An extension to
@@ -1587,40 +1663,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/RegExp.js

@@ -64,7 +64,8 @@ object.Mixin('RegExpProtoMixin', 'soft', {
 
 
 RegExpMixin(RegExp)
-RegExpProtoMixin(RegExp.prototype)
+// XXX EXPEREMENTAL...
+//RegExpProtoMixin(RegExp.prototype)
 
 
 var quoteRegExp =

package/package.json

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