From 4114dd633130252c7a333c04799ef6210dd2faa2 Mon Sep 17 00:00:00 2001
From: Raunak Kumar Gupta <95216822+raunak-dev-edu@users.noreply.github.com>
Date: Mon, 11 Mar 2024 18:36:06 +0530
Subject: [PATCH] feat: add `iter/do-until-each`

PR-URL: #1408
Closes: #807

Reviewed-by: Philipp Burckhardt <pburckhardt@outlook.com>
---
 .../@stdlib/iter/do-until-each/README.md      | 236 +++++++++++
 .../iter/do-until-each/benchmark/benchmark.js |  97 +++++
 .../@stdlib/iter/do-until-each/docs/repl.txt  |  57 +++
 .../iter/do-until-each/docs/types/index.d.ts  | 144 +++++++
 .../iter/do-until-each/docs/types/test.ts     | 120 ++++++
 .../iter/do-until-each/examples/index.js      |  52 +++
 .../@stdlib/iter/do-until-each/lib/index.js   |  62 +++
 .../@stdlib/iter/do-until-each/lib/main.js    | 165 ++++++++
 .../@stdlib/iter/do-until-each/package.json   |  68 ++++
 .../@stdlib/iter/do-until-each/test/test.js   | 368 ++++++++++++++++++
 10 files changed, 1369 insertions(+)
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/README.md
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/benchmark/benchmark.js
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/docs/repl.txt
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/docs/types/index.d.ts
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/docs/types/test.ts
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/examples/index.js
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/lib/index.js
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/lib/main.js
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/package.json
 create mode 100644 lib/node_modules/@stdlib/iter/do-until-each/test/test.js

