ig-types 6.14.1 → 6.15.6

package/Array.js

@@ -24,6 +24,9 @@ var STOP =
 module.STOP =
 	object.STOP
 
+var stoppable =
+module.stoppable =
+	generator.stoppable
 
 
 //---------------------------------------------------------------------
@@ -139,7 +142,8 @@ var makeChunkIter = function(iter, wrapper){
 						try {
 							// handle iteration...
 							res.push(
-								val = (chunk = chunks.shift())[iter](_wrapper, ...rest))
+								val = (chunk = chunks.shift())
+									[iter](_wrapper, ...rest))
 							// handle chunk...
 							postChunk
 								&& postChunk.call(that, 
@@ -211,6 +215,7 @@ object.Mixin('ArrayMixin', 'soft', {
 			// done...
 			: [] },
 
+	// XXX add handler function support -- a-la generator.js'
 	iter: function*(lst=[]){
 		yield* lst.iter() },
 })
@@ -319,9 +324,12 @@ object.Mixin('ArrayProtoMixin', 'soft', {
 	// NOTE: order is preserved... 
 	unique: function(normalize){
 		return normalize ? 
-			[...new Map(this.map(function(e){ return [normalize(e), e] })).values()]
-			// NOTE: we are calling .compact() here to avoid creating undefined 
-			// 		items from empty slots in sparse arrays...
+			[...new Map(this
+					.map(function(e){ 
+						return [normalize(e), e] }))
+				.values()]
+			// NOTE: we are calling .compact() here to avoid creating 
+			// 		undefined items from empty slots in sparse arrays...
 			: [...new Set(this.compact())] },
 	tailUnique: function(normalize){
 		return this
@@ -336,8 +344,8 @@ object.Mixin('ArrayProtoMixin', 'soft', {
 	// 		self to other (internal) while match compares two entities 
 	// 		externally.
 	// 		XXX not sure if we need the destinction in name, will have to 
-	// 			come back to this when refactoring diff.js -- all three have
-	// 			to be similar...
+	// 			come back to this when refactoring diff.js -- all three 
+	// 			have to be similar...
 	cmp: function(other){
 		if(this === other){
 			return true }
@@ -353,7 +361,8 @@ object.Mixin('ArrayProtoMixin', 'soft', {
 	// NOTE: this will ignore order and repeating elments...
 	setCmp: function(other){
 		return this === other 
-			|| (new Set([...this, ...other])).length == (new Set(this)).length },
+			|| (new Set([...this, ...other])).length 
+				== (new Set(this)).length },
 
 	// Sort as the other array...
 	//
@@ -369,12 +378,13 @@ object.Mixin('ArrayProtoMixin', 'soft', {
 	// This will sort the intersecting items in the head keeping the rest 
 	// of the items in the same relative order...
 	//
-	// NOTE: if an item is in the array multiple times only the first index 
-	// 		is used...
+	// NOTE: if an item is in the array multiple times only the first 
+	// 		index is used...
 	//
 	// XXX should this extend/patch .sort(..)???
-	// 		...currently do not see a clean way to do this without extending 
-	// 		and replacing Array or directly re-wrapping .sort(..)...
+	// 		...currently do not see a clean way to do this without 
+	// 		extending and replacing Array or directly re-wrapping 
+	// 		.sort(..)...
 	sortAs: function(other, place='head'){
 		place = place == 'tail' ? -1 : 1 
 		// NOTE: the memory overhead here is better than the time overhead 
@@ -441,8 +451,8 @@ object.Mixin('ArrayProtoMixin', 'soft', {
 
 	// Convert an array to a map...
 	//
-	// This is similar to Array.prototype.toKeys(..) but does not restrict 
-	// value type to string.
+	// This is similar to Array.prototype.toKeys(..) but does not 
+	// restrict value type to string.
 	//
 	// Format:
 	// 	Map([
@@ -482,8 +492,22 @@ object.Mixin('ArrayProtoMixin', 'soft', {
 	//		-> iterator
 	//
 	// XXX should this take an argument and be like map??
-	iter: function*(){
-		yield* this },
+	// XXX this should handle throwing STOP!!!
+	// 		...might also ne a good idea to isolate the STOP mechanics 
+	// 		into a spearate module/package...
+	iter: stoppable(function*(handler=undefined){
+		if(handler){
+			var i = 0
+			for(var e of this){
+				var res = handler.call(this, e, i++) 
+				// treat non-iterables as single elements...
+				if(typeof(res) == 'object' 
+						&& Symbol.iterator in res){
+					yield* res
+				} else {
+					yield res } } 
+		} else {
+			yield* this }}),
 
 
 	// Stoppable iteration...

package/Promise.js

@@ -5,8 +5,7 @@
 * 	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).
+* 		Similar to Promise.all(..) but adds basic iterator API.
 *
 * 	Promise.interactive(handler)
 * 		Interactive promise object.
@@ -31,6 +30,8 @@
 
 var object = require('ig-object')
 
+//var generator = require('./generator')
+
 
 
 //---------------------------------------------------------------------
@@ -39,16 +40,6 @@ 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 (XXX) 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: the following can not be implemented here:
 // 			.splice(..)				- can't both modify and return
 // 									  a result...
@@ -68,18 +59,19 @@ var object = require('ig-object')
 // 		back to the complex IterablePromise...
 // 		
 // XXX how do we handle errors/rejections???
+// 		...mostly the current state is OK, but need more testing...
+// XXX add support for async generators...
 // 		
 
-// XXX should these be exported???
 var iterPromiseProxy = 
-//module.iterPromiseProxy = 
+module.iterPromiseProxy = 
 function(name){
 	return function(...args){
 		return this.constructor(
 			this.then(function(lst){
 				return lst[name](...args) })) } }
 var promiseProxy =
-//module.promiseProxy =
+module.promiseProxy =
 function(name){
 	return async function(...args){
 		return (await this)[name](...args) } }
@@ -87,6 +79,10 @@ function(name){
 var IterablePromise =
 module.IterablePromise =
 object.Constructor('IterablePromise', Promise, {
+	get STOP(){
+		return Array.STOP },
+
+}, {
 	// packed array...
 	//
 	// Holds promise state.
@@ -100,14 +96,14 @@ object.Constructor('IterablePromise', Promise, {
 	// 	]
 	//
 	// This format has several useful features:
-	// 	- concatenating packed list results in a packed list
+	// 	- concatenating packed lists 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...
-	// NOTE: we are not isolation any internals to enable users to 
-	// 		responsibly extend the code.
+	// 		it is not recomended to ever edit this in-place...
+	// NOTE: we are not isolating or "protecting" any internals to 
+	// 		enable users to responsibly extend the code.
 	__packed: null,
 
 	// low-level .__packed handlers/helpers...
@@ -115,6 +111,20 @@ 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 add support for async generators...
+	// 		...an async generator is not "parallel", i.e. intil one 
+	// 		returned promise is resolved the generator blocks (will not 
+	// 		advance)...
+	// 		...can we feed out a results one by one???
 	__pack: function(list, handler=undefined){
 		var that = this
 		// handle iterable promise list...
@@ -131,6 +141,57 @@ object.Constructor('IterablePromise', Promise, {
 		handler = handler 
 			?? function(elem){ 
 				return [elem] }
+
+		//* XXX EXPEREMENTAL: STOP...
+		var stoppable = false
+		var stop = false
+		var map = 'map'
+		var pack = function(){
+			return [list].flat()
+				[map](function(elem){
+					return elem && elem.then ?
+							(stoppable ?
+								// 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){
+			stoppable = true
+			map = 'smap'
+			var handleSTOP = function(err){
+				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() },
+		/*/
 		return [list].flat()
 			.map(function(elem){
 				return elem && elem.then ?
@@ -143,6 +204,7 @@ object.Constructor('IterablePromise', Promise, {
 					: !handle ?
 						elem
 					: handler(elem) }) },
+		//*/
 	// transform/handle packed array (sync)...
 	__handle: function(list, handler=undefined){
 		var that = this
@@ -159,13 +221,21 @@ object.Constructor('IterablePromise', Promise, {
 		// 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.
+		//* XXX EXPEREMENTAL: STOP...
+		var map = !!this.constructor.STOP ?
+			'smap'
+			: 'map'
+		return list[map](function(elem){
+		/*/
 		return list.map(function(elem){
+		//*/
 			return elem instanceof Array ?
 					that.__pack(elem, handler)
 				: elem instanceof Promise ?
 					that.__pack(elem, handler)
-						.then(function(elem){
-							return elem.flat() })
+						//.then(function(elem){
+						.then(function([elem]){
+							return elem })
 				: [handler(elem)] })
    			.flat() },
 	// unpack array (async)...
@@ -224,6 +294,8 @@ object.Constructor('IterablePromise', Promise, {
 			.then(function(){ 
 				return res }) },
 
+	// XXX .chain(..) -- see generator.chain(..)
+
 	flat: function(depth=1){
 		return this.constructor(this, 
 			function(e){ 
@@ -280,12 +352,6 @@ object.Constructor('IterablePromise', Promise, {
 		return this.constructor([elem])
 			.concat(this) },
 
-
-	// 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.
@@ -300,6 +366,7 @@ object.Constructor('IterablePromise', Promise, {
 		var list = this.__packed
 		return ((i != 0 && i != -1)
 					|| list instanceof Promise
+					// XXX not sure if this is correct...
 					|| list.at(i) instanceof Promise) ?
 				(await this).at(i)
 			// NOTE: we can only reason about first/last explicit elements, 
@@ -316,29 +383,91 @@ object.Constructor('IterablePromise', Promise, {
 	
 	// NOTE: unlike .reduce(..) this needs the parent fully resolved 
 	// 		to be able to iterate from the end.
-	// XXX ???
+	// XXX is it faster to do .reverse().reduce(..) ???
 	reduceRight: promiseProxy('reduceRight'),
 
 	// NOTE: there is no way we can do a sync generator returning 
-	// 		promises for values because any promise in .__packed makes the 
-	// 		value count/index non-deterministic...
+	// 		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'),
 
+	//
+	// 	.find(<func>)
+	// 	.find(<func>, 'value')
+	// 		-> <promise>(<value>)
+	//
+	// 	.find(<func>, 'result')
+	// 		-> <promise>(<result>)
+	//
+	// 	.find(<func>, 'bool')
+	// 		-> <promise>(<bool>)
+	//
+	// NOTE: this is slightly different to Array's .find(..) in that it 
+	// 		accepts the result value enabling returning both the value 
+	// 		itself ('value', default), the test function's result 
+	// 		('result') or true/false ('bool') -- this is added to be 
+	// 		able to distinguish between the undefined as a stored value 
+	// 		and undefined as a "nothing found" result.
+	// NOTE: I do not get how essentially identical methods .some(..) 
+	// 		and .find(..) got added to JS's Array...
+	// 		the only benefit is that .some(..) handles undefined values 
+	// 		stored in the array better...
+	// NOTE: this will return the result as soon as it's available but 
+	// 		it will not stop the created but unresolved at the time 
+	// 		promises from executing, this is both good and bad:
+	// 		+ it will not break other clients waiting for promises 
+	// 			to resolve...
+	// 		- if no clients are available this can lead to wasted 
+	// 			CPU time...
+	find: async function(func, result='value'){
+		var that = this
+		// NOTE: not using pure await here as this is simpler to actually 
+		// 		control the moment the resulting promise resolves without 
+		// 		the need for juggling state...
+		return new Promise(function(resolve, reject){
+			var resolved = false
+			that.map(function(elem){
+					var res = func(elem)
+					if(res){
+						resolved = true
+						resolve(
+							result == 'bool' ?
+								true
+							: result == 'result' ?
+								res
+							: elem)
+						// XXX EXPEREMENTAL: STOP...
+						// NOTE: we do not need to throw STOP here 
+						// 		but it can prevent some overhead...
+						if(that.constructor.STOP){
+							throw that.constructor.STOP } } })
+				.then(function(){
+					resolved
+						|| resolve(
+							result == 'bool' ?
+								false
+								: undefined) }) }) },
+	findIndex: promiseProxy('findIndex'),
+
+	// NOTE: this is just a special-case of .find(..)
+	some: async function(func){
+		return this.find(func, 'bool') },
 	every: promiseProxy('every'),
-	// XXX this can be lazy... (???)
-	some: promiseProxy('some'),
+
+
+	// this is defined globally as Promise.prototype.iter(..)
+	//
+	// for details see: PromiseMixin(..) below...
+	//iter: function(handler=undefined){ ... },
 
 
 	// promise api...
@@ -368,12 +497,6 @@ 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([ .. ])
@@ -394,6 +517,7 @@ object.Constructor('IterablePromise', Promise, {
 	// 		items...
 	// 		XXX we can make the index a promise, then if the client needs
 	// 			the value they can wait for it...
+	// 			...this may be quite an overhead...
 	//
 	//
 	// Special cases useful for extending this constructor...
@@ -406,6 +530,10 @@ object.Constructor('IterablePromise', Promise, {
 	//	Promise.iter(false)
 	//		-> iterable-promise
 	//
+	//
+	// NOTE: if 'types/Array' is imported this will support throwing STOP,
+	// 		for more info see notes for .__pack(..)
+	// 		XXX EXPEREMENTAL: STOP...
 	__new__: function(_, list, handler){
 		// instance...
 		var promise
@@ -526,6 +654,7 @@ object.Constructor('InteractivePromise', Promise, {
 // Cooperative promise...
 // 
 // A promise that can be resolved/rejected externally.
+//
 // NOTE: normally this has no internal resolver logic...
 // 
 

package/README.md

@@ -78,10 +78,13 @@ Library of JavaScript type extensions, types and utilities.
       - [`<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)
+      - [`<promise-iter>.some(..)` / `<promise-iter>.find(..)`](#promise-itersome--promise-iterfind)
       - [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)
+      - [`promise.IterablePromise.STOP` / `promise.IterablePromise.STOP(..)`](#promiseiterablepromisestop--promiseiterablepromisestop)
       - [Advanced handler](#advanced-handler)
+      - [Stopping the iteration](#stopping-the-iteration)
     - [Promise proxies](#promise-proxies)
       - [`<promise>.as(..)`](#promiseas)
       - [`<promise-proxy>.<method>(..)`](#promise-proxymethod)
@@ -91,7 +94,7 @@ Library of JavaScript type extensions, types and utilities.
       - [`generator.iter(..)`](#generatoriter)
       - [`generator.STOP`](#generatorstop)
     - [Generator instance iteration](#generator-instance-iteration)
-      - [`<generator>.iter()`](#generatoriter-1)
+      - [`<generator>.iter(..)`](#generatoriter-1)
       - [`<generator>.map(..)` / `<generator>.filter(..)`](#generatormap--generatorfilter)
       - [`<generator>.reduce(..)` / `<generator>.greduce(..)`](#generatorreduce--generatorgreduce)
       - [`<generator>.slice(..)`](#generatorslice)
@@ -99,7 +102,6 @@ Library of JavaScript type extensions, types and utilities.
       - [`<generator>.flat(..)`](#generatorflat)
       - [`<generator>.shift()` / `<generator>.pop()` / `<generator>.gshift()` / `<generator>.gpop()`](#generatorshift--generatorpop--generatorgshift--generatorgpop)
       - [`<generator>.unshift(..)` / `<generator>.push(..)`](#generatorunshift--generatorpush)
-      - [`<generator>.promise()`](#generatorpromise)
       - [`<generator>.then(..)` / `<generator>.catch(..)` / `<generator>.finally(..)`](#generatorthen--generatorcatch--generatorfinally)
       - [`<generator>.toArray()`](#generatortoarray)
     - [Treating iterators the same as generators](#treating-iterators-the-same-as-generators)
@@ -121,6 +123,15 @@ Library of JavaScript type extensions, types and utilities.
       - [`generator.produce(..)`](#generatorproduce)
     - [Generator helpers](#generator-helpers)
       - [`generator.stoppable(..)`](#generatorstoppable)
+  - [Async generator extensions](#async-generator-extensions)
+      - [`generator.AsyncGenerator`](#generatorasyncgenerator)
+      - [`<async-generator>.then(..)` / `<async-generator>.catch(..)` / `<async-generator>.finally(..)`](#async-generatorthen--async-generatorcatch--async-generatorfinally)
+      - [`<async-generator>.iter(..)`](#async-generatoriter)
+      - [`<async-generator>.map(..)` / `<async-generator>.filter(..)` / `<async-generator>.reduce(..)`](#async-generatormap--async-generatorfilter--async-generatorreduce)
+      - [`<async-generator>.chain(..)`](#async-generatorchain)
+      - [`<async-generator>.flat(..)`](#async-generatorflat)
+      - [`<async-generator>.concat(..)`](#async-generatorconcat)
+      - [`<async-generator>.push(..)` / `<async-generator>.unshift(..)`](#async-generatorpush--async-generatorunshift)
   - [Containers](#containers)
     - [`containers.UniqueKeyMap()` (`Map`)](#containersuniquekeymap-map)
       - [`<unique-key-map>.set(..)`](#unique-key-mapset)
@@ -1674,6 +1685,46 @@ parent `<promise-iter>`.
 
 XXX
 
+#### `<promise-iter>.some(..)` / `<promise-iter>.find(..)`
+
+```bnf
+<promise-iter>.some(<func>)
+    -> <promise>
+
+<promise-iter>.find(<func>)
+    -> <promise>
+```
+
+The main difference between `.some(..)` and `.find(..)` is in that the `<promise>`
+returned from the former will resolve to either `true` or `false`, and in the later
+to the found value or `undefined`.
+
+`.find(..)` supports an additional argument that controls what returned `<promise>`
+is resolved to...
+
+```bnf
+<promise-iter>.find(<func>)
+<promise-iter>.find(<func>, 'value')
+    -> <promise>
+
+<promise-iter>.find(<func>, 'bool')
+    -> <promise>
+
+<promise-iter>.find(<func>, 'result')
+    -> <promise>
+```
+
+- `value` (default)  
+  resolve to the stored value if found and `undefined` otherwise.
+- `bool`  
+  resolve to `true` if the value is found and `false` otherwise, this is how 
+  `.some(..)` is impelemnted.
+- `result`  
+  resolve to the return value of the test `<func>`.
+
+These are similar to [`<array>.some(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) 
+and [`<array>.find(..)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find) 
+see them for more info.
 
 #### Array proxy methods returning `<promise-iter>`
 
@@ -1697,7 +1748,8 @@ XXX links...
 
 - `<promise-iter>.indexOf(..)` 
 - `<promise-iter>.includes(..)` 
-- `<promise-iter>.every(..)` / `<promise-iter>.some(..)`
+- `<promise-iter>.every(..)`
+- `<promise-iter>.findIndex(..)`
 
 These methods are proxies to the appropriate array methods.
 
@@ -1727,6 +1779,16 @@ this adds the ability to pass no arguments
 This will return a generic promise wrapper passing through the results as-is. This 
 can be useful to hide the extended promise API from further code.
 
+#### `promise.IterablePromise.STOP` / `promise.IterablePromise.STOP(..)`
+
+A special object that when thrown from a function/promise handler will stop 
+further iteration.
+
+This is `undefined` until the `ig-types/Array` module is loaded.
+
+For more info see: [Stopping the iteration](#stopping-the-iteration) below, and
+[the 'Array' STOP section](#arraystop--arraystop)
+
 
 #### Advanced handler
 
@@ -1778,6 +1840,24 @@ var p = Promise.iter(
         console.log(lst) }) // -> [2, 2, 4, 4, [5, 6]]
 ```
 
+#### Stopping the iteration
+
+Like the [`Array`](#arraystop--arraystop) module, this support throwing `STOP` to 
+stop iteration. As we uses [`.smap(..)`](#arraysmap--arraysfilter--arraysreduce--arraysforeach) 
+stopping support is supported if `ig-types/Array` module is loaded.
+
+```javascript
+require('ig-types/Array')
+```
+
+This is also different semantically, as promise iteration can happen out of order,
+stopping affects the order of processing and not order of the input array with one exception: promises already created can not be stopped in `JavaScript`.
+
+Any handler function passed to a `<promise-iter>` method can `throw` a STOP.
+
+For more details see: [the 'Array' STOP section](#arraystop--arraystop)
+
+
 
 ### Promise proxies
 
@@ -1951,7 +2031,7 @@ Chained generators handle items depth-first, i.e. the items are passed as they
 are yielded down the generator chain.
 
 
-#### `<generator>.iter()`
+#### `<generator>.iter(..)`
 
 Iterate over the generator.
 ```bnf
@@ -1959,7 +2039,24 @@ Iterate over the generator.
     -> <generator>
 ```
 
-This is here mainly for compatibility with [`<array>`'s `.iter()`](#arrayiter--arrayiter).
+XXX move this to `generator.iter(..)`
+
+Compatible with [`<array>`'s `.iter()`](#arrayiter--arrayiter).
+
+`.iter(..)` also supports a handler function
+```bnf
+<generator>.iter(<handler>)
+    -> <generator>
+
+
+<handler>(<elem>, <index>)
+    -> <elem>
+    -> [<elem>, ..]
+    -> []
+```
+
+Note that the iterables returned by `<handler>(..)` will be expanded, to prevent 
+this wrap them in an array.
 
 
 #### `<generator>.map(..)` / `<generator>.filter(..)` 
@@ -2084,30 +2181,29 @@ Value added by `.unshift(..)` will be yielded by `<generator>` "first", i.e. on
 _next_ call to `.next()`, regardless of the current generator state.
 
 
-#### `<generator>.promise()`
+#### `<generator>.then(..)` / `<generator>.catch(..)` / `<generator>.finally(..)`
+
+Return a promise and resolve it with the generator value.
 
 ```bnf
-<generator>.promise()
+<generator>.then()
     -> <promise>
 ```
-Return a promise and resolve it with the generator value.
 
-Note that this will deplete the generator.
-
-
-#### `<generator>.then(..)` / `<generator>.catch(..)` / `<generator>.finally(..)`
+Adding handlers to the promise
 
 ```bnf
 <generator>.then(<resolve>, <reject>)
     -> <promise>
 
-<generator>.then(<reject>)
+<generator>.then(<resolve>)
     -> <promise>
 
 <generator>.finally(<handler>)
     -> <promise>
 ```
-Shorthands to `<generator>.promise().then(..)` / `<generator>.promise().catch(..)` / `<generator>.promise().finally(..)`
+
+Note that this will deplete the generator.
 
 These are the same as equivalent `Promise` methods, for more info see:  
 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
@@ -2411,6 +2507,26 @@ stoppable(<generator>)
 
 <!-- XXX example? -->
 
+## Async generator extensions
+
+XXX EXPERIMENTAL
+
+#### `generator.AsyncGenerator`
+
+#### `<async-generator>.then(..)` / `<async-generator>.catch(..)` / `<async-generator>.finally(..)`
+
+#### `<async-generator>.iter(..)`
+
+#### `<async-generator>.map(..)` / `<async-generator>.filter(..)` / `<async-generator>.reduce(..)`
+
+#### `<async-generator>.chain(..)`
+
+#### `<async-generator>.flat(..)`
+
+#### `<async-generator>.concat(..)`
+
+#### `<async-generator>.push(..)` / `<async-generator>.unshift(..)`
+
 
 
 ## Containers

package/generator.js

@@ -66,6 +66,14 @@ module.Generator =
 	(function*(){}).constructor
 
 
+var AsyncGeneratorPrototype =
+	(async function*(){}).constructor.prototype
+
+var AsyncGenerator =
+module.AsyncGenerator =
+	(async function*(){}).constructor
+
+
 // base iterator prototypes...
 var ITERATOR_PROTOTYPES = [
 	Array,
@@ -78,13 +86,86 @@ var ITERATOR_PROTOTYPES = [
 
 //---------------------------------------------------------------------
 
+// XXX should this be part of object???
+var stoppable = 
+module.stoppable =
+function(func){
+	return Object.assign(
+		func instanceof Generator ?
+			// NOTE: the only difference between Generator/AsyncGenerator 
+			// 		versions of this is the async keyword -- keep them 
+			// 		in sync...
+			function*(){
+				try{
+					yield* func.call(this, ...arguments)
+				} catch(err){
+					if(err === STOP){
+						return
+					} else if(err instanceof STOP){
+						yield err.value
+						return }
+					throw err } }
+		: func instanceof AsyncGenerator ?
+			// NOTE: the only difference between Generator/AsyncGenerator 
+			// 		versions of this is the async keyword -- keep them 
+			// 		in sync...
+			async function*(){
+				try{
+					yield* func.call(this, ...arguments)
+				} catch(err){
+					if(err === STOP){
+						return
+					} else if(err instanceof STOP){
+						yield err.value
+						return }
+					throw err } }
+		: function(){
+			try{
+				return func.call(this, ...arguments)
+			} catch(err){
+				if(err === STOP){
+					return
+				} else if(err instanceof STOP){
+					return err.value }
+				throw err } },
+		{ toString: function(){
+			return func.toString() }, }) }
+
+
+//---------------------------------------------------------------------
 // generic generator wrapper...
+
+// helper...
+var __iter = 
+module.__iter =
+function*(lst=[]){
+	if(typeof(lst) == 'object' 
+			&& Symbol.iterator in lst){
+		yield* lst 
+	} else {
+		yield lst } }
+
+// XXX updatae Array.js' version for compatibility...
+// XXX DOCS!!!
 var iter = 
 module.iter = 
 Generator.iter =
-	function*(lst=[]){
-		for(var e of lst){
-			yield e } }
+	stoppable(function(lst=[]){
+		// handler -> generator-constructor...
+		if(typeof(lst) == 'function'){
+			// we need to be callable...
+			var that = this instanceof Function ?
+				this
+				// generic root generator...
+				: module.__iter
+			return function*(){
+				yield* that(...arguments).iter(lst) } }
+		// no handler -> generator instance...
+		return module.__iter(lst) })
+
+// NOTE: we need .iter(..) to both return generators if passed an iterable
+// 		and genereator constructos if passed a function...
+iter.__proto__ = GeneratorPrototype
 
 
 
@@ -113,9 +194,11 @@ Generator.iter =
 
 //
 // 	makeGenerator(<name>)
+// 	makeGenerator(<name>, <handler>)
 // 		-> <func>
 //
-// 	makeGenerator(<name>, <handler>)
+// 	makeGenerator('async', <name>)
+// 	makeGenerator('async', <name>, <handler>)
 // 		-> <func>
 //
 //
@@ -132,14 +215,26 @@ Generator.iter =
 // XXX this needs to be of the correct type... (???)
 // XXX need to accept generators as handlers...
 var makeGenerator = function(name, pre){
+	var sync = true
+	if(name == 'async'){
+		sync = false
+		var [name, pre] = [...arguments].slice(1) }
 	return function(...args){
 		var that = this
 		return Object.assign(
-			function*(){
-				var a = pre ? 
-					pre.call(this, args, ...arguments)
-					: args
-				yield* that(...arguments)[name](...a) }, 
+			// NOTE: the two branches here are identical, the only 
+			// 		difference is the async keyword...
+			sync ?
+				function*(){
+					var a = pre ? 
+						pre.call(this, args, ...arguments)
+						: args
+					yield* that(...arguments)[name](...a) }
+				: async function*(){
+					var a = pre ? 
+						pre.call(this, args, ...arguments)
+						: args
+					yield* that(...arguments)[name](...a) }, 
 			{ toString: function(){
 				return [
 					that.toString(), 
@@ -155,34 +250,6 @@ var makePromise = function(name){
 			return that(...arguments)[name](func) } } }
 
 
-var stoppable = 
-module.stoppable =
-function(func){
-	return Object.assign(
-		func instanceof Generator ?
-			function*(){
-				try{
-					yield* func.call(this, ...arguments)
-				} catch(err){
-					if(err === STOP){
-						return
-					} else if(err instanceof STOP){
-						yield err.value
-						return }
-					throw err } }
-			: function(){
-				try{
-					return func.call(this, ...arguments)
-				} catch(err){
-					if(err === STOP){
-						return
-					} else if(err instanceof STOP){
-						return err.value }
-					throw err } },
-		{ toString: function(){
-			return func.toString() }, }) }
-
-
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
 
 var GeneratorMixin =
@@ -190,9 +257,7 @@ module.GeneratorMixin =
 object.Mixin('GeneratorMixin', 'soft', {
 	STOP: object.STOP,
 
-	// NOTE: this is here for compatibility with Array.iter(..)
-	iter: function*(lst=[]){
-		yield* module.iter(lst) },
+	iter: module.iter,
 
 	gat: makeGenerator('gat'),
 	at: function(i){
@@ -264,15 +329,31 @@ object.Mixin('GeneratorMixin', 'soft', {
 						e(...args)
 						: e }) }),
 	//zip: makeGenerator('zip'),
+	
+	enumerate: makeGenerator('enumerate'),
 })
 
 
 var GeneratorProtoMixin =
 module.GeneratorProtoMixin =
 object.Mixin('GeneratorProtoMixin', 'soft', {
-	// NOTE: this is here for compatibility with [..].iter()
-	iter: function*(){ 
-		yield* this },
+	// XXX use module.iter(..) ???
+	iter: stoppable(function*(handler){ 
+		if(handler){
+			var i = 0
+			for(var elem of this){
+				var res = handler.call(this, elem, i) 
+				// expand iterables...
+				if(typeof(res) == 'object' 
+						&& Symbol.iterator in res){
+					yield* res
+				// as-is...
+				} else {
+					yield res }}
+		// no handler...
+		} else {
+			yield* this } }),
+	//*/
 
 	at: function(i){
 		return this.gat(i).next().value },
@@ -382,17 +463,19 @@ object.Mixin('GeneratorProtoMixin', 'soft', {
 
 	// promises...
 	//
-	// XXX how do we handle reject(..) / .catch(..)???
-	promise: function(){
+	then: function(onresolve, onreject){
 		var that = this
-		return new Promise(function(resolve){
-				resolve([...that]) }) },
-	then: function(func){
-		return this.promise().then(func) },
+		var p = new Promise(
+			function(resolve){
+				resolve([...that]) }) 
+		p = (onresolve || onreject) ?
+			p.then(...arguments)
+			: p
+		return p },
 	catch: function(func){
-		return this.promise().catch(func) },
+		return this.then().catch(func) },
 	finally: function(func){
-		return this.promise().finally(func) },
+		return this.then().finally(func) },
 
 	// combinators...
 	//
@@ -415,6 +498,11 @@ object.Mixin('GeneratorProtoMixin', 'soft', {
 		// XXX
 	},
 	//*/
+
+	enumerate: function*(){
+		var i = 0
+		for(var e of this){
+			yield [i++, e] } },
 })
 
 
@@ -428,6 +516,107 @@ ITERATOR_PROTOTYPES
 		GeneratorProtoMixin(proto) })
 
 
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+// XXX EXPERIMENTAL...
+
+var AsyncGeneratorMixin =
+module.AsyncGeneratorMixin =
+object.Mixin('AsyncGeneratorMixin', 'soft', {
+	// XXX TEST...
+	iter: makeGenerator('async', 'iter'),
+
+	map: makeGenerator('async', 'map'),
+	filter: makeGenerator('async', 'filter'),
+	reduce: makeGenerator('async', 'reduce'),
+})
+
+var AsyncGeneratorProtoMixin =
+module.AsyncGeneratorProtoMixin =
+object.Mixin('AsyncGeneratorProtoMixin', 'soft', {
+	// promise...
+	//
+	// NOTE: this will unwind the generator...
+	// XXX create an iterator promise???
+	// XXX should we unwind???
+	then: function(resolve, reject){
+		var that = this
+		var p = new Promise(async function(_resolve, _reject){
+			var res = []
+			for await(var elem of that){
+				res.push(elem) }
+			_resolve(res) }) 
+		p = (resolve || reject) ?
+			p.then(...arguments)
+			: p
+		return p },
+	catch: function(func){
+		return this.then().catch(func) },
+	finally: function(){
+		return this.then().finally(func) },
+
+	// XXX might be a good idea to use this approach above...
+	iter: stoppable(async function*(handler=undefined){
+		var i = 0
+		if(handler){
+			for await(var e of this){
+				var res = handler.call(this, e, i++)
+				if(typeof(res) == 'object' 
+						&& Symbol.iterator in res){
+					yield* res
+				} else {
+					yield res } }
+		} else {
+			yield* this } }),
+
+	map: async function*(func){
+		yield* this.iter(function(elem, i){
+			return [func.call(this, elem, i)] }) },
+	filter: async function*(func){
+		yield* this.iter(function(elem, i){
+			return func.call(this, elem, i) ?
+	   			[elem]
+				: [] }) },
+	// NOTE: there is not much point in .reduceRight(..) in an async 
+	// 		generator as we'll need to fully unwind it then go from the 
+	// 		end...
+	reduce: async function(func, state){
+		this.iter(function(elem, i){
+			state = func.call(this, state, elem, i) 
+			return [] })
+		return state },
+
+	// XXX TEST...
+	chain: async function*(...next){
+		yield* next
+			.reduce(function(cur, next){
+				return next(cur) }, this) },
+
+	flat: async function*(){
+		for await(var e of this){
+			if(e instanceof Array){
+				yield* e
+			} else {
+				yield e }}},
+
+	concat: async function*(other){
+		yield* this
+		yield* other },
+	push: async function*(elem){
+		yield* this
+		yield elem },
+	unsift: async function*(elem){
+		yield elem 
+		yield* this },
+
+	// XXX
+	// 	slice -- not sure if we need this...
+	// 	...
+})
+
+AsyncGeneratorMixin(AsyncGeneratorPrototype)
+AsyncGeneratorProtoMixin(AsyncGeneratorPrototype.prototype)
+
+
 
 //---------------------------------------------------------------------
 // Generators...

package/package.json

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