Make functions generic so it can cast to opaque (branded) types (#521)

* Make functions generic so it can cast to opaque types

* Add TypeScript section translations to ru, zh-CN and id-ID

Author: kossnocorp

README.id-ID.md

@@ -302,6 +302,29 @@ LZfXLFzPPR4NNrgjlWDxn
 
 Bila ingin mengganti alfabet atau ukuran ID, dapat menggunakan [`nanoid-cli`](https://github.com/twhitbeck/nanoid-cli).
 
+### TypeScript
+
+Nano ID memungkinkan untuk mengubah string yang dihasilkan menjadi string opak
+dalam TypeScript. Sebagai contoh:
+
+```ts
+type UserId = string & { [userIdBrand]: true }
+declare const userIdBrand: unique symbol
+
+interface User {
+  id: UserId
+  name: string
+}
+
+const user: User = {
+  // Secara otomatis diubah menjadi UserId:
+  id: nanoid(),
+  name: 'Alice'
+}
+
+// Gunakan parameter tipe secara eksplisit:
+mockUser(nanoid<UserId>())
+```
 
 ### Bahasa Pemrograman Lainnya
 

README.md

@@ -416,6 +416,29 @@ $ npx nanoid --alphabet abc --size 15
 bccbcabaabaccab
 ```
 
+### TypeScript
+
+Nano ID allows casting generated strings into opaque strings in TypeScript.
+For example:
+
+```ts
+type UserId = string & { [userIdBrand]: true }
+declare const userIdBrand: unique symbol
+
+interface User {
+  id: UserId
+  name: string
+}
+
+const user: User = {
+  // Automatically casts to UserId:
+  id: nanoid(),
+  name: 'Alice'
+}
+
+// Use explicit type parameter:
+mockUser(nanoid<UserId>())
+```
 
 ### Other Programming Languages
 

README.ru.md

@@ -396,6 +396,30 @@ $ npx nanoid --alphabet abc --size 15
 bccbcabaabaccab
 ```
 
+### TypeScript
+
+Nano ID позволяет приводить сгенерированные строки к непрозрачным строкам в
+TypeScript. Например:
+
+```ts
+type UserId = string & { [userIdBrand]: true }
+declare const userIdBrand: unique symbol
+
+interface User {
+  id: UserId
+  name: string
+}
+
+const user: User = {
+  // Автоматически приводится к типу UserId:
+  id: nanoid(),
+  name: 'Alice'
+}
+
+// Используйте явный параметр типа:
+mockUser(nanoid<UserId>())
+```
+
 ### Другие языки программирования
 
 Nano ID был портирован на множество языков. Это полезно, чтобы сервер и клиент

README.zh-CN.md

@@ -370,6 +370,28 @@ $ npx nanoid --alphabet abc --size 15
 bccbcabaabaccab
 ```
 
+### TypeScript
+
+Nano ID 允许将生成的字符串转换为 TypeScript 中的不透明字符串。 例如：
+
+```ts
+type UserId = string & { [userIdBrand]: true }
+declare const userIdBrand: unique symbol
+
+interface User {
+  id: UserId
+  name: string
+}
+
+const user: User = {
+  // 自动转换为 UserId:
+  id: nanoid(),
+  name: 'Alice'
+}
+
+// 使用显式类型参数:
+mockUser(nanoid<UserId>())
+```
 
 ### 其他编程语言
 

index.d.ts

@@ -10,9 +10,10 @@
  * ```
  *
  * @param size Size of the ID. The default size is 21.
+ * @typeparam Type The type of the generated ID.
  * @returns A random string.
  */
-export function nanoid(size?: number): string
+export function nanoid<Type extends string>(size?: number): Type
 
 /**
  * Generate secure unique ID with custom alphabet.
@@ -22,6 +23,7 @@ export function nanoid(size?: number): string
  *
  * @param alphabet Alphabet used to generate the ID.
  * @param defaultSize Size of the ID. The default size is 21.
+ * @typeparam Type The type of the generated ID.
  * @returns A random string generator.
  *
  * ```js
@@ -30,10 +32,10 @@ export function nanoid(size?: number): string
  * nanoid() //=> "8ё56а"
  * ```
  */
-export function customAlphabet(
+export function customAlphabet<Type extends string>(
   alphabet: string,
   defaultSize?: number
-): (size?: number) => string
+): (size?: number) => Type
 
 /**
  * Generate unique ID with custom random generator and alphabet.
@@ -58,13 +60,14 @@ export function customAlphabet(
  * @param alphabet Alphabet used to generate a random string.
  * @param size Size of the random string.
  * @param random A random bytes generator.
+ * @typeparam Type The type of the generated ID.
  * @returns A random string generator.
  */
-export function customRandom(
+export function customRandom<Type extends string>(
   alphabet: string,
   size: number,
   random: (bytes: number) => Uint8Array
-): () => string
+): () => Type
 
 /**
  * URL safe symbols.