Add overloads

kgryte · kgryte · commit 3a608eaec8c4 · 2022-01-15T02:24:50.000-08:00
diff --git a/lib/node_modules/@stdlib/array/promotion-rules/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/promotion-rules/docs/types/index.d.ts
@@ -18,20 +18,31 @@
 
 // TypeScript Version: 2.0
 
+/// <reference types="@stdlib/types"/>
+
+import { DataType } from '@stdlib/types/array';
+
 /**
 * Interface describing a promotion table.
 */
 interface Table {
-	// Table properties:
-	[key: string]: string | number;
+	/**
+	* Data type promotion rules.
+	*/
+	[key: string]: DataType | number;
 }
 
+/**
+* Promotion rule.
+*/
+type PromotionRule = DataType | number;
+
 /**
 * Returns the array data type with the smallest size and closest "kind" to which array data types can be safely cast.
 *
 * @param dtype1 - array data type
 * @param dtype2 - array data type
-* @returns promotion rule(s) or null
+* @returns promotion rule
 *
 * @example
 * var dt = promotionRules( 'float32', 'uint32' );
@@ -41,11 +52,34 @@ interface Table {
 * var dt = promotionRules( 'float32', 'foo' );
 * // returns null
 */
-declare function promotionRules( dtype1: string, dtype2: string ): number | string | null; // tslint-disable-line max-line-length
+declare function promotionRules( dtype1: DataType, dtype2: DataType ): PromotionRule; // tslint:disable-line:max-line-length
+
+/**
+* Returns the array data type with the smallest size and closest "kind" to which array data types can be safely cast.
+*
+* @param dtype1 - array data type
+* @param dtype2 - array data type
+* @returns promotion rule
+*
+* @example
+* var dt = promotionRules( 'float32', 'foo' );
+* // returns null
+*
+* @example
+* var dt = promotionRules( 'bar', 'float32' );
+* // returns null
+*
+* @example
+* var dt = promotionRules( 'bar', 'foo' );
+* // returns null
+*/
+declare function promotionRules( dtype1: string, dtype2: string ): null;
 
 /**
 * Returns a type promotion table displaying array data types with the smallest size and closest "kind" to which array data types can be safely cast.
 *
+* @param dtype1 - array data type
+* @param dtype2 - array data type
 * @returns promotion rule table
 *
 * @example
diff --git a/lib/node_modules/@stdlib/array/promotion-rules/docs/types/test.ts b/lib/node_modules/@stdlib/array/promotion-rules/docs/types/test.ts
@@ -21,12 +21,22 @@ import promotionRules = require( './index' );
 
 // TESTS //
 
-// The function returns an object, array of strings, or null...
+// The function returns an object when not provided any arguments...
 {
 	promotionRules(); // $ExpectType Table
-	promotionRules( 'float32', 'uint32' ); // $ExpectType string | number | null
-	promotionRules( 'int32', 'generic' ); // $ExpectType string | number | null
-	promotionRules( 'float32', 'foo' ); // $ExpectType string | number | null
+}
+
+// The function returns a promoted data type promotion rule when provided recognized data types...
+{
+	promotionRules( 'float32', 'uint32' ); // $ExpectType PromotionRule
+	promotionRules( 'int32', 'generic' ); // $ExpectType PromotionRule
+}
+
+// The function returns null when provided unrecognized data types...
+{
+	promotionRules( 'float32', 'foo' ); // $ExpectType null
+	promotionRules( 'bar', 'foo' ); // $ExpectType null
+	promotionRules( 'bar', 'float32' ); // $ExpectType null
 }
 
 // The function does not compile if provided a first argument that is not a string...
