ig-types 6.24.16 → 6.24.20

package/Promise.js

@@ -34,6 +34,292 @@ var generator = require('./generator')
 
 
 
+//---------------------------------------------------------------------
+
+// packed format API...
+//
+// This is separate from IterablePromise to enable low-level testing and
+// experimentation.
+//
+// Packed format
+// 	[
+// 		<value>,
+//
+// 		[
+// 			<value>,
+//
+// 			<promise( <value> )>,
+//
+// 			.. 
+// 		],
+//
+// 		<promise( <value> )>,
+//
+// 		<promise( [ <value>, .. ] )>,
+//
+// 		..
+// 	]
+//
+// 	<packed> ::=
+// 		<value>
+// 		| <packed-array>
+// 		| <promise( <value> )>
+// 		| <promise( <packed-array> )>
+//
+// 	<packed-array> ::=
+// 		[ <packed-item>, .. ]
+//
+// 	<packed-item> ::=
+// 		<value>
+// 		| [ <nested-value>, .. ]
+// 		| <promise( <value> )>
+// 		| <promise( [ <value>, .. ] )>
+//
+// 	<nested-value> ::=
+// 		<value>
+// 		| <promise( <value> )>
+//		
+// 	
+//
+// XXX revise bnf...
+// XXX should this be a container or just a set of function???
+// 		...for simplicity I'll keep it a stateless set of functions for 
+// 		now, to avoid yet another layer of indirection -- IterablePromise...
+var packed = 
+module.packed =
+{
+	//
+	//	pack(<array>)
+	//	pack(<promise>)
+	//		-> <packed>
+	//
+	// NOTE: when all promises are expanded the packed array can be unpacked 
+	// 		by simply calling .flat()
+	// NOTE: if 'types/Array' is imported this will support throwing STOP
+	// 		from the handler.
+	// 		Due to the async nature of promises though the way stops are 
+	// 		handled may be unpredictable -- the handlers can be run out 
+	// 		of order, as the nested promises resolve and thus throwing 
+	// 		stop will stop the handlers not yet run and not the next 
+	// 		handlers in sequence.
+	// XXX does this need onerror(..) ???
+	// 		...essentially this can make sense only in generator expansion,
+	// 		but not sure if this should be done here as it is sync...
+	pack: function(list){
+		var that = this
+		// list: promise...
+		// XXX should we just test for typeof(list.then) == 'function'???
+		// XXX should we expand async generators here???
+		if(list instanceof Promise
+				// list: async promise...
+				|| (typeof(list) == 'object' 
+					&& list.then
+					&& Symbol.asyncIterator in list)){
+			return list
+				.then(this.pack.bind(this)) }
+		// list: generator...
+		if(typeof(list) == 'object' 
+				&& !list.map
+				&& Symbol.iterator in list){
+			list = [...list] }
+		/* XXX on one hand this should be here and on the other I'm not 
+		// 		sure how are we going to thread handler and onerror to 
+		// 		here...
+		// list: promise / async-iterator...
+		if(typeof(list) == 'object' 
+					&& Symbol.asyncIterator in list){
+			return list
+				// XXX
+				.iter(handler, onerror) 
+				.then(function(list){
+					return that.pack(list) }) } 
+		//*/
+		// list: non-array / non-iterable...
+		if(typeof(list.map) != 'function'){
+			list = [list].flat() }
+		// list: array...
+		return list
+			.map(function(elem){
+				// XXX should we expand generators here???
+				return elem instanceof Array ?
+						[elem]
+					// XXX should we just test for .then(..)???
+					: elem instanceof Promise ?
+						elem.then(function(elem){
+							return elem instanceof Array ?
+								[elem]
+								: elem })
+					: elem }) },
+	// 
+	// 	handle(<packed>, <handler>[, <onerror>])
+	// 		-> <packed>
+	//
+	handle: function(packed, handler, onerror){
+		var that = this
+		var handlers = [...arguments].slice(1)
+
+		if(packed instanceof Promise){
+			return packed.then(function(packed){
+				return that.handle(packed, ...handlers) }) }
+
+		var handleSTOP = function(err){
+			if(err && err === Array.STOP){
+				stop = true
+				return []
+			} else if(err && err instanceof Array.STOP){
+				return err.value }
+			throw err }
+
+		var stop = false
+		var map = Array.STOP ?
+			'smap'
+			: 'map'
+		return packed
+			// NOTE: we do not need to rapack after this because the handlers 
+			// 		will get the correct (unpacked) values and it's their 
+			// 		responsibility to pack them if needed...
+			// NOTE: this removes the need to handle sub-arrays unless they are
+			// 		in a promise...
+			.flat()
+			[map](
+				function(elem){
+					return elem instanceof Promise ?
+						elem.then(function(elem){
+							if(stop){
+								return [] }
+							try{
+								var has_promise = false
+								// NOTE: do the same thing handle(..) does 
+								// 		but on a single level, without expanding 
+								// 		arrays...
+								if(elem instanceof Array){
+									var res = elem.map(function(elem){
+										var res = elem instanceof Promise ?
+											elem.then(function(elem){
+												try{
+													return !stop ?
+														handler(elem) 
+														: [] 
+												} catch(err){
+													return handleSTOP(err) } })
+											: handler(elem)
+										has_promise = has_promise
+											|| res instanceof Promise
+										return res })
+								// non-arrays...
+								} else {
+									// NOTE: we are wrapping the result in an array to 
+									// 		normalize it with the above...
+									res = [handler(elem)]
+									has_promise = has_promise 
+										|| res[0] instanceof Promise }
+
+								// compensate for the outer .flat()...
+								// NOTE: at this point res is always an array...
+								return has_promise ?
+									// NOTE: since we are already in a promise 
+									// 		grouping things here is not a big 
+									// 		deal, however this is needed to link 
+									// 		nested promises with the containing 
+									// 		promise...
+									Promise.all(res)
+										.then(function(res){
+											return res.flat() })
+									: res.flat() 
+							} catch(err){
+								return handleSTOP(err) } })
+						: handler(elem) },
+				// onerror...
+				function(err){
+					stop = true
+					typeof(onerror) == 'function'
+						&& onerror(err) }) },
+	//
+	// 	unpack(<packed>)
+	// 		-> <array>
+	//
+	unpack: function(packed){
+		if(packed instanceof Promise){
+			return packed.then(this.unpack.bind(this)) }
+		var input = packed
+		// NOTE: we expand promises on the first two levels of the packed 
+		// 		list and then flatten the result...
+		for(var [i, elem] of Object.entries(packed)){
+			// expand promises in lists...
+			if(elem instanceof Array){
+				for(var e of elem){
+					if(e instanceof Promise){
+						// copy the input (on demand) list as we'll need to 
+						// modify it...
+						packed === input
+							&& (packed = packed.slice())
+						// NOTE: this will immediately be caught by the 
+						// 		Promise condition below...
+						elem = packed[i] = 
+							Promise.all(elem)
+						break } } }
+			// expand promises...
+			if(elem instanceof Promise){
+				return Promise.all(packed)
+					.then(this.unpack.bind(this)) } }
+		// the list is expanded here...
+		return packed.flat() },
+}
+
+
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+
+//
+// 	itemResolved(<list>, <onupdate>[, <ondone>])
+// 	itemResolved(<list>, <options>)
+// 		-> <list>
+//
+// 	<onupdate>(<elem>, <index>, <list>)
+//
+// 	<ondone>(<list>)
+//
+// options format:
+// 	{
+// 		onupdate: <func>,
+//
+// 		// optional
+// 		ondone: <func>,
+// 	}
+//
+// XXX rename to Promise.each(..) or Promise.eachPromise(..) ???
+var itemResolved =
+module.itemResolved =
+function(list, onupdate, ondone){
+	if(typeof(onupdate) != 'function'){
+		var {onupdate, ondone} = onupdate }
+	typeof(ondone) == 'function'
+		&& Promise.all(list)
+			.then(ondone)
+	for(let [i, elem] of Object.entries(list)){
+		if(elem instanceof Promise){
+			elem.then(function(elem){
+				onupdate(elem, i, list) }) } }
+	return list }
+
+// Like itemResolved(..) but both onupdate and ondone are optional...
+//
+// XXX do not modify the array after this is called and until ondone(..) is called...
+// XXX should this know how to expand things???
+var selfResolve =
+module.selfResolve =
+function(list, onupdate, ondone){
+	if(onupdate 
+			&& typeof(onupdate) != 'function'){
+		var {onupdate, ondone} = onupdate }
+	return itemResolved(list, 
+		function(elem, i, list){
+			list[i] = elem 
+			typeof(onupdate) == 'function'
+				&& onupdate(elem, i, list) }, 
+		ondone) }
+
+
+
 //---------------------------------------------------------------------
 // Iterable promise...
 // 