diff --git a/lib/node_modules/@stdlib/iter/do-until-each/README.md b/lib/node_modules/@stdlib/iter/do-until-each/README.md
new file mode 100644
index 00000000000..fad705536b9
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/README.md
@@ -0,0 +1,236 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# iterDoUntilEach
+
+> Create an iterator which, while a test condition is false, invokes a function for each iterated value before returning the iterated value.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var iterDoUntilEach = require( '@stdlib/iter/do-until-each' );
+```
+
+#### iterDoUntilEach( iterator, predicate, fcn\[, thisArg] )
+
+Returns an iterator which invokes a function for each iterated value **before** returning the iterated value until either a `predicate` function returns `true` or the iterator has iterated over all values. Note that the condition is evaluated **after** executing `fcn`; thus, `fcn` **always** executes at least once.
+
+```javascript
+var array2iterator = require( '@stdlib/array/to-iterator' );
+
+function predicate( v ) {
+    return v > 2;
+}
+
+function assert( v ) {
+    if ( v !== v ) {
+        throw new Error( 'should not be NaN' );
+    }
+}
+
+var it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+// returns {}
+
+var r = it.next().value;
+// returns 1
+
+r = it.next().value;
+// returns 2
+
+r = it.next().value;
+// undefined
+
+// ...
+```
+
+The returned iterator protocol-compliant object has the following properties:
+
+-   **next**: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a `value` property and a `done` property having a boolean value indicating whether the iterator is finished.
+-   **return**: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.
+
+Both the `predicate` function and the function to invoke for each iterated value are provided two arguments:
+
+-   **value**: iterated value
+-   **index**: iteration index (zero-based)
+
+```javascript
+var array2iterator = require( '@stdlib/array/to-iterator' );
+
+function predicate( v ) {
+    return v > 2;
+}
+
+function assert( v, i ) {
+    if ( i > 2 ) {
+        throw new Error( 'unexpected error' );
+    }
+}
+
+var it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+// returns <Object>
+
+var r = it.next().value;
+// returns 1
+
+r = it.next().value;
+// returns 2
+
+r = it.next().value;
+// undefined
+
+// ...
+```
+
+To set the execution context for `fcn`, provide a `thisArg`.
+
+<!-- eslint-disable no-invalid-this -->
+
+```javascript
+var array2iterator = require( '@stdlib/array/to-iterator' );
+
+function assert( v ) {
+    this.count += 1;
+    if ( v !== v ) {
+        throw new Error( 'should not be NaN' );
+    }
+}
+
+function predicate( v ) {
+    return v > 2;
+}
+
+var c = {
+    'count': 0
+};
+
+var it = iterDoUntilEach( array2iterator( [ 1, 2, 3 ] ), predicate, assert, c );
+// returns <Object>
+
+var r = it.next().value;
+// returns 1
+
+r = it.next().value;
+// returns 2
+
+r = it.next().value;
+// returns undefined
+
+var count = c.count;
+// returns 3
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+-   If an environment supports `Symbol.iterator` **and** a provided iterator is iterable, the returned iterator is iterable.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var randu = require( '@stdlib/random/iter/randu' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var iterDoUntilEach = require( '@stdlib/iter/do-until-each' );
+
+function assert( v ) {
+    if ( isnan( v ) ) {
+        throw new Error( 'should not be NaN' );
+    }
+}
+
+function predicate( v ) {
+    return v <= 0.75;
+}
+
+// Create a seeded iterator for generating pseudorandom numbers:
+var rand = randu({
+    'seed': 1234,
+    'iter': 10
+});
+
+// Create an iterator which validates generated numbers:
+var it = iterDoUntilEach( rand, predicate, assert );
+
+// Perform manual iteration...
+var r;
+while ( true ) {
+    r = it.next();
+    if ( r.done ) {
+        break;
+    }
+    console.log( r.value );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/benchmark/benchmark.js b/lib/node_modules/@stdlib/iter/do-until-each/benchmark/benchmark.js
new file mode 100644
index 00000000000..4cd9c9827fa
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/benchmark/benchmark.js
@@ -0,0 +1,97 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var randu = require( '@stdlib/random/iter/randu' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var isIteratorLike = require( '@stdlib/assert/is-iterator-like' );
+var pkg = require( './../package.json' ).name;
+var iterator = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var rand;
+	var iter;
+	var i;
+
+	rand = randu();
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		iter = iterator( rand, predicate, fcn );
+		if ( typeof iter !== 'object' ) {
+			b.fail( 'should return an object' );
+		}
+	}
+	b.toc();
+	if ( !isIteratorLike( iter ) ) {
+		b.fail( 'should return an iterator protocol-compliant object' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+
+	function fcn( v ) {
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+
+	function predicate( v ) {
+		return ( v < 0.5 );
+	}
+});
+
+bench( pkg+'::iteration', function benchmark( b ) {
+	var rand;
+	var iter;
+	var z;
+	var i;
+
+	rand = randu();
+	iter = iterator( rand, predicate, fcn );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		z = iter.next().value;
+		if ( isnan( z ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( z ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+
+	function fcn( v ) {
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+
+	function predicate( v ) {
+		return ( v < 0.5 );
+	}
+});
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/docs/repl.txt b/lib/node_modules/@stdlib/iter/do-until-each/docs/repl.txt
new file mode 100644
index 00000000000..74dcde16eeb
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/docs/repl.txt
@@ -0,0 +1,57 @@
+
+{{alias}}( iterator, predicate, fcn[, thisArg] )
+    Returns an iterator which invokes a function for each iterated value before 
+    returning the iterated value until either a predicate function returns true
+    or the iterator has iterated over all values.
+
+    The condition is evaluated *after* executing the provided function; thus,
+    `fcn` *always* executes at least once.
+
+    When invoked, both input functions are provided two arguments:
+
+    - value: iterated value
+    - index: iteration index (zero-based)
+
+    If an environment supports Symbol.iterator, the returned iterator is
+    iterable.
+
+    Parameters
+    ----------
+    iterator: Object
+        Input iterator.
+
+    predicate: Function
+        Function which indicates whether to continue iterating.
+
+    fcn: Function
+        Function to invoke for each iterated value.
+
+    thisArg: any (optional)
+        Execution context.
+
+    Returns
+    -------
+    iterator: Object
+        Iterator.
+
+    iterator.next(): Function
+        Returns an iterator protocol-compliant object containing the next
+        iterated value (if one exists) and a boolean flag indicating whether the
+        iterator is finished.
+
+    iterator.return( [value] ): Function
+        Finishes an iterator and returns a provided value.
+
+    Examples
+    --------
+    > function predicate( v ) { return v !== v };
+    > function f( v ) { if ( v !== v ) { throw new Error( 'beep' ); } };
+    > var it = {{alias}}( {{alias:@stdlib/random/iter/randu}}(), predicate, f );
+    > var r = it.next().value
+    <number>
+    > r = it.next().value
+    <number>
+
+    See Also
+    --------
+
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/docs/types/index.d.ts b/lib/node_modules/@stdlib/iter/do-until-each/docs/types/index.d.ts
new file mode 100644
index 00000000000..778c0121373
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/docs/types/index.d.ts
@@ -0,0 +1,144 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+/// <reference types="@stdlib/types"/>
+
+import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter';
+
+// Define a union type representing both iterable and non-iterable iterators:
+type Iterator = Iter | IterableIterator;
+
+/**
+* Callback function invoked for each iterated value.
+*
+* @returns callback result
+*/
+type nullaryCallback = () => unknown;
+
+/**
+* Callback function invoked for each iterated value.
+*
+* @param value - iterated value
+* @returns callback result
+*/
+type unaryCallback = ( value: unknown ) => unknown;
+
+/**
+* Callback function invoked for each iterated value.
+*
+* @param value - iterated value
+* @param i - iteration index
+* @returns callback result
+*/
+type binaryCallback = ( value: unknown, i: number ) => unknown;
+
+/**
+* Callback function invoked for each iterated value.
+*
+* @param value - iterated value
+* @param i - iteration index
+* @returns callback result
+*/
+type Callback = nullaryCallback | unaryCallback | binaryCallback;
+
+/**
+* Predicate function invoked for each iterated value.
+*
+* @returns a boolean indicating whether to continue iterating or not
+*/
+type nullaryPredicate = () => boolean;
+
+/**
+* Predicate function invoked for each iterated value.
+*
+* @param value - iterated value
+* @returns a boolean indicating whether to continue iterating or not
+*/
+type unaryPredicate = ( value: unknown ) => boolean;
+
+/**
+* Predicate function invoked for each iterated value.
+*
+* @param value - iterated value
+* @param i - iteration index
+* @returns a boolean indicating whether to continue iterating or not
+*/
+type binaryPredicate = ( value: unknown, i: number ) => boolean;
+
+/**
+* Predicate function invoked for each iterated value.
+*
+* @param value - iterated value
+* @param i - iteration index
+* @returns a boolean indicating whether to continue iterating or not
+*/
+type Predicate = nullaryPredicate | unaryPredicate | binaryPredicate;
+
+/**
+* Returns an iterator which invokes a function for each iterated value **before** returning the iterated value until either a predicate function returns `true` or the iterator has iterated over all values.
+*
+* ## Notes
+*
+* -   When invoked, both the `predicate` and callback functions are provided two arguments:
+*
+*     -   **value**: iterated value
+*     -   **index**: iteration index (zero-based)
+*
+* -   If an environment supports `Symbol.iterator` **and** a provided iterator is iterable, the returned iterator is iterable.
+*
+* @param iterator - input iterator
+* @param predicate - function which indicates whether to continue iterating
+* @param fcn - callback function to invoke for each iterated value
+* @param thisArg - execution context
+* @returns iterator
+*
+* @example
+* var array2iterator = require( '@stdlib/array/to-iterator' );
+*
+* function predicate( v ) {
+*     return v > 2;
+* }
+*
+* function assert( v, i ) {
+*     if ( i > 1 ) {
+*         throw new Error( 'unexpected error' );
+*     }
+* }
+*
+* var it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+* // returns {}
+*
+* var r = it.next().value;
+* // returns 1
+*
+* r = it.next().value;
+* // returns 2
+*
+* r = it.next().value;
+* // undefined
+*
+* // ...
+*/
+declare function iterDoUntilEach( iterator: Iterator, predicate: Predicate, fcn: Callback, thisArg?: unknown ): Iterator;
+
+
+// EXPORTS //
+
+export = iterDoUntilEach;
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/docs/types/test.ts b/lib/node_modules/@stdlib/iter/do-until-each/docs/types/test.ts
new file mode 100644
index 00000000000..973607f5831
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/docs/types/test.ts
@@ -0,0 +1,120 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+import iterDoUntilEach = require( './index' );
+
+/**
+* Returns an iterator protocol-compliant object.
+*
+* @returns iterator protocol-compliant object
+*/
+function iterator(): unknown {
+	/**
+	* Implements the iterator protocol `next` method.
+	*
+	* @returns iterator protocol-compliant object
+	*/
+	function next(): unknown {
+		return {
+			'value': true,
+			'done': false
+		};
+	}
+
+	return {
+		'next': next
+	};
+}
+
+/**
+* Conditional predicate function.
+*
+* @param v - iterated value
+* @param i - iteration index
+* @returns a boolean indicating whether to continue iterating or not
+*/
+function predicate( v: unknown, i: number ): boolean {
+	return v === v && i === i;
+}
+
+/**
+* Callback function.
+*
+* @param v - iterated value
+* @param i - iteration index
+* @returns callback result
+*/
+function fcn( v: unknown, i: number ): void {
+	if ( v !== v || i !== i ) {
+		throw new Error( 'something went wrong' );
+	}
+}
+
+
+// TESTS //
+
+// The function returns an iterator...
+{
+	iterDoUntilEach( iterator(), predicate, fcn ); // $ExpectType Iterator
+	iterDoUntilEach( iterator(), predicate, fcn, {} ); // $ExpectType Iterator
+	iterDoUntilEach( iterator(), predicate, fcn, null ); // $ExpectType Iterator
+}
+
+// The compiler throws an error if the function is provided a first argument which is not an iterator protocol-compliant object...
+{
+	iterDoUntilEach( '5', predicate, fcn ); // $ExpectError
+	iterDoUntilEach( 5, predicate, fcn ); // $ExpectError
+	iterDoUntilEach( true, predicate, fcn ); // $ExpectError
+	iterDoUntilEach( false, predicate, fcn ); // $ExpectError
+	iterDoUntilEach( null, predicate, fcn ); // $ExpectError
+	iterDoUntilEach( undefined, predicate, fcn ); // $ExpectError
+	iterDoUntilEach( [], predicate, fcn ); // $ExpectError
+	iterDoUntilEach( {}, predicate, fcn ); // $ExpectError
+	iterDoUntilEach( ( x: number ): number => x, predicate, fcn ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument which is not a valid predicate function...
+{
+	iterDoUntilEach( iterator(), '5', fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), 5, fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), true, fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), false, fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), null, fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), undefined, fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), [], fcn ); // $ExpectError
+	iterDoUntilEach( iterator(), {}, fcn ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not a valid callback function...
+{
+	iterDoUntilEach( iterator(), predicate, '5' ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, 5 ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, true ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, false ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, null ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, undefined ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, [] ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided insufficient arguments...
+{
+	iterDoUntilEach(); // $ExpectError
+	iterDoUntilEach( iterator() ); // $ExpectError
+	iterDoUntilEach( iterator(), predicate ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/examples/index.js b/lib/node_modules/@stdlib/iter/do-until-each/examples/index.js
new file mode 100644
index 00000000000..5c9ab0b2a6e
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/examples/index.js
@@ -0,0 +1,52 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var randu = require( '@stdlib/random/iter/randu' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var iterDoUntilEach = require( './../lib' );
+
+function assert( v ) {
+	if ( isnan( v ) ) {
+		throw new Error( 'should not be NaN' );
+	}
+}
+
+function predicate( v ) {
+	return ( v <= 0.75 );
+}
+
+// Create a seeded iterator for generating pseudorandom numbers:
+var rand = randu({
+	'seed': 1234,
+	'iter': 10
+});
+
+// Create an iterator which validates generated numbers:
+var it = iterDoUntilEach( rand, predicate, assert );
+
+// Perform manual iteration...
+var r;
+while ( true ) {
+	r = it.next();
+	if ( r.done ) {
+		break;
+	}
+	console.log( r.value );
+}
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/lib/index.js b/lib/node_modules/@stdlib/iter/do-until-each/lib/index.js
new file mode 100644
index 00000000000..72e297ef4c7
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/lib/index.js
@@ -0,0 +1,62 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Create an iterator which, while a test condition is false, invokes a function for each iterated value before returning the iterated value.
+*
+* @module @stdlib/iter/do-until-each
+*
+* @example
+* var array2iterator = require( '@stdlib/array/to-iterator' );
+* var iterDoUntilEach = require( '@stdlib/iter/do-until-each' );
+*
+* function predicate( v ) {
+*     return v > 2;
+* }
+*
+* function assert( v ) {
+*     if ( v !== v ) {
+*         throw new Error( 'should not be NaN' );
+*     }
+* }
+*
+* var it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+* // returns {}
+*
+* var r = it.next().value;
+* // returns 1
+*
+* r = it.next().value;
+* // returns 2
+*
+* r = it.next().value;
+* // undefined
+*
+* // ...
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/lib/main.js b/lib/node_modules/@stdlib/iter/do-until-each/lib/main.js
new file mode 100644
index 00000000000..ba7b86cedfb
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/lib/main.js
@@ -0,0 +1,165 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
+var isFunction = require( '@stdlib/assert/is-function' );
+var isIteratorLike = require( '@stdlib/assert/is-iterator-like' );
+var iteratorSymbol = require( '@stdlib/symbol/iterator' );
+var format = require( '@stdlib/string/format' );
+
+
+// MAIN //
+
+/**
+* Returns an iterator which invokes a function for each iterated value before returning the iterated value until either a predicate function returns `true` or the iterator has iterated over all values.
+*
+* @param {Iterator} iterator - input iterator
+* @param {Function} predicate - function which indicates whether to continue iterating
+* @param {Function} fcn - function to invoke
+* @param {*} [thisArg] - execution context
+* @throws {TypeError} first argument must be an iterator protocol-compliant object
+* @throws {TypeError} second argument must be a function
+* @throws {TypeError} third argument must be a function
+* @returns {Iterator} iterator
+*
+* @example
+* var array2iterator = require( '@stdlib/array/to-iterator' );
+* var iterDoUntilEach = require( '@stdlib/iter/do-until-each' );
+*
+* function predicate( v ) {
+*     return v > 2;
+* }
+*
+* function assert( v ) {
+*     if ( v !== v ) {
+*         throw new Error( 'should not be NaN' );
+*     }
+* }
+*
+* var it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+* // returns {}
+*
+* var r = it.next().value;
+* // returns 1
+*
+* r = it.next().value;
+* // returns 2
+*
+* r = it.next().value;
+* // undefined
+*
+* // ...
+*/
+function iterDoUntilEach( iterator, predicate, fcn, thisArg ) {
+	var iter;
+	var FLG;
+	var i;
+	if ( !isIteratorLike( iterator ) ) {
+		throw new TypeError( format( 'invalid argument. First argument must be an iterator protocol-compliant object. Value: `%s`.', iterator ) );
+	}
+	if ( !isFunction( predicate ) ) {
+		throw new TypeError( format( 'invalid argument. Second argument must be a function. Value: `%s`.', predicate ) );
+	}
+	if ( !isFunction( fcn ) ) {
+		throw new TypeError( format( 'invalid argument. Third argument must be a function. Value: `%s`.', fcn ) );
+	}
+	i = -1;
+
+	// Create an iterator protocol-compliant object:
+	iter = {};
+	setReadOnly( iter, 'next', next );
+	setReadOnly( iter, 'return', end );
+
+	// If an environment supports `Symbol.iterator`, make the iterator iterable:
+	if ( iteratorSymbol && isFunction( iterator[ iteratorSymbol ] ) ) {
+		setReadOnly( iter, iteratorSymbol, factory );
+	}
+	return iter;
+
+	/**
+	* Returns an iterator protocol-compliant object containing the next iterated value.
+	*
+	* @private
+	* @returns {Object} iterator protocol-compliant object
+	*/
+	function next() {
+		var v;
+		i += 1;
+		if ( FLG ) {
+			return {
+				'done': true
+			};
+		}
+		v = iterator.next();
+		if ( v.done ) {
+			FLG = true;
+			return v;
+		}
+		v = v.value;
+		fcn.call( thisArg, v, i );
+		if ( predicate( v, i ) === true ) {
+			FLG = true;
+			return {
+				'done': true
+			};
+		}
+		return {
+			'value': v,
+			'done': false
+		};
+	}
+
+	/**
+	* Finishes an iterator.
+	*
+	* @private
+	* @param {*} [value] - value to return
+	* @returns {Object} iterator protocol-compliant object
+	*/
+	function end( value ) {
+		FLG = true;
+		if ( arguments.length ) {
+			return {
+				'value': value,
+				'done': true
+			};
+		}
+		return {
+			'done': true
+		};
+	}
+
+	/**
+	* Returns a new iterator.
+	*
+	* @private
+	* @returns {Iterator} iterator
+	*/
+	function factory() {
+		return iterDoUntilEach( iterator[ iteratorSymbol ](), predicate, fcn, thisArg ); // eslint-disable-line max-len
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = iterDoUntilEach;
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/package.json b/lib/node_modules/@stdlib/iter/do-until-each/package.json
new file mode 100644
index 00000000000..930b47f0f32
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/package.json
@@ -0,0 +1,68 @@
+{
+    "name": "@stdlib/iter/until-each",
+    "version": "0.0.0",
+    "description": "Create an iterator which, while a test condition is false, invokes a function for each iterated value before returning the iterated value.",
+    "license": "Apache-2.0",
+    "author": {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    },
+    "contributors": [
+      {
+        "name": "The Stdlib Authors",
+        "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+      }
+    ],
+    "main": "./lib",
+    "directories": {
+      "benchmark": "./benchmark",
+      "doc": "./docs",
+      "example": "./examples",
+      "lib": "./lib",
+      "test": "./test"
+    },
+    "types": "./docs/types",
+    "scripts": {},
+    "homepage": "https://github.com/stdlib-js/stdlib",
+    "repository": {
+      "type": "git",
+      "url": "git://github.com/stdlib-js/stdlib.git"
+    },
+    "bugs": {
+      "url": "https://github.com/stdlib-js/stdlib/issues"
+    },
+    "dependencies": {},
+    "devDependencies": {},
+    "engines": {
+      "node": ">=0.10.0",
+      "npm": ">2.7.0"
+    },
+    "os": [
+      "aix",
+      "darwin",
+      "freebsd",
+      "linux",
+      "macos",
+      "openbsd",
+      "sunos",
+      "win32",
+      "windows"
+    ],
+    "keywords": [
+      "stdlib",
+      "stdutils",
+      "stdutil",
+      "utilities",
+      "utility",
+      "utils",
+      "util",
+      "do-until-each",
+      "dountileach",
+      "until",
+      "each",
+      "iterator",
+      "iterable",
+      "iterate"
+    ]
+  }
+  
\ No newline at end of file
diff --git a/lib/node_modules/@stdlib/iter/do-until-each/test/test.js b/lib/node_modules/@stdlib/iter/do-until-each/test/test.js
new file mode 100644
index 00000000000..e9d25466688
--- /dev/null
+++ b/lib/node_modules/@stdlib/iter/do-until-each/test/test.js
@@ -0,0 +1,368 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var tape = require( 'tape' );
+var proxyquire = require( 'proxyquire' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var randu = require( '@stdlib/random/iter/randu' );
+var iteratorSymbol = require( '@stdlib/symbol/iterator' );
+var array2iterator = require( '@stdlib/array/to-iterator' );
+var noop = require( '@stdlib/utils/noop' );
+var iterDoUntilEach = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+	t.ok( true, __filename );
+	t.strictEqual( typeof iterDoUntilEach, 'function', 'main export is a function' );
+	t.end();
+});
+
+tape( 'the function throws an error if provided an iterator argument which is not an iterator protocol-compliant object', function test( t ) {
+	var values;
+	var i;
+
+	values = [
+		'5',
+		5,
+		NaN,
+		true,
+		false,
+		null,
+		void 0,
+		{},
+		[],
+		function noop() {}
+	];
+
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] );
+	}
+	t.end();
+
+	function badValue( value ) {
+		return function badValue() {
+			iterDoUntilEach( value, noop, noop );
+		};
+	}
+});
+
+tape( 'the function throws an error if provided a second argument which is not a function', function test( t ) {
+	var values;
+	var i;
+
+	values = [
+		'5',
+		5,
+		NaN,
+		true,
+		false,
+		null,
+		void 0,
+		[],
+		{}
+	];
+
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] );
+	}
+	t.end();
+
+	function badValue( value ) {
+		return function badValue() {
+			iterDoUntilEach( randu(), value, noop );
+		};
+	}
+});
+
+tape( 'the function throws an error if provided a third argument which is not a function', function test( t ) {
+	var values;
+	var i;
+
+	values = [
+		'5',
+		5,
+		NaN,
+		true,
+		false,
+		null,
+		void 0,
+		[],
+		{}
+	];
+
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] );
+	}
+	t.end();
+
+	function badValue( value ) {
+		return function badValue() {
+			iterDoUntilEach( randu(), noop, value );
+		};
+	}
+});
+
+tape( 'the function returns an iterator protocol-compliant object', function test( t ) {
+	var count;
+	var it;
+	var r;
+	var i;
+
+	it = iterDoUntilEach( randu(), predicate, assert );
+	t.equal( it.next.length, 0, 'has zero arity' );
+
+	count = -1;
+	i = 0;
+	do {
+		r = it.next();
+		if ( typeof r.value !== 'undefined' ) {
+			t.equal( typeof r.value, 'number', 'returns a number' );
+		}
+		t.equal( typeof r.done, 'boolean', 'returns a boolean' );
+		if ( r.done ) {
+			count += 1;
+		}
+		i += 1;
+	} while ( r.done === false );
+	t.equal( count, i, 'returns expected value' );
+	t.end();
+
+	function assert( v, i ) {
+		count += 1;
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( v <= 0.5 && i >= 0 );
+	}
+});
+
+tape( 'the function returns an iterator protocol-compliant object which invokes a function for each iterated value before returning the iterated value until either a `predicate` function returns `true` or the iterator has iterated over all values.', function test( t ) {
+	var expected;
+	var opts;
+	var rand;
+	var it;
+	var r;
+	var i;
+
+	opts = {
+		'iter': 10
+	};
+	rand = randu( opts );
+	it = iterDoUntilEach( rand, predicate, assert );
+	t.equal( it.next.length, 0, 'has zero arity' );
+
+	expected = [];
+	i = 0;
+	do {
+		r = it.next();
+		if ( typeof r.value !== 'undefined' ) {
+			t.equal( i, expected[ i ][ 1 ], 'provides expected value' );
+			t.equal( r.value, expected[ i ][ 0 ], 'returns expected value' );
+		}
+		t.equal( typeof r.done, 'boolean', 'returns a boolean' );
+		i += 1;
+	} while ( r.done === false );
+	t.equal( expected.length, i, 'has expected length' );
+
+	r = it.next();
+	t.equal( r.value, void 0, 'returns expected value' );
+	t.equal( r.done, true, 'returns expected value' );
+
+	t.end();
+
+	function assert( v, i ) {
+		expected.push( [ v, i ] );
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( v <= 0.75 && i >= 0 );
+	}
+});
+
+tape( 'the returned iterator has a `return` method for closing an iterator (no argument)', function test( t ) {
+	var it;
+	var r;
+
+	it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+
+	r = it.next();
+	t.equal( typeof r.value, 'number', 'returns a number' );
+	t.equal( r.done, false, 'returns expected value' );
+
+	r = it.next();
+	t.equal( typeof r.value, 'number', 'returns a number' );
+	t.equal( r.done, false, 'returns expected value' );
+
+	r = it.return();
+	t.equal( r.value, void 0, 'returns expected value' );
+	t.equal( r.done, true, 'returns expected value' );
+
+	r = it.next();
+	t.equal( r.value, void 0, 'returns expected value' );
+	t.equal( r.done, true, 'returns expected value' );
+
+	t.end();
+
+	function assert( v, i ) {
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( v > 4 && i >= 0 );
+	}
+});
+
+tape( 'the returned iterator has a `return` method for closing an iterator (argument)', function test( t ) {
+	var it;
+	var r;
+
+	it = iterDoUntilEach( array2iterator( [ 1, 2, 3, 4 ] ), predicate, assert );
+
+	r = it.next();
+	t.equal( typeof r.value, 'number', 'returns a number' );
+	t.equal( r.done, false, 'returns expected value' );
+
+	r = it.next();
+	t.equal( typeof r.value, 'number', 'returns a number' );
+	t.equal( r.done, false, 'returns expected value' );
+
+	r = it.return( 'finished' );
+	t.equal( r.value, 'finished', 'returns expected value' );
+	t.equal( r.done, true, 'returns expected value' );
+
+	r = it.next();
+	t.equal( r.value, void 0, 'returns expected value' );
+	t.equal( r.done, true, 'returns expected value' );
+
+	t.end();
+
+	function assert( v, i ) {
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( v > 4 && i >= 0 );
+	}
+});
+
+tape( 'if an environment supports `Symbol.iterator` and the provided iterator is iterable, the returned iterator is iterable', function test( t ) {
+	var iterDoUntilEach;
+	var opts;
+	var rand;
+	var it1;
+	var it2;
+	var i;
+
+	iterDoUntilEach = proxyquire( './../lib/main.js', {
+		'@stdlib/symbol/iterator': '__ITERATOR_SYMBOL__'
+	});
+
+	opts = {
+		'seed': 12345
+	};
+	rand = randu( opts );
+	rand[ '__ITERATOR_SYMBOL__' ] = factory;
+
+	it1 = iterDoUntilEach( rand, predicate, assert );
+	t.equal( typeof it1[ '__ITERATOR_SYMBOL__' ], 'function', 'has method' );
+	t.equal( it1[ '__ITERATOR_SYMBOL__' ].length, 0, 'has zero arity' );
+
+	it2 = it1[ '__ITERATOR_SYMBOL__' ]();
+	t.equal( typeof it2, 'object', 'returns an object' );
+	t.equal( typeof it2.next, 'function', 'has method' );
+	t.equal( typeof it2.return, 'function', 'has method' );
+
+	for ( i = 0; i < 100; i++ ) {
+		t.equal( it2.next().value, it1.next().value, 'returns expected value' );
+	}
+	t.end();
+
+	function factory() {
+		return randu( opts );
+	}
+
+	function assert( v, i ) {
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( !( isnan( v ) || isnan( i ) ) );
+	}
+});
+
+tape( 'if an environment does not support `Symbol.iterator`, the returned iterator is not "iterable"', function test( t ) {
+	var iterDoUntilEach;
+	var it;
+
+	iterDoUntilEach = proxyquire( './../lib/main.js', {
+		'@stdlib/symbol/iterator': false
+	});
+
+	it = iterDoUntilEach( randu(), predicate, assert );
+	t.equal( it[ iteratorSymbol ], void 0, 'does not have property' );
+
+	t.end();
+
+	function assert( v, i ) {
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( !( isnan( v ) || isnan( i ) ) );
+	}
+});
+
+tape( 'if a provided iterator is not iterable, the returned iterator is not iterable', function test( t ) {
+	var iterDoUntilEach;
+	var rand;
+	var it;
+
+	iterDoUntilEach = proxyquire( './../lib/main.js', {
+		'@stdlib/symbol/iterator': '__ITERATOR_SYMBOL__'
+	});
+
+	rand = randu();
+	rand[ '__ITERATOR_SYMBOL__' ] = null;
+
+	it = iterDoUntilEach( rand, predicate, assert );
+	t.equal( it[ iteratorSymbol ], void 0, 'does not have property' );
+	t.end();
+
+	function assert( v, i ) {
+		t.equal( isnan( v ), false, 'is not NaN' );
+		t.equal( isnan( i ), false, 'is not NaN' );
+	}
+
+	function predicate( v, i ) {
+		return ( !( isnan( v ) || isnan( i ) ) );
+	}
+});