ig-types 6.13.7 → 6.14.0

package/Promise.js

@@ -1,11 +1,9 @@
 /**********************************************************************
-* 
-*
-*
 *
 * This defines the following extensions to Promise:
 *
 * 	Promise.iter(seq)
+* 	<promise>.iter()
 * 		Iterable promise object.
 * 		Similar to Promise.all(..) but adds basic iterator/generator
 * 		API and will resolve the items as they are ready (resolved).
@@ -19,6 +17,11 @@
 * 		Exposes the API to resolve/reject the promise object 
 * 		externally.
 *
+* 	<promise>.as(obj)
+* 		Promise proxy.
+* 		Proxies the methods available from obj to promise value.
+*
+*
 *
 *
 **********************************************/  /* c8 ignore next 2 */
@@ -28,18 +31,6 @@
 
 var object = require('ig-object')
 
-// XXX required for STOP...
-//var generator = require('./generator')
-
-
-/*********************************************************************/
-
-/* XXX not used yet...
-// NOTE: this is used in a similar fashion to Python's StopIteration...
-var STOP =
-module.STOP =
-	object.STOP
-//*/
 
 
 //---------------------------------------------------------------------
@@ -48,13 +39,38 @@ module.STOP =
 // Like Promise.all(..) but adds ability to iterate through results
 // via generators .map(..)/.reduce(..) and friends...
 // 
