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.

Author: Planeshifter

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 //

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...

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 //

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...

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 //

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...

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 //

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...

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 //

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...

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 //

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...

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 //

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...

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 //

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...