ig-types 6.24.10 → 6.24.12

package/README.md

@@ -758,8 +758,26 @@ Resulting array length is strictly equal to the longest input array length.
 
 Return an iterator/generator from the current array.
 
+```bnf
+<array>.iter()
+<array>.iter(<func>)
+<array>.iter(<func>, <onstop>)
+	-> <generator>
+
+<func>(<elem>, <index>)
+	-> <value>
+
+<onstop>(STOP, ...<args>)
+<onstop>(<value>, ...<args>)
+```
+
 This is mostly useful in combination with the [Generator extensions and utilities](#generator-extensions-and-utilities)
 
+Note that all stoppable functions/iterators support `<onstop>` callback as 
+the last argument.
+
+<!-- XXX document <onstop> in all applicable functions -->
+
 
 ### `<array>.between(..)`
 
@@ -820,6 +838,9 @@ a supporting iterator method will abort further execution and correctly exit.
 Like `Array`'s `.map(..)`, `.filter(..)`, `.reduce(..)` and `.forEach(..)` but 
 with added support for aborting iteration by throwing `STOP` or `STOP(<value>)`.
 
+These can be passed a `<onstop>` callback as an additional last argument 
+that will be called if `STOP`/`STOP(<value>)` is returned or thrown.
+
 
 ### Large `Array` iteration (chunked)
 
@@ -2117,6 +2138,9 @@ Note that if the last `<value>` is a function and no `<onerror>` function
 is given then `.awaitOrRun(..)` will confuse the `<value>` for `<func>`,
 to avoid this one needs to explicitly pass `null`/`undefined` as `<onerror>`.
 
+_Special-case: this will expand async generators if they define `.then(..)`, 
+this may change in the future._
+
 
 ## Generator extensions and utilities
 
@@ -2301,6 +2325,10 @@ var L = [1,2,3,4,5]
         .toArray()
 ```
 
+These also support passing the `<onstop>` callback as additional last 
+argument. It will be called when `STOP`/`STOP(<value>)` is thrown or 
+returned.
+
 
 #### `<generator>.reduce(..)` / `<generator>.greduce(..)`
 

package/generator.js

@@ -91,23 +91,36 @@ function*(lst=[]){
 	} else {
 		yield lst } }
 
+// handle stops is onstop(..) is defined...
+var __onstop =
+function(res, _, ...args){
+	var onstop = args.at(-1)
+	typeof(onstop) == 'function'
+		&& onstop.call(this, 
+			...(res === STOP ? 
+				[] 
+				: [res])) }
+	
+
 // XXX updatae Array.js' version for compatibility...
 // XXX DOCS!!!
 var iter = 
 module.iter = 
 Generator.iter =
-	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) })
+	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) },
+		__onstop)
 
 // NOTE: we need .iter(..) to both return generators if passed an iterable
 // 		and genereator constructos if passed a function...
@@ -308,31 +321,33 @@ var GeneratorProtoMixin =
 module.GeneratorProtoMixin =
 object.Mixin('GeneratorProtoMixin', 'soft', {
 	// XXX use module.iter(..) ???
-	iter: stoppable(function*(handler, onerror){ 
-		try{
-			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 } 
-		}catch(err){
-			if(onerror){
-				if(!(err === STOP 
-						|| err instanceof STOP)){
-					var res = onerror(err)
-					if(res){
-						yield res
-						return } } }
-			throw err }}),
+	iter: stoppable(
+		function*(handler, onerror){ 
+			try{
+				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 } 
+			}catch(err){
+				if(onerror){
+					if(!(err === STOP 
+							|| err instanceof STOP)){
+						var res = onerror(err)
+						if(res){
+							yield res
+							return } } }
+				throw err }},
+		__onstop),
 	//*/
 
 	at: function(i){
@@ -396,8 +411,10 @@ object.Mixin('GeneratorProtoMixin', 'soft', {
 					yield* func(e, i++, this) } 
 			} else {
 				for(var e of this){
-					yield func(e, i++, this) } } }),
-	filter: stoppable(function*(func){
+					yield func(e, i++, this) } } },
+		__onstop),
+	filter: stoppable(
+		function*(func){
 			var i = 0
 			try{
 				for(var e of this){
@@ -409,28 +426,36 @@ object.Mixin('GeneratorProtoMixin', 'soft', {
 					if(!err.value){
 						throw STOP }
 					err.value = e }
-				throw err } }),
+				throw err } },
+		__onstop),
 
-	reduce: stoppable(function(func, res){
-		var i = 0
-		for(var e of this){
-			res = func(res, e, i++, this) }
-		return res }),
+	reduce: stoppable(
+		function(func, res){
+			var i = 0
+			for(var e of this){
+				res = func(res, e, i++, this) }
+			return res },
+		// NOTE: we need to wrap __onstop(..) here to prevent res if it 
+		// 		was passed a function from ever being treated as onstop(..)...
+		function(res, f, _, onstop){
+			return __onstop.call(this, res, onstop) }),
 	greduce: function*(func, res){
 		yield this.reduce(...arguments) },
 
-	between: stoppable(function*(func){
-		var i = 0
-		var j = 0
-		var prev
-		for(var e of this){
-			if(i > 0){
-				yield typeof(func) == 'function' ?
-					func.call(this, [prev, e], i-1, i + j++, this)
-					: func }
-			prev = e
-			yield e
-			i++ } }),
+	between: stoppable(
+		function*(func){
+			var i = 0
+			var j = 0
+			var prev
+			for(var e of this){
+				if(i > 0){
+					yield typeof(func) == 'function' ?
+						func.call(this, [prev, e], i-1, i + j++, this)
+						: func }
+				prev = e
+				yield e
+				i++ } },
+		__onstop),
 
 	// NOTE: this is a special case in that it will unwind the generator...
 	// NOTE: this is different from <array>.forEach(..) in that this will
@@ -566,29 +591,31 @@ object.Mixin('AsyncGeneratorProtoMixin', 'soft', {
 		return this.unwind.finally(...arguments) },
 
 	// XXX might be a good idea to use this approach above...
-	iter: stoppable(async function*(handler=undefined, onerror=undefined){
-		try{
-			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 } 
-		}catch(err){
-			if(onerror){
-				if(!(err === STOP || err instanceof STOP)){
-					var res = onerror(err) 
-					if(res !== undefined){
-						yield handler ?
-							handler(res)
-				   			: res } 
-					return } }
-			throw err } }),
+	iter: stoppable(
+		async function*(handler=undefined, onerror=undefined){
+			try{
+				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 } 
+			}catch(err){
+				if(onerror){
+					if(!(err === STOP || err instanceof STOP)){
+						var res = onerror(err) 
+						if(res !== undefined){
+							yield handler ?
+								handler(res)
+								: res } 
+						return } }
+				throw err } },
+		__onstop),
 
 	map: async function*(func){
 		yield* this.iter(function(elem, i){
@@ -686,9 +713,11 @@ function*(value=true, stop){
 
 var produce =
 module.produce =
-stoppable(function*(func){
-	while(true){
-		yield func() } })
+stoppable(
+	function*(func){
+		while(true){
+			yield func() } },
+	__onstop)
 
 
 

package/package.json

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