ig-types 6.14.1 → 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

@@ -39,7 +39,7 @@ var object = require('ig-object')
 // Like Promise.all(..) but adds ability to iterate through results
 // via generators .map(..)/.reduce(..) and friends...
 // 
-// NOTE: it would be nice to support throwing STOP (XXX) from the iterable 
+// 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...
@@ -48,7 +48,7 @@ var object = require('ig-object')
 // 			...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...
+// 		XXX EXPEREMENTAL: STOP...
 // NOTE: the following can not be implemented here:
 // 			.splice(..)				- can't both modify and return
 // 									  a result...
@@ -87,6 +87,11 @@ function(name){
 var IterablePromise =
 module.IterablePromise =
 object.Constructor('IterablePromise', Promise, {
+	// XXX EXPEREMENTAL: STOP...
+	get STOP(){
+		return Array.STOP },
+
+}, {
 	// packed array...
 	//
 	// Holds promise state.
@@ -100,14 +105,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 +120,15 @@ 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...
 	__pack: function(list, handler=undefined){
 		var that = this
 		// handle iterable promise list...
@@ -131,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 ?
@@ -143,6 +208,7 @@ object.Constructor('IterablePromise', Promise, {
 					: !handle ?
 						elem
 					: handler(elem) }) },
+		//*/
 	// transform/handle packed array (sync)...
 	__handle: function(list, handler=undefined){
 		var that = this
@@ -159,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 ?
@@ -280,12 +353,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.
@@ -316,29 +383,86 @@ object.Constructor('IterablePromise', Promise, {
 	
 	// 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...
+	// 		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'),
 
 
 	// promise api...
@@ -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

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)
@@ -1674,6 +1677,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 +1740,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 +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
 
@@ -1778,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.14.1",
+  "version": "6.15.0",
   "description": "Generic JavaScript types and type extensions...",
   "main": "main.js",
   "scripts": {