ig-types 6.13.7 → 6.15.0

package/Array.js

@@ -139,7 +139,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, 
@@ -319,9 +320,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 +340,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 +357,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 +374,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 +447,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([

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,62 @@ 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 EXPEREMENTAL: STOP...
+// 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 = 
+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,
+	// XXX EXPEREMENTAL: STOP...
+	get STOP(){
+		return Array.STOP },
 
+}, {
+	// packed array...
+	//
+	// Holds promise state.
 	//
 	// Format:
 	// 	[
@@ -64,16 +104,36 @@ object.Constructor('IterablePromise', Promise, {
 	//		...
 	// 	]
 	//
-	__list: null,
+	// This format has several useful features:
+	// 	- 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 in-place...
+	// NOTE: we are not isolating or "protecting" 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)...
+	//
+	// 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...
+	__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){
@@ -85,6 +145,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 ?
@@ -97,11 +208,13 @@ 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...
@@ -112,7 +225,14 @@ 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 ?
@@ -121,48 +241,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(..)
 	map: function(func){
 		return this.constructor(this, 
 			function(e){
@@ -184,11 +284,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){
@@ -196,6 +296,7 @@ object.Constructor('IterablePromise', Promise, {
 					return [] })
 			.then(function(){ 
 				return res }) },
+
 	flat: function(depth=1){
 		return this.constructor(this, 
 			function(e){ 
@@ -207,7 +308,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){
@@ -252,15 +353,120 @@ object.Constructor('IterablePromise', Promise, {
 		return this.constructor([elem])
 			.concat(this) },
 
-	// XXX do we need these?
-	// 			.pop()
-	// 			.shift()
-	// 			.first() / .last()
-	// 			.at(..)
-	// 		...would be nice if these could stop everything that's not
-	// 		needed to execute...
+	// 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.__packed
+		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: unlike .reduce(..) this needs the parent fully resolved 
+	// 		to be able to iterate from the end.
+	// XXX is it faster to do .reverse().reduce(..) ???
+	// XXX ???
+	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...
+	sort: iterPromiseProxy('sort'),
+	slice: iterPromiseProxy('slice'),
+
+	entries: iterPromiseProxy('entries'),
+	keys: iterPromiseProxy('keys'),
+	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'),
+
+
+	// promise api...
+	//
 	// Overload .then(..), .catch(..) and .finally(..) to return a plain 
 	// Promise instnace...
 	//
@@ -286,6 +492,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
@@ -295,8 +508,9 @@ object.Constructor('IterablePromise', Promise, {
 	//
 	//
 	// 	handler(e)
-	// 		-> [value]
+	// 		-> [value, ..]
 	// 		-> []
+	// 		-> <promise>
 	//
 	//
 	// NOTE: element index is unknowable until the full list is expanded
@@ -308,7 +522,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
 	//
@@ -317,18 +531,9 @@ object.Constructor('IterablePromise', Promise, {
 	//		-> iterable-promise
 	//
 	//
-	// XXX iterator/generator as input:
-	// 		- 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???
+	// 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
@@ -344,14 +549,14 @@ object.Constructor('IterablePromise', Promise, {
 				promise = {resolve, reject} }], 
 			IterablePromise)
 
-		// new instance...
+		// populate new instance...
 		if(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,
 			})
@@ -414,13 +619,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 ?? [])
@@ -507,10 +713,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){
@@ -521,6 +730,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]){
@@ -535,11 +747,15 @@ 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] = 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 },
 })
@@ -563,7 +779,7 @@ var PromiseProtoMixin =
 module.PromiseProtoMixin =
 object.Mixin('PromiseProtoMixin', 'soft', {
 	as: ProxyPromise,
-	iter: function(handler){
+	iter: function(handler=undefined){
 		return IterablePromise(this, handler) },
 })
 
@@ -573,4 +789,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,8 +77,14 @@ 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)
+      - [`<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)
@@ -1508,6 +1514,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
@@ -1652,6 +1669,95 @@ 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
+
+#### `<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>`
+
+- `<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>.findIndex(..)`
+
+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
@@ -1665,6 +1771,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
 
@@ -1716,6 +1832,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
 

package/package.json

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