From 67858b341e920fed871e34ba0d6b6809804916f7 Mon Sep 17 00:00:00 2001
From: Philipp Burckhardt <pburckhardt@outlook.com>
Date: Sat, 13 Jul 2024 19:09:43 -0400
Subject: [PATCH] feat!: improve type safety

The functions now use generics for improved type safety.

BREAKING CHANGE:

The return types are now more specific. This may break existing code that relies on less strict typing, but should not affect most users. To preserve the prior behavior, you can cast the return value to `string` via a type assertion.
---
 .../@stdlib/string/base/capitalize/docs/types/index.d.ts  | 4 +++-
 .../@stdlib/string/base/capitalize/docs/types/test.ts     | 6 +++++-
 .../@stdlib/string/base/lowercase/docs/types/index.d.ts   | 2 +-
 .../@stdlib/string/base/lowercase/docs/types/test.ts      | 4 +++-
 .../string/base/uncapitalize/docs/types/index.d.ts        | 4 +++-
 .../@stdlib/string/base/uncapitalize/docs/types/test.ts   | 6 +++++-
 .../@stdlib/string/base/uppercase/docs/types/index.d.ts   | 2 +-
 .../@stdlib/string/base/uppercase/docs/types/test.ts      | 6 +++++-
 .../@stdlib/string/capitalize/docs/types/index.d.ts       | 4 +++-
 .../@stdlib/string/capitalize/docs/types/test.ts          | 8 ++++++--
 .../@stdlib/string/lowercase/docs/types/index.d.ts        | 2 +-
 .../@stdlib/string/lowercase/docs/types/test.ts           | 4 +++-
 .../@stdlib/string/uncapitalize/docs/types/index.d.ts     | 4 +++-
 .../@stdlib/string/uncapitalize/docs/types/test.ts        | 6 +++++-
 .../@stdlib/string/uppercase/docs/types/index.d.ts        | 2 +-
 .../@stdlib/string/uppercase/docs/types/test.ts           | 6 +++++-
 16 files changed, 53 insertions(+), 17 deletions(-)

diff --git a/lib/node_modules/@stdlib/string/base/capitalize/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/capitalize/docs/types/index.d.ts
index 0a53a3227c0..2e261a40d9d 100644
--- a/lib/node_modules/@stdlib/string/base/capitalize/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/base/capitalize/docs/types/index.d.ts
@@ -18,6 +18,8 @@
 
 // TypeScript Version: 4.1
 
+type Capitalize<S extends string> = S extends `${infer F}${infer R}` ? `${Uppercase<F>}${R}` : S;
+
 /**
 * Capitalizes the first character in a string.
 *
@@ -40,7 +42,7 @@
 * var out = capitalize( 'Hidden Treasures' );
 * // returns 'Hidden Treasures'
 */
