ig-types 6.11.3 → 6.12.0

package/Promise.js

@@ -121,6 +121,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 +160,45 @@ 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...
+	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) },
+
 	// 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...

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)
@@ -1613,7 +1615,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 +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/package.json

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