feat: add dtype option support in ndarray/flatten-by

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: passed
  - task: lint_license_headers
    status: passed
---

Author: headlessNode

lib/node_modules/@stdlib/ndarray/flatten-by/README.md

@@ -78,6 +78,8 @@ The function accepts the following options:
 
 -   **depth**: maximum number of input [ndarray][@stdlib/ndarray/ctor] dimensions to flatten.
 
+-   **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having the same [data type][@stdlib/ndarray/dtypes] as a provided input [ndarray][@stdlib/ndarray/ctor].
+
 By default, the function flattens all dimensions of the input [ndarray][@stdlib/ndarray/ctor]. To flatten to a desired depth, specify the `depth` option.
 
 ```javascript
@@ -126,6 +128,33 @@ var arr = ndarray2array( y );
 // returns [ 2.0, 6.0, 10.0, 4.0, 8.0, 12.0 ]
 ```
 
+By default, the output ndarray [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor]. To return an ndarray with a different [data type][@stdlib/ndarray/dtypes], specify the `dtype` option.
+
+```javascript
+var array = require( '@stdlib/ndarray/array' );
+var dtype = require( '@stdlib/ndarray/dtype' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+function scale( value ) {
+    return value * 2.0;
+}
+
+var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
+// returns <ndarray>
+
+var opts = {
+    'dtype': 'float32'
+};
+var y = flattenBy( x, opts, scale );
+// returns <ndarray>
+
+var dt = dtype( y );
+// returns 'float32'
+
+var arr = ndarray2array( y );
+// returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
+```
+
 To set the callback function execution context, provide a `thisArg`.
 
 <!-- eslint-disable no-invalid-this, max-len -->