@@ -63,6 +349,9 @@ var generator = require('./generator')
 // XXX add support for async generators...
 // 		
 
+var EMPTY = {doc: 'empty placeholder'}
+
+
 var iterPromiseProxy = 
 module.iterPromiseProxy = 
 function(name){
@@ -114,284 +403,45 @@ object.Constructor('IterablePromise', Promise, {
 	// NOTE: these can be useful for debugging and extending...
 	//
 	// pack and oprionally transform/handle an array (sync)...
-	//
-	// NOTE: if 'types/Array' is imported this will support throwing STOP
-	// 		from the handler.
-	// 		Due to the async nature of promises though the way stops are 
-	// 		handled may be unpredictable -- the handlers can be run out 
-	// 		of order, as the nested promises resolve and thus throwing 
-	// 		stop will stop the handlers not yet run and not the next 
-	// 		handlers in sequence.
-	// 		XXX EXPEREMENTAL: STOP...
-	// XXX ITER can we unwind (sync/async) generators one by one???
-	/* XXX this repeats part of the functionality of .__handle(..)
 	__pack: function(list, handler=undefined, onerror=undefined){
-		var that = this
-		// handle iterator...
-		// XXX ITER do we unwind the iterator here or wait to unwind later???
-		if(typeof(list) == 'object' 
-				&& Symbol.iterator in list){
-			if(!onerror){
-				list = [...list]
-			// handle errors in input generator...
-			// NOTE: this does not offer the most control because semantically 
-			// 		we bust behave in the same manner as <generator>.iter(..)
-			} else {
-				var res = []
-				try{
-					for(var e of list){
-						res.push(e) }
-				}catch(err){
-					var r = onerror(err)
-					r !== undefined
-						&& res.push(r) } 
-				list = res } } 
 		// handle iterable promise...
 		if(list instanceof IterablePromise){
 			return this.__handle(list.__packed, handler, onerror) }
 		// handle promise / async-iterator...
-		// XXX ITER do we unwind the iterator here or wait to unwind later???
 		if(typeof(list) == 'object' 
 					&& Symbol.asyncIterator in list){
 			return list
 				.iter(handler, onerror) 
 				.then(function(list){
 					return that.__pack(list) }) } 
-		if(list instanceof Promise){
-			return list
-				.then(function(list){
-					return that.__pack(list, handler, onerror) }) }
-		// do the work...
-		// NOTE: packing and handling are mixed here because it's faster
-		// 		to do them both on a single list traverse...
-		var handle = !!handler
-		handler = handler 
-			?? function(elem){ 
-				return [elem] }
-		// XXX this repeats .__handle(..), need to unify...
-		var stop = false
-		var map = 'map'
-		var pack = function(){
-			return [list].flat()
-				[map](function(elem){
-					// XXX EXPEREMENTAL...
-					return elem instanceof IterablePromise ?
-							(elem.isSync() ?
-								handler(elem.sync())
-								// XXX need to handle this but keep it IterablePromise...
-								: elem.iterthen(handler))
-						: (elem instanceof SyncPromise
-								&& !(elem.sync() instanceof Promise)) ?
-							handler(elem.sync())
-						: elem && elem.then ?
-							(handleSTOP ?
-								// stoppable -- need to handle stop async...
-								elem
-									.then(function(res){
-										return !stop ?
-											handler(res)
-											: [] }) 
-									// NOTE: we are using .catch(..) here
-									// 		instead of directly passing the
-									// 		error handler to be able to catch
-									// 		the STOP from the handler...
-									.catch(handleSTOP)
-								// non-stoppable...
-								: elem.then(handler))
-						: elem instanceof Array ?
-							handler(elem)
-						// NOTE: we keep things that do not need protecting 
-						// 		from .flat() as-is...
-						: !handle ?
-							elem
-						: handler(elem) }) }
-		// pack (stoppable)...
-		if(!!this.constructor.STOP){
-			map = 'smap'
-			var handleSTOP = function(err){
-				// handle stop...
-				stop = err
-				if(err === that.constructor.STOP
-						|| err instanceof that.constructor.STOP){
-					return 'value' in err ?
-						err.value
-						: [] }
-				throw err }
-			try{
-				return pack()
-			}catch(err){
-				return handleSTOP(err) } }
 
-		// pack (non-stoppable)...
-		return pack() },
-	// transform/handle packed array (sync, but can return promises in the list)...
-	__handle: function(list, handler=undefined, onerror=undefined){
-		var that = this
-		if(typeof(list) == 'function'){
-			handler = list
-			list = this.__packed }
-		if(!handler){
-			return list }
-		// handle promise list...
-		if(list instanceof Promise){
-			return list.then(function(list){
-				return that.__handle(list, handler, onerror) }) }
-		// do the work...
-		// NOTE: since each section of the packed .__array is the same 
-		// 		structure as the input we'll use .__pack(..) to handle 
-		// 		them, this also keeps all the handling code in one place.
-		var map = !!this.constructor.STOP ?
-			'smap'
-			: 'map'
-		return list[map](function(elem){
-				elem = elem instanceof Array 
-						|| elem instanceof Promise ?
-					that.__pack(elem, handler, onerror)
-					: [handler(elem)]
-				elem = elem instanceof Promise ?
-					elem.then(function([e]){
-						return e })
-					: elem
-				return elem })
-   			.flat() },
-	/*/
-	__pack: function(list, handler=undefined, onerror=undefined){
-		var that = this
-		// handle iterator...
-		// XXX ITER do we unwind the iterator here or wait to unwind later???
-		if(typeof(list) == 'object' 
-				&& Symbol.iterator in list){
-			if(!onerror){
-				list = [...list]
-			// handle errors in input generator...
-			// NOTE: this does not offer the most control because semantically 
-			// 		we bust behave in the same manner as <generator>.iter(..)
-			} else {
-				var res = []
-				try{
-					for(var e of list){
-						res.push(e) }
-				}catch(err){
-					var r = onerror(err)
-					r !== undefined
-						&& res.push(r) } 
-				list = res } } 
-		// handle iterable promise...
-		if(list instanceof IterablePromise){
-			return this.__handle(list.__packed, handler, onerror) }
-		// handle promise / async-iterator...
-		// XXX ITER do we unwind the iterator here or wait to unwind later???
-		if(typeof(list) == 'object' 
-					&& Symbol.asyncIterator in list){
-			return list
-				.iter(handler, onerror) 
-				.then(function(list){
-					return that.__pack(list) }) } 
-		if(list instanceof Promise){
-			return list
-				.then(function(list){
-					return that.__pack(list, handler, onerror) }) }
-		// pack...
-		list = [list].flat()
-			.map(function(elem){
-				return elem instanceof Array ?
-						[elem]
-					: elem instanceof Promise ?
-						elem.then(function(e){
-							return [e] })
-					: elem })
+		// do the packing...
+		var packed = module.packed.pack(list)
 		// handle if needed...
 		return handler ?
-			this.__handle(list, handler, onerror)
-			: list },
+			this.__handle(packed, handler, onerror)
+			: packed },
 	// transform/handle packed array (sync, but can return promises in the list)...
-	// XXX need a strict spec...
-	__handle: function(list, handler=undefined, onerror=undefined){
+	__handle: function(packed, handler=undefined, onerror=undefined){
 		var that = this
-		if(typeof(list) == 'function'){
-			handler = list
-			list = this.__packed }
+		// do .__handle(<func>)
+		if(typeof(packed) == 'function'){
+			handler = packed
+			packed = this.__packed }
 		if(!handler){
-			return list }
-		// handle promise list...
-		if(list instanceof Promise){
-			return list.then(function(list){
-				return that.__handle(list, handler, onerror) }) }
-		// do the work...
-		list = list instanceof Array ?
-			list
-			: [list]
-		var map = !!this.constructor.STOP ?
-			'smap'
-			: 'map'
-		var stop = false
-		// XXX do we handle generators here???
-		var each = function(elem){
-			return elem instanceof Array ?
-				elem
-					.map(handler)
-					.flat()
-				: handler(elem) }
-		return list
-			[map](
-				function(elem){
-					// NOTE: we are calling .flat() on the result so we 
-					// 		need to keep a handled array as a single 
-					// 		element by wrapping the return of handled(..)...
-					return elem instanceof IterablePromise ?
-							(elem.isSync() ?
-								each(elem.sync())
-								: elem.iterthen(each))
-						// sync sync promise...
-						: (elem instanceof SyncPromise
-								&& !(elem.sync() instanceof Promise)) ?
-							[each(elem.sync())]
-						// promise / promise-like...
-						: elem && elem.then ?
-							// NOTE: when this is explicitly stopped we 
-							// 		do not call any more handlers after 
-							// 		STOP is thrown/returned...
-							// NOTE: the promise protects this from .flat()
-							elem.then(function(elem){
-								return !stop ?
-									each(elem)
-									: [] })
-						: elem instanceof Array ?
-							[each(elem)]
-						: each(elem) },
-				// handle STOP...
-				function(){
-					stop = true })
-   			.flat() },
-	//*/
-	// XXX this should return IterablePromise if .__packed is partially sync (???)
+			return packed }
+		return module.packed.handle(packed, ...[...arguments].slice(1)) },
 	// unpack array (sync/async)...
-	__unpack: function(list){
-		list = list 
+	__unpack: function(packed){
+		// do .__unpack()
+		packed = packed 
 			?? this.__packed
 		// handle promise list...
-		if(list instanceof IterablePromise){
-			return list.__unpack() }
-		if(list instanceof Promise){
-			return list
-				.then(this.__unpack.bind(this)) }
-		var res = []
-		for(var e of list){
-			if(e instanceof IterablePromise){
-				e = e.__unpack() }
-			if(e instanceof SyncPromise){
-				e = e.sync() }
-			// give up on a sync solution...
-			if(e instanceof Promise){
-				// XXX can we return an IterablePromise???
-				// XXX is there a more elegant way to do this???
-				return Promise.all(list)
-					.then(function(list){ 
-						return list.flat() })
-					.iter() }
-			res.push(e) }
-		return res.flat() },
-	
+		if(packed instanceof IterablePromise){
+			return packed.__unpack() }
+		return module.packed.unpack(packed) },
+
+
 	[Symbol.asyncIterator]: async function*(){
 		var list = this.__packed
 		if(list instanceof Promise){
@@ -415,22 +465,19 @@ object.Constructor('IterablePromise', Promise, {
 	map: function(func){
 		return this.constructor(this, 
 			function(e){
-				var res = func(e)
-				return res instanceof Promise ?
-		   			res.then(function(e){ 
-						return [e] })
-					: [res] }) },
+				return [func(e)] }) },
 	filter: function(func){
 		return this.constructor(this, 
 			function(e){
 				var res = func(e)
-				var _filter = function(elem){
-					return res ?
-						[elem]
-						: [] }
 				return res instanceof Promise ?
-					res.then(_filter)
-					: _filter(e) }) },
+					res.then(function(res){
+						return res ?
+							[e]
+							: [] })
+					: res ?
+						[e]
+					: [] }) },
 	// NOTE: this does not return an iterable promise as we can't know 
 	// 		what the user reduces to...
 	// NOTE: the items can be handled out of order because the nested 
