From 3fbf1e2c69f0fdb59ac0da3a7eb2cccdd0376c29 Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Mon, 6 Feb 2023 18:48:28 +0300
Subject: [PATCH] docs and cleanup...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 README.md    | 103 +++++++++++++++++++++++++++++++--------------------
 package.json |   2 +-
 test.js      |   2 +
 3 files changed, 66 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index fc7762f..b21d1a4 100644
--- a/README.md
+++ b/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(..)`
 
@@ -1687,46 +1750,6 @@ Return a shallow copy of the current promise iterator.
 
 #### `Promise.seqiter(..)` / `promise.IterableSequentialPromise(..)`
 
-```
-	.iter()
-	[value, promise, promise, value]
-	   + - - > + - - - >+ - - >	+
-	   |	   |		|		|
-	   v	   v		v		v
-```
-
-```
-	.seqstartiter()
-	[value, promise, promise, value]
-	   +	  .			.		.
-	   |	   			 		 
-	   + - - >+			.		.
-	   		  |			 		 
-			  + - - - >	+		.
-			  |			|		
-			  +			+ - - >	+
-						|		|
-						+		+
-```
-
-```
-	.seqiter()
-	[value, promise, promise, value]
-	   +	  .			.		.
-	   |	 
-	   + - - >+			.		.
-	   		  |
-			  +			.		.
-			  |
-			  + - - - >	+		.
-						|
-						+		.
-						|
-			   			+ - - >	+
-								|
-								+
-```
-
 #### `<promise>.seqiter()` / `<promise-iter>.seqiter()`
 
 #### `Promise.seqstartiter(..)` / `promise.IterableSequentialStartPromise(..)`
diff --git a/package.json b/package.json
index e0fe655..81d45f7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ig-types",
-  "version": "6.24.22",
+  "version": "6.24.23",
   "description": "Generic JavaScript types and type extensions...",
   "main": "main.js",
   "scripts": {
diff --git a/test.js b/test.js
index 3d14cad..aef7222 100755
--- a/test.js
+++ b/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