Use overloads to describe callback function

Author: kgryte

lib/node_modules/@stdlib/iter/map/docs/types/index.d.ts

@@ -25,14 +25,38 @@ 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 which transforms an iterated value.
+*
+* @returns callback result
+*/
+type Nullary = () => any;
+
+/**
+* Callback function which transforms an iterated value.
+*
+* @param value - iterated value
+* @returns callback result
+*/
+type Unary = ( value: any ) => any;
+
+/**
+* Callback function which transforms an iterated value.
+*
+* @param value - iterated value
+* @param i - iteration index
+* @returns callback result
+*/
+type Binary = ( value: any, i: number ) => any;
+
 /**
 * Callback function which transforms an iterated value.
 *
 * @param value - iterated value
 * @param i - iteration index
 * @returns callback result
 */
-type Callback = ( value?: any, i?: number ) => any;
+type Callback = Nullary | Unary | Binary;
 
 /**
 * Returns an iterator which invokes a function for each iterated value.

lib/node_modules/@stdlib/iter/map/docs/types/test.ts

@@ -44,10 +44,15 @@ function iterator() {
 /**
 * Callback function.
 *
+* @param v - iterated value
+* @param i - iteration index
 * @returns callback result
 */
-function fcn() {
-	return 'beep';
+function fcn( v: any, i: number ): any {
+	if ( i !== i ) {
+		throw new Error( 'something went wrong' );
+	}
+	return v;
 }