+// NOTE: it would be nice to support throwing STOP from the iterable 
+// 		promise but...
+// 		- this is more complicated than simply using .smap(..) instead 
+// 			of .map(..) because the list can contain async promises...
+// 			...would need to wrap each .then(..) call in try-catch and
+// 			manually handle the stop...
+// 			...then there's a question of derivative iterators etc.
+// 		- another issue here is that the stop would happen in order of 
+// 			execution and not order of elements...
+// 		XXX though stopping within a single level might be useful...
+//
+
+// NOTE: we are not using async/await here as we need to control the 
+// 		type of promise returned in cases where we know we are returning 
+// 		an array...
+// XXX should these be exported???
+var iterPromiseProxy = 
+//module.iterPromiseProxy = 
+function(name){
+	return function(...args){
+		return this.constructor(
+			this.then(function(lst){
+				return lst[name](...args) })) } }
+var promiseProxy =
+//module.promiseProxy =
+function(name){
+	return async function(...args){
+		return (await this)[name](...args) } }
 
 var IterablePromise =
 module.IterablePromise =
 object.Constructor('IterablePromise', Promise, {
-	// XXX
-	//STOP: object.STOP,
-
 	//
 	// Format:
 	// 	[
@@ -64,6 +80,13 @@ object.Constructor('IterablePromise', Promise, {
 	//		...
 	// 	]
 	//
+	// This format has several useful features:
+	// 	- concatenating packed list results in a packed list
+	// 	- adding an iterable promise (as-is) into a packed list results 
+	// 		in a packed list
+	//
+	// NOTE: in general iterable promises are implicitly immutable, so
+	// 		it is not recomended to ever edit this inplace...
 	__list: null,
 
 	// low-level .__list handlers/helpers...
@@ -163,6 +186,7 @@ object.Constructor('IterablePromise', Promise, {
 	// 			.includes(..)
 	// 			.some(..) / .every(..)
 	// 			.sort(..)
+	// 		XXX update this note...
 	map: function(func){
 		return this.constructor(this, 
 			function(e){
@@ -196,6 +220,7 @@ object.Constructor('IterablePromise', Promise, {
 					return [] })
 			.then(function(){ 
 				return res }) },
+
 	flat: function(depth=1){
 		return this.constructor(this, 
 			function(e){ 
@@ -252,14 +277,54 @@ object.Constructor('IterablePromise', Promise, {
 		return this.constructor([elem])
 			.concat(this) },
 
-	// XXX do we need these?
+	// XXX can we do these?
 	// 			.pop()
 	// 			.shift()
-	// 			.first() / .last()
-	// 			.at(..)
+	// 			.splice(..)
 	// 		...would be nice if these could stop everything that's not
-	// 		needed to execute...
+	// 		needed to execute -- likely not possible (XXX)
+	// 		...these need to somehow both return an element and affect 
+	// 		the iterator (or return a new one) -- we can trivially do either
+	// 		one action within the spec but not both...
+
+	// NOTE: this can avoid waiting for the whole promise to resolve only
+	// 		for indexes 0 and -1, everything else is non-deterministic and
+	// 		we'll have to wait for the whole thing to resolve.
+	at: async function(i){
+		var list = this.__list
+		return ((i != 0 && i != -1)
+					|| list instanceof Promise
+					|| list.at(i) instanceof Promise) ?
+				(await this).at(i)
+			// NOTE: we can only reason about first/last explicit elements, 
+			// 		anything else is non-deterministic...
+			: list.at(i) instanceof Promise ?
+				[await list.at(i)].flat().at(i)
+			: list.at(i) instanceof Array ?
+				list.at(i).at(i)
+			: list.at(i) },
+	first: function(){
+		return this.at(0) },
+	last: function(){
+		return this.at(-1) },
 	
+	// NOTE: there is no way we can do a sync generator returning 
+	// 		promises for values because any promise in .__list makes the 
+	// 		value count/index non-deterministic...
+	sort: iterPromiseProxy('sort'),
+	slice: iterPromiseProxy('slice'),
+	entries: iterPromiseProxy('entries'),
+	keys: iterPromiseProxy('keys'),
+	// XXX we could possibly make this better via .map(..)
+	values: iterPromiseProxy('values'),
+
+	indexOf: promiseProxy('indexOf'),
+	includes: promiseProxy('includes'),
+
+	every: promiseProxy('every'),
+	// XXX this can be lazy...
+	some: promiseProxy('some'),
+
 
 	// Overload .then(..), .catch(..) and .finally(..) to return a plain 
 	// Promise instnace...
@@ -295,8 +360,9 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	//
 	// 	handler(e)
-	// 		-> [value]
+	// 		-> [value, ..]
 	// 		-> []
+	// 		-> <promise>
 	//
 	//
 	// NOTE: element index is unknowable until the full list is expanded
@@ -321,14 +387,7 @@ object.Constructor('IterablePromise', Promise, {
 	// 		- do we unwind here or externally?
 	// 			...feels like with the generator external unwinding is 
 	// 			needed...
-	// XXX would be nice to support throwing STOP...
-	// 		- this is more complicated than simply suing .smap(..) instead 
-	// 			of .map(..) because the list can contain async promises...
-	// 			...would need to wrap each .then(..) call in try-catch and
-	// 			manually handle the stop...
-	// 		- another issue here is that the stop would happen in order of 
-	// 			execution and not order of elements...
-	// XXX how do we handle errors???
+	// XXX how do we handle errors/rejections???
 	__new__: function(_, list, handler){
 		// instance...
 		var promise
@@ -344,7 +403,7 @@ object.Constructor('IterablePromise', Promise, {
 				promise = {resolve, reject} }], 
 			IterablePromise)
 
-		// new instance...
+		// populate new instance...
 		if(promise){
 			// handle/pack input data...
 			if(handler != 'raw'){
@@ -536,10 +595,7 @@ object.Constructor('ProxyPromise', Promise, {
 							&& !value.enumerable){
 						return }
 					// proxy...
-					obj[key] = function(...args){
-						// XXX should we also .catch(..) here???
-						return context.then(function(res){
-							return res[key](...args) }) } })
+					obj[key] = promiseProxy(key) })
 			proto = proto.__proto__ } 
 		return obj },
 })

package/README.md

@@ -1508,6 +1508,17 @@ promise, even if the original is resolved.
 If all values are resolved the `<promise-iter>` will resolve on the next 
 execution frame.
 
+There are two types of iterator methods here, both are transparent but different
+in how they process values:
+- *Parallel methods*  
+  These handle elements as soon as they are available even if the parent promise
+  is not yet resolved.
+  <!-- XXX list -->
+- *Proxies*
+  These methods simply wait for the main promise to resolve and then call the
+  appropriate method on the result.
+  <!-- XXX list + mark definitions as "(proxy)" -->
+
 <!-- 
 XXX should we support generators as input?
     ...not sure about the control flow direction here, on one hand the generator

package/package.json

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