@@ -224,6 +253,8 @@ console.log( ndarray2array( y ) );
 
 [@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
 
+[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
+
 [@stdlib/ndarray/orders]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/orders
 
 </section>

lib/node_modules/@stdlib/ndarray/flatten-by/docs/repl.txt

@@ -26,6 +26,10 @@
 
         Default: 'row-major'.
 
+    options.dtype: string (optional)
+        Output ndarray data type. By default, the function returns an ndarray
+        having the same data type as the provided input ndarray.
+
     fcn: Function
         Callback function.
 

lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/index.d.ts

@@ -20,7 +20,7 @@
 
 /// <reference types="@stdlib/types"/>
 
-import { typedndarray, genericndarray, Order } from '@stdlib/types/ndarray';
+import { typedndarray, genericndarray, Order, DataType } from '@stdlib/types/ndarray';
 import { ComplexLike } from '@stdlib/types/complex';
 
 /**
@@ -95,6 +95,15 @@ interface Options {
 	* -   Default: 'row-major'.
 	*/
 	order?: Order | 'same' | 'any';
+
+	/**
+	* Output ndarray data type.
+	*
+	* ## Notes
+	*
+	* -   By default, the function returns an ndarray having the same data type as a provided input ndarray.
+	*/
+	dtype?: DataType;
 }
 
 /**
@@ -232,6 +241,7 @@ declare function flattenBy<T = unknown, U extends genericndarray<T> = genericnda
 * @param options - function options
 * @param options.depth - maximum number of dimensions to flatten
 * @param options.order - order in which input ndarray elements should be flattened
+* @param options.dtype - output ndarray data type
 * @param fcn - callback function
 * @param thisArg - callback execution context
 * @returns output ndarray
@@ -272,6 +282,7 @@ declare function flattenBy<T extends typedndarray<number> = typedndarray<number>
 * @param options - function options
 * @param options.depth - maximum number of dimensions to flatten
 * @param options.order - order in which input ndarray elements should be flattened
+* @param options.dtype - output ndarray data type
 * @param fcn - callback function
 * @param thisArg - callback execution context
 * @returns output ndarray
@@ -309,6 +320,7 @@ declare function flattenBy<T extends ComplexLike = ComplexLike, U extends typedn
 * @param options - function options
 * @param options.depth - maximum number of dimensions to flatten
 * @param options.order - order in which input ndarray elements should be flattened
+* @param options.dtype - output ndarray data type
 * @param fcn - callback function
 * @param thisArg - callback execution context
 * @returns output ndarray
@@ -349,6 +361,7 @@ declare function flattenBy<T extends typedndarray<boolean> = typedndarray<boolea
 * @param options - function options
 * @param options.depth - maximum number of dimensions to flatten
 * @param options.order - order in which input ndarray elements should be flattened
+* @param options.dtype - output ndarray data type
 * @param fcn - callback function
 * @param thisArg - callback execution context
 * @returns output ndarray

lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/test.ts

@@ -178,6 +178,23 @@ function identity( x: any ): any {
 	flattenBy( x, { 'order': [ 1 ] }, identity, {} ); // $ExpectError
 }
 
+// The compiler throws an error if the function is provided a second argument with invalid `dtype` option...
+{
+	const x = zeros( 'generic', [ 2, 2, 2 ], 'row-major' );
+
+	flattenBy( x, { 'dtype': '5' }, identity ); // $ExpectError
+	flattenBy( x, { 'dtype': true }, identity ); // $ExpectError
+	flattenBy( x, { 'dtype': false }, identity ); // $ExpectError
+	flattenBy( x, { 'dtype': null }, identity ); // $ExpectError
+	flattenBy( x, { 'dtype': [ 1 ] }, identity ); // $ExpectError
+
+	flattenBy( x, { 'dtype': '5' }, identity, {} ); // $ExpectError
+	flattenBy( x, { 'dtype': true }, identity, {} ); // $ExpectError
+	flattenBy( x, { 'dtype': false }, identity, {} ); // $ExpectError
+	flattenBy( x, { 'dtype': null }, identity, {} ); // $ExpectError
+	flattenBy( x, { 'dtype': [ 1 ] }, identity, {} ); // $ExpectError
+}
+
 // The compiler throws an error if the function is provided a callback which is not a function...
 {
 	const x = zeros( 'generic', [ 2, 2 ], 'row-major' );

lib/node_modules/@stdlib/ndarray/flatten-by/lib/main.js

@@ -55,6 +55,7 @@ var COL_MAJOR = 'column-major';
 * @param {Options} [options] - function options
 * @param {NonNegativeInteger} [options.depth] - maximum number of dimensions to flatten
 * @param {string} [options.order='row-major'] - order in which input ndarray elements should be flattened
+* @param {*} [options.dtype] - output ndarray data type
 * @param {Function} fcn - callback function
 * @param {*} [thisArg] - callback execution context
 * @throws {TypeError} first argument must be an ndarray-like object
@@ -102,7 +103,8 @@ function flattenBy( x, options, fcn, thisArg ) {
 	// Define default options:
 	opts = {
 		'depth': xsh.length, // by default, flatten to a one-dimensional ndarray
-		'order': ROW_MAJOR   // by default, flatten in lexicographic order (i.e., trailing dimensions first; e.g., if `x` is a matrix, flatten row-by-row)
+		'order': ROW_MAJOR,   // by default, flatten in lexicographic order (i.e., trailing dimensions first; e.g., if `x` is a matrix, flatten row-by-row)
+		'dtype': getDType( x )
 	};
 
 	// Case: flattenBy( x, fcn )
@@ -165,16 +167,21 @@ function flattenBy( x, options, fcn, thisArg ) {
 				throw new TypeError( format( 'invalid option. `%s` option must be a recognized order. Option: `%s`.', 'order', options.order ) );
 			}
 		}
+		if ( hasOwnProp( options, 'dtype' ) ) {
+			// Delegate `dtype` validation to `emptyLike` during output array creation:
+			opts.dtype = options.dtype;
+		}
 	}
 	// Create an output ndarray having contiguous memory:
 	y = emptyLike( x, {
 		'shape': flattenShape( xsh, opts.depth ),
-		'order': opts.order
+		'order': opts.order,
+		'dtype': opts.dtype
 	});
 
 	// Create a view on top of output ndarray having the same shape as the input ndarray:
 	st = ( xsh.length > 0 ) ? shape2strides( xsh, opts.order ) : [ 0 ];
-	view = ndarray( getDType( y ), getData( y ), xsh, st, 0, opts.order );
+	view = ndarray( opts.dtype, getData( y ), xsh, st, 0, opts.order );
 
 	// Transform and assign elements to the output ndarray:
 	map( [ x, view ], cb, ctx );

lib/node_modules/@stdlib/ndarray/flatten-by/test/test.js

@@ -272,6 +272,39 @@ tape( 'the function throws an error if provided an invalid `order` option', func
 	}
 });
 
+tape( 'the function throws an error if provided an invalid `dtype` option', function test( t ) {
+	var values;
+	var i;
+
+	values = [
+		'foo',
+		'bar',
+		1,
+		NaN,
+		true,
+		false,
+		void 0,
+		null,
+		[],
+		{},
+		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() {
+			var opts = {
+				'dtype': value
+			};
+			flattenBy( zeros( [ 2 ] ), opts, identity );
+		};
+	}
+});
+
 tape( 'the function throws an error if provided a callback argument which is not a function', function test( t ) {
 	var values;
 	var i;