ig-types 6.24.22 → 6.24.24

package/Promise.js

@@ -944,27 +944,30 @@ object.Constructor('IterableSequentialStartPromise', IterablePromise, {
 
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
-// XXX might also be a good idea to implement a version of the above to
-// 		handle the next element only after the promise returned by the
-// 		previous handler is resolved -- depth first...
-// 		...this would help prevent the await execution uncertainty, i.e.:
-//			console.log(1)
-//			// note that we are NOTE await'ing for the function here...
-//			(async function f(){ 
-//				console.log(2)})()
-//			console.log(3)
-//				-> prints 1, 2, 3
-//		and:
-//			console.log(1)
-//			(async function f(){ 
-//				// note the await -- this is the only difference...
-//				console.log(await 2)})()
-//			console.log(3)
-//				-> prints 1, 3, 2
-//		this is bad because of a handler has two execution paths one with
-//		an await and one without the order of actual handler execution can
-//		not be controlled unless we wait for the whole thing to resolve...
-// 		
+// Like IterableSequentialStartPromise(..) but each handler will be 
+// called after the previous handler's return value is resolved (if it
+// is a promise).
+//
+// This is needed to control the "unpredictable" behavior of await's in 
+// JavaScript, here is a trivial example with an async function starting 
+// as if it was sync and as a promise on the next execution frame:
+// 		console.log(1)
+// 		// note that we are NOTE await'ing for the function here...
+// 		(async function f(){ 
+// 			console.log(2)})()
+// 		console.log(3)
+// 			-> prints 1, 2, 3
+// and:
+// 		console.log(1)
+// 		(async function f(){ 
+// 			// note the await -- this is the only difference...
+// 			console.log(await 2)})()
+// 		console.log(3)
+// 			-> prints 1, 3, 2
+// this is bad because if a handler has two execution paths one with
+// an await and one without the order of actual handler execution can
+// not be controlled predictably unless we wait for the whole thing to 
+// resolve...
 var IterableSequentialPromise =
 module.IterableSequentialPromise =
 object.Constructor('IterableSequentialPromise', IterableSequentialStartPromise, {
@@ -1327,8 +1330,8 @@ object.Mixin('PromiseMixin', 'soft', {
 			// XXX should we just check for .then(..) ???
 			// XXX update README if this changes...
 			: (data.length == 1 
-					&& Symbol.asyncIterator in data[0]
-					&& 'then' in data[0]) ?
+					&& data[0][Symbol.asyncIterator]
+					&& data[0].then) ?
 				data[0].then(func, ...error)
 			: error.length > 0 ?
 				function(){

package/README.md

@@ -1651,6 +1651,69 @@ XXX should we support generators as input?
 XXX should we support infinite generators as input?
 -->
 
+Promise iteration supports three modes of synchronization:
+
+1. handle on ready
+  ```
+    .iter(
+        [value, promise, promise, value], handler)
+           +	   .		.		+
+           |				R		|
+           +	   R		|		+
+		   		   |		+
+				   + - - - - - - - - - - - - - - - -> resolve
+
+				   								  R - input resolved
+  ```
+  A handler is started as soon as it's value is ready/resolved, i.e. 
+  for non-promise values start immediately.
+
+
+2. handle sequentially when value is ready and previous handler is started
+  ```
+    .seqstartiter(
+        [value, promise, promise, value], handler)
+           +      .         .       .        |
+           |                R              <-+ 
+           ++- - >R         .       .        |
+            |     |                        <-+ 
+            +     ++ - - - >+       .        |
+            .      |        |              <-+
+                   +        + - - > +        |
+            .      .                |      <-+
+                                    + - - - - - - - > resolve
+            ^      ^
+            +------+-- returned promise
+				   								  R - input resolved
+  ```
+  A handler is started as soon as all previous handlers are started 
+  and the current value is ready/resolved.
+
+
+3. handle sequentially when value is ready and previous handler is resolved
+  ```
+    .seqiter(
+        [value, promise, promise, value], handler)
+           +      .         .       .        |
+           |                R              <-+
+           ++- - >R         .       .        |
+            |     |                        <-+
+            +     ++        .       .        |
+            .      |                         |
+                   + - - - >+       .        |
+            .      .        |              <-+
+                            + - - > +        |
+            .      .                |      <-+
+                                    + - - - - - - - > resolve
+            ^      ^
+            +------+-- returned promise
+				   								  R - input resolved
+  ```
+  A handler is started as soon as all previous handlers are done, their
+  return values are resolved and the current value is ready/resolved.
+
+
+
 
 #### `Promise.iter(..)` / `promise.IterablePromise(..)`
 

package/package.json

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

package/test.js

@@ -449,6 +449,8 @@ var cases = test.Cases({
 			// NOTE: 4 here is present as it was handled before the promise resolved...
 			[1,2,'stop'],
 			'.seqiter(..): STOP(..): delayed')
+
+		// XXX test .seqstartiter(..)
 	},
 
 	// Date.js