ig-types 6.14.0 → 6.14.1

package/Promise.js

@@ -39,7 +39,7 @@ var object = require('ig-object')
 // 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 
+// NOTE: it would be nice to support throwing STOP (XXX) from the iterable 
 // 		promise but...
 // 		- this is more complicated than simply using .smap(..) instead 
 // 			of .map(..) because the list can contain async promises...
@@ -49,11 +49,27 @@ var object = require('ig-object')
 // 		- 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: the following can not be implemented here:
+// 			.splice(..)				- can't both modify and return
+// 									  a result...
+// 			.pop() / .shift()		- can't modify the promise, use 
+// 									  .first() / .last() instead.
+// 			[Symbol.iterator]()		- needs to be sync and we can't
+// 									  know the number of elements to
+// 									  return promises before the whole
+// 									  iterable promise is resolved.
 // 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...
+// NOTE: there is no point in implementing a 1:1 version of this that 
+// 		would not support element expansion/contraction as it would only 
+// 		simplify a couple of methods that are 1:1 (like .map(..) and 
+// 		.some(..)) while methods like .filter(..) will throw everything
+// 		back to the complex IterablePromise...
+// 		
+// XXX how do we handle errors/rejections???
+// 		
+
 // XXX should these be exported???
 var iterPromiseProxy = 
 //module.iterPromiseProxy = 
