fix: reflect the returns option in @stdlib/utils find/bifurcate/group return types

lib/node_modules/@stdlib/utils/bifurcate-by/docs/types/index.d.ts

@@ -187,12 +187,12 @@ declare function bifurcateBy<T = unknown, U = unknown>( collection: Collection<T
 * var arr = [ 'beep', 'boop', 'foo', 'bar' ];
 *
 * var opts = {
-*     'returns': 'values'
+*     'returns': '*'
 * };
 * var out = bifurcateBy( arr, opts, predicate );
-* // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ]
+* // returns [ [ [ 0, 'beep' ], [ 1, 'boop' ], [ 3, 'bar' ] ], [ [ 2, 'foo' ] ] ]
 */
-declare function bifurcateBy<T = unknown, U = unknown>( collection: Collection<T>, options: ValuesOptions<T, U> | BaseOptions<T, U>, predicate: Predicate<T, U> ): [ Array<T>, Array<T> ];
+declare function bifurcateBy<T = unknown, U = unknown>( collection: Collection<T>, options: IndicesAndValuesOptions<T, U>, predicate: Predicate<T, U> ): [ Array<[ number, T ]>, Array<[ number, T ]> ];
 
 /**
 * Splits values into two groups according to a predicate function.
@@ -222,12 +222,12 @@ declare function bifurcateBy<T = unknown, U = unknown>( collection: Collection<T
 * var arr = [ 'beep', 'boop', 'foo', 'bar' ];
 *
 * var opts = {
-*     'returns': '*'
+*     'returns': 'values'
 * };
 * var out = bifurcateBy( arr, opts, predicate );
-* // returns [ [ [ 0, 'beep' ], [ 1, 'boop' ], [ 3, 'bar' ] ], [ [ 2, 'foo' ] ] ]
+* // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ]
 */
-declare function bifurcateBy<T = unknown, U = unknown>( collection: Collection<T>, options: IndicesAndValuesOptions<T, U>, predicate: Predicate<T, U> ): [ Array<[ number, T ]>, Array<[ number, T ]> ];
+declare function bifurcateBy<T = unknown, U = unknown>( collection: Collection<T>, options: ValuesOptions<T, U> | BaseOptions<T, U>, predicate: Predicate<T, U> ): [ Array<T>, Array<T> ];
 
 
 // EXPORTS //

lib/node_modules/@stdlib/utils/bifurcate/docs/types/index.d.ts

@@ -23,15 +23,45 @@
 import { Collection } from '@stdlib/types/array';
 
 /**
-* Interface defining function options.
+* Interface defining base function options.
 */
-interface Options {
+interface BaseOptions {
 	/**
 	* If `'values'`, values are returned; if `'indices'`, indices are returned; if `'*'`, both indices and values are returned.
 	*/
 	returns?: 'values' | 'indices' | '*';
 }
 
+/**
+* Interface defining function options when returning indices.
+*/
+interface IndicesOptions extends BaseOptions {
+	/**
+	* Specifies that indices should be returned.
+	*/
+	returns: 'indices';
+}
+
+/**
+* Interface defining function options when returning values.
+*/
+interface ValuesOptions extends BaseOptions {
+	/**
+	* Specifies that values should be returned.
+	*/
+	returns: 'values';
+}
+
+/**
+* Interface defining function options when returning indices and values.
+*/
+interface IndicesAndValuesOptions extends BaseOptions {
+	/**
+	* Specifies that indices and values should be returned.
+	*/
+	returns: '*';
+}
+
 /**
 * Splits values into two groups.
 *
@@ -43,7 +73,7 @@ interface Options {
 * @param collection - input collection
 * @param filter - collection indicating which group an element in the input collection belongs to
 * @throws first and last arguments must be the same length
-* @returns results
+* @returns group results
 *
 * @example
 * var arr = [ 'beep', 'boop', 'foo', 'bar' ];
@@ -67,7 +97,7 @@ declare function bifurcate<T = unknown>( collection: Collection<T>, filter: Coll
 * @param options.returns - if `values`, values are returned; if `indices`, indices are returned; if `*`, both indices and values are returned (default: 'values')
 * @param filter - collection indicating which group an element in the input collection belongs to
 * @throws first and last arguments must be the same length
-* @returns results
+* @returns group results
 *
 * @example
 * var arr = [ 'beep', 'boop', 'foo', 'bar' ];
@@ -79,6 +109,23 @@ declare function bifurcate<T = unknown>( collection: Collection<T>, filter: Coll
 *
 * var out = bifurcate( arr, opts, filter );
 * // returns [ [ 0, 1, 3 ], [ 2 ] ]
+*/
+declare function bifurcate<T = unknown>( collection: Collection<T>, options: IndicesOptions, filter: Collection ): Array<Array<number>>;
+
+/**
+* Splits values into two groups.
+*
+* ## Notes
+*
+* -   If an element in `filter` is truthy, then the corresponding element in the input collection belongs to the first group; otherwise, the collection element belongs to the second group.
+* -   If provided an empty collection, the function returns an empty array.
+*
+* @param collection - input collection
+* @param options - function options
+* @param options.returns - if `values`, values are returned; if `indices`, indices are returned; if `*`, both indices and values are returned (default: 'values')
+* @param filter - collection indicating which group an element in the input collection belongs to
+* @throws first and last arguments must be the same length
+* @returns group results
 *
 * @example
 * var arr = [ 'beep', 'boop', 'foo', 'bar' ];
@@ -91,7 +138,31 @@ declare function bifurcate<T = unknown>( collection: Collection<T>, filter: Coll
 * var out = bifurcate( arr, opts, filter );
 * // returns [ [ [ 0, 'beep' ], [ 1, 'boop' ], [ 3, 'bar' ] ], [ [ 2, 'foo' ] ] ]
 */
-declare function bifurcate<T = unknown>( collection: Collection<T>, options: Options, filter: Collection ): Array<Array<T>>;
+declare function bifurcate<T = unknown>( collection: Collection<T>, options: IndicesAndValuesOptions, filter: Collection ): Array<Array<[ number, T ]>>;
+
+/**
+* Splits values into two groups.
+*
+* ## Notes
+*
+* -   If an element in `filter` is truthy, then the corresponding element in the input collection belongs to the first group; otherwise, the collection element belongs to the second group.
+* -   If provided an empty collection, the function returns an empty array.
+*
+* @param collection - input collection
+* @param options - function options
+* @param options.returns - if `values`, values are returned; if `indices`, indices are returned; if `*`, both indices and values are returned (default: 'values')
+* @param filter - collection indicating which group an element in the input collection belongs to
+* @throws first and last arguments must be the same length
+* @returns group results
+*
+* @example
+* var arr = [ 'beep', 'boop', 'foo', 'bar' ];
+* var filter = [ true, true, false, true ];
+*
+* var out = bifurcate( arr, filter );
+* // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ]
+*/
+declare function bifurcate<T = unknown>( collection: Collection<T>, options: ValuesOptions | BaseOptions, filter: Collection ): Array<Array<T>>;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/utils/bifurcate/docs/types/test.ts

@@ -25,10 +25,20 @@ import bifurcate = require( './index' );
 {
 	bifurcate( [ 'beep', 'boop', 'foo', 'bar' ], [ true, true, false, true ] ); // $ExpectType string[][]
 
-	const opts = {
+	const indices = {
 		'returns': 'indices' as 'indices'
 	};
-	bifurcate( [ 'beep', 'boop', 'foo', 'bar' ], opts, [ true, true, false, true ] ); // $ExpectType string[][]
+	bifurcate( [ 'beep', 'boop', 'foo', 'bar' ], indices, [ true, true, false, true ] ); // $ExpectType number[][]
+
+	const values = {
+		'returns': 'values' as 'values'
+	};
+	bifurcate( [ 'beep', 'boop', 'foo', 'bar' ], values, [ true, true, false, true ] ); // $ExpectType string[][]
+
+	const both = {
+		'returns': '*' as '*'
+	};
+	bifurcate( [ 'beep', 'boop', 'foo', 'bar' ], both, [ true, true, false, true ] ); // $ExpectType [number, string][][]
 }
 
 // The compiler throws an error if the function is provided a first argument which is not a collection...

lib/node_modules/@stdlib/utils/find/docs/types/index.d.ts

@@ -141,7 +141,7 @@ declare function find<T = unknown>( arr: Collection<T> | string, clbk: Callback<
 * @param options.k - limits the number of returned elements (default: arr.length)
 * @param options.returns - if `values`, values are returned; if `indices`, indices are returned; if `*`, both indices and values are returned (default: 'indices')
 * @param clbk - function invoked for each array element. If the return value is truthy, the value is considered to have satisfied the test condition.
-* @returns array of indices
+* @returns array of values
 *
 * @example
 * function condition( val ) {
@@ -151,10 +151,10 @@ declare function find<T = unknown>( arr: Collection<T> | string, clbk: Callback<
 * var data = [ 30, 20, 50, 60, 10 ];
 * var opts = {
 *     'k': 2,
-*     'returns': 'indices'
+*     'returns': 'values'
 * };
 * var vals = find( data, opts, condition );
-* // returns [ 0, 2 ]
+* // returns [ 30, 50 ]
 *
 * @example
 * function condition( val ) {
@@ -164,12 +164,12 @@ declare function find<T = unknown>( arr: Collection<T> | string, clbk: Callback<
 * var data = [ 30, 20, 50, 60, 10 ];
 * var opts = {
 *     'k': -2,
-*     'returns': 'indices'
+*     'returns': 'values'
 * };
 * var vals = find( data, opts, condition );
-* // returns [ 3, 2 ]
+* // returns [ 60, 50 ]
 */
-declare function find<T = unknown>( arr: Collection<T> | string, options: IndicesOptions | BaseOptions, clbk: Callback<T> ): Array<number>;
+declare function find<T = unknown>( arr: Collection<T> | string, options: ValuesOptions, clbk: Callback<T> ): Array<T>;
 
 /**
 * Finds elements in an array-like object that satisfy a test condition.
@@ -179,20 +179,7 @@ declare function find<T = unknown>( arr: Collection<T> | string, options: Indice
 * @param options.k - limits the number of returned elements (default: arr.length)
 * @param options.returns - if `values`, values are returned; if `indices`, indices are returned; if `*`, both indices and values are returned (default: 'indices')
 * @param clbk - function invoked for each array element. If the return value is truthy, the value is considered to have satisfied the test condition.
-* @returns array of values
-*
-* @example
-* function condition( val ) {
-*     return val > 20;
-* }
-*
-* var data = [ 30, 20, 50, 60, 10 ];
-* var opts = {
-*     'k': 2,
-*     'returns': 'values'
-* };
-* var vals = find( data, opts, condition );
-* // returns [ 30, 50 ]
+* @returns array of index-value pairs
 *
 * @example
 * function condition( val ) {
@@ -202,12 +189,12 @@ declare function find<T = unknown>( arr: Collection<T> | string, options: Indice
 * var data = [ 30, 20, 50, 60, 10 ];
 * var opts = {
 *     'k': -2,
-*     'returns': 'values'
+*     'returns': '*'
 * };
 * var vals = find( data, opts, condition );
-* // returns [ 60, 50 ]
+* // returns [ [3, 60], [2, 50] ]
 */
-declare function find<T = unknown>( arr: Collection<T> | string, options: ValuesOptions, clbk: Callback<T> ): Array<T>;
+declare function find<T = unknown>( arr: Collection<T> | string, options: IndicesAndValuesOptions, clbk: Callback<T> ): Array<[ number, T ]>;
 
 /**
 * Finds elements in an array-like object that satisfy a test condition.
@@ -217,7 +204,20 @@ declare function find<T = unknown>( arr: Collection<T> | string, options: Values
 * @param options.k - limits the number of returned elements (default: arr.length)
 * @param options.returns - if `values`, values are returned; if `indices`, indices are returned; if `*`, both indices and values are returned (default: 'indices')
 * @param clbk - function invoked for each array element. If the return value is truthy, the value is considered to have satisfied the test condition.
-* @returns array of index-value pairs
+* @returns array of indices
+*
+* @example
+* function condition( val ) {
+*     return val > 20;
+* }
+*
+* var data = [ 30, 20, 50, 60, 10 ];
+* var opts = {
+*     'k': 2,
+*     'returns': 'indices'
+* };
+* var vals = find( data, opts, condition );
+* // returns [ 0, 2 ]
 *
 * @example
 * function condition( val ) {
@@ -227,12 +227,12 @@ declare function find<T = unknown>( arr: Collection<T> | string, options: Values
 * var data = [ 30, 20, 50, 60, 10 ];
 * var opts = {
 *     'k': -2,
-*     'returns': '*'
+*     'returns': 'indices'
 * };
 * var vals = find( data, opts, condition );
-* // returns [ [3, 60], [2, 50] ]
+* // returns [ 3, 2 ]
 */
-declare function find<T = unknown>( arr: Collection<T> | string, options: IndicesAndValuesOptions, clbk: Callback<T> ): Array<[ number, T ]>;
+declare function find<T = unknown>( arr: Collection<T> | string, options: IndicesOptions | BaseOptions, clbk: Callback<T> ): Array<number>;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/utils/find/docs/types/test.ts

@@ -53,6 +53,26 @@ function condition( v: number ): boolean {
 	find( arr, opts3, condition ); // $ExpectType [number, number][]
 }
 
+// The function resolves the element type according to the `returns` option...
+{
+	const arr = [ 'a', 'b', 'c' ];
+
+	/**
+	* Condition function.
+	*
+	* @param v - value
+	* @returns boolean result
+	*/
+	function isB( v: string ): boolean {
+		return ( v === 'b' );
+	}
+
+	find( arr, { 'returns': 'indices' as 'indices' }, isB ); // $ExpectType number[]
+	find( arr, { 'returns': 'values' as 'values' }, isB ); // $ExpectType string[]
+	find( arr, { 'returns': '*' as '*' }, isB ); // $ExpectType [number, string][]
+	find( arr, { 'k': 2 }, isB ); // $ExpectType number[]
+}
+
 // The compiler throws an error if the function is provided a first argument which is not a collection...
 {
 	find( true, condition ); // $ExpectError