cleanup and tweaking + docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

Promise.js

@@ -118,8 +118,11 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	// NOTE: .catch(..) and .finally(..) are implemented through .then(..)
 	// 		so we do not need to overload those...
+	// NOTE: this is slightly different from .then(..) in that it can be 
+	// 		called without arguments and return a promise wrapper. This can
+	// 		be useful to hide special promise functionality...
 	then: function (onfulfilled, onrejected){
-		return new Promise(
+		var p = new Promise(
 			function(resolve, reject){
 				Promise.prototype.then.call(this,
 					// NOTE: resolve(..) / reject(..) return undefined so
@@ -130,7 +133,9 @@ object.Constructor('IterablePromise', Promise, {
 					function(res){
 						reject(res)
 						return res }) }.bind(this))
-			.then(...arguments) },
+		return arguments.length > 0 ?
+			p.then(...arguments) 
+			: p },
 
 
 	//

README.md

@@ -58,10 +58,12 @@ A library of JavaScript type extensions, types and type utilities.
     - [Interactive promises](#interactive-promises)
       - [`Promise.interactive(..)`](#promiseinteractive)
       - [`<promise-inter>.send(..)`](#promise-intersend)
+      - [`<promise-inter>.then(..)`](#promise-interthen)
     - [Cooperative promises](#cooperative-promises)
-      - [`Promise.cooperative(..)`](#promisecooperative)
+      - [`Promise.cooperative()`](#promisecooperative)
       - [`<promise-coop>.set(..)`](#promise-coopset)
       - [`<promise-coop>.isSet`](#promise-coopisset)
+      - [`<promise-coop>.then(..)`](#promise-coopthen)
     - [Promise iteration](#promise-iteration)
       - [`Promise.iter(..)` / `promise.IterablePromise(..)`](#promiseiter--promiseiterablepromise)
       - [`<promise-iter>.map(..)` / `<promise-iter>.filter(..)` / `<promise-iter>.reduce(..)`](#promise-itermap--promise-iterfilter--promise-iterreduce)
@@ -1232,16 +1234,45 @@ Sending a message triggers message handlers registered via `<onmessage>(..)`
 passing each handler the arguments.
 
 
+#### `<promise-inter>.then(..)`
+
+<!-- XXX -->
+
+See [`<promise-iter>.then(..)`](#promise-iterthen--promise-itercatch--promise-iterfinally) for details.
+
+
 
 ### Cooperative promises
 
-A _cooperative promise_ is one the state of which can be controlled 
-externally/cooperatively.
+A _cooperative promise_ is one that can be finalized externally/cooperatively.
 
-<!-- XXX is this just a special case of the interactive promise??? -->
+This can be useful when breaking recursive dependencies between promises or when
+it is simpler to thread the result receiver promise down the stack than building 
+a promise stack and manually threading the result up.
+
+<!-- XXX Example: show a clear use-case -- ping-pong?... -->
+```javascript
+```
+
+Note that functionally this 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,
+- _Cooperative promises_ do not the implement `.send(..)` API.
+
+Note that implementing _Cooperative promises_ on top of _Interactive promises_ 
+cleanly, though feeling more _"beautiful"_, would be more complex than the 
+current standalone implementation, as it would require both implementing 
+the `.set(..)` API/logic _and_ active encapsulation of the message API.
 
 
-#### `Promise.cooperative(..)`
+
+#### `Promise.cooperative()`
+
+```bnf
+Promise.cooperative()
+    -> <promise-coop>
+```
 
 <!-- XXX -->
 
@@ -1256,6 +1287,13 @@ externally/cooperatively.
 <!-- XXX -->
 
 
+#### `<promise-coop>.then(..)`
+
+<!-- XXX -->
+
+See [`<promise-iter>.then(..)`](#promise-iterthen--promise-itercatch--promise-iterfinally) for details.
+
+
 
 ### Promise iteration
 
@@ -1338,6 +1376,10 @@ Promise.iter(<array>)
 
 <!-- XXX -->
 
+Note that `.then(..)` here can be called without arguments returning a generic 
+promise wrapper. This can be useful to hide the extended promise API from further 
+code.
+
 
 #### Advanced handler
 

package.json

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