feat!: improve type declarations for utils/map-arguments

This change significantly improves the type definition of the mapArguments
function, transitioning from broad 'Function' types to specific, generic types
and implementing conditional this context based on thisArg presence.

BREAKING CHANGE: function signature and return type now more strictly typed
The mapArguments function now uses generic types instead of 'Function', and its
return type depends on thisArg presence. 

Users should review and update their usage of mapArguments, particularly:

-   Ensure provided functions match the new, stricter type requirements
-   Update any type assertions or checks where mapArguments is used
-   Pay special attention to contexts where this binding is significant

PR-URL: #2050
Closes: #1087

Co-authored-by: Philipp Burckhardt <pburckhardt@outlook.com>
Co-authored-by: Prajwal Kulkarni <prajwalkulkarni76@gmail.com>
Reviewed-by: Philipp Burckhardt <pburckhardt@outlook.com>

lib/node_modules/@stdlib/utils/map-arguments/docs/types/index.d.ts

@@ -47,7 +47,57 @@
 * var out = bar( 1, 2, 3 );
 * // returns [ 2, 4, 6 ]
 */
-declare function mapArguments( fcn: Function, clbk: Function, thisArg?: any ): Function;
+declare function mapArguments<
+	T extends ( ...args: Array<any> ) => any,
+	C extends ( this: ThisParameterType<T>, value: Parameters<T>[number], index: number ) => any
+>(
+	fcn: T,
+	clbk: C
+): ( ...args: Parameters<T> ) => ReturnType<T>;
+
+/**
+* Returns a function that applies arguments to a provided function after transforming arguments according to a callback function.
+*
+* ## Notes
+*
+* -   The callback function is provided the following arguments:
+*
+*     -   **value**: argument value.
+*     -   **index**: argument index.
+*
+* @param fcn - input function
+* @param clbk - callback function
+* @param thisArg - input function context
+* @returns function wrapper
+*
+* @example
+* function foo( a, b, c ) {
+*     return [ a, b, c ];
+* }
+*
+* function clbk( v ) {
+*     this.count += 1;
+*     return v * 2;
+* }
+*
+* var thisArg = { 'count': 0 };
+* var bar = mapArguments( foo, clbk, thisArg );
+*
+* var out = bar( 1, 2, 3 );
+* // returns [ 2, 4, 6 ]
+*
+* var count = thisArg.count;
+* // returns 3
+*/
+declare function mapArguments<
+	T extends ( ...args: Array<any> ) => any,
+	C extends ( this: ThisParameterType<T>, value: Parameters<T>[number], index: number ) => any,
+	ThisArg
+>(
+	fcn: T,
+	clbk: C,
+	thisArg: ThisArg
+): ( this: ThisArg, ...args: Parameters<T> ) => ReturnType<T>;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/utils/map-arguments/docs/types/test.ts

@@ -18,23 +18,37 @@
 
 import mapArguments = require( './index' );
 
-/**
-* Callback function.
-*
-* @param v - argument
-* @returns result
-*/
-function clbk( v: any ): any {
+// FUNCTIONS //
+
+function clbk<T>( v: T ): T {
 	return v;
 }
 
+function stringify( n: number ): string {
+	return n.toString();
+}
+
+function sum( ...numbers: Array<number> ): number {
+	return numbers.reduce( ( a, b ) => a + b, 0 );
+}
+
+function greet( this: { name: string }, greeting: string ): string {
+	return `${greeting}, ${this.name}!`; // eslint-disable-line no-invalid-this
+}
+
 
 // TESTS //
 
 // The function returns a function...
 {
-	mapArguments( ( x: any, y: any, z: any ): Array<any> => [ x, y, z ], clbk ); // $ExpectType Function
-	mapArguments( ( x: any, y: any, z: any ): Array<any> => [ x, y, z ], clbk, {} ); // $ExpectType Function
+	mapArguments( ( x: number, y: number, z: number ): Array<number> => [ x, y, z ], clbk ); // $ExpectType (x: number, y: number, z: number) => number[]
+	mapArguments( ( x: string, y: string, z: string ): Array<string> => [ x, y, z ], clbk, {} ); // $ExpectType (this: {}, x: string, y: string, z: string) => string[]
+	mapArguments( ( x: number, y: number ): number => x + y, clbk ); // $ExpectType (x: number, y: number) => number
+
+	mapArguments( stringify, ( x: number ) => x * 2 ); // $ExpectType (n: number) => string
+	mapArguments( sum, ( x: number ) => x * 2 ); // $ExpectType (...args: number[]) => number
+
+	mapArguments( greet, ( s: string ) => s.toUpperCase(), { 'name': 'World' } ); // $ExpectType (this: { name: string; }, greeting: string) => string
 }
 
 // The compiler throws an error if the function is provided a first argument other than a function...