-declare function capitalize( str: string ): string;
+declare function capitalize<S extends string>( str: S ): Capitalize<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/base/capitalize/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/capitalize/docs/types/test.ts
index 072215f8e6a..8644f23a5b2 100644
--- a/lib/node_modules/@stdlib/string/base/capitalize/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/base/capitalize/docs/types/test.ts
@@ -23,7 +23,11 @@ import capitalize = require( './index' );
 
 // The function returns a string...
 {
-	capitalize( 'abc' ); // $ExpectType string
+	capitalize( 'abc' ); // $ExpectType "Abc"
+	capitalize( 'beep boop' ); // $ExpectType "Beep boop"
+	capitalize( 'a' ); // $ExpectType "A"
+	capitalize( 'A' ); // $ExpectType "A"
+	capitalize( 'abc' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/base/lowercase/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/lowercase/docs/types/index.d.ts
index d06fef844d1..b73454a5f91 100644
--- a/lib/node_modules/@stdlib/string/base/lowercase/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/base/lowercase/docs/types/index.d.ts
@@ -28,7 +28,7 @@
 * var str = lowercase( 'bEEp' );
 * // returns 'beep'
 */
-declare function lowercase( str: string ): string;
+declare function lowercase<S extends string>( str: S ): Lowercase<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/base/lowercase/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/lowercase/docs/types/test.ts
index daa8c245422..50fbe9a6a5b 100644
--- a/lib/node_modules/@stdlib/string/base/lowercase/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/base/lowercase/docs/types/test.ts
@@ -23,7 +23,9 @@ import lowercase = require( './index' );
 
 // The function returns a string...
 {
-	lowercase( 'abc' ); // $ExpectType string
+	lowercase( 'ABC' ); // $ExpectType "abc"
+	lowercase( 'Beep BOOP' ); // $ExpectType "beep boop"
+	lowercase( 'abc' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/index.d.ts
index 31bbdd81082..a7860f7e5e4 100644
--- a/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/index.d.ts
@@ -18,6 +18,8 @@
 
 // TypeScript Version: 4.1
 
+type Uncapitalize<S extends string> = S extends `${infer F}${infer R}` ? `${Lowercase<F>}${R}` : S;
+
 /**
 * Uncapitalizes the first character of a string.
 *
@@ -40,7 +42,7 @@
 * var out = uncapitalize( 'Hidden Treasures' );
 * // returns 'hidden Treasures'
 */
-declare function uncapitalize( str: string ): string;
+declare function uncapitalize<S extends string>( str: S ): Uncapitalize<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/test.ts
index bb1a0d2ff48..197c29a2566 100644
--- a/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/base/uncapitalize/docs/types/test.ts
@@ -23,7 +23,11 @@ import uncapitalize = require( './index' );
 
 // The function returns a string...
 {
-	uncapitalize( 'Last man standing' ); // $ExpectType string
+	uncapitalize( 'Last man standing' ); // $ExpectType "last man standing"
+	uncapitalize( 'Hello World!' ); // $ExpectType "hello World!"
+	uncapitalize( 'BeepBoop' ); // $ExpectType "beepBoop"
+	uncapitalize( 'A' ); // $ExpectType "a"
+	uncapitalize( 'foo' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/base/uppercase/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/base/uppercase/docs/types/index.d.ts
index 6c3eb612a14..4341559f382 100644
--- a/lib/node_modules/@stdlib/string/base/uppercase/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/base/uppercase/docs/types/index.d.ts
@@ -28,7 +28,7 @@
 * var str = uppercase( 'bEEp' );
 * // returns 'BEEP'
 */
-declare function uppercase( str: string ): string;
+declare function uppercase<S extends string>( str: S ): Uppercase<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/base/uppercase/docs/types/test.ts b/lib/node_modules/@stdlib/string/base/uppercase/docs/types/test.ts
index 9d3278894f3..beae3f0d85e 100644
--- a/lib/node_modules/@stdlib/string/base/uppercase/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/base/uppercase/docs/types/test.ts
@@ -23,7 +23,11 @@ import uppercase = require( './index' );
 
 // The function returns a string...
 {
-	uppercase( 'Last man standing' ); // $ExpectType string
+	uppercase( 'Last man standing' ); // $ExpectType "LAST MAN STANDING"
+	uppercase( 'Hello World!' ); // $ExpectType "HELLO WORLD!"
+	uppercase( 'beep' ); // $ExpectType "BEEP"
+	uppercase( 'BOOP' ); // $ExpectType "BOOP"
+	uppercase( 'foo' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/capitalize/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/capitalize/docs/types/index.d.ts
index c559d18cbe2..60c2849ff64 100644
--- a/lib/node_modules/@stdlib/string/capitalize/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/capitalize/docs/types/index.d.ts
@@ -18,6 +18,8 @@
 
 // TypeScript Version: 4.1
 
+type Capitalize<S extends string> = S extends `${infer F}${infer R}` ? `${Uppercase<F>}${R}` : S;
+
 /**
 * Capitalizes the first character in a string.
 *
@@ -40,7 +42,7 @@
 * var out = capitalize( 'Hidden Treasures' );
 * // returns 'Hidden Treasures'
 */
-declare function capitalize( str: string ): string;
+declare function capitalize<S extends string>( str: S ): Capitalize<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/capitalize/docs/types/test.ts b/lib/node_modules/@stdlib/string/capitalize/docs/types/test.ts
index 508d191b4e1..621a6c85cb9 100644
--- a/lib/node_modules/@stdlib/string/capitalize/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/capitalize/docs/types/test.ts
@@ -21,9 +21,13 @@ import capitalize = require( './index' );
 
 // TESTS //
 
-// The function returns a string...
+// The function returns a capitalized string...
 {
-	capitalize( 'abc' ); // $ExpectType string
+	capitalize( 'abc' ); // $ExpectType "Abc"
+	capitalize( 'beep boop' ); // $ExpectType "Beep boop"
+	capitalize( 'a' ); // $ExpectType "A"
+	capitalize( 'A' ); // $ExpectType "A"
+	capitalize( 'abc' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/lowercase/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/lowercase/docs/types/index.d.ts
index 56d30464277..2d0b221e4a8 100644
--- a/lib/node_modules/@stdlib/string/lowercase/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/lowercase/docs/types/index.d.ts
@@ -28,7 +28,7 @@
 * var str = lowercase( 'bEEp' );
 * // returns 'beep'
 */
-declare function lowercase( str: string ): string;
+declare function lowercase<S extends string>( str: S ): Lowercase<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/lowercase/docs/types/test.ts b/lib/node_modules/@stdlib/string/lowercase/docs/types/test.ts
index 5e3fcaef9a9..0f9c14554d4 100644
--- a/lib/node_modules/@stdlib/string/lowercase/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/lowercase/docs/types/test.ts
@@ -23,7 +23,9 @@ import lowercase = require( './index' );
 
 // The function returns a string...
 {
-	lowercase( 'abc' ); // $ExpectType string
+	lowercase( 'ABC' ); // $ExpectType "abc"
+	lowercase( 'Beep BOOP' ); // $ExpectType "beep boop"
+	lowercase( 'abc' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/uncapitalize/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/uncapitalize/docs/types/index.d.ts
index 0950b30c33d..3b7c488f54e 100644
--- a/lib/node_modules/@stdlib/string/uncapitalize/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/uncapitalize/docs/types/index.d.ts
@@ -18,6 +18,8 @@
 
 // TypeScript Version: 4.1
 
+type Uncapitalize<S extends string> = S extends `${infer F}${infer R}` ? `${Lowercase<F>}${R}` : S;
+
 /**
 * Uncapitalizes the first character of a string.
 *
@@ -40,7 +42,7 @@
 * var out = uncapitalize( 'Hidden Treasures' );
 * // returns 'hidden Treasures'
 */
-declare function uncapitalize( str: string ): string;
+declare function uncapitalize<S extends string>( str: S ): Uncapitalize<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/uncapitalize/docs/types/test.ts b/lib/node_modules/@stdlib/string/uncapitalize/docs/types/test.ts
index 82ca1b0f1ac..b35d326b4d8 100644
--- a/lib/node_modules/@stdlib/string/uncapitalize/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/uncapitalize/docs/types/test.ts
@@ -23,7 +23,11 @@ import uncapitalize = require( './index' );
 
 // The function returns a string...
 {
-	uncapitalize( 'Last man standing' ); // $ExpectType string
+	uncapitalize( 'Last man standing' ); // $ExpectType "last man standing"
+	uncapitalize( 'Hello World!' ); // $ExpectType "hello World!"
+	uncapitalize( 'BeepBoop' ); // $ExpectType "beepBoop"
+	uncapitalize( 'A' ); // $ExpectType "a"
+	uncapitalize( 'foo' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...
diff --git a/lib/node_modules/@stdlib/string/uppercase/docs/types/index.d.ts b/lib/node_modules/@stdlib/string/uppercase/docs/types/index.d.ts
index c8ea504b14b..6254b6535f7 100644
--- a/lib/node_modules/@stdlib/string/uppercase/docs/types/index.d.ts
+++ b/lib/node_modules/@stdlib/string/uppercase/docs/types/index.d.ts
@@ -28,7 +28,7 @@
 * var str = uppercase( 'bEEp' );
 * // returns 'BEEP'
 */
-declare function uppercase( str: string ): string;
+declare function uppercase<S extends string>( str: S ): Uppercase<S>;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/string/uppercase/docs/types/test.ts b/lib/node_modules/@stdlib/string/uppercase/docs/types/test.ts
index f9d11f96dbd..2cadcfa6c2b 100644
--- a/lib/node_modules/@stdlib/string/uppercase/docs/types/test.ts
+++ b/lib/node_modules/@stdlib/string/uppercase/docs/types/test.ts
@@ -23,7 +23,11 @@ import uppercase = require( './index' );
 
 // The function returns a string...
 {
-	uppercase( 'Last man standing' ); // $ExpectType string
+	uppercase( 'Last man standing' ); // $ExpectType "LAST MAN STANDING"
+	uppercase( 'Hello World!' ); // $ExpectType "HELLO WORLD!"
+	uppercase( 'beep' ); // $ExpectType "BEEP"
+	uppercase( 'BOOP' ); // $ExpectType "BOOP"
+	uppercase( 'foo' as string ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a value other than a string...