>
97 | : T extends `${string}:${infer P}`
98 | ? Params | ResolveRouteParam
99 | : Params;
100 | ```
101 |
102 | 对于路由定义 `/users/:userId@number/books/:bookId@number`，上述的 `ParseRouteString` 的返回类型为：`["userId", number] | ["bookId", number]`。接下来的问题是如何将它转换为期望的对象类型。
103 |
104 | ```typescript
105 | type MakeParamsType<
106 | T extends string,
107 | R extends [string, unknown] = ParseRouteString
108 | > = {
109 | // 👇 注意到 R[0] 返回 "userId" | "bookId"
110 | [K in R[0]]: R extends [K, infer U] ? U : never;
111 | // 👆 使用分配式条件类型找到 K 对应的元组的第二个元素，即它的路由参数类型
112 | // 分配式条件类型的计算过程（当 K 为 "bookId" 时）：
113 | // 1. ["userId", number] | ["bookId", number] extends ["bookId", infer U]...
114 | // 2. ["userId", number] extends ["bookId", infer U]... | ["bookId", number] extends ["bookId", infer U]...
115 | // 3. never | number
116 | // 4. number
117 | } & {};
118 | ```
119 |
120 | 最后，我们检验一下上面的代码是否正常工作：
121 |
122 | ```typescript
123 | get("/users/:userId@number/books/:bookId@number", (req) => {
124 | const { params } = req;
125 | // ^? const params: { userId: number; bookId: number }
126 | });
127 |
128 | get("/users/:userId/:phone@number", (req) => {
129 | const { params } = req;
130 | // ^? const params: { userId: unknown, phone: number }
131 | });
132 | ```
133 |
134 | ## 类型安全的装饰器 `5.0+`
135 |
136 | 这里讨论的「装饰器」并不是 [TypeScript 5.0 版本实现的新装饰器提案](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#decorators)，而是旧的 Stage 2 装饰器提案。不过，我们会在本节末尾稍微讨论一下是否可以使用新装饰器提案实现本节的功能。
137 |
138 | 许多依赖注入框架提供了类似 `@Inject` 的装饰器用来修饰一个类的属性，这样框架就能在实例化这个类时根据装饰器注入的元数据知道应该向这个属性赋予什么值（注意，这个过程发生在运行时而不是编译时）。
139 |
140 | 假如有下面的代码，我们这里使用的框架需要通过向 `@Inject` 中提供需要注入的类实例的构造函数（即 `SomeService`）来让框架注入对应的元数据。这里我们遇到了一个问题：如何确保给 `someService` 属性标注的类型是正确的？
141 |
142 | ```typescript
143 | class SomeService {}
144 |
145 | class MyService {
146 | constructor(@Inject(SomeService) private readonly someService: SomeService) {}
147 | }
148 | ```
149 |
150 | 考虑一个进阶的装饰器 `@OptionalInject`，它告诉框架如果对应的服务不存在就直接注入 `null` 值，而不是像 `@Inject` 那样直接抛错。在这种情况下应该给属性的类型额外标上 `null`，就像下面这样：
151 |
152 | ```typescript
153 | class MyService {
154 | constructor(
155 | @Inject(SomeService) private readonly someService: SomeService,
156 | @OptionalInject(OtherService)
157 | private readonly otherService: OtherService | null
158 | ) {}
159 | }
160 | ```
161 |
162 | 这种依赖于用户自觉的办法是不稳妥的，因为他们很可能不会仔细阅读 `OptionalInject` 的文档，不会知道它可能会使得属性被赋予 `null` 值。另外，后续一旦 `OptionalInject` 发生了修改，从注入 `null` 值修改为了注入 `undefined` 值，那么所有的引用都需要一个个地查找和修改，这不是一种可扩展的方法。
163 |
164 | 可惜的是，TypeScript 不能通过装饰器的修饰来为类属性赋予类型，所以我们没有办法略去类型标注而让装饰器负责提供类型。不过，也许可以退而求次，提供一种类型检查的手段让 TypeScript 检查下面两个类型的关系：
165 |
166 | - 向装饰器传入的类构造函数的类型
167 | - 为装饰器装饰的属性提供的类型标注
168 |
169 | ### 解决方案
170 |
171 | TypeScript 要求属性装饰器函数必须满足下面的类型，注意到它的返回值类型必须为 `void` 或 `any`。
172 |
173 | ```typescript
174 | type ParameterDecorator = (
175 | // 被装饰的属性所在的类的构造函数
176 | target: Object,
177 | // 被装饰的属性所在函数的键
178 | propertyKey: string | symbol | undefined,
179 | // 被装饰的属性是所在函数的第几个参数
180 | parameterIndex: number
181 | ) => void;
182 | ```
183 |
184 | 当某个属性装饰器函数的类型返回值不为 `void` 或 `any` 时，TypeScript 会在*使用这个装饰器的地方*报错：
185 |
186 | > Decorator function return type is '...' but is expected to be 'void' or 'any'.
187 |
188 | 于是我们有了下面的实现思路：提供一种类型化的装饰器函数，当被装饰属性的类型（即 `target` 的类型）不满足一定条件时，让函数的返回值类型不再为 `void`，从而触发 TypeScript 的报错。
189 |
190 | 我们的实现先从装饰器函数本身开始，为了实现上述功能，需要一个返回装饰器的函数 `OptionalInjectDecoratorFactory`。注意在 `@Inject(...)` 中我们实际上是调用了 `Inject` 这个函数，然后再将它返回的装饰器（它本质上也是一个函数）交给 TypeScript。
191 |
192 | ```typescript
193 | interface OptionalInjectDecoratorFactory {
194 | // 通过函数类型推导，获得输入的构造函数对应的类实例类型
195 | (token: { new (): T }): TypedParameterDecorator;
196 |
197 | // 似乎不是必要的，但许多装饰器实现都会包含这个
198 | new (): OptionalInjectDecoratorFactory;
199 | }
200 |
201 | // 具体的装饰器实现就不讨论了
202 | declare const OptionalInject: OptionalInjectDecoratorFactory;
203 | ```
204 |
205 | `TypedParameterDecorator` 类型的计算结果即为我们的装饰器的类型，请看下面的代码：
206 |
207 | ```typescript
208 | type TypedParameterDecorator = <
209 | Target extends abstract new (...args: any) => any,
210 | Index extends number
211 | >(
212 | target: Target,
213 | propertyKey: string | symbol | undefined,
214 | parameterIndex: Index
215 | // 👇 检查传入的 T 类型是否和被装饰的属性的类型相等
216 | ) => DoCheck[Index]>;
217 | // 👆 先得到构造函数的参数列表，然后使用下标访问
218 |
219 | // 当两个类型相等时，返回 `void` 让装饰器通过类型检查，否则返回 `false`。
220 | // 这里的 `false` 可以是其它一些能够满足上述条件的类型
221 | type DoCheck = IsEqual extends true ? void : false;
222 |
223 | // TypeScript 社区发明了很多方法来检查两个类型是否「相等」，但是它们都或多或少存在一些边界条件
224 | // 下面这个版本是泛用性比较强的，详见 Stack Overflow 上的讨论
225 | type IsEqual = (() => T extends X ? 1 : 2) extends () => T extends Y
226 | ? 1
227 | : 2
228 | ? true
229 | : false;
230 | ```
231 |
232 | 下面，让我们来测试一下这个装饰器的效果如何：
233 |
234 | ```typescript
235 | class MyService {
236 | constructor(
237 | @OptionalInject(SomeService) // 类型检查通过！
238 | private readonly _0: SomeService | null,
239 |
240 | @OptionalInject(SomeService) // 类型检查不通过！
241 | private readonly _1: SomeService,
242 |
243 | @OptionalInject(SomeService) // 类型检查不通过！
244 | private readonly _2: boolean
245 | ) {}
246 | }
247 | ```
248 |
249 | 尽管 TypeScript 在很久以前就支持了旧的 Stage 2 装饰器提案，但直到 5.0 版本开始 TypeScript 内部引入了某项未知的修改，使得我们能够在 `TypedParameterDecorator` 中得到 `Target` 的具体类型。在 4.9 版本及以前，我们只能获得 `unknown`，无法实现对被装饰的属性进行类型检查。
250 |
251 | ### 提供具体的报错信息
252 |
253 | 在上面的代码中，当装饰器的类型检查不通过时的报错信息是：
254 |
255 | > Decorator function return type is 'boolean' but is expected to be 'void' or 'any'.
256 |
257 | 这样的报错信息非常原始，甚至会让用户感到费解。是否有一种办法可以告诉用户「你的类型标错了」呢？有的，而且这种方法算是比较常见的，当人们在使用类似的进阶类型技巧时用来提示用户的方法。
258 |
259 | ```typescript
260 | declare const ERROR: unique symbol;
261 | type MyTypeError = { [ERROR]: S };
262 |
263 | type DoCheck = IsEqual extends true
264 | ? void
265 | : MyTypeError<"Type of parameter is not equal to type of decorator">;
266 | ```
267 |
268 | 此时，我们得到的错误信息如下，变得清晰了很多：
269 |
270 | > Decorator function return type is 'MyTypeError<"Type of parameter is not equal to type of decorator">' but is expected to be 'void' or 'any'.
271 |
272 | 如果 TypeScript 能够帮帮忙，引入一种能够在 type 定义中被编译器检测的特殊类型作为报错信息的直接来源，我们还能得到更加直观的错误信息，例如：
273 |
274 | > The type of parameter is not equal to the type of decorator
275 |
276 | ### 关于新装饰器的讨论
277 |
278 | 对于从 5.0 版本开始支持的新装饰器提案来说，它并不支持装饰声明在构造函数中的类成员变量：
279 |
280 | ```typescript
281 | class Main {
282 | constructor(
283 | @Inject(...)
284 | private readonly foo: SomeService // Error: Decorators are not valid here.
285 | ) {}
286 | }
287 | ```
288 |
289 | 不过，我们可以选择另外一种形式，即装饰那些直接声明在类中的成员变量：
290 |
291 | ```typescript
292 | class Main {
293 | @Inject(...)
294 | private readonly foo: SomeService // OK
295 | }
296 | ```
297 |
298 | 对于新装饰器提案，TypeScript 仍然对装饰器的函数返回值类型存在约束，我们依然可以利用前面的技巧完成功能，且由于 TypeScript 为新装饰器提供的类型定义本身就包含了被装饰属性的类型，实现起来会更加简单。不过，由于篇幅限制这里不再赘述，感兴趣的读者可以自行实现。
299 |
300 | > 或许就是因为新装饰器能够获得被装饰的属性的具体类型，从 TypeScript 5.0 开始旧装饰器也跟着具备了上述的访问 `Target` 类型的能力。
301 |
302 | ## 类型安全的 Event Emitter
303 |
304 | Event Emitter 相信大家用的都很多了，我们接下来用 TypeScript 写一个「类型安全」的 Event Emitter。本节的重心在如何使用 TypeScript 的类型系统，所以不会提供具体的代码实现，也会省略 `off()` 函数。
305 |
306 | 我们先来编写一个简易的 Event Emitter 实现：
307 |
308 | ```typescript
309 | // 调用这个函数释放事件，可以通过 `args` 向监听器传递参数
310 | declare function emit(key: string, ...args: unknown[]): void;
311 |
312 | // 调用这个函数监听事件
313 | declare function on(key: string, handler: (...args: unknown[]) => void): void;
314 |
315 | // 省略 off
316 | ```
317 |
318 | ### 简易实现的问题
319 |
320 | 简易实现的这简简单单的几行代码，却存在着比有效行数更多的问题。我们接下来先分析这些问题，然后尝试使用多种方案解决上面的问题。方案的先后顺序不代表绝对的优劣，却或多或少地体现出我个人对它们的偏好（不同的方案总是有着不同的魅力……你应该懂的）。
321 |
322 | #### 参数类型匹配
323 |
324 | 如何确保释放事件的参数类型和监听事件的参数类型相匹配？例如，在下面的代码中：
325 |
326 | - 没有办法确保 `isReallyHungry` 参数确实存在且为 `boolean`
327 | - 如果调用了 `emit('I_AM_HUNGRY')` 却没有传递任何参数，我们不会在编译期得到任何报错
328 |
329 | ```typescript
330 | // 释放事件：
331 | emit("I_AM_HUNGRY", true);
332 |
333 | // 监听事件：
334 | on("I_AM_HUNGRY", (isReallyHungry) => {
335 | // ...
336 | });
337 | ```
338 |
339 | #### 事件名的正确性 & 冲突问题
340 |
341 | 如何确保监听事件传入的事件名正确？
342 |
343 | - 如果我们不小心将 `I_AM_HUNGRY` 拼成了 `I_AM_HUNGARY`，并不会得到任何编译报错
344 | - 如果释放事件经过修改之后，没有任何地方会发布 `I_AM_HUNGRY` 事件了，那么这个监听事件就失去了作用
345 |
346 | 目前的很多实践会通过手动定义并导出一些常量或枚举来让事件名常量化，但取决于具体的实现方式，它可能会带来额外的问题：不存在一种中心化的机制防止事件名冲突。
347 |
348 | #### 参数名称标注
349 |
350 | 在上面的例子中，我们发现事件提供的参数的名称是由事件的监听器定义的，这看上去是非常奇怪的。事件的定义，包括参数的名称应由释放事件一方负责，但碍于简易实现的问题没有办法做到这点。
351 |
352 | 参数名称的标注问题同样是危险的，因为一旦事件释放一方修改了参数的含义，使得它和现有的监听事件方不再一致，那么很可能导致一些出人意料且难以排查的运行时 bug。
353 |
354 | ### 解决方案
355 |
356 | ```typescript
357 | interface EventDefinitions {
358 | // 通过将事件声明收敛到同一个 interface，能够防止事件名冲突
359 | I_AM_HUNGRY: [isReallyHungry: boolean];
360 | }
361 |
362 | declare function emit(
363 | key: T,
364 | ...args: EventDefinitions[T]
365 | ): void;
366 |
367 | declare function on(
368 | key: T,
369 | handler: (...args: EventDefinitions[T]) => void
370 | ): void;
371 |
372 | // 🎉 正确地报错，没有提供足够的参数
373 | emit("I_AM_HUNGRY");
374 |
375 | // 🎉 输入逗号时，自动补全提示第二个参数叫「isReallyHungry」且类型为 boolean
376 | emit("I_AM_HUNGRY", true);
377 |
378 | // 🎉 输入逗号时，自动补全提示函数接收一个名为「isReallyHungry」且类型为 boolean 的参数
379 | on("I_AM_HUNGRY", (isReallyHungry) => {});
380 |
381 | // 🎉 正确地报错，没有这样的事件名
382 | on("I_AM_HUNGARY", () => {});
383 | ```
384 |
385 | 上述方案的要点如下：
386 |
387 | - 使用 `interface` 的属性名作为事件名，我们可以通过 `keyof` 取出它的属性名
388 | - 使用[具名元组](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#%E5%85%B7%E5%90%8D%E5%85%83%E7%BB%84%E5%85%83%E7%B4%A0labeled-tuple-elements40)定义参数列表。当在函数参数中使用具名元组作为 [Rest Parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) 的类型时，TypeScript 会自动使用元素的名称作为对应参数的名称
389 |
390 | 我们目前做到的功能已经和拥有着 9.6k 个 star 的 Event Emitter 库 [mitt](https://github.com/developit/mitt) 基本一样了，但是它还是存在下列缺点：
391 |
392 | 1. 如果要修改已有事件的名字，例如将 `I_AM_HUNGRY` 改为 `WO_E_LE`，TypeScript 不会自动修改使用了这个事件的 `emit` 和 `on` 调用中传入的字符串名称，这意味着你可能需要依赖全局搜索手动修改
393 | 2. 在大型项目中，维护一个中心化的 `interface` 定义可能是困难的，或者说有时会存在一些扩展需求，即在另外的源文件中定义特殊的事件
394 |
395 | ### 解决第一个缺点
396 |
397 | 对于第一个缺点，其实这是使用联合类型作为枚举时的「通病」，要解决这种通病可以尝试直接使用枚举。
398 |
399 | ```typescript
400 | enum EventKeys {
401 | I_AM_HUNGRY,
402 | }
403 |
404 | interface EventDefinitions {
405 | [EventKeys.I_AM_HUNGRY]: [isReallyHungry: boolean];
406 | }
407 |
408 | on(EventKeys.I_AM_HUNGRY, (isReallyHungry) => {});
409 | ```
410 |
411 | ### 解决第二个缺点
412 |
413 | 还记得我们在[模块扩充](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#%E6%A8%A1%E5%9D%97%E6%89%A9%E5%85%85module-augmentation)中的讨论吗？对于接口 `EventDefinitions`，可以在某个单独的源文件中定义一个空接口，然后在其它源文件中通过模块扩充来扩充它的定义，这样可以实现在不同的源文件中扩充同一个类型定义。
414 |
415 | 对于 `EventKeys` 来说，因为枚举定义涉及到值的定义，而模块扩充只能扩充类型定义，所以不能直接如法炮制。不过，你也许记得[常值枚举和模块扩充之间奇妙的化学反应](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#%E5%9C%A8%E6%A8%A1%E5%9D%97%E6%89%A9%E5%85%85%E4%B8%AD%E4%BD%BF%E7%94%A8)。我们可以将 `EventKeys` 声明为常值枚举来让它能够在模块扩充中使用，绕开了值定义的问题。
416 |
417 | ```typescript
418 | // registry.ts
419 | export const enum EventKeys {}
420 | export interface EventDefinitions {}
421 |
422 | // foo.ts，是 I_AM_HUNGRY 这个事件主要触发的地方，提供了事件的注册
423 | declare module "./registry" {
424 | export const enum EventKeys {
425 | I_AM_HUNGRY,
426 | }
427 |
428 | export interface EventDefinitions {
429 | [EventKeys.I_AM_HUNGRY]: [isReallyHungry: boolean];
430 | }
431 | }
432 |
433 | emit(EventKeys.I_AM_HUNGRY, ...);
434 | export {};
435 |
436 | // bar.ts
437 | import { EventKeys } from "./registry";
438 | // 并不需要导入 `foo.ts`，TypeScript 知道 I_AM_HUNGRY 来自 `foo.ts`
439 | on(EventKeys.I_AM_HUNGRY, (isReallyHungry) => {});
440 | ```
441 |
442 | - 在 `EventKeys` 枚举中定义的事件的键仍然可以避免重复的键
443 |
444 | TypeScript 能够检查是否存在重复的键，即使它们是通过模块扩充声明的
445 |
446 | - 在 `EventDefinitions` 接口中定义的事件的参数仍然可以避免重复的键
447 |
448 | TypeScript 不允许定义另一个 `[EventKeys.I_AM_HUNGRY]: X`，其中 `X` 为 `[boolean]` 以外的类型
449 |
450 | - 还可以将上面的 `registry.ts` 通过 tsconfig.json 中的配置赋予一些特殊的路径名，例如 `@registry`，这样可以让各个源文件都能通过方便的方式引用到这个文件
451 |
452 | > [!WARNING]
453 | > 不建议将 `registry.ts` 或者任何常值枚举通过共享库的方式发布，换句话说上述技巧只推荐在一些终端应用（不会被其它包依赖）中使用。参见[前文的讨论](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#%E4%B8%8D%E6%8E%A8%E8%8D%90%E5%9C%A8%E5%85%B1%E4%BA%AB%E5%BA%93%E4%B8%AD%E4%BD%BF%E7%94%A8)。
454 |
455 | > [!WARNING]
456 | > 常值枚举以及关于它的模块扩充是一个极为复杂的功能，对于除了 tsc 以外的 TypeScript 编译器（例如 swc、esbuild、babel 等）来说它们很可能不会提供「正确」的输出，如果你想要在生产环境中接入这里的解决方案，请务必事先确认自己使用的编译工具链是否能输出正确的结果。参见[前文的讨论](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#%E5%9C%A8%E6%A8%A1%E5%9D%97%E6%89%A9%E5%85%85%E4%B8%AD%E4%BD%BF%E7%94%A8)。
457 |
458 | ## 类型安全的文案注册
459 |
460 | 某个 Web App 的文案定义在 `.ts` 文件中，具有下面的形式：
461 |
462 | ```typescript
463 | const i18n = {
464 | "en-US": {
465 | "page.login.login_button": "Login",
466 | "page.login.forgot_password": "Forgot Password?",
467 | "page.login.users_online": "{count} users online",
468 | },
469 | "zh-CN": {
470 | "page.login.login_button": "登录", // 不要打错成「登陆」了哦，太多人被苹果输入法坑害了
471 | "page.login.forgot_password": "忘记密码？",
472 | "page.login.users_online": "{count} 位会员在线",
473 | },
474 | };
475 | ```
476 |
477 | 请尝试为 `i18n` 对象字面量提供类型检查能力：
478 |
479 | 1. 键只能为 `'en-US'` 或 `'zh-CN'`，其它语言还没做，因为没钱
480 | 2. 每个值对应的对象的键必须一致，换句话说每个语言必须拥有相同的文案种类，防止缺漏
481 | 3. 对应的文案的翻译必须引用相同的插值，比如英文中的 `page.login.users_online` 的值里引用了一个 `{count}` 插值，那么中文里的 `page.login.users_online` 的值里也必须引用这个插值，反之亦然
482 |
483 | ```typescript
484 | type Resource = {
485 | [K in keyof T]: {
486 | [M in keyof T[K]]: T[K][M];
487 | };
488 | };
489 |
490 | function defineResource(resource: Resource) {
491 | return resource;
492 | }
493 | ```
494 |
495 | 接下来我们分别实现三个能力，最后再将它们合并到一起。不过在此之前，先来介绍一下本节会反复使用的一个工具类型：`IsEqual`。我们会使用它来检查两个类型是否相等。它有些像三目表达式，不过我们为 true 分支和两个 false 分支都提供了默认值。
496 |
497 | ```typescript
498 | type IsEqual = [A] extends [B]
499 | ? [B] extends [A]
500 | ? T
501 | : F2
502 | : F1;
503 | ```
504 |
505 | 我们还有下面的工具类型，其中的 `I18nError` 就是一个用于承载报错信息的名义类型。
506 |
507 | ```typescript
508 | type Pass = unknown;
509 |
510 | type I18n = Record>;
511 |
512 | declare const ERROR_SYMBOL: unique symbol;
513 | interface I18nError {
514 | [ERROR_SYMBOL]: T;
515 | }
516 | ```
517 |
518 | 本节的完整的代码可以在 [TypeScript Playground](https://www.typescriptlang.org/play?ts=5.2.2&q=483#code/C4TwDgpgBACghgZwVAvFArgOwNaYPYDumA3AFCmiRQCSAjAByapQBKEAxngE4AmAPAmBcAlpgDmAGlYdu-QSPFT5osQD5VZUjw4AbOF2idMgqAFEWLAPIsA+gGUAmgFkAQpYAyALgyZhAR3RoBBAAWwAjPB1NUWAILgAzOHZoOkZTLi5uPgAVKAgAD1jMHmRlcVUoAG9SKCgAbXMrW0dXDwBdb2yyAF9yShSEUwC4HT4AQSkXKVy0CagAMVpmKYWAJmZFirQ6sba8wohi5DqXNpqoAH560-2ikvrd89qr7Keob3nV84-aTX6oADCAAsONh3HBxOg4GIIAgcrdDvdUpgtjRBsNRudsBAQHh4lBshJzgAiQ4AWgAqnZiVAAD5QYkALyBZIBADliUTavAkFyaAxMOlMlw+MTsng8FAQhCQFA9JDodBtPFRMJgMI8MZiao+cihVliU5hEgVHKIWIoTCoMrVerNQhtaQNH1wNAAOIQYBjHQ6bJcCEIPR2zAAaRxcNyBTuyGRqOqtTqIagoig2Nx+OyHVTOLxBMTbR6dTTuczf1dgJB7GwfoDQY1ofDfHOkYOR35jD5YwRbbKYmYHq9PprxjrmrDIAjFQAZFBe3yk2hi-j47V6kmU0uCVBEGihlDRpvsvmpHNMBAAG5xKQh1RZs+XrhkWq9VHUdH7pu1EN8+9X848hBdQFfURQAAyNE1xGzCcoHibgzQVK0AHIABJKiTGde26JDQNUJ0yyoNgEEiS9qEwWIuDASI4GDOFm27e453OIiGNKIRTTQX8uCdZgW2jKBQLQrDKjQ0R4jiKBx26bpRMwcSuGkQRulA84riIkiIDIiiqNHYw+CI4ApBY+lxzw2pvCIgjoGBUEtLiHSaPrCMpHcVjZ3YxQoAANTc3tUU3FdE2TJhD23GN3xGT9VyPEM2jqVyZ0PfM2j5Wp1J0UjyPs6jaL4LydTeLjUsk85b28LieisitQWHQNHM1LyRkCOjaj4xEYwFPkKWYFcE3XEKcwzLNetXOonGC6CS2SizYQ0uzKJypycnzMa2mdVcoG6J9Nr5Hy0BGoKN0GglhreBNxqO9M81irMbKreaHNyikpHGzCPMka64qcNbtufbaX2YN890i84ivOA7+sm-EvNOjbzomzcvOm3cMSiuHvJW77io2sH0dqXG8b1DIslAsjrQgFVfGDKBc1Q9CoDehQxGwqQhFreqmAINUgWgqA6des64awpDrTwWEoHwYBZyBfRoGAEFZzgEJoBibLdOQLn5ageWaJp-E6aR2LVoZwWNuF3DBfW1duiLY7DbaAtzhtxGUvOLBcEITB8JdKgABE8Du7AIzc2NAYizFuUQQDzkD8FENhHICtqIHUbeADisD2rdPHSdipTj90+qqss45xqdGaxOzKgPDnVIeIsHYambTPdT0C4ZI+CMEw2rbWMAApzgMYi2+SbwIYR47MzHqAyQMOAeE1HRZTGierpih3OkxvYtqdhmoH9wPJ1IABKKpB89NumCHvAR4gHpyC7qXhAFZhm4gVv24gPuV1JTBKWpMebxiRgEVAAOh0HgMQohwGQNEDYMI6BgDAE1MSbwxJ3CwMwJyIBICYQwKgZgUBcEuBiDwMAGwICkAEFkKghk8xuCkKlgBahvALjYI2sAsBECCGgPQAgOICAbCL1EBAWhxJKicCwMAboGB+FcGQMIs87CdokmZKyDkgCOG4IgPg6B3C4EIKQSgtBgBvN0AKr6yjaicLwfowhxDGEUKjiwngYjAAb+oABujABj2oAQA9AD4-5Yhk2jdGEL4QIoRmAdAiLERIm+5EZGAFl5QAWPKAA0VQAFOqAH6-ZR3QiTdGPmQIAA) 中看到。
519 |
520 | ### 检查对象的键
521 |
522 | 检查对象是否仅含 `en-US` 和 `zh-CN` 两个键是平凡的，只需要让它们和 `keyof T` 进行比较即可。不过，由于 `keyof T` 会返回联合类型，为了绕过[分配式联合类型](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter3.md#%E5%88%86%E9%85%8D%E5%BC%8F%E6%9D%A1%E4%BB%B6%E7%B1%BB%E5%9E%8Bdistributive-conditional-types)特性，我们用方括号将比较双方包围，这样比较的就是元组类型而不是联合类型（`IsEqual` 内部已经做了这件事情）。
523 |
524 | ```typescript
525 | type CheckLanguages = IsEqual<
526 | keyof T,
527 | "en-US" | "zh-CN",
528 | Pass, // T
529 | I18nError<"Too many language definitions">, // F1
530 | I18nError<"Missing language definitions"> // F2
531 | >;
532 | ```
533 |
534 | ### 检查是否具有相同的文案种类
535 |
536 | 这里使用一个简单的实现思路：将各个语言对应的对象的所有键（也就是文案）表示为联合类型，然后将这些联合类型合并在一起得到一个大的联合类型，最后检查每个语言对应的对象的键构成的联合类型是否等于这个联合类型。
537 |
538 | > 这里的联合类型充当了 Set 的作用，即：可自动去重的元组类型。特别地，`never` 表示「空状态」。
539 |
540 | ```typescript
541 | type GetAllTranslationKeys = {
542 | // 获得 I18n 对象里各个语言对应的对象有哪些键（用联合类型表示）
543 | [K in keyof T]: keyof T[K];
544 | }[keyof T]; // 使用 IIMT 将对象的值合并在一起得到大的联合类型
545 |
546 | type CheckTranslationKeys<
547 | T extends I18n,
548 | // 这种用法类似于命令式编程里在函数体中声明的本地变量
549 | A extends string = GetAllTranslationKeys & string,
550 | K = keyof {
551 | // 使用映射类型中键的重映射，检查每个语言的对象里的键是否等于上面的 A
552 | // 如果等于，返回 never，这会使得这个键不会出现在构造出来的映射类型中
553 | // 否则，返回 K 本身，让它出现在映射类型里，通过第 10 行的 keyof 收集出来
554 | [K in keyof T as IsEqual]: never;
555 | }
556 | > = IsEqual<
557 | // 检查我们找到的有问题的键 K（联合类型）是否为空（never）
558 | K,
559 | never,
560 | Pass,
561 | // 当 K 不为空时，会返回这个报错类型，我们实际上可以将 K 嵌入到报错信息里
562 | I18nError<`Missing keys for language '${K & string}'`>
563 | >;
564 | ```
565 |
566 | ### 检查文案的翻译是否引用相同的插值
567 |
568 | 给定一个字符串字面量类型，提取出它格式为 `{key}` 的插值并表示为联合类型是简单的。具体的代码如下所示，注意到我们仍然使用了联合类型去充当 Set 的作用，它一方面用来存储找到的插值，另一方面可以自动去重。
569 |
570 | ```typescript
571 | type ResolveInterpolations<
572 | T extends string,
573 | Res extends string = never
574 | > = T extends `${string}{${infer Key}}${infer Rest}`
575 | ? ResolveInterpolations
576 | : Res;
577 | ```
578 |
579 | 假如我们通过上面的类型，得到了文案对象里面各个文案字符串使用了哪些插值，就像下面的类型：
580 |
581 | ```typescript
582 | type T = {
583 | "en-US": {
584 | "page.login.login_button": never;
585 | "page.login.forgot_password": never;
586 | "page.login.users_online": "count";
587 | };
588 | "zh-CN": {
589 | "page.login.login_button": never;
590 | "page.login.forgot_password": never;
591 | "page.login.users_online": "count" | "test";
592 | };
593 | };
594 | ```
595 |
596 | 假如我们现在在检查某个文案，它的键为 `L`，值为 `V`。如何结合上面的信息检查它是否使用了和其它语言的对应文案完全相同的插值呢？下面的代码实现了这一点。
597 |
598 | ```typescript
599 | // 注意第二行末尾的 keyof 哦，它实际上返回了「哪些语言的对应文案，使用的插值不一样」
600 | type CheckInterpolations = keyof {
601 | [K in keyof T as IsEqual<
602 | // 检查各个语言中的对应文案（即键同样为 `L` 的属性）使用的插值
603 | T[K][L & keyof T[K]],
604 | // 当前文案使用了哪些插值
605 | ResolveInterpolations,
606 | // 两类型相等时，返回 never 让 TypeScript 去掉这个属性
607 | never,
608 | // 否则，将 K 作为这个属性的键，也就是语言
609 | K
610 | >]: never;
611 | };
612 | ```
613 |
614 | 下面是完成功能的主体代码：
615 |
616 | - `U` 作为「局部变量」存储了从 `ResolveInterpolations` 得到的信息：各个语言的各个文案使用了哪些插值，用联合类型表示
617 | - `V` 作为另一个「局部变量」存储了从 `CheckInterpolations` 得到的信息：各个语言的各个文案，使用了和哪些语言的对应文案不同的插值，为 `never` 时表示「没有，都一样！」
618 | - 从第十三行开始，我们检查 `V` 的各个值是否为 `never`，也即「是否存在有问题的文案值」。注意我们这里是如何利用对应的泛型参数构造信息量充足的报错信息的。这里还使用了两层嵌套的 [IIMT](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#immediately-indexed-mapped-typeiimt)，用来将可能存在的 `I18nError` 提取出来作为联合类型。
619 | - 当然，如果整个文案对象都没有错误，它会返回 `never`，通过 `IsEqual` 的判断最终返回 `unknown`。
620 |
621 | ```typescript
622 | type CheckTranslationValues<
623 | T extends I18n,
624 | U = {
625 | [K in keyof T]: {
626 | [M in keyof T[K]]: ResolveInterpolations;
627 | };
628 | },
629 | V = {
630 | [K in keyof T]: {
631 | [M in keyof T[K]]: CheckInterpolations;
632 | };
633 | }
634 | > = IsEqual<
635 | never,
636 | {
637 | [K in keyof V]: {
638 | [M in keyof V[K]]: IsEqual<
639 | V[K][M],
640 | never,
641 | never,
642 | I18nError<`In definition of '${K & string}', translation with key '${M &
643 | string}' does not share the same interpolations with that of '${V[K][M] &
644 | string}'`>
645 | >;
646 | }[keyof V[K]];
647 | }[keyof V],
648 | unknown
649 | >;
650 | ```
651 |
652 | ### 将三种检查串在一起
653 |
654 | 为了防止三种检查相互干扰，我们通过条件类型来先后执行这三种检查。如果前面的检查失败，后面的检查就不会执行。请看下面的代码：
655 |
656 | ```typescript
657 | type DoChecks = IsEqual<
658 | Pass,
659 | CheckLanguages,
660 | IsEqual<
661 | Pass,
662 | CheckTranslationKeys,
663 | IsEqual>
664 | >
665 | >;
666 | ```
667 |
668 | 函数 `defineResource` 的代码如下所示，注意：
669 |
670 | - 使用 `const T` 是为了让 TypeScript 推导输入对象的类型时，将内含的字符串类型推导为字面量类型
671 | - 使用第 3 行的映射类型，而不是 `Record>` 是为了[提供更强的 contextual types](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter3.md#type-parameter-inference)，让 TypeScript 顺利推导出文案对象这种复杂对象结构的字面量类型。这里的做法是通过经验试出来的。
672 | - `-readonly` 是为了去掉 `const T` 为属性附加的 `readonly` 修饰符。
673 |
674 | ```typescript
675 | function defineResource(
676 | resource: {
677 | [K in keyof T]: { -readonly [M in keyof T[K]]: T[K][M] };
678 | } & DoChecks
679 | ) {
680 | return resource;
681 | }
682 | ```
683 |
684 | ### 效果展示
685 |
686 | 本节的完整的代码可以在 [TypeScript Playground](https://www.typescriptlang.org/play?ts=5.2.2&q=483#code/C4TwDgpgBACghgZwVAvFArgOwNaYPYDumA3AFCmiRQCSAjAByapQBKEAxngE4AmAPAmBcAlpgDmAGlYdu-QSPFT5osQD5VZUjw4AbOF2idMgqAFEWLAPIsA+gGUAmgFkAQpYAyALgyZhAR3RoBBAAWwAjPB1NUWAILgAzOHZoOkZTLi5uPgAVKAgAD1jMHmRlcVUoAG9SKCgAbXMrW0dXDwBdb2yyAF9yShSEUwC4HT4AQSkXKVy0CagAMVpmKYWAJmZFirQ6sba8wohi5DqXNpqoAH560-2ikvrd89qr7Keob3nV84-aTX6oADCAAsONh3HBxOg4GIIAgcrdDvdUpgtjRBsNRudsBAQHh4lBshJzgAiQ4AWgAqnZiVAAD5QYkALyBZIBADliUTavAkFyaAxMOlMlw+MTsng8FAQhCQFA9JDodBtPFRMJgMI8MZiao+cihVliU5hEgVHKIWIoTCoMrVerNQhtaQNH1wNAAOIQYBjHQ6bJcCEIPR2zAAaRxcNyBTuyGRqOqtTqIagoig2Nx+OyHVTOLxBMTbR6dTTuczf1dgJB7GwfoDQY1ofDfHOkYOR35jD5YwRbbKYmYHq9PprxjrmrDIAjFQAZFBe3yk2hi-j47V6kmU0uCVBEGihlDRpvsvmpHNMBAAG5xKQh1RZs+XrhkWq9VHUdH7pu1EN8+9X848hBdQFfURQAAyNE1xGzCcoHibgzQVK0AHIABJKiTGde26JDQNUJ0yyoNgEEiS9qEwWIuDASI4GDOFm27e453OIiGNKIRTTQX8uCdZgW2jKBQLQrDKjQ0R4jiKBx26bpRMwcSuGkQRulA84riIkiIDIiiqNHYw+CI4ApBY+lxzw2pvCIgjoGBUEtLiHSaPrCMpHcVjZ3YxQoAANTc3tUU3FdE2TJhD23GN3xGT9VyPEM2jqVyZ0PfM2j5Wp1J0UjyPs6jaL4LydTeLjUsk85b28LieisitQWHQNHM1LyRkCOjaj4xEYwFPkKWYFcE3XEKcwzLNetXOonGC6CS2SizYQ0uzKJypycnzMa2mdVcoG6J9Nr5Hy0BGoKN0GglhreBNxqO9M81irMbKreaHNyikpHGzCPMka64qcNbtufbaX2YN890i84ivOA7+sm-EvNOjbzomzcvOm3cMSiuHvJW77io2sH0dqXG8b1DIslAsjrQgFVfGDKBc1Q9CoDehQxGwqQhFreqmAINUgWgqA6des64awpDrTwWEoHwYBZyBfRoGAEFZzgEJoBibLdOQLn5ageWaJp-E6aR2LVoZwWNuF3DBfW1duiLY7DbaAtzhtxGUvOLBcEITB8JdKgABE8Du7AIzc2NAYizFuUQQDzkD8FENhHICtqIHUbeADisD2rdPHSdipTj90+qqss45xqdGaxOzKgPDnVIeIsHYambTPdT0C4ZI+CMEw2rbWMAApzgMYi2+SbwIYR47MzHqAyQMOAeE1HRZTGierpih3OkxvYtqdhmoH9wPJ1IABKKpB89NumCHvAR4gHpyC7qXhAFZhm4gVv24gPuV1JTBKWpMebxiRgEVAAOh0HgMQohwGQNEDYMI6BgDAE1MSbwxJ3CwMwJyIBICYQwKgZgUBcEuBiDwMAGwICkAEFkKghk8xuCkKlgBahvALjYI2sAsBECCGgPQAgOICAbCL1EBAWhxJKicCwMAboGB+FcGQMIs87CdokmZKyDkgCOG4IgPg6B3C4EIKQSgtBgBvN0AKr6yjaicLwfowhxDGEUKjiwngYjAAb+oABujABj2oAQA9AD4-5Yhk2jdGEL4QIoRmAdAiLERIm+5EZGAFl5QAWPKAA0VQAFOqAH6-ZR3QiTdGPmQIAA) 中找到。下面的视频展示了最终的效果。
687 |
688 |
689 | 
690 |
691 |
692 | > 我们其实可以做得更好，可以考虑改进报错的粒度以及报错信息里的提示。
693 |
694 | ## 端到端类型安全（End-to-End Type-Safety）
695 |
696 | Web 前端界每隔一段时间就会出现一些爆款，感觉很多都有不少的水分，不过其中的 [tRPC](https://trpc.io/) 库却让人眼前一亮。这个库宣称自己为 API 调用提供了「端到端」的类型安全支持。可能就是这个库提出或者发扬了「端到端的类型安全」这个概念，以至于后续出现的很多新的服务端框架都提供了这种功能。
697 |
698 |
699 | 
700 |
701 |
702 | 虽然文档中似乎没有解释这个概念具体是什么意思，不过我暂且假定它指的是这种能力：服务端源文件的路由的类型定义（包括具体的请求体类型和响应体类型）可以直接传播到客户端的源文件中。
703 |
704 | 这种功能是怎么实现的？为了探究问题的答案，本节会研究一个形式较为简单的「端到端类型安全」的实现：[ElysiaJS](https://elysiajs.com/)，它是一款新式的服务端框架，主要服务于 [Bun](https://bun.sh/)（一个爆款 JavaScript 运行时）。ElysiaJS 提供了下面例子的端到端类型安全功能（这个功能需要安装它的一个名为 [Eden](https://elysiajs.com/plugins/eden/overview.html) 的插件……唔，熟悉的名字）。
705 |
706 | 先来看看服务端的源文件 `server.ts`：
707 |
708 | ```TypeScript
709 | import { Elysia, t } from "elysia";
710 |
711 | const app = new Elysia()
712 | // 这个端点响应体是一个字符串，来自给定的 id
713 | .get("/id/:id", ({ params: { id } }) => id)
714 | // 这个端点响应体是一个 JSON 对象，来自请求体
715 | .post("/json", ({ body }) => body, {
716 | // 对请求体的类型验证
717 | body: t.Object({
718 | name: t.String(),
719 | }),
720 | })
721 | .listen(3000);
722 |
723 | export type App = typeof app;
724 | ```
725 |
726 | 再来看看在客户端中，我们能得到怎么样的「端到端类型安全」。注意下面三处高亮标记的地方。
727 |
728 | ```TypeScript
729 | import { edenTreaty } from "@elysiajs/eden";
730 | import type { App } from "./server";
731 |
732 | const api = edenTreaty("http://0.0.0.0:8080");
733 |
734 | // 这是 Elysia 调用它的服务端的特殊方式，下面等价于 GET /id/seele 请求
735 | const _0 = await api.id.seele.get();
736 | // 它的返回值类型等于下面的 T0
737 | type T0 = (
738 | | { // Elysia 成功地根据 server.ts 第 6 行的函数返回值推导出了响应体类型
739 | data: string;
740 | error: null;
741 | }
742 | | { // 客户端请求错误时的响应体，在这个例子是固定的
743 | data: null;
744 | error: EdenFetchError;
745 | }
746 | ) & { // 响应体的公共属性，在这个例子是固定的
747 | status: number;
748 | response: Response;
749 | headers: Record;
750 | };
751 |
752 | const _1 = await api.json.post({ name: "saltyaom" });
753 | // 它的返回值类型等于下面的 T1
754 | type T1 = (
755 | | { // 看！它又推导出正确的响应体类型了
756 | data: {
757 | name: string;
758 | };
759 | error: null;
760 | }
761 | | { // 客户端请求错误时的响应体，在这个例子是固定的
762 | data: null;
763 | error: EdenFetchError;
764 | }
765 | ) & { // 响应体的公共属性，在这个例子是固定的
766 | status: number;
767 | response: Response;
768 | headers: Record;
769 | };
770 |
771 |
772 | api.json.post({
773 | // TypeScript 正确地报错，因为 server.ts 第 10 行说 name 应该是个字符串
774 | name: 1,
775 | });
776 | ```
777 |
778 | 由于篇幅原因，我们这里只简单地研究它的 `get` 函数是如何实现的并解答下面的问题：
779 |
780 | > 在 `server.ts` 中的代码是 `get("/id/:id", ({ params: { id } }) => id)`
781 |
782 | - 为什么它可以推导出 `params` 中存在一个 `id` 字符串类型？
783 | - 为什么处理函数的返回值类型 `string` 可以被客户端知道？
784 |
785 | 解决了这些问题之后再阅读其它函数的实现不是一件困难的事情（我相信能坚持读到这里的你一定有足够的能力……），而且对于端到端类型安全的原理分析，如果要「认真地」写，恐怕又会需要写出一篇万字长文。
786 |
787 | 在开始研究源码之前，我们先说结论：它的原理是对函数泛型的巧妙利用，尤其是前文讨论的[各种匹配方法](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter3.md#%E5%B8%B8%E7%94%A8%E7%9A%84%E5%8C%B9%E9%85%8D%E6%96%B9%E6%B3%95)和[函数类型闭包](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter3.md#%E5%87%BD%E6%95%B0%E7%B1%BB%E5%9E%8B%E9%97%AD%E5%8C%85)。简化后的 `get` 函数源码如下所示（只需要关心高亮的代码）。
788 |
789 | - `Elysia` 本身就是一个带有泛型参数的类，它携带了包括路由信息 `Routes` 在内的类型闭包
790 | - 每次调用 `get` 函数之后得到的返回值是一个被扩充了类型信息之后的 `Elysia` 类型，具体被扩充了什么类型信息可以看下面的代码，对于 `get` 函数来说只需要扩充 `Routes` 的定义
791 | - `Routes` 定义中，当前路由的响应体类型在我们的例子中由第 28 行的 `ReturnType` 得到
792 | - 因此，`client.ts` 之所以能得到每个请求的请求体类型、响应体类型的类型信息，就是因为包括 `Routes` 在内的类型信息被通过类型闭包（`export type App = typeof app`）传递到了 `client.ts` 中
793 | - `Function` 具体是如何推导出来的？请看后文！
794 |
795 | ```TypeScript
796 | // ⚠️ 省略了很多类型参数以及其它内容，具体以源码为准！
797 | class Elysia<
798 | BasePath extends string = '',
799 | Routes extends RouteBase = {},
800 | >{
801 | get<
802 | const Path extends string,
803 | const Route extends MergeSchema< // 省略了 LocalSchema 的定义
804 | UnwrapRoute,
805 | ParentSchema
806 | >,
807 | const Function extends Handler
808 | >(
809 | path: Path,
810 | handler: Function
811 | ): Elysia<
812 | BasePath,
813 | // 👇 通过交叉类型将新构造的对象类型扩充到 Routes 里
814 | Routes & {
815 | // 👇 映射类型，意思是「构造一个对象类型，它具有一个键为这个的属性」
816 | [path in `${BasePath}${Path}`]: {
817 | get: {
818 | body: Route["body"];
819 | params: Route["params"];
820 | query: Route["query"];
821 | headers: Route["headers"];
822 | response: unknown extends Route["response"]
823 | ? { 200: ReturnType } // 👈 处理函数的返回值类型通过这种方式保存了下来
824 | : Route["response"] extends { 200: any }
825 | ? Route["response"]
826 | : { 200: Route["response"] };
827 | };
828 | };
829 | }
830 | > {
831 | // 本函数在运行时中的实现是很简单的
832 | this.add("GET", path, handler as any, hook);
833 | // 让它通过 TypeScript 的类型检查，库作者会确保扩充的 Elysia 类型定义不会造成运行时错误
834 | return this as any;
835 | }
836 | }
837 | ```
838 |
839 | 我们来看看 `Function` 类型依靠的 `Handler` 类型的定义：
840 |
841 | ```TypeScript
842 | export type Handler<
843 | Route extends RouteSchema = {},
844 | Path extends string = ''
845 | > = (context: Context) => // 注意，这个类型是个函数类型
846 | Route['response'] extends { 200: unknown }
847 | ? Response | MaybePromise
848 | : Response | MaybePromise
849 | ```
850 |
851 | 从这里可以看出来，`Context` 类型应该是一个对象类型，`id` 应该是它根据 `Path` 字符串类型推导出来的。
852 |
853 | ```TypeScript
854 | export type Context<
855 | Route extends RouteSchema = RouteSchema,
856 | Decorators extends DecoratorBase = {
857 | request: {}
858 | store: {}
859 | },
860 | Path extends string = ''
861 | > = {
862 | // 👇 看！这里发生了和前文类型安全的路由器类似的字符串解析过程
863 | params: undefined extends Route['params']
864 | ? Path extends `${string}/${':' | '*'}${string}`
865 | ? Record, string>
866 | : never
867 | : Route['params']
868 | // ... 省略其它属性
869 | } & Decorators['request']
870 | ```
871 |
872 | 至于 `Handler` 返回的函数类型的返回值，它定义中的返回值类型是用来做类型检查的，如果我们使用了其它 Elysia 的 API，那么这些 API 可能会限制处理函数能够返回的值的类型。
873 |
874 | ---
875 |
876 | | **上一章** | **目录** | **下一章** |
877 | | :------------- | :----------: | :------: |
878 | | [第三章：类型编程](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter3.md) | [你可能不知道的 TypeScript](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript#%E4%BD%A0%E5%8F%AF%E8%83%BD%E4%B8%8D%E7%9F%A5%E9%81%93%E7%9A%84-typescript) | [第五章：探索之路](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter5.md) |
879 |
--------------------------------------------------------------------------------
/chapter5.md:
--------------------------------------------------------------------------------
1 | | **上一章** | **目录** |
2 | | :------------- | :----------: |
3 | | [第四章：生产实践](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter4.md) | [你可能不知道的 TypeScript](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript#%E4%BD%A0%E5%8F%AF%E8%83%BD%E4%B8%8D%E7%9F%A5%E9%81%93%E7%9A%84-typescript) |
4 |
5 | ---
6 |
7 | # 第五章：探索之路
8 |
9 | 本章节将介绍一些和 TypeScript 相关的资料、书籍和类型库，希望能够帮助你继续在 TypeScript 的道路上探索下去。
10 |
11 | ## 资料
12 |
13 | ### [type-challenges](https://github.com/type-challenges/type-challenges)
14 |
15 | 收集了一系列难度从简单到极难的 TypeScript 类型谜题。曾经是 [antfu](https://github.com/antfu) 的个人仓库，可能就是因为这个仓库，前端界把钻研 TypeScript 各种类型技巧的行为称为「类型体操」。本文开头说的「体操家」的出处就是这里。
16 |
17 | ### [FAQs](https://github.com/microsoft/TypeScript/wiki/FAQ)
18 |
19 | TypeScript 仓库的 Wiki 里提供的 FAQ 列表，介绍了和 TypeScript 有关的一些基本概念，以及解答了许多常见的疑难杂症。
20 |
21 | ### [How the TypeScript Compiler Compiles](https://www.youtube.com/watch?v=X8k_4tZ16qU&list=PLYUbsZda9oHu-EiIdekbAzNO0-pUM5Iqj&index=5)
22 |
23 | TypeScript 前开发者 Orta Therox 的一个关于 TypeScript 编译器实现细节的简短介绍，重心放在了类型检查的部分。不过内容比较浅薄，只能提供一种宏观视角。
24 |
25 | ### [TypeScript-Compiler-Notes](https://github.com/microsoft/TypeScript-Compiler-Notes)
26 |
27 | 关于 TypeScript 源码的笔记：
28 |
29 | - 编译器，特别是类型检查部分的一些概念的介绍、原理的解释
30 | - 语言服务的部分介绍
31 | - 源码调试技巧、开发流程介绍
32 |
33 | > Fun fact：我们在使用 TypeScript 的过程中遇到的绝大多数类型报错都来自一个名为 `checker.ts` 的源文件提供的类型检查能力。截至 2023 年 10 月 15 日，这个源文件有 50463 行！
34 |
35 | 阅读 TypeScript 的源码可能不是简单的，因为它涉及了太多、太复杂的概念（请思考这个事实：TypeScript 的历史已经超过了 13 年）。一种效率较高的「理解 TypeScript 如何工作」的方式可能是：
36 |
37 | 1. 将源码克隆下来
38 | 2. 运行 `npm install` 和 `npm run build:compiler`
39 | 3. 使用[笔记里的调试配置](https://github.com/microsoft/TypeScript-Compiler-Notes/blob/main/systems/debugging/settings.md#hard-coded-file)，在随便什么地方建一个 `.ts` 文件，将路径填到配置里
40 | 4. 在源码中设置断点，然后运行调试
41 | 5. 一步一步、反反复复地看你感兴趣的过程
42 |
43 | ### [TypeScript Origins: The Documentary](https://www.youtube.com/watch?v=U6s2pdxebSo)
44 |
45 | TypeScript 的纪录片，比较有看点的地方：
46 |
47 | - TypeScript 的起源，为什么会做这个东西
48 | - 微软对开源的态度是如何从 TypeScript 开始发生变化的
49 | - TypeScript 的发展过程中比较重要的一些时间节点，比如 Angular 2 的接入
50 |
51 | ## 书籍
52 |
53 | 关于 TypeScript 的书籍，我能找到的似乎都是一些内容偏向基础的书籍。它们讨论的内容并不会像本文那样深入（或者说硬核），也许是因为这些知识不太成体系，并且大多属于经验之谈（尽管有一定的源码和文档支撑）。
54 |
55 | | **Effective TypeScript** | **Learning TypeScript** |
56 | | :------------- | :---------- |
57 | | 
提供了 62 种改善 TypeScript 使用技巧的方式，让你摆脱一些关于 TypeScript 的常见误用。书中还讨论了 TypeScript 的许多并没有在文档中介绍得清楚的机制，例如 Type Narrowing 和 Type Widening，帮助你理清 TypeScript 的一些设计原则和机制细节。
总的来说，这是一本在闲暇之余可以读读看的好书。
注意：此书第一版发布于 2019 年底，至今已经接近 4 年，在这个过程中 TypeScript 已经发生了很多新的改变。书中讨论的一些问题已经有了更好、更现代的解法，可以参考本文章来形成互补。 | 
补充 TypeScript 基础知识的好书，涵盖了很多 TypeScript 官方文档没有涉及或讲得不多的内容，尤其是其中的：- 关于泛型的各种机制的介绍
- 对 declaration files（声明文件，即 d.ts 文件）的介绍
- 对 TypeScript 的配置项（特别是 tsconfig）的介绍
本书的发布日期非常新，于 2022 年 7 月发行第二版，可以说是目前入门 TypeScript 的首选好书。 |
58 |
59 | ## 类型库
60 |
61 | 下面是一些能够帮助我们编写类型的工具库，注意这些库提供的 API 大多数都是 TypeScript 类型，所以并不会出现在编译产物中，也不会增加包体积。除了使用上的价值外，这些类型库还有学习上的价值，当我们对 TypeScript 的某个类型或功能不了解时，可以查看这些库的源码实现，从中获取思路。
62 |
63 | ### [ts-typesafe-decorators](https://github.com/sorgloomer/ts-typesafe-decorators)
64 |
65 | 为旧的 Stage 2 装饰器提供类型检查的工具类型库，本文在生产实践中[类型安全的装饰器](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter4.md#%E7%B1%BB%E5%9E%8B%E5%AE%89%E5%85%A8%E7%9A%84%E8%A3%85%E9%A5%B0%E5%99%A8-50)一节就是受到了这个库的启发。它同样依赖于 TypeScript 5.0 或以上版本，所以又多了一个理由升级 TypeScript。
66 |
67 | ### [ts-essentials](https://github.com/ts-essentials/ts-essentials)
68 |
69 | 提供一些 TypeScript 没有自带但是很有用的工具类型。例如：
70 |
71 | - `XOR`
72 | - 构造一个只能被赋给 `Type1` 或 `Type2` 的类型，但它不会同时可以被赋给两个类型
73 | - `MarkWritable`
74 | - 取消给定对象类型中给定属性的 `readonly` 标识
75 |
76 | ### [ts-pattern](https://github.com/gvergnaud/ts-pattern)
77 |
78 | 用于对复杂联合类型进行匹配的类型库，下面的例子来自它的 README。
79 |
80 | - 注意它是如何利用[函数类型闭包](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter3.md#%E5%87%BD%E6%95%B0%E7%B1%BB%E5%9E%8B%E9%97%AD%E5%8C%85)提供丰富的类型功能的
81 | - 它的 `exhaustive()` 提供了和本文的 [Exhaustive Guard](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter2.md#exhaustive-guardexhaustive-check) 类似的功能
82 |
83 | ```typescript
84 | import { match, P } from 'ts-pattern';
85 |
86 | type Data =
87 | | { type: 'text'; content: string }
88 | | { type: 'img'; src: string };
89 |
90 | type Result =
91 | | { type: 'ok'; data: Data }
92 | | { type: 'error'; error: Error };
93 |
94 | const result: Result = ...;
95 |
96 | const html = match(result)
97 | .with({ type: 'error' }, () => Oups! An error occured
)
98 | .with({ type: 'ok', data: { type: 'text' } }, (res) => {res.data.content}
)
99 | .with({ type: 'ok', data: { type: 'img', src: P.select() } }, (src) => 
)
100 | .exhaustive();
101 | ```
102 |
103 | ### [ts-reset](https://github.com/total-typescript/ts-reset)
104 |
105 | - `fetch.json()` 和 `JSON.parse()` 会返回 `unknown` 而不是问题多多的 `any` 了
106 |
107 | - `Array.filter(Boolean)` 的返回值类型能够去掉空类型了
108 |
109 | ```typescript
110 | const input = [null, undefined, true, "seele"];
111 | // ^? const input: (string | boolean | null | undefined)[]
112 | const result = input.filter(Boolean);
113 | // ^? const result: (string | boolean)[]
114 | ```
115 |
116 | - 还有许多对 TypeScript 自带的类型库的改进
117 |
118 | ### [string-ts](https://github.com/gustavoguichard/string-ts)
119 |
120 | 针对字符串字面量类型的工具类型库，下面的图片来自它的 README。
121 |
122 |
123 | 
124 |
125 |
126 | ### [type-fest](https://github.com/sindresorhus/type-fest)
127 |
128 | 也是一个类似 `ts-essentials` 的工具类型库，提供了许多 TypeScript 没有自带的工具类型。
129 |
130 | 具体请看它的 README。
131 |
132 | ### [hotscript](https://github.com/gvergnaud/hotscript)
133 |
134 | 使用 TypeScript 的类型系统构建的一套新的类型「语言」，内置了很多类似函数式编程的组合式 API（你可以尝试将它类比为给类型系统用的 lodash）。它提供的 API 能够让我们通过一种统一、直观的方式表达各种复杂的类型计算，不过看上去学习成本有些高。下面是来自它的 README 的一些例子：
135 |
136 | - Transforming a list
137 |
138 | ```typescript
139 | type _ = Pipe<
140 | // ^? type _ = 62
141 | [1, 2, 3, 4],
142 | [
143 | Tuples.Map>, // [4, 5, 6, 7]
144 | Tuples.Join<".">, // "4.5.6.7"
145 | Strings.Split<".">, // ["4", "5", "6", "7"]
146 | Tuples.Map>, // ["14", "15", "16", "17"]
147 | Tuples.Map, // [14, 15, 16, 17]
148 | Tuples.Sum // 62
149 | ]
150 | >;
151 | ```
152 |
153 | - Parsing a route path
154 |
155 | ```typescript
156 | type _ = Pipe<
157 | // ^? type _ = { id: string, index: number }
158 | "/users//posts/",
159 | [
160 | Strings.Split<"/">,
161 | Tuples.Filter>,
162 | Tuples.Map">, Strings.Split<":">]>>,
163 | Tuples.ToUnion,
164 | Objects.FromEntries,
165 | Objects.MapValues<
166 | Match<[Match.With<"string", string>, Match.With<"number", number>]>
167 | >
168 | ]
169 | >;
170 | ```
171 |
172 | ---
173 |
174 | | **上一章** | **目录** |
175 | | :------------- | :----------: |
176 | | [第四章：生产实践](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript/blob/main/chapter4.md) | [你可能不知道的 TypeScript](https://github.com/darkyzhou/You-Might-Not-Know-TypeScript#%E4%BD%A0%E5%8F%AF%E8%83%BD%E4%B8%8D%E7%9F%A5%E9%81%93%E7%9A%84-typescript) |
177 |
--------------------------------------------------------------------------------
152 | 
181 | 
339 | 
244 | 
369 | 
535 |