@@ -71,6 +87,9 @@ function(name){
 var IterablePromise =
 module.IterablePromise =
 object.Constructor('IterablePromise', Promise, {
+	// packed array...
+	//
+	// Holds promise state.
 	//
 	// Format:
 	// 	[
@@ -87,16 +106,20 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	// NOTE: in general iterable promises are implicitly immutable, so
 	// 		it is not recomended to ever edit this inplace...
-	__list: null,
+	// NOTE: we are not isolation any internals to enable users to 
+	// 		responsibly extend the code.
+	__packed: null,
 
-	// low-level .__list handlers/helpers...
+	// low-level .__packed handlers/helpers...
 	//
 	// NOTE: these can be useful for debugging and extending...
-	__pack: function(list, handler){
+	//
+	// pack and oprionally transform/handle an array (sync)...
+	__pack: function(list, handler=undefined){
 		var that = this
 		// handle iterable promise list...
 		if(list instanceof IterablePromise){
-			return this.__handle(list.__list, handler) }
+			return this.__handle(list.__packed, handler) }
 		// handle promise list...
 		if(list instanceof Promise){
 			return list.then(function(list){
@@ -120,11 +143,12 @@ object.Constructor('IterablePromise', Promise, {
 					: !handle ?
 						elem
 					: handler(elem) }) },
-	__handle: function(list, handler){
+	// transform/handle packed array (sync)...
+	__handle: function(list, handler=undefined){
 		var that = this
 		if(typeof(list) == 'function'){
 			handler = list
-			list = this.__list }
+			list = this.__packed }
 		if(!handler){
 			return list }
 		// handle promise list...
@@ -144,49 +168,28 @@ object.Constructor('IterablePromise', Promise, {
 							return elem.flat() })
 				: [handler(elem)] })
    			.flat() },
-	__unpack: function(list){
+	// unpack array (async)...
+	__unpack: async function(list){
 		list = list 
-			?? this.__list
+			?? this.__packed
 		// handle promise list...
-		if(list instanceof Promise){
-			var that = this
-			return list.then(function(list){
-				return that.__unpack(list) }) }
-		// do the work...
-		return Promise.all(list)
-			.then(function(list){
-				return list.flat() }) },
+		return list instanceof Promise ?
+			this.__unpack(await list)
+			// do the work...
+			: (await Promise.all(list))
+				.flat() },
 
 
 	// iterator methods...
 	//
 	// These will return a new IterablePromise instance...
 	//
-	// When called from a resolved promise these will return a new 
-	// resolved promise with updated values...
-	//
-	// When called from a rejected promise these will return a rejected 
-	// with the same reason promise...
-	//
-	//
 	// NOTE: these are different to Array's equivalents in that the handler
 	// 		is called not in the order of the elements but rather in order 
 	// 		of promise resolution...
 	// NOTE: index of items is unknowable because items can expand and
-	// 		contract depending on handlrs (e.g. .filter(..) can remove 
+	// 		contract depending on handlers (e.g. .filter(..) can remove 
 	// 		items)...
-	// 		This the following can not be implemented here:
-	// 			.slice(..)
-	// 			.splice(..)
-	// 			.values() / .keys()
-	// 			.at(..)
-	// 			[Symbol.iterator]()		- needs to be sync...
-	// 		The followng methods are questionable:
-	// 			.indexOf(..)
-	// 			.includes(..)
-	// 			.some(..) / .every(..)
-	// 			.sort(..)
-	// 		XXX update this note...
 	map: function(func){
 		return this.constructor(this, 
 			function(e){
@@ -208,11 +211,11 @@ object.Constructor('IterablePromise', Promise, {
 					: _filter(e) }) },
 	// NOTE: this does not return an iterable promise as we can't know 
 	// 		what the user reduces to...
-	// 		XXX we could look at the initial state though...
 	// NOTE: the items can be handled out of order because the nested 
 	// 		promises can resolve in any order...
 	// NOTE: since order of execution can not be guaranteed there is no
-	// 		point in implementing .reduceRight(..)
+	// 		point in implementing .reduceRight(..) in the same way 
+	// 		(see below)...
 	reduce: function(func, res){
 		return this.constructor(this, 
 				function(e){
@@ -232,7 +235,7 @@ object.Constructor('IterablePromise', Promise, {
 						e
 					: [e] }) },
 	reverse: function(){
-		var lst = this.__list
+		var lst = this.__packed
 		return this.constructor(
 			lst instanceof Promise ?
 				lst.then(function(elems){
@@ -277,21 +280,24 @@ object.Constructor('IterablePromise', Promise, {
 		return this.constructor([elem])
 			.concat(this) },
 
-	// XXX can we do these?
-	// 			.pop()
-	// 			.shift()
-	// 			.splice(..)
-	// 		...would be nice if these could stop everything that's not
-	// 		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.
+
+	// XXX thses need to stop once an element is found so we cant simply 
+	// 		use .map(..) or .reduce(..)...
+	// XXX .find(func) / .findIndex(func)
+
+
+	// proxy methods...
+	//
+	// These require the whole promise to resolve to trigger.
+	//
+	// An exception to this would be .at(0)/.first() and .at(-1)/.last()
+	// that can get the target element if it's accessible.
+	//
+	// NOTE: methods that are guaranteed to return an array will return
+	// 		an iterable promise (created with iterPromiseProxy(..))...
+	//
 	at: async function(i){
-		var list = this.__list
+		var list = this.__packed
 		return ((i != 0 && i != -1)
 					|| list instanceof Promise
 					|| list.at(i) instanceof Promise) ?
@@ -308,24 +314,35 @@ object.Constructor('IterablePromise', Promise, {
 	last: function(){
 		return this.at(-1) },
 	
+	// NOTE: unlike .reduce(..) this needs the parent fully resolved 
+	// 		to be able to iterate from the end.
+	// XXX ???
+	reduceRight: promiseProxy('reduceRight'),
+
 	// NOTE: there is no way we can do a sync generator returning 
-	// 		promises for values because any promise in .__list makes the 
+	// 		promises for values because any promise in .__packed makes the 
 	// 		value count/index non-deterministic...
 	sort: iterPromiseProxy('sort'),
+	// XXX we could have a special-case here for .slice()/slice(0, -1)
+	// 		and possibly othets, should we???
 	slice: iterPromiseProxy('slice'),
+
 	entries: iterPromiseProxy('entries'),
 	keys: iterPromiseProxy('keys'),
 	// XXX we could possibly make this better via .map(..)
 	values: iterPromiseProxy('values'),
 
 	indexOf: promiseProxy('indexOf'),
+	lastIndexOf: promiseProxy('lastIndexOf'),
 	includes: promiseProxy('includes'),
 
 	every: promiseProxy('every'),
-	// XXX this can be lazy...
+	// XXX this can be lazy... (???)
 	some: promiseProxy('some'),
 
 
+	// promise api...
+	//
 	// Overload .then(..), .catch(..) and .finally(..) to return a plain 
 	// Promise instnace...
 	//
@@ -351,6 +368,13 @@ object.Constructor('IterablePromise', Promise, {
 			: p },
 
 
+	// this is defined globally as Promise.prototype.iter(.,)
+	//
+	// for details see: PromiseMixin(..) below...
+	//iter: function(handler=undefined){ ... },
+
+
+	// constructor...
 	//
 	//	Promise.iter([ .. ])
 	//		-> iterable-promise
@@ -374,7 +398,7 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	// Special cases useful for extending this constructor...
 	//
-	//	Set raw .__list without any pre-processing...
+	//	Set raw .__packed without any pre-processing...
 	//	Promise.iter([ .. ], 'raw')
 	//		-> iterable-promise
 	//
@@ -382,12 +406,6 @@ object.Constructor('IterablePromise', Promise, {
 	//	Promise.iter(false)
 	//		-> iterable-promise
 	//
-	//
-	// XXX iterator/generator as input:
-	// 		- do we unwind here or externally?
-	// 			...feels like with the generator external unwinding is 
-	// 			needed...
-	// XXX how do we handle errors/rejections???
 	__new__: function(_, list, handler){
 		// instance...
 		var promise
@@ -408,9 +426,9 @@ object.Constructor('IterablePromise', Promise, {
 			// handle/pack input data...
 			if(handler != 'raw'){
 				list = list instanceof IterablePromise ?
-					this.__handle(list.__list, handler)
+					this.__handle(list.__packed, handler)
 					: this.__pack(list, handler) }
-			Object.defineProperty(obj, '__list', {
+			Object.defineProperty(obj, '__packed', {
 				value: list,
 				enumerable: false,
 			})
@@ -473,13 +491,14 @@ object.Constructor('InteractivePromise', Promise, {
 			// register a handler...
 			} else {
 				var h = obj == null ?
-					// NOTE: we need to get the handlers from .__message_handlers
-					// 		unless we are not fully defined yet, then use the 
-					// 		bootstrap container (handlers)...
-					// 		...since we can call onmessage(..) while the promise 
-					// 		is still defined there is no way to .send(..) until it
-					// 		returns a promise object, this races here are highly 
-					// 		unlikely...
+					// NOTE: we need to get the handlers from 
+					// 		.__message_handlers unless we are not 
+					// 		fully defined yet, then use the bootstrap 
+					// 		container (handlers)...
+					// 		...since we can call onmessage(..) while 
+					// 		the promise is still defined there is no 
+					// 		way to .send(..) until it returns a promise 
+					// 		object, this races here are highly unlikely...
 					handlers
 					: (obj.__message_handlers = 
 						obj.__message_handlers ?? [])
@@ -566,10 +585,13 @@ object.Constructor('CooperativePromise', Promise, {
 var ProxyPromise =
 module.ProxyPromise =
 object.Constructor('ProxyPromise', Promise, {
-	__new__: function(context, constructor){
-		var proto = 'prototype' in constructor ?
-			constructor.prototype
-			: constructor
+
+	then: IterablePromise.prototype.then,
+
+	__new__: function(context, other, nooverride=false){
+		var proto = 'prototype' in other ?
+			other.prototype
+			: other
 		var obj = Reflect.construct(
 			ProxyPromise.__proto__, 
 			[function(resolve, reject){
@@ -580,6 +602,9 @@ object.Constructor('ProxyPromise', Promise, {
 		// NOTE: we are not using object.deepKeys(..) here as we need 
 		// 		the key origin not to trigger property getters...
 		var seen = new Set()
+		nooverride = nooverride instanceof Array ?
+			new Set(nooverride)
+			: nooverride
 		while(proto != null){
 			Object.entries(Object.getOwnPropertyDescriptors(proto))
 				.forEach(function([key, value]){
@@ -594,6 +619,13 @@ object.Constructor('ProxyPromise', Promise, {
 								&& Object.prototype.run === value.value) 
 							&& !value.enumerable){
 						return }
+					// do not override existing methods...
+					if(nooverride === true ? 
+								key in obj
+							: nooverride instanceof Set ?
+								nooverride.has(key)
+							: nooverride){
+						return }
 					// proxy...
 					obj[key] = promiseProxy(key) })
 			proto = proto.__proto__ } 
@@ -619,7 +651,7 @@ var PromiseProtoMixin =
 module.PromiseProtoMixin =
 object.Mixin('PromiseProtoMixin', 'soft', {
 	as: ProxyPromise,
-	iter: function(handler){
+	iter: function(handler=undefined){
 		return IterablePromise(this, handler) },
 })
 
@@ -629,4 +661,4 @@ PromiseProtoMixin(Promise.prototype)
 
 
 /**********************************************************************
-* vim:set ts=4 sw=4 :                               */ return module })
+* vim:set ts=4 sw=4 nowrap :                        */ return module })

package/README.md

@@ -77,6 +77,9 @@ Library of JavaScript type extensions, types and utilities.
       - [`<promise-iter>.reverse()`](#promise-iterreverse)
       - [`<promise-iter>.concat(..)`](#promise-iterconcat)
       - [`<promise-iter>.push(..)` / `<promise-iter>.unshift(..)`](#promise-iterpush--promise-iterunshift)
+      - [`<promise-iter>.at(..)` / `<promise-iter>.first()` / `<promise-iter>.last()`](#promise-iterat--promise-iterfirst--promise-iterlast)
+      - [Array proxy methods returning `<promise-iter>`](#array-proxy-methods-returning-promise-iter)
+      - [Array proxy methods returning a `<promise>`](#array-proxy-methods-returning-a-promise)
       - [`<promise-iter>.then(..)` / `<promise-iter>.catch(..)` / `<promise-iter>.finally(..)`](#promise-iterthen--promise-itercatch--promise-iterfinally)
       - [Advanced handler](#advanced-handler)
     - [Promise proxies](#promise-proxies)
@@ -1663,6 +1666,54 @@ and [`<array>.unshift(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScr
 see them for more info.
 
 
+#### `<promise-iter>.at(..)` / `<promise-iter>.first()` / `<promise-iter>.last()`
+
+Proxies to the appropriate array methods with a special-case: when getting elements 
+at positions `0` or `-1` (i.e. `.first()` / `.last()`) these _can_ resolve before the
+parent `<promise-iter>`.
+
+XXX
+
+
+#### Array proxy methods returning `<promise-iter>`
+
+- `<promise-iter>.sort(..)`
+- `<promise-iter>.slice(..)`
+- `<promise-iter>.entries()` / `<promise-iter>.keys()` / `<promise-iter>.values()` 
+
+These methods are proxies to the appropriate array methods.
+
+```bnf
+<promise-iter>.<method>(..)
+    -> <promise-iter>
+```
+
+These methods need the parent `<promise-iter>` to resolve before resolving themselves.
+
+XXX links...
+
+
+#### Array proxy methods returning a `<promise>`
+
+- `<promise-iter>.indexOf(..)` 
+- `<promise-iter>.includes(..)` 
+- `<promise-iter>.every(..)` / `<promise-iter>.some(..)`
+
+These methods are proxies to the appropriate array methods.
+
+```bnf
+<promise-iter>.<method>(..)
+    -> <promise>
+```
+
+These methods need the parent `<promise-iter>` to resolve before resolving themselves.
+
+Since the equivalent array methods do not return iterables these will return a basic
+(non-iterable) `<promise>`.
+
+XXX links...
+
+
 #### `<promise-iter>.then(..)` / `<promise-iter>.catch(..)` / `<promise-iter>.finally(..)`
 
 An extension to

package/package.json

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