@@ -756,6 +803,7 @@ object.Constructor('IterablePromise', Promise, {
 	// NOTE: if 'types/Array' is imported this will support throwing STOP,
 	// 		for more info see notes for .__pack(..)
 	// 		XXX EXPEREMENTAL: STOP...
+	// XXX use selfResolve(..)
 	__new__: function(_, list, handler=undefined, onerror=undefined){
 		// instance...
 		var promise
@@ -803,12 +851,16 @@ object.Constructor('IterablePromise', Promise, {
 			list instanceof Promise ?
 				list.then(function(list){
 					obj.__packed = list })
+				/*/ XXX use selfResolve(..)
+				: selfResolve(list) }
+				/*/
 				: list.forEach(function(elem, i){
 					elem instanceof Promise
 						&& elem.then(function(elem){
 							lst = obj.__packed.slice()
 							lst[i] = elem
 							obj.__packed = lst }) }) }
+				//*/
 		return obj },
 })
 
@@ -816,6 +868,7 @@ object.Constructor('IterablePromise', Promise, {
 
 //---------------------------------------------------------------------
 // XXX EXPEREMENTAL/HACK...
+// Sequential iterable promise...
 
 // This like IterablePromise but guarantees handler execution in order 
 // element occurrence.
@@ -827,7 +880,7 @@ object.Constructor('IterablePromise', Promise, {
 // 		Promise.iter([ .. ]).iter(func)
 // 			- func per element
 // 			- func is called when an element is resolved/ready 
-// 				in any order
+// 				in order of resolution/readiness
 // 		Promise.seqiter([ .. ]).iter(func)
 // 			- func per element
 // 			- func is called when an element is resolved/ready 
@@ -836,6 +889,13 @@ object.Constructor('IterablePromise', Promise, {
 // NOTE: that here a promise will block handling of later promises even 
 // 		if they are resolved before it.
 //
+// XXX is this correct???
+// 			> g = function*(){ yield* [1,2,3] }
+//			// XXX should this expand the generator???
+//			> await Promise.seqiter([0, g()])
+//				-> [ 0, Object [Generator] {} ]
+//			> await Promise.seqiter([0, g()]).flat()
+//				-> [ 0, 1, 2, 3 ]
 // XXX check if this behaves correctly (call order) on concatenation and
 // 		other methods...
 // XXX not sure if this is a viable strategy....
@@ -848,13 +908,14 @@ object.Constructor('IterableSequentialPromise', IterablePromise, {
 		var repack = function(list){
 			var res = []
 			for(var [i, e] of list.entries()){
-				// XXX check for .then(..) instead???
-				//if(e instanceof Promise 
 				if(e.then
 						// skip last promise -- nothing to wrap...
 						&& i < list.length-1){
 					res.push(e
 						.then(function(e){ 
+							// NOTE: this does not call any handlers, thus
+							// 		there should be no risk of out of order 
+							// 		handler execution....
 							return seqiter(
 									[e, ...list.slice(i+1)])
 								.flat() }))
@@ -867,14 +928,12 @@ object.Constructor('IterableSequentialPromise', IterablePromise, {
 		list = list instanceof SyncPromise ?
 			list.sync()
 			: list
+		// repack...
 		list = list instanceof Array ?
 				repack(list)
-			// XXX check for .then(..) instead???
-			//: list instanceof Promise ?
 			: list.then ?
 				list.then(repack)
 			: list 
-
 		return handler ?
 			this.__handle(list, handler, onerror)
 			: list },

package/package.json

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

package/runner.js

@@ -12,6 +12,8 @@
 * 		- ...
 * 	would be nice to make the task just a slightly extended or better
 * 	defined function/generator, ideally to make them interchangable...
+* XXX BUG: there seems to be an odd bug somplace here where each item 
+* 	gets processed once per "thread"... (ImageGrid.Viewer export)
 *
 **********************************************/  /* c8 ignore next 2 */
 ((typeof define)[0]=='u'?function(f){module.exports=f(require)}:define)
@@ -360,6 +362,7 @@ object.Constructor('Queue', Array, {
 			// report...
 			that.trigger('taskCompleted', task, res) }
 		var fail = {doc: 'fail runningDone(..)'}
+		// XXX should this also remove .__running when empty???
 		var runningDone = function(mode){
 			running.splice(0, running.length, 
 				// NOTE: there can be multiple occurrences of res...
@@ -409,7 +412,7 @@ object.Constructor('Queue', Array, {
 		// collect results...
 		this.collect_results
 			&& res !== module.SKIP
-			&& (this.__results = this.__results || []).push(res)
+			&& (this.__results = this.__results ?? []).push(res)
 
 		// handle task results...
 		//
@@ -516,6 +519,9 @@ object.Constructor('Queue', Array, {
 	//
 	// NOTE: this helps get around the argument number limitation in JS...
 	add: function(tasks){
+		tasks = tasks instanceof Array ?
+			tasks
+			: [tasks]
 		// handle too large a number of args...
 		var MAX_ARGS = 10000
 		if(tasks.length > MAX_ARGS){
@@ -568,37 +574,51 @@ module.FinalizableQueue =
 object.Constructor('FinalizableQueue', Queue, {
 	auto_stop: true,
 
+	// not for direct use...
+	__freeze: function(){
+		Object.freeze(this)
+		// XXX do we remove/freeze .__running???
+		this.__results
+			&& Object.freeze(this.__results) 
+		return this },
+
 	__onempty__: function(){
 		return this.trigger('done') },
 
 	done: events.Event('done', function(handle){
 		// abort only once...
-		if(this.state == 'aborted' || this.state == 'done'){
+		if(this.state == 'aborted' 
+				|| this.state == 'done'){
 			return handle(false) }
 		this.__state = 'done' 
-		Object.freeze(this) }),
+		this.__freeze() }),
 	abort: events.Event('abort', function(handle){
 		// abort only once...
-		if(this.state == 'aborted' || this.state == 'done'){
+		if(this.state == 'aborted' 
+				|| this.state == 'done'){
 			return handle(false) }
 		this.__state = 'aborted' 
-		Object.freeze(this) }),
+		this.__freeze() }),
 
 	// NOTE: each handler will get called once when the next time the 
 	// 		queue is emptied...
 	promise: function(){
+		return this.__promise },
+	then: function(onresolve, onreject){
+		return this.promise().then(...arguments) },
+	catch: function(onreject){
+		return this.promise().catch(...arguments) },
+
+	__init__: function(options){
 		var that = this
-		return new Promise(function(resolve, reject){
+		this.__promise = new Promise(function(resolve, reject){
 			that
 				.one('done', function(){
 					resolve(...(that.collect_results ? 
-						[that.__results || []]
+						[that.__results ?? []]
 						: [])) })
-				.one('abort', reject) }) },
-	then: function(onresolve, onreject){
-		return this.promise().then(...arguments) },
-	catch: function(onreject){
-		return this.promise().catch(...arguments) },
+				.one('abort', reject) })
+		return object.parentCall(FinalizableQueue.prototype.__init__, this, ...arguments) },
 })
 
 

package/test.js

@@ -112,9 +112,9 @@ var cases = test.Cases({
 	},
 
 	IterablePromise: test.TestSet(function(){
-		var create = function(assert, value){
+		var create = function(assert, value, expected){
 			return {
-				input: value, 
+				input: expected ?? value, 
 				output: assert(Promise.iter(value), 'Promise.iter(', value, ')'),
 			} }
 
@@ -136,29 +136,53 @@ var cases = test.Cases({
 			array_mixed: function(assert){
 				return create(assert, [1, Promise.resolve(2), 3]) },
 			nested_array_mixed: function(assert){
-				return create(assert, [
-					1, 
-					Promise.resolve(2), 
-					[3], 
-					Promise.resolve([4]),
-				]) },
+				return create(assert, 
+					[1, Promise.resolve(2), [3], Promise.resolve([4])],
+					[1, 2, [3], [4]]) },
 			promise_array_mixed: function(assert){
-				return create(assert, Promise.resolve([1, Promise.resolve(2), 3])) },
+				return create(assert, 
+					Promise.resolve([1, Promise.resolve(2), 3]), 
+					[1, 2, 3]) },
 			promise_nested_array_mixed: function(assert){
-				return create(assert, Promise.resolve([
-					1, 
-					Promise.resolve(2), 
-					[3], 
-					Promise.resolve([4]),
-				])) },
+				return create(assert, 
+					Promise.resolve([
+						1, 
+						Promise.resolve(2), 
+						[3],
+						Promise.resolve([4]),
+					]),
+					[1, 2, [3], [4]]) },
 		})
 		this.Modifier({
 			nest: function(assert, setup){
 				setup.output = Promise.iter(setup.output)
 				return setup },
-			iter: function(assert, setup){
+			iter_noargs: function(assert, setup){
 				setup.output = setup.output.iter()
 				return setup },
+			iter_asis: function(assert, setup){
+				setup.output = setup.output
+					.iter(function(e){ 
+						return [e] })
+				return setup },
+			iter_clear: function(assert, setup){
+				return {
+					input: [],
+					output: setup.output
+						.iter(function(e){ 
+							return [] }),
+				} },
+			/* XXX does not account for promises as input...
+			iter_flat: async function(assert, setup){
+				return {
+					input: setup.input instanceof Array ?
+						(await Promise.all(setup.input)).flat()
+						: [await setup.input],
+					output: setup.output
+						.iter(function(e){ 
+							return e }),
+				} },
+			//*/
 
 			map_asis: function(assert, setup){
 				setup.output = setup.output
@@ -182,6 +206,19 @@ var cases = test.Cases({
 					output: setup.output
 						.filter(function(e){ return false }),
 				} },
+			filter_promise_all: function(assert, setup){
+				setup.output = setup.output
+					.filter(function(e){ 
+						return Promise.resolve(true) }) 
+				return setup },
+			filter_promise_none: function(assert, setup){
+				return {
+					input: [],
+					output: setup.output
+						.filter(function(e){ 
+							return Promise.resolve(false) }),
+				} },
+			//*/
 
 			/* XXX need tuning...
 			concat_basic: function(assert, {input, output}){
@@ -300,6 +337,118 @@ var cases = test.Cases({
 				[1,2,3],
 					'flat unpack', meth)
 		}
+
+		var order = []
+		await Promise.seqiter([
+				1,
+				Promise.resolve(2),
+				Promise.all([3,4]),
+				Promise.seqiter([5]),
+				6,
+			])
+			.flat()
+			.map(function(e){
+				order.push(e)
+				return e })
+		assert.array(
+			order,
+			[1,2,3,4,5,6],
+				'Promise.seqiter(..) handle order')
+
+
+		var test_async_handler = async function(input, output, handler, msg){
+			// sanity check...
+			assert.array(
+				await Promise.iter(input, handler),
+				output,
+				msg+' (sanity check -- fix first)')
+			assert.array(
+				await Promise.iter(input,
+					function(e){ 
+						return Promise.resolve(handler(e)) }),
+				await Promise.iter(input, handler),
+				msg) }
+
+		await test_async_handler(
+			[
+				1, 
+				[2], 
+				Promise.resolve(3), 
+				Promise.resolve([4]),
+			], 
+			[],
+			function(e){ 
+				return [] },
+			'handler returns promise (empty)')
+		await test_async_handler(
+			[
+				1, 
+				[2], 
+				Promise.resolve(3), 
+				Promise.resolve([4]),
+			], 
+			[ 'moo', 'moo', 'moo', 'moo' ],
+			function(e){ 
+				return ['moo'] },
+			'handler returns promise (array)')
+		await test_async_handler(
+			[
+				1, 
+				[2], 
+				Promise.resolve(3), 
+				Promise.resolve([4]),
+			], 
+			[ ['moo'], ['moo'], ['moo'], ['moo'] ],
+			function(e){ 
+				return [['moo']] },
+			'handler returns promise (array-array)')
+
+		// test STOP...
+		assert.array(
+			await Promise.iter([1,2,3,4], function(e){
+				if(e == 3){
+					throw Array.STOP }
+				return e }),
+			[1,2],
+			'.iter(..): STOP: basic')
+		assert.array(
+			await Promise.iter([1,2,Promise.resolve(3),4], function(e){
+				if(e == 3){
+					throw Array.STOP }
+				return e }),
+			// NOTE: 4 here is present as it was handled before the promise resolved...
+			[1,2,4],
+			'.iter(..): STOP: delayed')
+		assert.array(
+			await Promise.iter([1,2,Promise.resolve(3),4], function(e){
+				if(e == 3){
+					throw Array.STOP('stop') }
+				return e }),
+			// NOTE: 4 here is present as it was handled before the promise resolved...
+			[1,2,'stop',4],
+			'.iter(..): STOP(..): delayed')
+		assert.array(
+			await Promise.seqiter([1,2,3,4], function(e){
+				if(e == 3){
+					throw Array.STOP }
+				return e }),
+			[1,2],
+			'.seqiter(..): STOP: basic')
+		assert.array(
+			await Promise.seqiter([1,2,Promise.resolve(3),4], function(e){
+				if(e == 3){
+					throw Array.STOP }
+				return e }),
+			[1,2],
+			'.seqiter(..): STOP: delayed')
+		assert.array(
+			await Promise.seqiter([1,2,Promise.resolve(3),4], function(e){
+				if(e == 3){
+					throw Array.STOP('stop') }
+				return e }),
+			// NOTE: 4 here is present as it was handled before the promise resolved...
+			[1,2,'stop'],
+			'.seqiter(..): STOP(..): delayed')
 	},
 
 	// Date.js
@@ -557,8 +706,8 @@ Events.cases({
 
 
 		// test event list...
-		assert.array(obj.events, ['event', 'eventBlank'], '.events')
-		assert.array(obj.eventful, ['bareEvent', 'bareEventBlank'], '.eventful')
+		assert.array(obj.events, ['eventBlank', 'event'], '.events')
+		assert.array(obj.eventful, ['bareEventBlank', 'bareEvent'], '.eventful')
 
 		// bind...
 		var bind = function(evt){