` 是 `React.ComponentClass` 与 `React.StatelessComponent
` 的组合，所以你可以接受一些可以用作 Props 类型和使用 JSX 渲染的组件。
```ts
const X: React.Component = foo; // from somewhere
// Render X with some props:
;
```
### React JSX Tip: 可渲染的接口
React 可以渲染一些像 `JSX` 或者是 `string` 的内容，这些被合并到类型 `React.ReactNode` 中，因此，当你接收可渲染的内容时，你可以使用它：
```tsx
type Props = {
header: React.ReactNode;
body: React.ReactNode;
};
class MyComponent extends React.Component {
render() {
return (
{this.props.header}
{this.props.body}
);
}
}
Header} body={body} />
```
### React JSX tip: 接收组件的接口
React 声明文件提供 `React.ReactElement` 的接口，可以让你注解一个类组件实例化的返回值``，如：
```tsx
class MyAwesomeComponent extends React.Component {
render() {
return Hello
;
}
}
const foo: React.ReactElement = ; // Okay
const bar: React.ReactElement = ; // Error!
```
::: tip
你也可以将其用做函数参数的注解，或者是 React 组件的 prop 注解。
:::
### React JSX tip: 接收可以作为 props 的组件，并且使用 JSX 渲染它
类型 `React.Component` 合并了 `React.ComponentClass` 和 `React.StatelessComponent
`，因此，你可以接收一些使用 `Prop` 类型的组件，并使用 JSX 渲染它：
```tsx
const X: React.Component = foo // 来自其他地方
// 渲染 X
```
### React JSX tip: 泛型组件
它完全能按我们预期工作，如：
```tsx
// 一个泛型组件
type SelectProps = { items: T[] };
class Select extends React.Component, any> {}
// 使用
const Form = () => items={['a', 'b']} />;
```
### 泛型函数
一些像下面这样的正常工作：
```ts
function foo(x: T): T {
return x;
}
```
然而不能使用箭头泛型函数：
```ts
const foo = (x: T) => T; // Error: T 标签没有关闭
```
**解决办法**：在泛型参数里使用 `extends` 来提示编译器，这是个泛型：
```ts
const foo = (x: T) => x;
```
### React Tip: 强类型的 Refs
基本上你在初始化一个变量时，使用 ref 和 null 的联合类型，并且在回调函数中初始化他：
```ts
class Example extends React.Component {
example() {
// ... something
}
render() {
return Foo
;
}
}
class Use {
exampleRef: Example | null = null;
render() {
return (this.exampleRef = exampleRef)} />;
}
}
```
使用原生元素时也一样：
```ts
class FocusingInput extends React.Component<{ value: string; onChange: (value: string) => any }, {}> {
input: HTMLInputElement | null = null;
render() {
return (
(this.input = input)}
value={this.props.value}
onChange={e => {
this.props.onChange(e.target.value);
}}
/>
);
}
focus() {
if (this.input != null) {
this.input.focus();
}
}
}
```
### 类型断言
如我们之前[提到](../typings/typeAssertion.md#as-foo-与-foo)的，可以使用 `as Foo` 语法进行类型断言。
## 默认 Props
- 在有状态组件中使用默认的 Props：你可以通过 `null` 操作符（这不是一个理想的方式，但是这是我能想到的最简单的最小代码解决方案）告诉 TypeScript 一个属性将会被外部提供（React）。
```tsx
class Hello extends React.Component<{
/**
* @default 'TypeScript'
*/
compiler?: string;
framework: string;
}> {
static defaultProps = {
compiler: 'TypeScript'
};
render() {
const compiler = this.props.compiler!;
return (
{compiler}
{this.props.framework}
);
}
}
ReactDOM.render(
, // TypeScript React
document.getElementById('root')
);
```
- 在 SFC 中使用默认的 Props：推荐使用简单的 JavaScript 参数，因为同样适用于 TypeScript 类型系统：
```tsx
const Hello: React.SFC<{
/**
* @default 'TypeScript'
*/
compiler?: string;
framework: string;
}> = ({
compiler = 'TypeScript', // Default prop
framework
}) => {
return (
);
};
ReactDOM.render(
, // TypeScript React
document.getElementById('root')
);
```
================================================
FILE: docs/jsx/support.md
================================================
# 支持 JSX
TypeScript 支持 JSX 转换和代码分析，如果你还不了解 JSX，[官网](https://facebook.github.io/jsx/)上有关于它的摘要：
> JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. It's NOT a proposal to incorporate JSX into the ECMAScript spec itself. It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript.
JSX 背后的动机是允许用户在 JavaScript 中书写类似于 HTML 的视图，因此你可以：
- 使用相同代码，既能检查你的 JavaScript，同时能检查你的 HTML 视图层部分。
- 让视图层了解运行时的上下文（加强传统 MVC 中的控制器与视图连接）。
- 复用 JavaScript 设计模式维护 HTML 部分，例如：用 `Array.prototype.map.`、`?:`、`switch` 等，代替创建新的可替代品。
这能够减少错误的可能性，并且能增加用户界面的可维护性。目前 JSX 的主要消费者来自 [facebook 推出的 ReactJS](http://facebook.github.io/react/)，接下来我们结合它来讨论 JSX 用法。
================================================
FILE: docs/new/typescript-3.7.md
================================================
# TypeScript 3.7
## 可选链（Optional Chaining）
在我们的 issue 追踪器中，可选链在 [issue #16](https://github.com/microsoft/TypeScript/issues/16) 中，自那以后，有超过 23000 条 issues 被记录在 issue 中。
可选链的核心是允许我们写下如果碰到 `null` 或者 `undefined`，TypeScript 能立即停止运行的代码。可选链耀眼的部分是使用 `?.` 运算符来访问一个可选属性的运算符。
下面代码：
```ts
let x = foo?.bar.baz();
```
告诉我们，当 `foo` 被定义了，`foo.bar.baz()` 将会执行完成；但是当 `foo` 是 `null` 或者 `undefined` 时，TypeScript 会立即停止运行，并且仅仅是返回 `undefined`。
也就是说，上文的代码等效于如下代码：
```ts
let x = foo === null || foo === undefined ? undefined : foo.bar.baz();
```
注意，如果 `bar` 是 `null` 或者 `undefined`，在访问 `bar` 时，我们的代码仍然会抛出一个错误。
与此相似，如果 `baz` 是 `null` 或者 `undefined`，在调用时，它也会抛出一个错误。`?.` 只会检查它左边的值是 `undefined` 还是 `null` - 并不会检查后面的任何属性。
你可能已经发现你可以使用 `?.` 来替代很多使用 `&&` 执行空检查的代码：
```ts
// Before
if (foo && foo.bar && foo.bar.baz) {
// ...
}
// After-ish
if (foo?.bar?.baz) {
// ...
}
```
注意：`?.` 与 `&&` 运算符行为略有不同，因为 `&&` 专用于 "falsy" 的值（如：空字符串、`0`、`NaN`、和 `false`），但是 `?.` 是一个仅作用于结构上的操作符，`?.` 在验证有效数据如 `0` 或者空字符串时，它并没有使用短路验证的方式。
可选链还包含另外两个运算符，首先是可选元素的访问，它的行为类似于可选属性的访问，但是它允许我们访问非标志符属性（例如：任意的字符串、数字和 symbols）：
```ts
/**
* Get the first element of the array if we have an array.
* Otherwise return undefined.
*/
function tryGetFirstElement(arr?: T[]) {
return arr?.[0];
// equivalent to
// return (arr === null || arr === undefined) ?
// undefined :
// arr[0];
}
```
另外一个是可选调用，它能让我们有条件的调用表达式：
```ts
async function makeRequest(url: string, log?: (msg: string) => void) {
log?.(`Request started at ${new Date().toISOString()}`);
// roughly equivalent to
// if (log != null) {
// log(`Request started at ${new Date().toISOString()}`);
// }
const result = (await fetch(url)).json();
log?.(`Request finished at at ${new Date().toISOString()}`);
return result;
}
```
可选链的「短路运算」行为被局限在属性的访问、调用以及元素的访问 --- 它不会沿伸到后续的表达式中，也就是说：
```ts
let result = foo?.bar / someComputation()
```
可选链不会阻止除法运算或者 `someComputation()` 调用，它等价于：
```ts
let temp = foo === null || foo === undefined ? undefined : foo.bar;
let result = temp / someComputation();
```
它可能会导致除法运算的结果是 `undefined`，这就是为什么在 `strictNullChecks` 选项下，会抛出一个错误：
```ts
function barPercentage(foo?: { bar: number }) {
return foo?.bar / 100;
// ~~~~~~~~
// Error: Object is possibly undefined.
}
```
更多的信息，你可以阅读 [proposal](https://github.com/tc39/proposal-optional-chaining/) 以及该原始的 [PR](https://github.com/microsoft/TypeScript/pull/33294)
## Nullish Coalescing
nullish coalescing 运算符是另一个即将推出的 ECMAScript 功能，它与 Optional chaining 一同被推出，并且我们团队一直参与了 TC39 的有关讨论。
你可以这么想它的功能 - `??` 运算符 - 当处理 `null` 或者 `undefined` 时，它可以作为一种「倒退」到默认值的方式，当我们写下如下代码：
```ts
let x = foo ?? bar();
```
这种方式来表示当 `foo` 值存在时，`foo` 会被使用，但是当它是 `null` 或 `undefined`，它会计算 `bar()`。
它等价于如下代码：
```ts
let x = foo !== null && foo !== undefined ? foo : bar();
```
当尝试使用一个默认值时，`??` 运算符可以被 `||` 替代。例如，在下面的代码片段中，当尝试获取最后一次储存在 localStorage 中的 `volume` 时（如果它存在）；但是当使用 `||`，这会有个 bug：
```ts
function initializeAudio() {
let volume = localStorage.volume || 0.5;
// ...
}
```
当 `localStore.volume` 的值是 `0` 时，在这段代码里，将会把 `volume` 的值设置为 `0.5`。`??` 运算符能避免一些从 `0`、`NaN` 以及`''` 这些被认为是 `falsy` 值的意外行为。
## 断言函数
有一类特定的函数，在非预期结果出现时会抛出一个错误。这类函数就叫做断言函数。例如，Node.js 有一个专用的断言函数叫 `assert`。
```js
assert(someValue === 42);
```
在这个示例中，如果 `someValue` 不等于 `42`，那么 `assert` 就会抛出一个 `AssertionError`。
JavaScript 中的断言经常用于确保传入的是正确的类型。
比如，
```js
function multiply(x, y) {
assert(typeof x === 'number');
assert(typeof y === 'number');
return x * y;
}
```
不幸的是，在 TypeScript 中,这些检查可能从来不会被正确的编写。对于松散类型代码，意味着 TypeScript 检查较少，而对于稍微规范一些的写法，一般要求使用者添加类型断言。
```ts
function yell(str) {
assert(typeof str === 'string');
return str.toUppercase();
// Oops! We misspelled 'toUpperCase'.
// Would be great if TypeScript still caught this!
}
```
这里有可供选择的替代写法，可以让 TypeScript 分析出问题，不过并不方便。
```ts
function yell(str) {
if (typeof str !== 'string') {
throw new TypeError('str should have been a string.');
}
// Error caught!
return str.toUppercase();
}
```
TypeScript 的目标是以最小的改动为现存的 JavaScript 结构添加类型声明。因此，TypeScript 3.7 引入了一个「断言签名（assertion signatures）」的新概念，用来模拟这些断言函数。
第一种断言签名，模拟 Node 中的 `assert` 函数的功能。它确保在断言的范围内，断言条件必须为这个真。
```ts
function assert(condition: any, msg?: string): asserts condition {
if (!condition) {
throw new AssertionError(msg)
}
}
```
`asserts condition` 的意思是，如果 `assert` 函数有返回，传入 `condition` 的参数必须为真，因为如果不是这样，它肯定会抛出一个错误。这意味着，在剩下的作用域中（if 条件后）`condition` 必须为 `truthy`。
举一个例子，用这个断言函数意味着我们可以实现捕获之前的 `yell` 示例的错误。
```ts
function yell(str) {
assert(typeof str === "string");
return str.toUppercase();
// ~~~~~~~~~~~
// error: Property 'toUppercase' does not exist on type 'string'.
// Did you mean 'toUpperCase'?
}
function assert(condition: any, msg?: string): asserts condition {
if (!condition) {
throw new AssertionError(msg)
}
}
```
另外一种断言签名不是用来校验一个条件，而是告诉 TypeScript 某个变量或属性有不同的类型。
```ts
function assertIsString(val: any): asserts val is string {
if (typeof val !== "string") {
throw new AssertionError("Not a string!");
}
}
```
这里 `asserts val is string` 确保在 `assertIsString` 在被调用之后, 任何传入的变量将被认为是一个 `string`.
```ts
function yell(str: any) {
assertIsString(str);
// Now TypeScript knows that 'str' is a 'string'.
return str.toUppercase();
// ~~~~~~~~~~~
// error: Property 'toUppercase' does not exist on type 'string'.
// Did you mean 'toUpperCase'?
}
```
这里的断言签名非常类似于类型谓词（predicate）签名：
```ts
function isString(val: any): val is string {
return typeof val === 'string';
}
function yell(str: any) {
if (isString(str)) {
return str.toUppercase();
}
throw 'Oops!';
}
```
就像类型谓词签名一样，这些断言签名非常强大的。我们可以用它们实现一些非常复杂的想法和设计。
```ts
function assertIsDefined(val: T): asserts val is NonNullable {
if (val === undefined || val === null) {
throw new AssertionError(
`Expected 'val' to be defined, but received ${val}`
);
}
}
```
想阅读更多断言签名相关内容， [签出原始的 pull request](https://github.com/microsoft/TypeScript/pull/32695).
## 更好的支持返回函数的 `never`
为了能使断言签名工作，其中的一个工作是，TypeScript 需要对调用时的函数，以及位置信息编码更多的信息。这给了我们扩展另一类函数的机会：返回 `never` 的函数。
返回为 `never` 的函数，即是永远没有返回的函数。它表明抛出了异常、由于错误发生暂停、或者程序退出的情况。例如：[`process.exit(...)` 中的 `@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5299d372a220584e75a031c13b3d555607af13f8/types/node/globals.d.ts#l874) 指定返回为 `never`。
为了确保函数永远不会返回潜在的 `undefined`，或者从所有的代码路径中有效返回，TypeScript 需要一些句法（syntactic）信号 - 可以是函数末尾的 `return` 或者 `thorw`。因此使用者就会发现自己正在返回它们的故障函数：
```ts
function dispatch(x: string | number): SomeType {
if (typeof x === 'string') {
return doThingWithString(x);
} else if (typeof x === 'number') {
return doThingWithNumber(x);
}
return process.exit(1);
}
```
现在，当函数被调用时，TypeScript 能识别出它们会影响的流程并说明原因。
```ts
function dispatch(x: string | number): SomeType {
if (typeof x === 'string') {
return doThingWithString(x);
} else if (typeof x === 'number') {
return doThingWithNumber(x);
}
process.exit(1);
}
```
与断言函数一样，具体详情，你可以查看此 [PR](https://github.com/microsoft/TypeScript/pull/32695)
## 递归的类型别名
类型别名在如何“递归”引用方面一直存在局限性，原因在于对类型别名的任何使用都必须能够用这个来代替自己。在某些情况下，这是不可能的，因此编译器，会拒绝某些别名的递归：
```ts
type Foo = Foo;
```
这是一个合理的限制，因为 `Foo` 的任何使用都可以被 `Foo` 替代，`Foo` 的任何使用都可以被 `Foo` 替代（无限循环），到最后，没有类型可以替代 `Foo`
这与其他语言处理类型别名时是一致的。但是在用户如何利用该功能方面，它确实造成了一些令人疑惑的情景，例如，在 TypeScript 3.6 及其以下版本时，下面的代码会抛出错误：
```ts
type ValueOrArray = T | Array>;
// ~~~~~~~~~~~~
// error: Type alias 'ValueOrArray' circularly references itself.
```
这很令人疑惑，因为从技术上讲，这没有错误。使用者也可以通过引入接口的方式来实现上述中相同作用的代码：
```ts
type ValueOrArray = T | ArrayOfValueOrArray;
interface ArrayOfValueOrArray extends Array> {}
```
因为接口（和其他对象类型）引入了一个中间类型，并且不需要立马构建它们的完整结构，因此 TypeScript 在使用这种结构时没有问题。但是对于使用者来说，引入一个中间类型来说，并不是很直观。原则上，直接使用 `Array` 的 `ValueOrArray` 的原始版本确实没有任何问题。假如编译器有一点“偷懒”，并且只在必要时才计算 `Array` 的类型参数，则 TypeScript 可以正确表示出这些。
这正是 TypeScript 3.7 所引入的内容，在最顶级的类型别名中，TypeScript 将会推迟解析类型参数，已允许这种情况的发生。
这意味着，以下代码能成立：
```ts
type Json = string | number | boolean | null | JsonObject | JsonArray;
interface JsonObject {
[property: string]: Json;
}
interface JsonArray extends Array {}
```
在没有中间 interface 时，能重写为以下形式：
```ts
type Json = string | number | boolean | null | { [property: string]: Json } | Json[];
```
这种新的行为，可以让我们在元组中递归使用类型别名，下面的代码，在以前会抛出错误，但是现在是有效的：
```ts
type VirtualNode = string | [string, { [key: string]: any }, ...VirtualNode[]];
const myNode: VirtualNode = [
'div',
{ id: 'parent' },
['div', { id: 'first-child' }, "I'm the first child"],
['div', { id: 'second-child' }, "I'm the second child"]
];
```
更多信息，你可以查看 [PR](https://github.com/microsoft/TypeScript/pull/33050)。
## `--declaration` and `--allowJs`
`--declaration` 选项可以让我们从 TypeScript 源文件（如 `.ts`、`.tsx` 文件）中生成 `.d.ts`（声明文件）。这些 `.d.ts` 文件为什么很重要，有以下原因：
首先，它们允许 TypeScript 在不需要重新检查源代码的情况下，能对其他项目进行类型检查。其次，它们允许 TypeScript 与没有使用 TypeScript 构建的 JavaScript 库之间更好的协作。最后，一个被经常忽略小细节：当使用由 TypeScript 驱动的编辑器来获得一些更好功能（比如自动完成）时，TypeScript 和 JavaScript 用户都可以从这些文件中受益。
不幸的是，`--declaration` 与 `--allowJs` 并不能一起使用，`--declaration` 选项会混合 TypeScript 和 JavaScript 输入文件。这是一个令人沮丧的限制，因为它意味着用户在迁移代码库时，不能使用 `--declaration` 选项，即使是使用了 JSDoc 形式的注释。TypeScript 3.7 改变了此行为，它能让两个选项同时使用。
此功能带来最有影响力的结果，可能并不容易被发现：在 TypeScript 3.7 中，用户在 JavaScript 库中写的 JSDoc 注释，能帮助 TypeScript 用户。
它之所以能实现，是因为：当使用 `allowJs` 时，TypeScript 会尽可能的分析代码来了解常见的 JavaScript 模式。然而，一些在 JavaScript 能表示的模式，并不一定能在 TypeScript 等效表示出来。当 `declaration` 选项打开时，TypeScript 会找出将 JSDoc 注释和 CommonJS 输出到 `.d.ts` 文件中的类型声明的最佳方式。
请看如下例子：
```js
const assert = require('assert');
module.exports.blurImage = blurImage;
/**
* Produces a blurred image from an input buffer.
*
* @param input {Uint8Array}
* @param width {number}
* @param height {number}
*/
function blurImage(input, width, height) {
const numPixels = width * height * 4;
assert(input.length === numPixels);
const result = new Uint8Array(numPixels);
// TODO
return result;
}
```
将会产生如下的 `.d.ts`
```ts
/**
* Produces a blurred image from an input buffer.
*
* @param input {Uint8Array}
* @param width {number}
* @param height {number}
*/
export function blurImage(input: Uint8Array, width: number, height: number): Uint8Array;
```
使用 `@param` 注解也有益处：
```js
/**
* @callback Job
* @returns {void}
*/
/** Queues work */
export class Worker {
constructor(maxDepth = 10) {
this.started = false;
this.depthLimit = maxDepth;
/**
* NOTE: queued jobs may add more items to queue
* @type {Job[]}
*/
this.queue = [];
}
/**
* Adds a work item to the queue
* @param {Job} work
*/
push(work) {
if (this.queue.length + 1 > this.depthLimit) throw new Error('Queue full!');
this.queue.push(work);
}
/**
* Starts the queue if it has not yet started
*/
start() {
if (this.started) return false;
this.started = true;
while (this.queue.length) {
/** @type {Job} */ (this.queue.shift())();
}
return true;
}
}
```
将会生成如下 `.d.ts`
```ts
/**
* @callback Job
* @returns {void}
*/
/** Queues work */
export class Worker {
constructor(maxDepth?: number);
started: boolean;
depthLimit: number;
/**
* NOTE: queued jobs may add more items to queue
* @type {Job[]}
*/
queue: Job[];
/**
* Adds a work item to the queue
* @param {Job} work
*/
push(work: Job): void;
/**
* Starts the queue if it has not yet started
*/
start(): boolean;
}
export type Job = () => void;
```
注意，如果你想一起使用这些选项，TypeScript 不需要含有对应的 `.js` 文件，如果只是需要 TypeScript 生成简单的 `.d.ts` 文件，使用 `--emitDeclarationOnly` 选项即可。
更多详情，请参考 [PR](https://github.com/microsoft/TypeScript/pull/32372)
For more details, you can [check out the original pull request](https://github.com/microsoft/TypeScript/pull/32372).
## `useDefineForClassFields` 标记与 `declare` 属性修饰符
当在 TypeScript 中实现 class 中的公有字段时，我们尽可能的实现了以下代码功能：
```ts
class C {
foo = 100;
bar: string;
}
```
它等同于构造函数内的相似语句：
```ts
class C {
constructor() {
this.foo = 100;
}
}
```
不幸的是，虽然这是 TC39 早期提案的发展方向，但是极有可能对于公共 class 字段有不同的标准化方向。因此，原始的代码可能会被编译成如下代码：
```ts
class C {
constructor() {
Object.defineProperty(this, 'foo', {
enumerable: true,
configurable: true,
writable: true,
value: 100
});
Object.defineProperty(this, 'bar', {
enumerable: true,
configurable: true,
writable: true,
value: void 0
});
}
}
```
当然 TypeScript 3.7 版本在默认情况下编译出的代码不会有任何改变（与以前版本相同），我们一直在逐步更改，来帮助用户减少可能发生的破坏性更改。我们提供来一个新的标志 `useDefineForClassFields` 来使用此种模式，并带有一些新的逻辑检查。
最大的两个改变如下：
- 使用 `Object.defineProperty` 来初始化声明。
- 初始化的值都是 undefined，即使是它们没有被初始化。
对于使用继承的代码来说，这可能会造成很多问题。首先，来自于基类的 set 访问器，不再会被触发 -- 它可能会被完全重写。
```ts
class Base {
set data(value: string) {
console.log('data changed to ' + value);
}
}
class Derived extends Base {
// No longer triggers a 'console.log'
// when using 'useDefineForClassFields'.
data = 10;
}
```
其次，在基类中使用一个类字段来专门指定一个属性，它也不会正常工作。
```ts
interface Animal {
animalStuff: any;
}
interface Dog extends Animal {
dogStuff: any;
}
class AnimalHouse {
resident: Animal;
constructor(animal: Animal) {
this.resident = animal;
}
}
class DogHouse extends AnimalHouse {
// Initializes 'resident' to 'undefined'
// after the call to 'super()' when
// using 'useDefineForClassFields'!
resident: Dog;
constructor(dog: Dog) {
super(dog);
}
}
```
这两个问题，可以归结为在没有初始化的情况下，混合属性与访问器时，将会有重复声明出现。
为了检查访问器是否有上述问题，TypeScript 3.7 将会在 .d.ts 中编译出 `get`/`set`，于是 TypeScript 能够检查出是否有重写访问器的问题。
```ts
class Base {
set data(value: string) {
console.log('data changed to ' + value);
}
}
class Derived extends Base {
constructor() {
data = 10;
}
}
```
为了解决第二个问题，你可以添加一个显示的初始化值，或者添加一个 `declare` 修饰符来表明该属性不会被编译出任何值。
```ts
interface Animal {
animalStuff: any;
}
interface Dog extends Animal {
dogStuff: any;
}
class AnimalHouse {
resident: Animal;
constructor(animal: Animal) {
this.resident = animal;
}
}
class DogHouse extends AnimalHouse {
declare resident: Dog;
// ^^^^^^^^
// 'resident' now has a 'declare' modifier,
// and won't produce any output code.
constructor(dog: Dog) {
super(dog);
}
}
```
现在，只有当编译目标是 ES5 及其以上时，`useDefineForClassFields` 编译选项才可用，因为 ES3 并没有 `Object.defineProperty`。要实现类似的问题检查，你可以创建一个编译目标为 ES5 并且使用 `--noEmit` 来避免完全构建的单独项目。
更多的信息，你可以查看此 [PR](https://github.com/microsoft/TypeScript/pull/33509)。
## 编辑有项目引用的项目，无需构建
TypeScript 的项目引用功能给我们提供了一个方便的方式来拆分代码库，从而能让我们能实现更快地编译。
遗憾的是，当我们编辑一个依赖未被构建（或者构建结果已过期）的项目时，会得到不好的编辑体验。
在 TypeScript 3.7 中，当打开一个有依赖的项目时，TypeScript 将会自动地使用原始 `.ts`/`.tsx` 文件来代替。
这意味着在有依赖引用的项目中，代码的修改会马上同步和生效，从而编辑体验会有所提升，
你可以打开编译器选项 `disableSourceOfProjectReferenceRedirect` 来禁用这个引用的功能，因为在超大型项目中这个功能可能会影响性能。
你可以 [阅读它的 pull request，获取更多相关信息](https://github.com/microsoft/TypeScript/pull/32028).
## 没有调用的函数检查
一个常见且危险的错误是忘记调用一个函数，特别是当函数具有零参数或用暗示它可能是属性而不是函数的方式名称时。
```ts
interface User {
isAdministrator(): boolean;
notify(): void;
doNotDisturb?(): boolean;
}
// later...
// Broken code, do not use!
function doAdminThing(user: User) {
// oops!
if (user.isAdministrator) {
sudo();
editTheConfiguration();
} else {
throw new AccessDeniedError('User is not an admin');
}
}
```
在这里，我们忘记调用 `isAdministrator`，该代码错误的允许非管理员用户编辑配置。
在 TypeScript 3.7 中，它就会抛出错误：
```ts
function doAdminThing(user: User) {
if (user.isAdministrator) {
// ~~~~~~~~~~~~~~~~~~~~
// error! This condition will always return true since the function is always defined.
// Did you mean to call it instead?
```
这个检查是一个破坏性的更改，因此这个错误仅仅是发生在 `if` 条件语句中，并且如果 `strictNullChecks` 关闭或者在 if 块中，函数有被调用，不会发出此错误。
```ts
interface User {
isAdministrator(): boolean;
notify(): void;
doNotDisturb?(): boolean;
}
function issueNotification(user: User) {
if (user.doNotDisturb) {
// OK, property is optional
}
if (user.notify) {
// OK, called the function
user.notify();
}
}
```
如果你想在没有调用函数的前提下，对它进行测试。你可以修改它的声明，让它可能是 `undefined/null`，或者使用 `!!` 来写下一些 `if(!!user.isAdministrator)` 来表明这种行为是故意的。
================================================
FILE: docs/new/typescript-3.8.md
================================================
# TypeScript 3.8
[TypeScript 3.8](http://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html) 将会带来了许多特性，其中包含一些新的或即将到来的 ECMAScript 特性、仅仅导入/导出声明语法等。
## 仅仅导入/导出声明
为了能让我们导入类型，TypeScript 重用了 JavaScript 导入语法。例如在下面的这个例子中，我们确保 JavaScript 的值 `doThing` 以及 TypeScript 类型 `Options` 一同被导入
```ts
// ./foo.ts
interface Options {
// ...
}
export function doThing(options: Options) {
// ...
}
// ./bar.ts
import { doThing, Options } from './foo.js';
function doThingBetter(options: Options) {
// do something twice as good
doThing(options);
doThing(options);
}
```
这很方便的，因为在大多数的情况下，我们不必担心导入了什么 —— 仅仅是我们想导入的内容。
遗憾的是，这仅是因为一个被称之为「导入省略」的功能而起作用。当 TypeScript 输出一个 JavaScript 文件时，TypeScript 会识别出 `Options` 仅仅是当作了一个类型来使用，它将会删除 `Options`
```ts
// ./foo.js
export function doThing(options: Options) {
// ...
}
// ./bar.js
import { doThing } from './foo.js';
function doThingBetter(options: Options) {
// do something twice as good
doThing(options);
doThing(options);
}
```
在通常情况下，这种行为都是比较好的。但是它会导致一些其他问题。
首先，在一些场景下，TypeScript 会混淆导出的究竟是一个类型还是一个值。比如在下面的例子中， `MyThing` 究竟是一个值还是一个类型？
```ts
import { MyThing } from './some-module.js';
export { MyThing };
```
如果单从这个文件来看，我们无从得知答案。如果 `Mything` 仅仅是一个类型，Babel 和 TypeScript 使用的 `transpileModule` API 编译出的代码将无法正确工作，并且 TypeScript 的 `isolatedModules` 编译选项将会提示我们，这种写法将会抛出错误。问题的关键在于，没有一种方式能识别它仅仅是个类型，以及是否应该删除它，因此「导入省略」并不够好。
同时，这也存在另外一个问题，TypeScript 导入省略将会去除只包含用于类型声明的导入语句。对于含有副作用的模块，这造成了明显的不同行为。于是，使用者将会不得不添加一条额外的声明语句，来确保有副作用。
```ts
// This statement will get erased because of import elision.
import { SomeTypeFoo, SomeOtherTypeBar } from './module-with-side-effects';
// This statement always sticks around.
import './module-with-side-effects';
```
一个我们看到的具体例子是出现在 Angularjs（1.x）中， `services` 需要在全局在注册（它是一个副作用），但是导入的 `services` 仅仅用于类型声明中。
```ts
// ./service.ts
export class Service {
// ...
}
register('globalServiceId', Service);
// ./consumer.ts
import { Service } from './service.js';
inject('globalServiceId', function(service: Service) {
// do stuff with Service
});
```
结果 `./service.js` 中的代码不会被执行，导致在运行时会被中断。
为了避免这类行为，我们意识到在什么该被导入/删除方面，需要给使用者提供更细粒度的控制。
在 TypeScript 3.8 版本中，我们添加了一个仅仅导入/导出声明语法来作为解决方式。
```ts
import type { SomeThing } from "./some-module.js";
export type { SomeThing };
```
`import type` 仅仅导入被用于类型注解或声明的声明语句，它总是会被完全删除，因此在运行时将不会留下任何代码。与此相似，`export type` 仅仅提供一个用于类型的导出，在 TypeScript 输出文件中，它也将会被删除。
值得注意的是，类在运行时具有值，在设计时具有类型。它的使用与上下文有关。当使用 `import type` 导入一个类时，你不能做类似于从它继承的操作。
```ts
import type { Component } from "react";
interface ButtonProps {
// ...
}
class Button extends Component {
// ~~~~~~~~~
// error! 'Component' only refers to a type, but is being used as a value here.
// ...
}
```
如果在之前你使用过 Flow，它们的语法是相似的。一个不同的地方是我们添加了一个新的限制条件，来避免可能混淆的代码。
```ts
// Is only 'Foo' a type? Or every declaration in the import?
// We just give an error because it's not clear.
import type Foo, { Bar, Baz } from "some-module";
// ~~~~~~~~~~~~~~~~~~~~~~
// error! A type-only import can specify a default import or named bindings, but not both.
```
与 `import type` 相关联，我们提供来一个新的编译选项：`importsNotUsedAsValues`，通过它可以来控制没被使用的导入语句将会被如何处理，它的名字是暂定的，但是它提供来三个不同的选项。
- `remove`，这是现在的行为 —— 丢弃这些导入语句。这仍然是默认行为，没有破坏性的更改
- `preserve`，它将会保留所有的语句，即使是从来没有被使用。它可以保留副作用
- `error`，它将会保留所有的导入（与 `preserve` 选项相同）语句，但是当一个值的导入仅仅用于类型时将会抛出错误。如果你想确保没有意外导入任何值，这会是有用的，但是对于副作用，你仍然需要添加额外的导入语法。
对于该特性的更多信息，参考该 [PR](https://github.com/microsoft/TypeScript/pull/35200)。
## ECMAScript 私有字段
TypeScript 3.8 支持在 ECMAScript 中处于 [stage-3](https://github.com/tc39/proposal-class-fields/) 中的私有字段。
```ts
class Person {
#name: string
constructor(name: string) {
this.#name = name;
}
greet() {
console.log(`Hello, my name is ${this.#name}!`);
}
}
let jeremy = new Person("Jeremy Bearimy");
jeremy.#name
// ~~~~~
// Property '#name' is not accessible outside class 'Person'
// because it has a private identifier.
```
不同于正常属性（甚至是使用 `private` 修饰符声明的属性），私有字段有一些需要记住的规则：
- 私有字段使用 `#` 字符作为开始，通常，我们也把这些称为私有名称。
- 每个私有字段的名字，在被包含的类中，都是唯一的
- 在 TypeScript 中，像 `public` 和 `private` 修饰符不能用于私有字段
- 私有字段不能在所包含的类之外访问 —— 即使是对于 JavaScript 使用者来说也是如此。通常，我们把这种称为「hard privacy」。
除了「hard privacy」，私有字段的另外一个优点是我们先前提到的唯一性。
正常的属性容易被子类所改写
```ts
class C {
foo = 10;
cHelper() {
return this.foo;
}
}
class D extends C {
foo = 20;
dHelper() {
return this.foo;
}
}
let instance = new D();
// 'this.foo' refers to the same property on each instance.
console.log(instance.cHelper()); // prints '20'
console.log(instance.dHelper()); // prints '20'
```
使用私有字段时，你完全不必对此担心，因为每个私有字段，在所包含的类中，都是唯一的
```ts
class C {
#foo = 10;
cHelper() {
return this.#foo;
}
}
class D extends C {
#foo = 20;
dHelper() {
return this.#foo;
}
}
let instance = new D();
// 'this.#foo' refers to a different field within each class.
console.log(instance.cHelper()); // prints '10'
console.log(instance.dHelper()); // prints '20'
```
另外有一个值得注意的地方，访问一个有其他类型的私有字段，都将导致 `TypeError`。
```ts
class Square {
#sideLength: number;
constructor(sideLength: number) {
this.#sideLength = sideLength;
}
equals(other: any) {
return this.#sideLength === other.#sideLength;
}
}
const a = new Square(100);
const b = { sideLength: 100 };
// Boom!
// TypeError: attempted to get private field on non-instance
// This fails because 'b' is not an instance of 'Square'.
console.log(a.equals(b));
```
对于类属性来说，JavaScript 总是允许使用者访问没被声明的属性，而 TypeScript 需要使用者在访问之前先定义声明。使用私有字段时，无论时 `.js` 文件还是 `.ts`，都需要先声明。
```ts
class C {
/** @type {number} */
#foo;
constructor(foo: number) {
// This works.
this.#foo = foo;
}
}
```
更多信息，请查看此 [PR](https://github.com/Microsoft/TypeScript/pull/30829)。
### 该使用哪个？
我们已经收到很多关于「我该使用 `private` 关键字，还是使用 ECMAScript 提供的私有字段 `#` 了？」这类的问题。
像所有其他好的问题一样，答案总是令人遗憾的：它取决你。
在属性方面，TypeScript `private` 修饰符在编译后将会被删除 —— 因此，尽管有数据存在，但是在输出的 JavaScript 代码中没有关于该属性声明的任何编码。在运行时，它的行为就像一个普通的属性。当你使用 `private` 关键字时，私有属性的有关行为只会出现在编译阶段/设计阶段，而对于 JavaScript 消费者来说，则是完全无感知的。
```ts
class C {
private foo = 10;
}
// This is an error at compile time,
// but when TypeScript outputs .js files,
// it'll run fine and print '10'.
console.log(new C().foo); // prints '10'
// ~~~
// error! Property 'foo' is private and only accessible within class 'C'.
// TypeScript allows this at compile-time
// as a "work-around" to avoid the error.
console.log(new C()['foo']); // prints '10'
```
另一方面，ECMAScript 私有属性无法在类之外访问。
```ts
class C {
#foo = 10;
}
console.log(new C().#foo); // SyntaxError
// ~~~~
// TypeScript reports an error *and*
// this won't work at runtime!
console.log(new C()["#foo"]); // prints undefined
// ~~~~~~~~~~~~~~~
// TypeScript reports an error under 'noImplicitAny',
// and this prints 'undefined'.
```
「hard privacy」对于确保没有人能使用你的任何内部变量是有用的，如果你是一个库的作者，移除或者重命名一个私有字段不会造成任何重大变化。
正如上文所述，使用 ECMAScript 的私有字段，创建子类会更容易，因为它们是**真**私有。当使用 ECMAScript 私有字段时，子类无需担心字段名字的冲突。当使用 TypeScript `private` 属性声明时，使用者仍然需要小心不要覆盖父类中的相同字段。
最后，还有一些你需要考虑的事情，比如你打算让你的代码在哪运行？当前，TypeScript 只有在编译目标为 ECMAScript 2015（ES6）及其以上时，才能支持该私有字段。因为我们在底层使用 `WeakMaps` 实现这种方法 —— `WeakMaps` 并不能以一种不会导致内存泄漏的方式 polyfill。对比而言，TypeScript 的 `private` 声明属性能在所有的编译目标下正常工作 —— 甚至是 ECMAScript 3。
## `export * as ns` 语法
以下方式很常见
```ts
import * as utilities from './utilities.js';
export { utilities };
```
在 ECMAScript 2020 中，添加了一种新的语法来支持该模式：
```TS
export * as utilities from "./utilities.js";
```
这是一次 JavaScript 代码质量的改进，TypeScript 3.8 实现了此语法。
当你的编译目标早于 `es2020` 时，TypeScript 将会按照第一个代码片段输出内容。
## `Top-Level await`
大多数使用 JavaScript 提供 I/O（如 http 请求）的现代环境都是异步的，并且很多现代 API 都返回 `Promise`。尽管它在使操作无阻塞方面有诸多优点，但是它确实在一些如读取文件或外部内容时，会让人厌烦。
```ts
fetch('...')
.then(response => response.text())
.then(greeting => {
console.log(greeting);
});
```
为了避免使用 `Promise` 中 `.then` 的链式操作符，JavaScript 使用者通常会引入 `async` 函数以使用 `await`，在定义该函数之后，立即调用该函数。
```ts
async function main() {
const response = await fetch('...');
const greeting = await response.text();
console.log(greeting);
}
main().catch(e => console.error(e));
```
为了避免引入 `async` 函数，我们可以使用一个简便的语法，它在即将到来的 ECMAScript feature 中被称为 `top-level await`。
在当前的 JavaScript 中（以及其他具有相似功能的大多数其他语言），`await` 仅仅只能用于 `async` 函数内部。然而，使用 `top-level await` 时，我们可以在一个模块的顶层使用 `await`。
```ts
const response = await fetch('...');
const greeting = await response.text();
console.log(greeting);
// Make sure we're a module
export {};
```
这里有一个细节：`top-level await` 仅仅只能在一个模块的顶层工作 —— 仅当 TypeScript 发现文件代码中含有 `export` 或者 `import` 时，才会认为该文件是一个模块。在一些基础的实践中，你可能需要写下 `export {}` 作为样板，来确保这种行为。
`top-level await` 并不会在你可能期望的所有环境下工作。现在，只有在编译目标选项是 `es2017` 及其以上，`top-level await` 才能被使用，并且 `module` 选项必须为 `esnext` 或者 `system`。
更多相关信息，请查看该 [PR](https://github.com/microsoft/TypeScript/pull/35813)。
## JSDoc 属性修饰符
TypeScript 3.8 通过打开 `allowJs` 选项，能支持 JavaScript 文件，并且当使用 `checkJs` 选项或者在你的 `.js` 文件顶部中添加 `// @ts-check` 注释时，TypeScript 能对这些 `.js` 文件进行类型检查。
由于 JavaScript 文件没有专用的语法来进行类型检查，因此 TypeScript 选择利用 JSDoc。TypeScript 3.8 能理解一些新的 JSDoc 属性标签。
首先是所有的访问修饰符：`@public`、`@private`、`@protected`。这些标签的工作方式与 TypeScript 中 `public`、`private`、`protected` 相同。
```js
// @ts-check
class Foo {
constructor() {
/** @private */
this.stuff = 100;
}
printStuff() {
console.log(this.stuff);
}
}
new Foo().stuff;
// ~~~~~
// error! Property 'stuff' is private and only accessible within class 'Foo'.
```
- `@public` 是默认的，可以省略，它代表了一个属性可以从任何地方访问它
- `@private` 表示一个属性只能在包含的类中访问
- `@protected` 表示该属性只能在所包含的类及子类中访问，但不能在类的实例中访问
下一步，我们计划添加 `@readonly` 修饰符，来确保一个属性只能在初始化时被修改：
```ts
// @ts-check
class Foo {
constructor() {
/** @readonly */
this.stuff = 100;
}
writeToStuff() {
this.stuff = 200;
// ~~~~~
// Cannot assign to 'stuff' because it is a read-only property.
}
}
new Foo().stuff++;
// ~~~~~
// Cannot assign to 'stuff' because it is a read-only property.
```
## watchOptions
一直以来，TypeScript 致力于在 `--watch` 模式下和编辑器中提供可靠的文件监听功能。尽管在大部分情况下，它都能很好的工作，但是在 Node.js 中，文件监控非常困难，这主要体现在我们的代码逻辑中。在 Node.js 中内置的 API 中，要么占用大量的 CPU 资源，要么不准确（[fs.watchFile](https://nodejs.org/api/fs.html#fs_fs_watchfile_filename_options_listener)），甚至它们在各个平台的行为不一致（[fs.watch](https://nodejs.org/api/fs.html#fs_fs_watch_filename_options_listener)）。除此之外，我们几乎不可能确定哪个 API 会更好的工作，因为它们不仅依赖于平台，还取决于文件所在的文件系统。
这一直是个难题，因为 TypeScript 需要在更多平台上运行，而不仅仅是 Node.js。并且需要考虑到避免依赖模块完全独立。这尤其适用于对 Node.js 原生模块有依赖的模块。
由于每个项目在不同的策略下都可能更好的工作，TypeScript 3.8 在 `tsconfig.json` 和 `jsconfig.json` 中添加了一个新的 `watchOptions` 字段，它可以让使用者告诉编译器/语言服务，应该使用哪种监听策略来跟踪文件或目录。
```ts
{
// Some typical compiler options
"compilerOptions": {
"target": "es2020",
"moduleResolution": "node",
// ...
},
// NEW: Options for file/directory watching
"watchOptions": {
// Use native file system events for files and directories
"watchFile": "useFsEvents",
"watchDirectory": "useFsEvents",
// Poll files for updates more frequently
// when they're updated a lot.
"fallbackPolling": "dynamicPriority"
}
}
```
`watchOptions` 包含四种新的选项
- `watchFile`：监听单个文件的策略，它可以有以下值
- `fixedPollingInterval`，以固定的时间间隔，检查文件的更改
- `priorityPollingInterval`，以固定的时间间隔，检查文件的更改，但是使用「启发法」（heuristics）检查某些类型的文件的频率比其他文件低。（heuristics 概念可参考 [wiki](https://zh.wikipedia.org/wiki/%E5%90%AF%E5%8F%91%E6%B3%95)）
- `dynamicPriorityPolling`，使用动态队列，在该队列中，较少检查不经常修改的文件
- `useFsEvents`（默认），尝试使用操作系统/文件系统原生事件来监听文件更改
- `useFsEventsOnParentDirectory`，尝试使用操作系统/文件系统原生事件来监听文件、目录的更改，这样可以使用较小的文件监听程序，但是准确性可能较低
- `watchDirectory`，在缺少递归文件监听功能的系统中，使用哪种策略监听整个目录树，它可以有以下值
- `fixedPollingInterval`，以固定的时间间隔，检查目录树的更改
- `dynamicPriorityPolling`，使用动态队列，在该队列中，较少检查不经常修改的目录
- `useFsEvents`（默认），尝试使用操作系统/文件系统原生事件来监听目录更改
- `fallbackPolling`，当使用文件系统的事件，该选项用来指定使用特定策略，它可以有以下值
- `fixedPollingInterval`，同上
- `priorityPollingInterval`，同上
- `dynamicPriorityPolling`，同上
- `synchronousWatchDirectory`，在目录上禁用延迟监听功能。在可能一次发生大量文件（如 node_modules）更改时，它非常有用，但是你可能需要一些不太常见的设置时，禁用它。
## “快速和宽松”的增量检查
TypeScript 3.8 带来了一种新的变异选项 —— `assumeChangesOnlyAffectDirectDependencies`。当该选项开启时，TypeScript 将不会重新检查/构建可能受影响的文件，仅仅重新检查/构建已更改的文件和直接导入它们的文件。
例如：`fileD.ts` 导入 `fileC.ts`，`fileC.ts` 导入 `fileB.ts`，`fileB.ts` 导入 `fileA.ts` 文件。
```ts
fileA.ts < -fileB.ts < -fileC.ts < -fileD.ts;
```
在 `--watch` 模式下，改变 `fileA.ts` 文件通常意味着 TypeScript 需要至少重新检查 `fileB.ts`、`fileC.ts` 和 `fileD.ts`，当使用 `assumeChangesOnlyAffectDirectDependencies` 时，`fileA.ts` 改变，意味着只需要检查 `fileA.ts` 和 `fileB.ts` 即可。
在类似与 VSCode 的代码库中，使用该编译选项时，某些文件的构建时间从大约 14s 减小到 1s。然而我们并不推荐所有的代码库中都使用该编译选项，你可能对拥有庞大代码库时，延迟提示所有错误更感兴趣（例如一个专用的配置文件 `tsconfig.fullbuild.json` 或者是 CI 中）。
================================================
FILE: docs/new/typescript-3.9.md
================================================
# TypeScript 3.9
[TypeScript3.9 —— 前端之颠](https://wemp.app/posts/7b99df08-8245-4dbe-8514-c10919779e6a)
================================================
FILE: docs/project/compilationContext.md
================================================
# 编译上下文
编译上下文算是一个比较花哨的术语，可以用它来给文件分组，告诉 TypeScript 哪些文件是有效的，哪些是无效的。除了有效文件所携带信息外，编译上下文还包含有正在被使用的编译选项的信息。定义这种逻辑分组，一个比较好的方式是使用 `tsconfig.json` 文件。
## tsconfig.json
### 基础
开始使用 `tsconfig.json` 是一件比较容易的事，你仅仅需要写下：
```json
{}
```
例如，在项目的根目录下创建一个空 JSON 文件。通过这种方式，TypeScript 将 会把此目录和子目录下的所有 .ts 文件作为编译上下文的一部分，它还会包含一部分默认的编译选项。
### 编译选项
你可以通过 `compilerOptions` 来定制你的编译选项：
```js
{
"compilerOptions": {
/* 基本选项 */
"target": "es5", // 指定 ECMAScript 目标版本: 'ES3' (default), 'ES5', 'ES6'/'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'
"module": "commonjs", // 指定使用模块: 'commonjs', 'amd', 'system', 'umd' or 'es2015'
"lib": [], // 指定要包含在编译中的库文件
"allowJs": true, // 允许编译 javascript 文件
"checkJs": true, // 报告 javascript 文件中的错误
"jsx": "preserve", // 指定 jsx 代码的生成: 'preserve', 'react-native', or 'react'
"declaration": true, // 生成相应的 '.d.ts' 文件
"sourceMap": true, // 生成相应的 '.map' 文件
"outFile": "./", // 将输出文件合并为一个文件
"outDir": "./", // 指定输出目录
"rootDir": "./", // 用来控制输出目录结构 --outDir.
"removeComments": true, // 删除编译后的所有的注释
"noEmit": true, // 不生成输出文件
"importHelpers": true, // 从 tslib 导入辅助工具函数
"isolatedModules": true, // 将每个文件作为单独的模块 （与 'ts.transpileModule' 类似）.
/* 严格的类型检查选项 */
"strict": true, // 启用所有严格类型检查选项
"noImplicitAny": true, // 在表达式和声明上有隐含的 any类型时报错
"strictNullChecks": true, // 启用严格的 null 检查
"noImplicitThis": true, // 当 this 表达式值为 any 类型的时候，生成一个错误
"alwaysStrict": true, // 以严格模式检查每个模块，并在每个文件里加入 'use strict'
/* 额外的检查 */
"noUnusedLocals": true, // 有未使用的变量时，抛出错误
"noUnusedParameters": true, // 有未使用的参数时，抛出错误
"noImplicitReturns": true, // 并不是所有函数里的代码都有返回值时，抛出错误
"noFallthroughCasesInSwitch": true, // 报告 switch 语句的 fallthrough 错误。（即，不允许 switch 的 case 语句贯穿）
/* 模块解析选项 */
"moduleResolution": "node", // 选择模块解析策略： 'node' (Node.js) or 'classic' (TypeScript pre-1.6)
"baseUrl": "./", // 用于解析非相对模块名称的基目录
"paths": {}, // 模块名到基于 baseUrl 的路径映射的列表
"rootDirs": [], // 根文件夹列表，其组合内容表示项目运行时的结构内容
"typeRoots": [], // 包含类型声明的文件列表
"types": [], // 需要包含的类型声明文件名列表
"allowSyntheticDefaultImports": true, // 允许从没有设置默认导出的模块中默认导入。
/* Source Map Options */
"sourceRoot": "./", // 指定调试器应该找到 TypeScript 文件而不是源文件的位置
"mapRoot": "./", // 指定调试器应该找到映射文件而不是生成文件的位置
"inlineSourceMap": true, // 生成单个 soucemaps 文件，而不是将 sourcemaps 生成不同的文件
"inlineSources": true, // 将代码与 sourcemaps 生成到一个文件中，要求同时设置了 --inlineSourceMap 或 --sourceMap 属性
/* 其他选项 */
"experimentalDecorators": true, // 启用装饰器
"emitDecoratorMetadata": true // 为装饰器提供元数据的支持
}
}
```
关于这些（或者更多）编译选项，稍后将会讨论。
### TypeScript 编译
好的 IDE 支持对 TypeScript 的即时编译。但是，如果你想在使用 `tsconfig.json` 时从命令行手动运行 TypeScript 编译器，你可以通过以下方式：
- 运行 tsc，它会在当前目录或者是父级目录寻找 `tsconfig.json` 文件。
- 运行 `tsc -p ./path-to-project-directory` 。当然，这个路径可以是绝对路径，也可以是相对于当前目录的相对路径。
你甚至可以使用 `tsc -w` 来启用 TypeScript 编译器的观测模式，在检测到文件改动之后，它将重新编译。
## 指定文件
你也可以显式指定需要编译的文件：
```js
{
"files": [
"./some/file.ts"
]
}
```
你还可以使用 `include` 和 `exclude` 选项来指定需要包含的文件和排除的文件：
```js
{
"include": [
"./folder"
],
"exclude": [
"./folder/**/*.spec.ts",
"./folder/someSubFolder"
]
}
```
:::tip 注意
使用 `globs`：`**/*` （一个示例用法：`some/folder/**/*`）意味着匹配所有的文件夹和所有文件（扩展名为 `.ts/.tsx`，当开启了 `allowJs: true` 选项时，扩展名可以是 `.js/.jsx`）。
:::
================================================
FILE: docs/project/declarationspaces.md
================================================
# 声明空间
在 TypeScript 里存在两种声明空间：类型声明空间与变量声明空间。下文将分别讨论这两个概念。
## 类型声明空间
类型声明空间包含用来当做类型注解的内容，例如下面的类型声明：
```ts
class Foo {}
interface Bar {}
type Bas = {};
```
你可以将 `Foo`, `Bar`, `Bas` 作为类型注解使用，示例如下：
```ts
let foo: Foo;
let bar: Bar;
let bas: Bas;
```
注意，尽管你定义了 `interface Bar`，却并不能够把它作为一个变量来使用，因为它没有定义在变量声明空间中。
```ts
interface Bar {}
const bar = Bar; // Error: "cannot find name 'Bar'"
```
出现错误提示： `cannot find name 'Bar'` 的原因是名称 `Bar` 并未定义在变量声明空间。这将带领我们进入下一个主题 -- 变量声明空间。
## 变量声明空间
变量声明空间包含可用作变量的内容，在上文中 `Class Foo` 提供了一个类型 `Foo` 到类型声明空间，此外它同样提供了一个变量 `Foo` 到变量声明空间，如下所示：
```ts
class Foo {}
const someVar = Foo;
const someOtherVar = 123;
```
这很棒，尤其是当你想把一个类来当做变量传递时。
::: warning
我们并不能把一些如 `interface` 定义的内容当作变量使用。
:::
与此相似，一些用 `var` 声明的变量，也只能在变量声明空间使用，不能用作类型注解。
```js
const foo = 123;
let bar: foo; // ERROR: "cannot find name 'foo'"
```
提示 `ERROR: "cannot find name 'foo'"` 原因是，名称 foo 没有定义在类型声明空间里。
================================================
FILE: docs/project/dynamicImportExpressions.md
================================================
# 动态导入表达式
动态导入表达式是 ECMAScript 的一个新功能，它允许你在程序的任意位置异步加载一个模块，TC39 JavaScript 委员会有一个提案，目前处于第四阶段，它被称为 [import() proposal for JavaScript](https://github.com/tc39/proposal-dynamic-import)。
此外，**webpack** bundler 有一个 [`Code Splitting`](https://webpack.js.org/guides/code-splitting/) 功能，它能允许你将代码拆分为许多块，这些块在将来可被异步下载。因此，你可以在程序中首先提供一个最小的程序启动包，并在将来异步加载其他模块。
这很自然就会让人想到（如果我们工作在 webpack dev 的工作流程中）[TypeScript 2.4 dynamic import expressions](https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#dynamic-import-expressions) 将会把你最终生成的 JavaScript 代码自动分割成很多块。但是这似乎并不容易实现，因为它依赖于我们正在使用的 `tsconfig.json` 配置文件。
webpack 实现代码分割的方式有两种：使用 `import()` （首选，ECMAScript 的提案）和 `require.ensure()` （最后考虑，webpack 具体实现）。因此，我们期望 TypeScript 的输出是保留 `import()` 语句，而不是将其转化为其他任何代码。
让我们来看一个例子，在这个例子中，我们演示了如何配置 webpack 和 TypeScript 2.4 +。
在下面的代码中，我希望懒加载 `moment` 库，同时我也希望使用代码分割的功能，这意味 `moment` 会被分割到一个单独的 JavaScript 文件，当它被使用时，会被异步加载。
```ts
import(/* webpackChunkName: "momentjs" */ 'moment')
.then(moment => {
// 懒加载的模块拥有所有的类型，并且能够按期工作
// 类型检查会工作，代码引用也会工作 :100:
const time = moment().format();
console.log('TypeScript >= 2.4.0 Dynamic Import Expression:');
console.log(time);
})
.catch(err => {
console.log('Failed to load moment', err);
});
```
这是 `tsconfig.json` 的配置文件：
```js
{
"compilerOptions": {
"target": "es5",
"module": "esnext",
"lib": [
"dom",
"es5",
"scripthost",
"es2015.promise"
],
"jsx": "react",
"declaration": false,
"sourceMap": true,
"outDir": "./dist/js",
"strict": true,
"moduleResolution": "node",
"typeRoots": [
"./node_modules/@types"
],
"types": [
"node",
"react",
"react-dom"
]
}
}
```
:::danger 重要的提示
- 使用 `"module": "esnext"` 选项：TypeScript 保留 `import()` 语句，该语句用于 Webpack Code Splitting。
- 进一步了解有关信息，推荐阅读这篇文章：[Dynamic Import Expressions and webpack 2 Code Splitting integration with TypeScript 2.4.](https://blog.josequinto.com/2017/06/29/dynamic-import-expressions-and-webpack-code-splitting-integration-with-typescript-2-4/)
:::
================================================
FILE: docs/project/modules.md
================================================
# 模块
## 全局模块
在默认情况下，当你开始在一个新的 TypeScript 文件中写下代码时，它处于全局命名空间中。如在 foo.ts 里的以下代码。
```ts
const foo = 123;
```
如果你在相同的项目里创建了一个新的文件 `bar.ts`，TypeScript 类型系统将会允许你使用变量 `foo`，就好像它在全局可用一样：
```ts
const bar = foo; // allowed
```
毋庸置疑，使用全局变量空间是危险的，因为它会与文件内的代码命名冲突。我们推荐使用下文中将要提到的文件模块。
## 文件模块
文件模块也被称为外部模块。如果在你的 TypeScript 文件的根级别位置含有 `import` 或者 `export`，那么它会在这个文件中创建一个本地的作用域。因此，我们需要把上文 `foo.ts` 改成如下方式（注意 `export` 用法）：
```ts
export const foo = 123;
```
在全局命名空间里，我们不再有 `foo`，这可以通过创建一个新文件 `bar.ts` 来证明：
```ts
const bar = foo; // ERROR: "cannot find name 'foo'"
```
如果你想在 `bar.ts` 里使用来自 `foo.ts` 的内容，你必须显式地导入它，更新后的 `bar.ts` 如下所示。
```ts
import { foo } from './foo';
const bar = foo; // allow
```
在 `bar.ts` 文件里使用 `import` 时，它不仅允许你使用从其他文件导入的内容，还会将此文件 `bar.ts` 标记为一个模块，文件内定义的声明也不会“污染”全局命名空间
## 文件模块详情
文件模块拥有强大的功能和较强的可用性。下面我们来讨论它的功能及一些用法。
### 澄清：commonjs, amd, es modules, others
首先，我们需要澄清这些模块系统的不一致性。我将会提供给你我当前的建议，以及消除一些你的顾虑。
你可以根据不同的 `module` 选项来把 TypeScript 编译成不同的 JavaScript 模块类型，这有一些你可以忽略的东西：
- AMD：不要使用它，它仅能在浏览器工作；
- SystemJS：这是一个好的实验，已经被 ES 模块替代；
- ES 模块：它并没有准备好。
使用 `module: commonjs` 选项来替代这些模式，将会是一个好的主意。
怎么书写 TypeScript 模块呢？，这也是一件让人困惑的事。在今天我们应该这么做：
- 放弃使用 `import/require` 语法即 `import foo = require('foo')` 写法
- 推荐使用 ES 模块语法
这很酷，接下来，让我们看看 ES 模块语法。
:::tip
使用 `module: commonjs` 选项以及使用 ES 模块语法导入、导出、编写模块。
:::
### ES 模块语法
- 使用 `export` 关键字导出一个变量或类型
```ts
// foo.ts
export const someVar = 123;
export type someType = {
foo: string;
};
```
- `export` 的写法除了上面这种，还有另外一种：
```ts
// foo.ts
const someVar = 123;
type someType = {
type: string;
};
export { someVar, someType };
```
- 你也可以用重命名变量的方式导出：
```ts
// foo.ts
const someVar = 123;
export { someVar as aDifferentName };
```
- 使用 `import` 关键字导入一个变量或者是一个类型：
```ts
// bar.ts
import { someVar, someType } from './foo';
```
- 通过重命名的方式导入变量或者类型：
```ts
// bar.ts
import { someVar as aDifferentName } from './foo';
```
- 除了指定加载某个输出值，还可以使用整体加载，即用星号（\*）指定一个对象，所有输出值都加载在这个对象上面：
```ts
// bar.ts
import * as foo from './foo';
// 你可以使用 `foo.someVar` 和 `foo.someType` 以及其他任何从 `foo` 导出的变量或者类型
```
- 只导入模块：
```ts
import 'core-js'; // 一个普通的 polyfill 库
```
- 从其他模块导入后整体导出：
```ts
export * from './foo';
```
- 从其他模块导入后，部分导出：
```ts
export { someVar } from './foo';
```
- 通过重命名，部分导出从另一个模块导入的项目：
```ts
export { someVar as aDifferentName } from './foo';
```
#### 默认导入／导出
我并不喜欢用默认导出，虽然有默认导出的语法：
- 使用 `export default`
- 在一个变量之前（不需要使用 `let/const/var`）；
- 在一个函数之前；
- 在一个类之前。
```ts
// some var
export default (someVar = 123);
// some function
export default function someFunction() {}
// some class
export default class someClass {}
```
- 导入使用 `import someName from 'someModule'` 语法（你可以根据需要为导入命名）：
```ts
import someLocalNameForThisFile from './foo';
```
### 模块路径
:::tip
如果你需要使用 `moduleResolution: node` 选项，你应该将此选项放入你的配置文件中。如果你使用了 `module: commonjs` 选项， `moduleResolution: node` 将会默认开启。
:::
这里存在两种截然不同的模块：
- 相对模块路径（路径以 `.` 开头，例如：`./someFile` 或者 `../../someFolder/someFile` 等）；
- 其他动态查找模块（如：`core-js`，`typestyle`，`react` 或者甚至是 `react/core` 等）。
它们的主要区别在于系统如何解析模块。
:::tip
我将会使用一个概念性术语，`place` -- 将在提及查找模式后解释它。
:::
#### 相对模块路径
这很简单，仅仅是按照相对路径来就可以了：
- 如果文件 `bar.ts` 中含有 `import * as foo from './foo'`，那么 `foo` 文件必须与 `bar.ts` 文件存在于相同的文件夹下
- 如果文件 `bar.ts` 中含有 `import * as foo from '../foo'`，那么 `foo` 文件所存在的地方必须是 `bar.ts` 的上一级目录；
- 如果文件 `bar.ts` 中含有 `import * as foo from '../someFolder/foo'`，那么 `foo` 文件所在的文件夹 `someFolder` 必须与 `bar.ts` 文件所在文件夹在相同的目录下。
你还可以思考一下其他相对路径导入的场景。:smiley:
#### 动态查找
当导入路径不是相对路径时，模块解析将会模仿 [Node 模块解析策略](https://nodejs.org/api/modules.html#modules_all_together)，下面我将给出一个简单例子：
- 当你使用 `import * as foo from 'foo'`，将会按如下顺序查找模块：
- `./node_modules/foo`
- `../node_modules/foo`
- `../../node_modules/foo`
- 直到系统的根目录
- 当你使用 `import * as foo from 'something/foo'`，将会按照如下顺序查找内容
- `./node_modules/something/foo`
- `../node_modules/something/foo`
- `../../node_modules/something/foo`
- 直到系统的根目录
### 什么是 `place`
当我提及被检查的 `place` 时，我想表达的是在这个 `place` 上，TypeScript 将会检查以下内容（例如一个 `foo` 的 `place`）：
- 如果这个 `place` 表示一个文件，如：`foo.ts`，欢呼！
- 否则，如果这个 `place` 是一个文件夹，并且存在一个文件 `foo/index.ts`，欢呼！
- 否则，如果这个 `place` 是一个文件夹，并且存在一个 `foo/package.json` 文件，在该文件中指定 `types` 的文件存在，那么就欢呼！
- 否则，如果这个 `place` 是一个文件夹，并且存在一个 `package.json` 文件，在该文件中指定 `main` 的文件存在，那么就欢呼！
从文件类型上来说，我实际上是指 `.ts`， `.d.ts` 或者 `.js`
就是这样，现在你已经是一个模块查找专家（这并不是一个小小的成功）。
### 重写类型的动态查找
在你的项目里，你可以通过 `declare module 'somePath'` 声明一个全局模块的方式，来解决查找模块路径的问题。
```ts
// global.d.ts
declare module 'foo' {
// some variable declarations
export var bar: number;
}
```
接着 ：
```ts
// anyOtherTsFileInYourProject.ts
import * as foo from 'foo';
// TypeScript 将假设（在没有做其他查找的情况下）
// foo 是 { bar: number }
```
### `import/require` 仅仅是导入类型
以下导入语法：
```ts
import foo = require('foo');
```
它实际上只做了两件事：
- 导入 foo 模块的所有类型信息；
- 确定 foo 模块运行时的依赖关系。
你可以选择仅加载类型信息，而没有运行时的依赖关系。在继续之前，你可能需要重新阅读本书 [声明空间部分](./declarationspaces.md) 部分。
如果你没有把导入的名称当做变量声明空间来用，在编译成 JavaScript 时，导入的模块将会被完全移除。这最好用例子来解释，下面我们将会给出一些示例。
#### 例子 1
```ts
import foo = require('foo');
```
将会编译成 JavaScript：
```js
```
这是正确的，一个没有被使用的空文件。
#### 例子 2
```ts
import foo = require('foo');
var bar: foo;
```
将会被编译成：
```js
let bar;
```
这是因为 foo （或者其他任何属性如：`foo.bas`）没有被当做一个变量使用。
#### 例子 3
```ts
import foo = require('foo');
const bar = foo;
```
将会被编译成（假设是 commonjs）：
```js
const foo = require('foo');
const bar = foo;
```
这是因为 `foo` 被当做变量使用了。
#### 使用例子：懒加载
类型推断需要提前完成，这意味着，如果你想在 `bar` 文件里，使用从其他文件 `foo` 导出的类型，你将不得不这么做：
```ts
import foo = require('foo');
let bar: foo.SomeType;
```
然而，在某些情景下，你只想在需要时加载模块 `foo`，此时你需要仅在类型注解中使用导入的模块名称，而**不**是在变量中使用。在编译成 JavaScript 时，这些将会被移除。接着，你可以手动导入你需要的模块。
作为一个例子，考虑以下基于 `commonjs` 的代码，我们仅在一个函数内导入 `foo` 模块：
```ts
import foo = require('foo');
export function loadFoo() {
// 这是懒加载 foo，原始的加载仅仅用来做类型注解
const _foo: typeof foo = require('foo');
// 现在，你可以使用 `_foo` 替代 `foo` 来作为一个变量使用
}
```
一个同样简单的 `amd` 模块（使用 requirejs）：
```ts
import foo = require('foo');
export function loadFoo() {
// 这是懒加载 foo，原始的加载仅仅用来做类型注解
require(['foo'], (_foo: typeof foo) => {
// 现在，你可以使用 `_foo` 替代 `foo` 来作为一个变量使用
});
}
```
这些通常在以下情景使用：
- 在 web app 里， 当你在特定路由上加载 JavaScript 时；
- 在 node 应用里，当你只想加载特定模块，用来加快启动速度时。
#### 使用例子：打破循环依赖
类似于懒加载的使用用例，某些模块加载器（commonjs/node 和 amd/requirejs）不能很好的处理循环依赖。在这种情况下，一方面我们使用延迟加载代码，并在另一方面预先加载模块是很实用的。
#### 使用例子：确保导入
当你加载一个模块，只是想引入其附加的作用（如：模块可能会注册一些像 [CodeMirror addons](https://codemirror.net/doc/manual.html#addons)）时，然而，如果你仅仅是 `import/require` （导入）一些并没有与你的模块或者模块加载器有任何依赖的 JavaScript 代码，（如：webpack），经过 TypeScript 编译后，这些将会被完全忽视。在这种情况下，你可以使用一个 `ensureImport` 变量，来确保编译的 JavaScript 依赖与模块。如：
```ts
import foo = require('./foo');
import bar = require('./bar');
import bas = require('./bas');
const ensureImport: any = foo || bar || bas;
```
## global.d.ts
在上文中，当我们讨论文件模块时，比较了全局变量与文件模块，并且我们推荐使用基于文件的模块，而不是选择污染全局命名空间。
然而，如果你的团队里有 TypeScript 初学者，你可以提供他们一个 `global.d.ts` 文件，用来将一些接口或者类型放入全局命名空间里，这些定义的接口和类型能在你的所有 TypeScript 代码里使用。
:::tip
对于任何需要编译成 `JavaScript` 的代码，我们强烈建议你放入文件模块里。
:::
- `global.d.ts` 是一种扩充 `lib.d.ts` 很好的方式，如果你需要的话。
- 当你从 `JS` 迁移到 `TS` 时，定义 `declare module "some-library-you-dont-care-to-get-defs-for"` 能让你快速开始。
================================================
FILE: docs/project/namespaces.md
================================================
# 命名空间
在 JavaScript 使用命名空间时， 这有一个常用的、方便的语法：
```js
(function(something) {
something.foo = 123;
})(something || (something = {}));
```
`something || (something = {})` 允许匿名函数 `function (something) {}` 向现有对象添加内容，或者创建一个新对象，然后向该对象添加内容。这意味着你可以拥有两个由某些边界拆成的块。
```js
(function(something) {
something.foo = 123;
})(something || (something = {}));
console.log(something);
// { foo: 123 }
(function(something) {
something.bar = 456;
})(something || (something = {}));
console.log(something); // { foo: 123, bar: 456 }
```
在确保创建的变量不会泄漏至全局命名空间时，这种方式在 JavaScript 中很常见。当基于文件模块使用时，你无须担心这点，但是该模式仍然适用于一组函数的逻辑分组。因此 TypeScript 提供了 `namespace` 关键字来描述这种分组，如下所示。
```ts
namespace Utility {
export function log(msg) {
console.log(msg);
}
export function error(msg) {
console.log(msg);
}
}
// usage
Utility.log('Call me');
Utility.error('maybe');
```
`namespace` 关键字编译后的 JavaScript 代码，与我们早些时候看到的 JavaScript 代码一样。
```js
(function (Utility) {
// 添加属性至 Utility
})(Utility || Utility = {});
```
值得注意的一点是，命名空间是支持嵌套的。因此，你可以做一些类似于在 `Utility` 命名空间下嵌套一个命名空间 `Messaging` 的事情。
对于大多数项目，我们建议使用外部模块和命名空间，来快速演示和移植旧的 JavaScript 代码。
================================================
FILE: docs/tips/avoidExportDefault.md
================================================
# `export default` 被认为是有害的
假如你有一个包含以下内容的 `foo.ts` 文件：
```ts
class Foo {}
export default Foo;
```
你可能会使用 ES6 语法导入它（在 `bar.ts` 里）：
```ts
import Foo from './foo';
```
这存在一些可维护性的问题：
- 如果你在 `foo.ts` 里重构 `Foo`，在 `bar.ts` 文件中，它将不会被重新命名；
- 如果你最终需要从 `foo.ts` 文件中导出更多有用的信息（在你的很多文件中都存在这种情景），那么你必须兼顾导入语法。
由于这些原因，我推荐在导入时使用简单的 `export` 与解构的形式，如 `foo.ts`：
```ts
export class Foo {}
```
接着：
```ts
import { Foo } from './Foo';
```
下面，我将会介绍更多的原因。
## 可发现性差
默认导出的可发现性非常差，你不能智能的辨别一个模块它是否有默认导出。
在使用默认导出时，你什么也没有得到（可能它有默认导出，可能它没有）。
```ts
import /* here */ from 'something';
```
没有默认导出，你可以用以下方式获取智能提示：
```ts
import /* here */ 'something';
```
## 自动完成
不管你是否了解导出，你都可以在 `import { /* here */ } from './foo'` 的 `here` 位置，来了解导出模块的信息。
## CommonJS 互用
对于必须使用 `const { default } = require('module/foo')` 而不是 `const { Foo } = require('module/foo')` 的 CommonJS 的用户来说，这会是一个糟糕的体验。当你导入一个模块时，你很可能想重命名 `default` 作为导入的名字。
## 防止拼写错误
当你在开发时使用 `import Foo from './foo'` 时，并不会得到有关于拼写的任何错误，其他人可能会这么写 `import foo from './foo'`；
## 再次导出
再次导出是没必要的，但是在 `npm` 包的根文件 `index` 却是很常见。如：`import Foo from './foo'；export { Foo }`（默认导出）VS `export * from './foo'` （命名导出）。
## 动态导入
在动态的 `import` 中，默认导出会以 `default` 的名字暴露自己，如：
```ts
const HighChart = await import('https://code.highcharts.com/js/es-modules/masters/highcharts.src.js');
HighChart.default.chart('container', { ... }); // Notice `.default`
```
================================================
FILE: docs/tips/barrel.md
================================================
# Barrel
Barrel 就像是一个容器，它的作用是把分散在多个模块的导出合并到一个模块里导出。一般来说，barrel 本身就是一个包含模块的文件，这个模块做的就是重新导出其他（多个）模块导出的东西。
想象一下，在一个库中，具有如下结构的类。
```ts
// demo/foo.ts
export class Foo {}
// demo/bar.ts
export class Bar {}
// demo/baz.ts
export class Baz {}
```
如果不用 barrel，那么用户在引入时就需要三条 `import` 语句：
```ts
import { Foo } from '../demo/foo';
import { Bar } from '../demo/bar';
import { Baz } from '../demo/baz';
```
但如果我们在同级添加 barrel 文件 `demo/index.ts`，然后这样定义它：
```ts
// demo/index.ts
export * from './foo'; // 重新导出 foo 导出的东西
export * from './bar'; // 重新导出 bar 导出的东西
export * from './baz'; // 重新导出 baz 导出的东西
```
现在，用户就可以直接用一条 `import` 语句从 barrel file 导入所有东西：
```ts
import { Foo, Bar, Baz } from '../demo'; // ../demo，会自动解析成 ../demo/index.ts
```
## 命名导出
除了使用通配符 `*` 导出模块中的所有东西，我们也可以选择要导出什么以及如何导出。试想一个存在多个函数的 `baz.ts`：
```ts
// demo/foo.ts
export class Foo {}
// demo/bar.ts
export class Bar {}
// demo/baz.ts
export function getBaz() {}
export function setBaz() {}
```
如果不想在 `demo` 模块上直接提供 `getBaz` 和 `setBaz` 接口，你可以把它们挂载到一个变量下。你需要做的只是在 barrel file 里导入全部并命名，然后导出命名后的名称即可。
```ts
// demo/index.ts
export * from './foo'; // 重新导出 foo 导出的东西
export * from './bar'; // 重新导出 bar 导出的东西
import * as baz from './baz'; // 导入 baz 中所有的东西，并命名为 baz
export { baz }; // 导出命名后的名称
```
现在，用户需要这样调用：
```ts
import { Foo, Bar, baz } from '../demo'; // ../demo，会自动解析成 ../demo/index.ts
// 使用
baz.getBaz();
baz.setBaz();
// ……
```
================================================
FILE: docs/tips/bind.md
================================================
# Bind 是有害的
::: tip
译者注：在这个 [PR](https://github.com/Microsoft/TypeScript/pull/27028?from=timeline&isappinstalled=0) 下，已经解决 `bind`、`call`、`apply` 类型正确推导的问题，预计在 3.2 版本中发布。
:::
这是在 `lib.d.ts` 中 `bind` 的定义：
```ts
bind(thisArg: any, ...argArray: any[]): any
```
你可以看到他的返回值是 `any`，这意味着在函数上调用 `bind` 会导致你在原始函数调用签名上将会完全失去类型的安全检查。
如下所示：
```ts
function twoParams(a: number, b: number) {
return a + b;
}
let curryOne = twoParams.bind(null, 123);
curryOne(456); // ok
curryOne('456'); // ok
```
一个更好的方式的是使用类型注解的箭头函数：
```ts
function twoParams(a: number, b: number) {
return a + b;
}
let curryOne = (x: number) => twoParams(123, x);
curryOne(456); // ok
curryOne('456'); // Error
```
如果你想用一个柯里化的函数，你可以看看[此章节](./curry.md)：
## 类成员
另一个常见用途是在传递类函数时使用 `bind` 来确保 `this` 的正确值，不要这么做。
在接下来的示例中，如果你使用了 `bind`，你将会失去函数参数的类型安全：
```ts
class Adder {
constructor(public a: string) {}
add(b: string): string {
return this.a + b;
}
}
function useAdd(add: (x: number) => number) {
return add(456);
}
let adder = new Adder('mary had a little 🐑');
useAdd(adder.add.bind(adder)); // 没有编译的错误
useAdd(x => adder.add(x)); // Error: number 不能分配给 string
```
如果你想传递一个类成员的函数，使用箭头函数。例如：
```ts
class Adder {
constructor(public a: string) {}
// 此时，这个函数可以安全传递
add = (b: string): string => {
return this.a + b;
};
}
```
另一种方法是手动指定要绑定的变量的类型：
```ts
const add: typeof adder.add = adder.add.bind(adder);
```
================================================
FILE: docs/tips/buildToggles.md
================================================
# 构建切换
根据 JavaScript 项目的运行环境进行切换环境变量是很常见的，通过 webpack 可以很轻松地做到这一点，因为它支持基于环境变量的死代码排除。
在你的 `package.json script` 里，添加不同的编译目标：
```json
"build:test": "webpack -p --config ./src/webpack.config.js",
"build:prod": "webpack -p --define process.env.NODE_ENV='\"production\"' --config ./src/webpack.config.js"
```
当然，假设你已经安装了 webpack `npm install webpack`，现在，你可以运行 `npm run build:test` 了。
使用环境变量也超级简单：
```ts
/**
* This interface makes sure we don't miss adding a property to both `prod` and `test`
*/
interface Config {
someItem: string;
}
/**
* We only export a single thing. The config.
*/
export let config: Config;
/**
* `process.env.NODE_ENV` definition is driven from webpack
*
* The whole `else` block will be removed in the emitted JavaScript
* for a production build
*/
if (process.env.NODE_ENV === 'production') {
config = {
someItem: 'prod'
};
console.log('Running in prod');
} else {
config = {
someItem: 'test'
};
console.log('Running in test');
}
```
::: tip
我们使用 `process.env.NODE_ENV` 仅仅是因为绝大多数 JavaScript 库中都使用此变量，例如：`React`。
:::
================================================
FILE: docs/tips/classAreUseful.md
================================================
# 类是有用的
以下结构在应用中很常见：
```ts
function foo() {
let someProperty;
// 一些其他的初始化代码
function someMethod() {
// 用 someProperty 做一些事情
// 可能有其他属性
}
// 可能有其他的方法
return {
someMethod
// 可能有其他方法
};
}
```
它被称为模块模式（利用 JavaScript 的闭包）。
如果你使用[文件模块](../project/modules.md#文件模块)（你确实应该将全局变量视为错误），文件中的代码与示例一样，都不是全局变量。
然而，开发者有时会写以下类似代码：
```ts
let someProperty;
function foo() {
// 一些初始化代码
}
foo();
someProperty = 123; // 其他初始化代码
// 一些其它未导出
// later
export function someMethod() {}
```
尽管我并不是一个特别喜欢使用**继承**的人，但是我确实发现让开发者使用类，可以在一定程度上更好的组织他们的代码，例如：
```ts
class Foo {
public someProperty;
constructor() {
// 一些初始化内容
}
public someMethod() {
// ..code
}
public someUtility() {
// .. code
}
}
export = new Foo();
```
这并不仅仅有利于开发者，在创建基于类的更出色可视化工具中，它更常见。并且，这有利于项目的理解和维护。
::: tip
在浅层次的结构中，如果它们能够提供明显的重复使用和减少模版的好处，那么在这个观点里，我并没有错误。
:::
================================================
FILE: docs/tips/covarianceAndContravariance.md
================================================
# 协变与逆变
> [原文链接: what are covariance and contravariance](https://www.stephanboyer.com/post/132/what-are-covariance-and-contravariance)
[子类型](https://en.wikipedia.org/wiki/Subtyping) 在编程理论上是一个复杂的话题，而他的复杂之处来自于一对经常会被混淆的现象，我们称之为*协变*与*逆变*。这篇文章将会解释上述两个概念。
开始文章之前我们先约定如下的标记：
- `A ≼ B` 意味着 `A` 是 `B` 的子类型。
- `A → B` 指的是以 `A` 为参数类型，以 `B` 为返回值类型的函数类型。
- `x : A` 意味着 `x` 的类型为 `A`。
## 一个有趣的问题
假设我有如下三种类型：
> `Greyhound ≼ Dog ≼ Animal`
`Greyhound` （灰狗）是 `Dog` （狗）的子类型，而 `Dog` 则是 `Animal` （动物）的子类型。由于子类型通常是可传递的，因此我们也称 `Greyhound` 是 `Animal` 的子类型。
**问题**：以下哪种类型是 `Dog → Dog` 的子类型呢？
1. `Greyhound → Greyhound`
2. `Greyhound → Animal`
3. `Animal → Animal`
4. `Animal → Greyhound`
让我们来思考一下如何解答这个问题。首先我们假设 `f` 是一个以 `Dog → Dog` 为参数的函数。它的返回值并不重要，为了具体描述问题，我们假设函数结构体是这样的： `f : (Dog → Dog) → String`。
现在我想给函数 `f` 传入某个函数 `g` 来调用。我们来瞧瞧当 `g` 为以上四种类型时，会发生什么情况。
**1. 我们假设 `g : Greyhound → Greyhound`， `f(g)` 的类型是否安全？**
不安全，因为在f内调用它的参数`(g)`函数时，使用的参数可能是一个不同于灰狗但又是狗的子类型，例如 `GermanShepherd` （牧羊犬）。
**2. 我们假设 `g : Greyhound → Animal`， `f(g)` 的类型是否安全？**
不安全。理由同(1)。
**3. 我们假设 `g : Animal → Animal`， `f(g)` 的类型是否安全？**
不安全。因为 `f` 有可能在调用完参数之后，让返回值，也就是 `Animal` （动物）狗叫。并非所有动物都会狗叫。
**4. 我们假设 `g : Animal → Greyhound`， `f(g)` 的类型是否安全？**
是的，它的类型是安全的。首先，`f` 可能会以任何狗的品种来作为参数调用，而所有的狗都是动物。其次，它可能会假设结果是一条狗，而所有的灰狗都是狗。
## 展开讲讲？
如上所述，我们得出结论：
> `(Animal → Greyhound) ≼ (Dog → Dog)`
返回值类型很容易理解：灰狗是狗的子类型。但参数类型则是相反的：动物是狗的*父类*！
用合适的术语来描述这个奇怪的表现，可以说我们允许一个函数类型中，返回值类型是*协变*的，而参数类型是*逆变*的。返回值类型是协变的，意思是 `A ≼ B` 就意味着 `(T → A) ≼ (T → B)` 。参数类型是逆变的，意思是 `A ≼ B` 就意味着 `(B → T) ≼ (A → T)` （ `A` 和 `B` 的位置颠倒过来了）。
**一个有趣的现象**：在 `TypeScript` 中， [参数类型是双向协变的](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-function-parameters-bivariant)
，也就是说既是协变又是逆变的，而这并不安全。但是现在你可以在 [`TypeScript 2.6`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html) 版本中通过 `--strictFunctionTypes` 或 `--strict` 标记来修复这个问题。
## 那其他类型呢？
**问题**：`List` 能否为 `List` 的子类型？
答案有点微妙。如果列表是不可变的（immutable），那么答案是肯定的，因为类型很安全。但是假如列表是可变的，那么答案绝对是否定的！
原因是，假设我需要一串 `List` 而你传给我一串 `List`。由于我认为我拥有的是一串 `List` ，我可能会尝试往列表插入一只 `Cat`。那么你的 `List` 里面就会有一只猫！类型系统不应该允许这种情况发生。
总结一下，我们可以允许不变的列表（immutable）在它的参数类型上是协变的，但是对于可变的列表（mutable），其参数类型则必须是不变的（invariant），既不是协变也不是逆变。
**一个有趣的现象**：在 `Java` 中，数组[既是可变的，又是协变的](https://en.wikipedia.org/wiki/Covariance_and_contravariance_%28computer_science%29#Covariant_arrays_in_Java_and_C.23)。当然，这并不安全。
================================================
FILE: docs/tips/createArrays.md
================================================
# 创建数组
创建数组十分简单：
```ts
const foo: string[] = [];
```
你也可以在创建数组时使用 ES6 的 `Array.prototype.fill` 方法为数组填充数据：
```ts
const foo: string[] = new Array(3).fill('');
console.log(foo); // 会输出 ['','','']
```
================================================
FILE: docs/tips/curry.md
================================================
# 柯里化
仅仅需要使用一系列箭头函数：
```ts
// 一个柯里化函数
let add = (x: number) => (y: number) => x + y;
// 简单使用
add(123)(456);
// 部分应用
let add123 = add(123);
// fully apply the function
add123(456);
```
================================================
FILE: docs/tips/functionParameters.md
================================================
# 函数参数
如果你有一个含有很多参数或者相同类型参数的函数，那么你可能需要考虑将函数改为接收对象的形式：
如下一个函数：
```ts
function foo(flagA: boolean, flagB: boolean) {
// 函数主体
}
```
像这样的函数，你可能会很容易错误的调用它，如 `foo(flagB, flagA)`，并且你并不会从编译器得到想要的帮助。
你可以将函数变为接收对象的形式：
```ts
function foo(config: { flagA: boolean; flagB: boolean }) {
const { flagA, flagB } = config;
}
```
现在，函数将会被 `foo({ flagA, flagB })` 的形式调用，这样有利于发现错误及代码审查。
::: tip
如果你的函数足够简单，并且你不希望增加代码，忽略这个建议。
:::
================================================
FILE: docs/tips/infer.md
================================================
# infer
## 介绍
`infer` 最早出现在此 [PR](https://github.com/Microsoft/TypeScript/pull/21496) 中，表示在 `extends` 条件语句中待推断的类型变量。
简单示例如下：
```ts
type ParamType = T extends (arg: infer P) => any ? P : T;
```
在这个条件语句 `T extends (arg: infer P) => any ? P : T` 中，`infer P` 表示待推断的函数参数。
整句表示为：如果 `T` 能赋值给 `(arg: infer P) => any`，则结果是 `(arg: infer P) => any` 类型中的参数 `P`，否则返回为 `T`。
```ts
interface User {
name: string;
age: number;
}
type Func = (user: User) => void;
type Param = ParamType; // Param = User
type AA = ParamType; // string
```
## 内置类型
在 2.8 版本中，TypeScript 内置了一些与 `infer` 有关的映射类型：
- 用于提取函数类型的返回值类型：
```ts
type ReturnType = T extends (...args: any[]) => infer P ? P : any;
```
相比于文章开始给出的示例，`ReturnType` 只是将 `infer P` 从参数位置移动到返回值位置，因此此时 `P` 即是表示待推断的返回值类型。
```ts
type Func = () => User;
type Test = ReturnType; // Test = User
```
- 用于提取构造函数中参数（实例）类型：
一个构造函数可以使用 `new` 来实例化，因此它的类型通常表示如下：
```ts
type Constructor = new (...args: any[]) => any;
```
当 `infer` 用于构造函数类型中，可用于参数位置 `new (...args: infer P) => any;` 和返回值位置 `new (...args: any[]) => infer P;`。
因此就内置如下两个映射类型：
```ts
// 获取参数类型
type ConstructorParameters any> = T extends new (...args: infer P) => any
? P
: never;
// 获取实例类型
type InstanceType any> = T extends new (...args: any[]) => infer R ? R : any;
class TestClass {
constructor(public name: string, public age: number) {}
}
type Params = ConstructorParameters; // [string, number]
type Instance = InstanceType; // TestClass
```
## 一些用例
至此，相信你已经对 `infer` 已有基本了解，我们来看看一些使用它的「骚操作」：
- **tuple** 转 **union** ，如：`[string, number]` -> `string | number`
解答之前，我们需要了解 tuple 类型在一定条件下，是可以赋值给数组类型：
```ts
type TTuple = [string, number];
type TArray = Array;
type Res = TTuple extends TArray ? true : false; // true
type ResO = TArray extends TTuple ? true : false; // false
```
因此，在配合 `infer` 时，这很容易做到：
```ts
type ElementOf = T extends Array ? E : never;
type TTuple = [string, number];
type ToUnion = ElementOf; // string | number
```
在 [stackoverflow](https://stackoverflow.com/questions/44480644/typescript-string-union-to-string-array/45486495#45486495) 上看到另一种解法，比较简（牛）单（逼）：
```ts
type TTuple = [string, number];
type Res = TTuple[number]; // string | number
```
- **union** 转 **intersection**，如：`T1 | T2` -> `T1 & T2`
这个可能要稍微麻烦一点，需要 `infer` 配合「 [Distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types) 」使用。
在[相关链接](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types)中，我们可以了解到「Distributive conditional types」是由「naked type parameter」构成的条件类型。而「naked type parameter」表示没有被 `Wrapped` 的类型（如：`Array`、`[T]`、`Promise` 等都是不是「naked type parameter」）。「Distributive conditional types」主要用于拆分 `extends` 左边部分的联合类型，举个例子：在条件类型 `T extends U ? X : Y` 中，当 `T` 是 `A | B` 时，会拆分成 `A extends U ? X : Y | B extends U ? X : Y`；
有了这个前提，再利用在逆变位置上，[同一类型变量的多个候选类型将会被推断为交叉类型](https://github.com/Microsoft/TypeScript/pull/21496)的特性，即
```ts
type T1 = { name: string };
type T2 = { age: number };
type Bar = T extends { a: (x: infer U) => void; b: (x: infer U) => void } ? U : never;
type T20 = Bar<{ a: (x: string) => void; b: (x: string) => void }>; // string
type T21 = Bar<{ a: (x: T1) => void; b: (x: T2) => void }>; // T1 & T2
```
因此，综合以上几点，我们可以得到在 [stackoverflow](https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type) 上的一个答案：
```ts
type UnionToIntersection = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
type Result = UnionToIntersection; // T1 & T2
```
当传入 `T1 | T2` 时：
- 第一步：`(U extends any ? (k: U) => void : never)` 会把 union 拆分成 `(T1 extends any ? (k: T1) => void : never) | (T2 extends any ? (k: T2)=> void : never)`，即是得到 `(k: T1) => void | (k: T2) => void`；
- 第二步：`(k: T1) => void | (k: T2) => void extends ((k: infer I) => void) ? I : never`，根据上文，可以推断出 `I` 为 `T1 & T2`。
当然，你可以玩出更多花样，比如 [**union** 转 **tuple**](https://zhuanlan.zhihu.com/p/58704376)。
## LeetCode 的一道 TypeScript 面试题
前段时间，在 [GitHub](https://github.com/LeetCode-OpenSource/hire/blob/master/typescript_zh.md) 上，发现一道来自 LeetCode TypeScript 的面试题，比较有意思，题目的大致意思是：
假设有一个这样的类型（原题中给出的是类，这里简化为 interface）：
```ts
interface Module {
count: number;
message: string;
asyncMethod(input: Promise): Promise>;
syncMethod(action: Action): Action;
}
```
在经过 `Connect` 函数之后，返回值类型为
```ts
type Result = {
asyncMethod(input: T): Action;
syncMethod(action: T): Action;
}
```
其中 `Action` 的定义为：
```ts
interface Action {
payload?: T;
type: string;
}
```
这里主要考察两点
- 挑选出函数
- 此篇文章所提及的 `infer`
挑选函数的方法，已经在 [handbook](http://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html) 中已经给出，只需判断 value 能赋值给 Function 就行了：
```ts
type FuncName = { [P in keyof T]: T[P] extends Function ? P : never }[keyof T];
type Connect = (module: Module) => { [T in FuncName]: Module[T] };
/*
* type Connect = (module: Module) => {
* asyncMethod: (input: Promise) => Promise>;
* syncMethod: (action: Action) => Action;
* }
*/
```
接下来就比较简单了，主要是利用条件类型 + `infer`，如果函数可以赋值给 `asyncMethod(input: Promise): Promise>`，则取值为 `asyncMethod(input: T): Action`。具体答案就不给出了，感兴趣的小伙伴可以尝试一下。
================================================
FILE: docs/tips/lazyObjectLiteralInitialization.md
================================================
# 对象字面量的惰性初始化
在 JavaScript 中，像这样用字面量初始化对象的写法十分常见：
```ts
let foo = {};
foo.bar = 123;
foo.bas = 'Hello World';
```
但在 TypeScript 中，同样的写法就会报错：
```ts
let foo = {};
foo.bar = 123; // Error: Property 'bar' does not exist on type '{}'
foo.bas = 'Hello World'; // Error: Property 'bas' does not exist on type '{}'
```
这是因为 TypeScript 在解析 `let foo = {}` 这段赋值语句时，会进行“类型推断”：它会认为等号左边 `foo` 的类型即为等号右边 `{}` 的类型。由于 `{}` 本没有任何属性，因此，像上面那样给 `foo` 添加属性时就会报错。
## 最好的解决方案
最*好*的解决方案就是在为变量赋值的同时，添加属性及其对应的值：
```ts
let foo = {
bar: 123,
bas: 'Hello World'
};
```
这种写法也比较容易通过其他人或工具的代码审核，对后期维护也是有利的。
> 以下的快速解决方案采用*惰性*的思路，本质上是*在初始化变量时忘了添加属性*的做法。
## 快速解决方案
如果你的 JavaScript 项目很大，那么在迁移到 TypeScript 的时候，上面的做法可能会比较麻烦。此时，你可以利用 TypeScript 的“类型断言”机制让代码顺利通过编译：
```ts
let foo = {} as any;
foo.bar = 123;
foo.bas = 'Hello World';
```
## 折中的解决方案
当然，总是用 `any` 肯定是不好的，因为这样做其实是在想办法绕开 TypeScript 的类型检查。那么，折中的方案就是创建 `interface`，这样的好处在于：
- 方便撰写类型文档
- TypeScript 会参与类型检查，确保类型安全
请看以下的示例：
```ts
interface Foo {
bar: number;
bas: string;
}
let foo = {} as Foo;
foo.bar = 123;
foo.bas = 'Hello World';
```
使用 `interface` 可以确保类型安全，比如这种情况：
```ts
interface Foo {
bar: number;
bas: string;
}
let foo = {} as Foo;
foo.bar = 123;
foo.bas = 'Hello World';
// 然后我们尝试这样做：
foo.bar = 'Hello Stranger'; // 错误：你可能把 `bas` 写成了 `bar`，不能为数字类型的属性赋值字符串
```
================================================
FILE: docs/tips/limitPropertySetters.md
================================================
# 减少 setter 属性的使用
倾向于使用更精确的 `set/get` 函数（如 `setBar`, `getBar`），减少使用 `setter/getter`；
考虑以下代码：
```ts
foo.bar = {
a: 123,
b: 456
};
```
存在 `setter/getter` 时：
```ts
class Foo {
a: number;
b: number;
set bar(value: { a: number; b: number }) {
this.a = value.a;
this.b = value.b;
}
}
let foo = new Foo();
```
这并不是 `setter` 的一个好的使用场景，当开发人员阅读第一段代码时，不知道将要更改的所有内容的上下文。然而，当开发者使用 `foo.setBar(value)`，他可能会意识到在 `foo` 里可能会引起一些改变。
================================================
FILE: docs/tips/metadata.md
================================================
# Reflect Metadata
## 基础
Reflect Metadata 是 ES7 的一个提案，它主要用来在声明的时候添加和读取元数据。TypeScript 在 1.5+ 的版本已经支持它，你只需要：
- `npm i reflect-metadata --save`。
- 在 `tsconfig.json` 里配置 `emitDecoratorMetadata` 选项。
Reflect Metadata 的 API 可以用于类或者类的属性上，如：
```ts
function metadata(
metadataKey: any,
metadataValue: any
): {
(target: Function): void;
(target: Object, propertyKey: string | symbol): void;
};
```
`Reflect.metadata` 当作 `Decorator` 使用，当修饰类时，在类上添加元数据，当修饰类属性时，在类原型的属性上添加元数据，如：
```ts
@Reflect.metadata('inClass', 'A')
class Test {
@Reflect.metadata('inMethod', 'B')
public hello(): string {
return 'hello world';
}
}
console.log(Reflect.getMetadata('inClass', Test)); // 'A'
console.log(Reflect.getMetadata('inMethod', new Test(), 'hello')); // 'B'
```
它具有诸多使用场景。
## 获取类型信息
譬如在 [`vue-property-decorator`](https://github.com/kaorun343/vue-property-decorator) 6.1 及其以下版本中，通过使用 `Reflect.getMetadata` API，`Prop` Decorator 能获取属性类型传至 Vue，简要代码如下：
```ts
function Prop(): PropertyDecorator {
return (target, key: string) => {
const type = Reflect.getMetadata('design:type', target, key);
console.log(`${key} type: ${type.name}`);
// other...
};
}
class SomeClass {
@Prop()
public Aprop!: string;
}
```
运行代码可在控制台看到 `Aprop type: string`。除能获取属性类型外，通过 `Reflect.getMetadata("design:paramtypes", target, key)` 和 `Reflect.getMetadata("design:returntype", target, key)` 可以分别获取函数参数类型和返回值类型。
## 自定义 `metadataKey`
除能获取类型信息外，常用于自定义 `metadataKey`，并在合适的时机获取它的值，示例如下：
```ts
function classDecorator(): ClassDecorator {
return target => {
// 在类上定义元数据，key 为 `classMetaData`，value 为 `a`
Reflect.defineMetadata('classMetaData', 'a', target);
};
}
function methodDecorator(): MethodDecorator {
return (target, key, descriptor) => {
// 在类的原型属性 'someMethod' 上定义元数据，key 为 `methodMetaData`，value 为 `b`
Reflect.defineMetadata('methodMetaData', 'b', target, key);
};
}
@classDecorator()
class SomeClass {
@methodDecorator()
someMethod() {}
}
Reflect.getMetadata('classMetaData', SomeClass); // 'a'
Reflect.getMetadata('methodMetaData', new SomeClass(), 'someMethod'); // 'b'
```
## 例子
### 控制反转和依赖注入
在 Angular 2+ 的版本中，[控制反转与依赖注入](https://segmentfault.com/a/1190000008626680)便是基于此实现，现在，我们来实现一个简单版：
```ts
type Constructor = new (...args: any[]) => T;
const Injectable = (): ClassDecorator => target => {};
class OtherService {
a = 1;
}
@Injectable()
class TestService {
constructor(public readonly otherService: OtherService) {}
testMethod() {
console.log(this.otherService.a);
}
}
const Factory = (target: Constructor): T => {
// 获取所有注入的服务
const providers = Reflect.getMetadata('design:paramtypes', target); // [OtherService]
const args = providers.map((provider: Constructor) => new provider());
return new target(...args);
};
Factory(TestService).testMethod(); // 1
```
### Controller 与 Get 的实现
如果你在使用 TypeScript 开发 Node 应用，相信你对 `Controller`、`Get`、`POST` 这些 Decorator，并不陌生：
```ts
@Controller('/test')
class SomeClass {
@Get('/a')
someGetMethod() {
return 'hello world';
}
@Post('/b')
somePostMethod() {}
}
```
这些 Decorator 也是基于 `Reflect Metadata` 实现，这次，我们将 `metadataKey` 定义在 `descriptor` 的 `value` 上：
```ts
const METHOD_METADATA = 'method'；
const PATH_METADATA = 'path'；
const Controller = (path: string): ClassDecorator => {
return target => {
Reflect.defineMetadata(PATH_METADATA, path, target);
}
}
const createMappingDecorator = (method: string) => (path: string): MethodDecorator => {
return (target, key, descriptor) => {
Reflect.defineMetadata(PATH_METADATA, path, descriptor.value);
Reflect.defineMetadata(METHOD_METADATA, method, descriptor.value);
}
}
const Get = createMappingDecorator('GET');
const Post = createMappingDecorator('POST');
```
接着，创建一个函数，映射出 `route`：
```ts
function mapRoute(instance: Object) {
const prototype = Object.getPrototypeOf(instance);
// 筛选出类的 methodName
const methodsNames = Object.getOwnPropertyNames(prototype)
.filter(item => !isConstructor(item) && isFunction(prototype[item]))；
return methodsNames.map(methodName => {
const fn = prototype[methodName];
// 取出定义的 metadata
const route = Reflect.getMetadata(PATH_METADATA, fn);
const method = Reflect.getMetadata(METHOD_METADATA, fn)；
return {
route,
method,
fn,
methodName
}
})
};
```
因此，我们可以得到一些有用的信息：
```ts
Reflect.getMetadata(PATH_METADATA, SomeClass); // '/test'
mapRoute(new SomeClass());
/**
* [{
* route: '/a',
* method: 'GET',
* fn: someGetMethod() { ... },
* methodName: 'someGetMethod'
* },{
* route: '/b',
* method: 'POST',
* fn: somePostMethod() { ... },
* methodName: 'somePostMethod'
* }]
*
*/
```
最后，只需把 `route` 相关信息绑在 `express` 或者 `koa` 上就 ok 了。
================================================
FILE: docs/tips/nominalTyping.md
================================================
# 名义化类型
TypeScript 的类型系统是结构化的，[这也是其主要的优点之一](https://basarat.gitbooks.io/typescript/content/docs/why-typescript.html)。然而，在实际的特定用例中，有时尽管变量具有相同的结构，你也想将他们视为不同类型。一个非常常见的用例是身份类型结构（它们可能只是在 C# 或者 Java 中表示一个它们语义化名字的字符串）。
这有一些社区使用的方式，我按照个人喜好降序排列：
## 使用字面量类型
这种模式使用泛型和字面量类型：
```ts
// 泛型 Id 类型
type Id = {
type: T;
value: string;
};
// 特殊的 Id 类型
type FooId = Id<'foo'>;
type BarId = Id<'bar'>;
// 可选：构造函数
const createFoo = (value: string): FooId => ({ type: 'foo', value });
const createBar = (value: string): BarId => ({ type: 'bar', value });
let foo = createFoo('sample');
let bar = createBar('sample');
foo = bar; // Error
foo = foo; // Okey
```
- 优点
- 不需要类型断言。
- 缺点
- 如上结构 `{type,value}` 可能不那么尽如人意，而且需要服务器序列化支持。
## 使用枚举
TypeScript 中[枚举](../typings/enums.md) 提供一定程度的名义化类型。如果两个枚举的命名不相同，则它们类型不相等。我们可以利用这个事实来为结构上兼容的类型，提供名义化类型。
解决办法包括：
- 创建一个只有名字的枚举；
- 利用这个枚举与实际结构体创建一个交叉类型（`&`）。
如下所示，当实际结构体仅仅是一个字符串时：
```ts
// FOO
enum FooIdBrand {
_ = ''
}
type FooId = FooIdBrand & string;
// BAR
enum BarIdBrand {
_ = ''
}
type BarId = BarIdBrand & string;
// user
let fooId: FooId;
let barId: BarId;
// 类型安全
fooId = barId; // error
barId = fooId; // error
// 创建一个新的
fooId = 'foo' as FooId;
barId = 'bar' as BarId;
// 两种类型都与基础兼容
let str: string;
str = fooId;
str = barId;
```
请注意上文中的 `FooIdBrand` 与 `BarIdBrand`，它们都有一个 `_` 映射到空字符串的成员，即 `{ _ = '' }`。这可以强制 TypeScript 推断出这是一个基于字符串的枚举，而不是一个数字类型的枚举。这是很重要的，因为 TypeScript 会把一个空的枚举类型（`{}`）推断为一个数字类型的枚举，在 TypeScript 3.6.2 版本及其以上时，数字类型的枚举与 `string` 的交叉类型是 `never`。
## 使用接口
因为 `number` 类型与 `enum` 类型在类型上是兼容的，因此我们不能使用上述提到的方法来处理它们。取而代之，我们可以使用接口打破这种类型的兼容性。TypeScript 编译团队仍然在使用这种方法，因此它值得一提。使用 `_` 前缀和 `Brand` 后缀是一种我强烈推荐的惯例方法（[TypeScript 也这么推荐](https://github.com/Microsoft/TypeScript/blob/7b48a182c05ea4dea81bab73ecbbe9e013a79e99/src/compiler/types.ts#L693-L698)）。
解决办法包括：
- 在类型上添加一个不用的属性，用来打破类型兼容性；
- 在新建或向下转换类型的时候使用断言。
如下所示：
```ts
// FOO
interface FooId extends String {
_fooIdBrand: string; // 防止类型错误
}
// BAR
interface BarId extends String {
_barIdBrand: string; // 防止类型错误
}
// 使用
let fooId: FooId;
let barId: BarId;
// 类型安全
fooId = barId; // error
barId = fooId; // error
fooId = barId; // error
barId = fooId; // error
// 创建新的
fooId = 'foo' as any;
barId = 'bar' as any;
// 如果你需要以字符串作为基础
var str: string;
str = fooId as any;
str = barId as any;
```
================================================
FILE: docs/tips/outFileCaution.md
================================================
# 谨慎使用 `--outFile`
由于以下几点原因，你应该谨慎使用 `--outFile` 选项：
- 运行时的错误；
- 快速编译；
- 全局作用域；
- 难以分析；
- 难以扩展；
- `_references`；
- 代码重用；
- 多目标；
- 单独编译；
## 运行时的错误
如果你的代码依赖于上文中的 JavaScript，你可能会在运行时得到错误：
- 类的继承在运行时中断。
有如下 `foo.ts`：
```ts
class Foo {}
```
以及 `bar.ts`：
```ts
class Bar extends Foo {}
```
如果你没有按正确的顺序编译它（例如：`tsc bar.ts foo.ts`），虽然它能够被编译成功，但是会在运行时抛出 `ReferenceError` 的错误。
- 模块拆分在运行时会失败。
`foo.ts`：
```ts
namespace App {
export const foo = 123;
}
```
`bar.ts`：
```ts
namespace App {
export const bar = foo + 456;
}
```
与上文中一致，当你没有用正确的顺序编译它，它会在运行时将 `NaN` 赋值给 `bar`；
## 快速编译
如果你使用 `--out` 编译选项，而没有使用一些 `hacks` 时，单独的 `.ts` 文件是不会被编译成单独的 `.js` 文件。 `--out` 选项实际上使用了较慢的构建方式。
此外，由于 source map 基于长度编码，且对位置信息敏感，因此，大部分 source map 都会在编译时重新构建（如果你使用 source map）。
## 全局作用域
当然，你可以使用命名空间，但是它仍然在 `window` 上（如果你在浏览器中打开），命名空间仅仅是一个临时的解决方式。`/// {
this.count++;
console.log(`Called : ${this.count}`);
};
}();
called(); // Called : 1
called(); // Called : 2
```
================================================
FILE: docs/tips/staticConstructors.md
================================================
# TypeScript 中的静态构造函数
TypeScript 中的 `class` （JavaScript 中的 `class`）没有静态构造函数的功能，但是你可以通过调用它自己来获取相同的效果：
```ts
class MyClass {
static initalize() {
//
}
}
MyClass.initalize();
```
================================================
FILE: docs/tips/stringBasedEmuns.md
================================================
# 基于字符串的枚举
有时你需要在公共的键下收集一些字符串的集合。在 TypeScript 2.4 以前，它仅支持基于数字类型的枚举，如果你在使用 TypeScript 2.4 以上的版本，你通过可以使用[字符串字面量类型与联合类型组合使用创建基于字符串枚举类型的方式](../typings/literals.md#使用用例)。
================================================
FILE: docs/tips/truthy.md
================================================
# Truthy
JavaScript 有一个 `truthy` 概念，即在某些场景下会被推断为 `true`，例如除 `0` 以外的任何数字：
```ts
if (123) {
// 将会被推断出 `true`
console.log('Any number other than 0 is truthy');
}
```
你可以用下表来做参考：
| **Variable Type** | **When it is falsy** | **When it is truthy** |
| ------------------------------------------------ | -------------------- | --------------------- |
| boolean | false | true |
| string | ' ' (empty string) | any other string |
| number | 0 NaN | any other number |
| null | always | never |
| Any other Object including empty ones like {},[] | never | always |
## 明确的
通过操作符 `!!`，你可以很容易的将某些值转化为布尔类型的值，例如：`!!foo`，它使用了两次 `!`，第一个 `!` 用来将其（在这里是 `foo`）转换为布尔值，但是这一操作取得的是其取反后的值，第二个取反时，能得到真正的布尔值。
这在很多地方都可以看到：
```ts
// Direct variables
const hasName = !!name;
// As members of objects
const someObj = {
hasName: !!name
};
// ReactJS
{
!!someName && {someName}
;
}
```
================================================
FILE: docs/tips/typeInstantiation.md
================================================
# 泛型的实例化类型
假如你有一个具有泛型参数的类型，如一个类 `Foo`：
```ts
class Foo {
foo: T;
}
```
你想为一个特定的类型创建单独的版本，可以通过将它拷贝到一个新变量里，并且用具体类型代替泛型的类型注解的方式来实现。例如，如果你想有一个类：`Foo`：
```ts
class Foo {
foo: T;
}
const FooNumber = Foo as { new (): Foo }; // ref 1
```
在 `ref 1` 中，你说 `FooNumber` 与 `Foo` 相同，但是，只是将其看作使用 `new` 运算符调用时的一个 `Foo` 实例。
## 继承
类型断言模式是不安全的，因为编译器相信你在做正确的事情。在其他语言中用于类的常见模式是使用继承：
```ts
class FooNumber extends Foo {}
```
::: warning
这里需要注意的一点，如果你在基类上使用修饰器，继承类可能没有与基类相同的行为（它不再被修饰器包裹）。
:::
当然，如果你不需要一个单独的类，你仍然写出一个有效的强制/断言模式，因此在开始时，我们便展示出了普通的断言模式：
```ts
function id(x: T) {
return x;
}
const idNum = id as { (x: number): number };
```
> 灵感来源于：[stackoverflow question](https://stackoverflow.com/questions/34859911/instantiated-polymorphic-function-as-argument-in-typescript/34864705#34864705)
================================================
FILE: docs/tips/typesafeEventEmitter.md
================================================
# 类型安全的 Event Emitter
通常来说，在 Node.js 与传统的 JavaScript 里，你有一个单一的 Event Emitter，你可以用它来为不同的事件添加监听器。
```ts
const emitter = new EventEmitter();
// Emit
emitter.emit('foo', foo);
emitter.emit('bar', bar);
// Listen
emitter.on('foo', foo => console.log(foo));
emitter.on('bar', bar => console.log(bar));
```
实际上，在 `EventEmitter` 内部以映射数组的形式存储数据：
```ts
{ foo: [fooListeners], bar: [barListeners] }
```
为了事件的类型安全，你可以为每个事件类型创建一个 emitter：
```ts
const onFoo = new TypedEvent();
const onBar = new TypedEvent();
// Emit:
onFoo.emit(foo);
onBar.emit(bar);
// Listen:
onFoo.on(foo => console.log(foo));
onBar.on(bar => console.log(bar));
```
它一些优点：
- 事件的类型，能以变量的形式被发现。
- Event Emitter 非常容易被重构。
- 事件数据结构是类型安全的。
## 参考 TypedEvent
```ts
export interface Listener {
(event: T): any;
}
export interface Disposable {
dispose(): any;
}
export class TypedEvent {
private listeners: Listener[] = [];
private listenersOncer: Listener[] = [];
public on = (listener: Listener): Disposable => {
this.listeners.push(listener);
return {
dispose: () => this.off(listener)
};
};
public once = (listener: Listener): void => {
this.listenersOncer.push(listener);
};
public off = (listener: Listener) => {
const callbackIndex = this.listeners.indexOf(listener);
if (callbackIndex > -1) this.listeners.splice(callbackIndex, 1);
};
public emit = (event: T) => {
this.listeners.forEach(listener => listener(event));
this.listenersOncer.forEach(listener => listener(event));
this.listenersOncer = [];
};
public pipe = (te: TypedEvent): Disposable => {
return this.on(e => te.emit(e));
};
}
```
================================================
FILE: docs/typings/ambient.md
================================================
# 环境声明
正如我们在为什么使用 [TypeScript](https://basarat.gitbooks.io/typescript/content/docs/why-typescript.html) 中所说：
> TypeScript 的设计目标之一是让你在 TypeScript 中安全、轻松地使用现有的 JavaScript 库，TypeScript 通过声明文件来做到这一点
环境声明允许你安全地使用现有的 JavaScript 库，并且能让你的 JavaScript、CoffeeScript 或者其他需要编译成 JavaScript 的语言逐步迁移至 TypeScript。
学习为第三方 JavaScript 库编写环境声明，是一种为 TypeScript 写注解比较好的实践方式。
## 声明文件
你可以通过 `declare` 关键字来告诉 TypeScript，你正在试图表述一个其他地方已经存在的代码，如：写在 JavaScript、CoffeeScript 或者是像浏览器和 Node.js 运行环境里的代码：
```ts
foo = 123; // Error: 'foo' is not defined
```
和：
```ts
declare var foo: any;
foo = 123; // allow
```
你可以选择把这些声明放入 `.ts` 或者 `.d.ts` 里。在你实际的项目里，我们强烈建议你应该把声明放入独立的 `.d.ts` 里（可以从一个命名为 `global.d.ts` 或者 `vendor.d.ts` 文件开始）。
如果一个文件有扩展名 `.d.ts`，这意味着每个根级别的声明都必须以 `declare` 关键字作为前缀。这有利于让开发者清楚的知道，在这里 TypeScript 将不会把它编译成任何代码，同时开发者需要确保这些在编译时存在。
::: tip
- 环境声明就好像你与编译器之间的一个约定，如果在编译时它们不存在，但是你却使用了它们，程序将会在没有警告的情况下中断。
- 环境声明就好像是一个文档。如果源文件更新了，你应该同步更新。所以，当你在运行时有新的行为时，如果没有去更新环境声明，编译器将会报错。
:::
## 变量
当你想告诉 TypeScript 编辑器关于 `process` 变量时，你可以这么做：
```ts
declare let process: any;
```
::: tip
你并不需要为 `process` 做这些，因为这已经存在于社区维护的 [`node.d.ts`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/index.d.ts)
:::
这允许你使用 `process`，并能成功通过 TypeScript 的编译：
```ts
process.exit();
```
我们推荐尽可能的使用接口，例如：
```ts
interface Process {
exit(code?: number): void;
}
declare let process: Process;
```
因为这允许其他人扩充这些全局变量，并且会告诉 TypeScript 有关于这些声明的修改。例如：考虑到以下情况，我们添加一个 `exitWithLogging` 函数至 `process`：
```ts
interface Process {
exitWithLogging(code?: number): void;
}
process.exitWithLogging = function() {
console.log('exiting');
process.exit.apply(process, arguments);
};
```
接下来，让我们更详细的了解接口。
================================================
FILE: docs/typings/callable.md
================================================
# 可调用的
你可以使用类型别名或者接口来表示一个可被调用的类型注解：
```ts
interface ReturnString {
(): string;
}
```
它可以表示一个返回值为 `string` 的函数：
```ts
declare const foo: ReturnString;
const bar = foo(); // bar 被推断为一个字符串。
```
## 一个实际的例子
当然，像这样一个可被调用的类型注解，你也可以根据实际来传递任何参数、可选参数以及 rest 参数，这有一个稍微复杂的例子：
```ts
interface Complex {
(foo: string, bar?: number, ...others: boolean[]): number;
}
```
一个接口可提供多种调用签名，用以特殊的函数重载：
```ts
interface Overloaded {
(foo: string): string;
(foo: number): number;
}
// 实现接口的一个例子：
function stringOrNumber(foo: number): number;
function stringOrNumber(foo: string): string;
function stringOrNumber(foo: any): any {
if (typeof foo === 'number') {
return foo * foo;
} else if (typeof foo === 'string') {
return `hello ${foo}`;
}
}
const overloaded: Overloaded = stringOrNumber;
// 使用
const str = overloaded(''); // str 被推断为 'string'
const num = overloaded(123); // num 被推断为 'number'
```
这也可以用于内联注解中：
```ts
let overloaded: {
(foo: string): string;
(foo: number): number;
};
```
## 箭头函数
为了使指定可调用的类型签名更容易，TypeScript 也允许你使用简单的箭头函数类型注解。例如，在一个以 number 类型为参数，以 string 类型为返回值的函数中，你可以这么写：
```ts
const simple: (foo: number) => string = foo => foo.toString();
```
::: tip
它仅仅只能作为简单的箭头函数，你无法使用重载。如果想使用重载，你必须使用完整的 `{ (someArgs): someReturn }` 的语法
:::
## 可实例化
可实例化仅仅是可调用的一种特殊情况，它使用 `new` 作为前缀。它意味着你需要使用 `new` 关键字去调用它：
```ts
interface CallMeWithNewToGetString {
new (): string;
}
// 使用
declare const Foo: CallMeWithNewToGetString;
const bar = new Foo(); // bar 被推断为 string 类型
```
================================================
FILE: docs/typings/discrominatedUnion.md
================================================
# 辨析联合类型
当类中含有[字面量成员](./literals.md)时，我们可以用该类的属性来辨析联合类型。
作为一个例子，考虑 `Square` 和 `Rectangle` 的联合类型 `Shape`。`Square` 和 `Rectangle`有共同成员 `kind`，因此 `kind` 存在于 `Shape` 中。
```ts
interface Square {
kind: 'square';
size: number;
}
interface Rectangle {
kind: 'rectangle';
width: number;
height: number;
}
type Shape = Square | Rectangle;
```
如果你使用类型保护风格的检查（`==`、`===`、`!=`、`!==`）或者使用具有判断性的属性（在这里是 `kind`），TypeScript 将会认为你会使用的对象类型一定是拥有特殊字面量的，并且它会为你自动把类型范围变小：
```ts
function area(s: Shape) {
if (s.kind === 'square') {
// 现在 TypeScript 知道 s 的类型是 Square
// 所以你现在能安全使用它
return s.size * s.size;
} else {
// 不是一个 square ？因此 TypeScript 将会推算出 s 一定是 Rectangle
return s.width * s.height;
}
}
```
## 详细的检查
通常，联合类型的成员有一些自己的行为（代码）：
```ts
interface Square {
kind: 'square';
size: number;
}
interface Rectangle {
kind: 'rectangle';
width: number;
height: number;
}
// 有人仅仅是添加了 `Circle` 类型
// 我们可能希望 TypeScript 能在任何被需要的地方抛出错误
interface Circle {
kind: 'circle';
radius: number;
}
type Shape = Square | Rectangle | Circle;
```
一个可能会让你的代码变差的例子：
```ts
function area(s: Shape) {
if (s.kind === 'square') {
return s.size * s.size;
} else if (s.kind === 'rectangle') {
return s.width * s.height;
}
// 如果你能让 TypeScript 给你一个错误，这是不是很棒？
}
```
你可以通过一个简单的向下思想，来确保块中的类型被推断为与 `never` 类型兼容的类型。例如，你可以添加一个更详细的检查来捕获错误：
```ts
function area(s: Shape) {
if (s.kind === 'square') {
return s.size * s.size;
} else if (s.kind === 'rectangle') {
return s.width * s.height;
} else {
// Error: 'Circle' 不能被赋值给 'never'
const _exhaustiveCheck: never = s;
}
}
```
它将强制你添加一种新的条件：
```ts
function area(s: Shape) {
if (s.kind === 'square') {
return s.size * s.size;
} else if (s.kind === 'rectangle') {
return s.width * s.height;
} else if (s.kind === 'circle') {
return Math.PI * s.radius ** 2;
} else {
// ok
const _exhaustiveCheck: never = s;
}
}
```
## Switch
::: tip
你可以通过 `switch` 来实现以上例子。
:::
```ts
function area(s: Shape) {
switch (s.kind) {
case 'square':
return s.size * s.size;
case 'rectangle':
return s.width * s.height;
case 'circle':
return Math.PI * s.radius ** 2;
default:
const _exhaustiveCheck: never = s;
}
}
```
## strictNullChecks
如果你使用 `strictNullChecks` 选项来做详细的检查，你应该返回 `_exhaustiveCheck` 变量（类型是 `never`），否则 TypeScript 可能会推断返回值为 `undefined`：
```ts
function area(s: Shape) {
switch (s.kind) {
case 'square':
return s.size * s.size;
case 'rectangle':
return s.width * s.height;
case 'circle':
return Math.PI * s.radius ** 2;
default:
const _exhaustiveCheck: never = s;
return _exhaustiveCheck;
}
}
```
## Redux
Redux 库正是使用的上述例子。
以下是添加了 TypeScript 类型注解的[redux 要点](https://github.com/reduxjs/redux#the-gist)。
```ts
import { createStore } from 'redux';
type Action =
| {
type: 'INCREMENT';
}
| {
type: 'DECREMENT';
};
/**
* This is a reducer, a pure function with (state, action) => state signature.
* It describes how an action transforms the state into the next state.
*
* The shape of the state is up to you: it can be a primitive, an array, an object,
* or even an Immutable.js data structure. The only important part is that you should
* not mutate the state object, but return a new object if the state changes.
*
* In this example, we use a `switch` statement and strings, but you can use a helper that
* follows a different convention (such as function maps) if it makes sense for your
* project.
*/
function counter(state = 0, action: Action) {
switch (action.type) {
case 'INCREMENT':
return state + 1;
case 'DECREMENT':
return state - 1;
default:
return state;
}
}
// Create a Redux store holding the state of your app.
// Its API is { subscribe, dispatch, getState }.
let store = createStore(counter);
// You can use subscribe() to update the UI in response to state changes.
// Normally you'd use a view binding library (e.g. React Redux) rather than subscribe() directly.
// However it can also be handy to persist the current state in the localStorage.
store.subscribe(() => console.log(store.getState()));
// The only way to mutate the internal state is to dispatch an action.
// The actions can be serialized, logged or stored and later replayed.
store.dispatch({ type: 'INCREMENT' });
// 1
store.dispatch({ type: 'INCREMENT' });
// 2
store.dispatch({ type: 'DECREMENT' });
// 1
```
与 TypeScript 一起使用可以有效的防止拼写错误，并且能提高重构和书写文档化代码的能力。
================================================
FILE: docs/typings/enums.md
================================================
# 枚举
枚举是组织收集有关联变量的一种方式，许多程序语言（如：c/c#/Java）都有枚举数据类型。下面是定义一个 TypeScript 枚举类型的方式：
```ts
enum CardSuit {
Clubs,
Diamonds,
Hearts,
Spades
}
// 简单的使用枚举类型
let Card = CardSuit.Clubs;
// 类型安全
Card = 'not a member of card suit'; // Error: string 不能赋值给 `CardSuit` 类型
```
这些枚举类型的值都是数字类型，因此它们被称为数字类型枚举。
## 数字类型枚举与数字类型
数字类型枚举，允许我们将数字类型或者其他任何与数字类型兼容的类型赋值给枚举类型的实例。
```ts
enum Color {
Red,
Green,
Blue
}
let col = Color.Red;
col = 0; // 有效的，这也是 Color.Red
```
## 数字类型枚举与字符串类型
在我们继续深入学习枚举类型之前，先来看看它编译的 JavaScript 吧，以下是一个简单的 TypeScript 枚举类型：
```ts
enum Tristate {
False,
True,
Unknown
}
```
其被编译成 JavaScript 后如下所示：
```ts{3}
var Tristate;
(function(Tristate) {
Tristate[(Tristate['False'] = 0)] = 'False';
Tristate[(Tristate['True'] = 1)] = 'True';
Tristate[(Tristate['Unknown'] = 2)] = 'Unknown';
})(Tristate || (Tristate = {}));
```
先让我们聚焦 `Tristate[Tristate['False'] = 0] = 'False'` 这行代码，其中 `Tristate['False'] = 0` 的意思是将 `Tristate` 对象里的 `False` 成员值设置为 `0`。注意，JavaScript 赋值运算符返回的值是被赋予的值（在此例子中是 `0`），因此下一次 JavaScript 运行时执行的代码是 `Tristate[0] = 'False'`。意味着你可以使用 `Tristate` 变量来把字符串枚举类型改造成一个数字或者是数字类型的枚举类型，如下所示：
```ts
enum Tristate {
False,
True,
Unknown
}
console.log(Tristate[0]); // 'False'
console.log(Tristate['False']); // 0
console.log(Tristate[Tristate.False]); // 'False' because `Tristate.False == 0`
```
## 改变与数字枚举关联的数字
默认情况下，第一个枚举值是 `0`，然后每个后续值依次递增 1：
```ts
enum Color {
Red, // 0
Green, // 1
Blue // 2
}
```
但是，你可以通过特定的赋值来改变给任何枚举成员关联的数字，如下例子，我们从 3 开始依次递增：
```ts
enum Color {
DarkRed = 3, // 3
DarkGreen, // 4
DarkBlue // 5
}
```
::: tip
我通常用 `= 1` 初始化，因为在枚举类型值里，它能让你做一个安全可靠的检查。
:::
## 使用数字类型作为标志
枚举的一个很好用途是使用枚举作为标志。这些标志允许你检查一组条件中的某个条件是否为真。考虑如下代码例子，我们有一组关于 animals 的属性：
```ts
enum AnimalFlags {
None = 0,
HasClaws = 1 << 0,
CanFly = 1 << 1,
EatsFish = 1 << 2,
Endangered = 1 << 3
}
```
在这里，我们使用了左移的位运算符，将数字 `1` 的二进制向左移动位置得到数字 `0001`、`0010`、`0100` 和 `1000`（换成十进制结果是：1, 2, 4, 8）。当你在使用这种标记的时候，这些位运算符 `|` (或)、`&` （和）、`~` （非）将会是你最好的朋友：
```ts
enum AnimalFlags {
None = 0,
HasClaws = 1 << 0,
CanFly = 1 << 1
}
interface Animal {
flags: AnimalFlags;
[key: string]: any;
}
function printAnimalAbilities(animal: Animal) {
var animalFlags = animal.flags;
if (animalFlags & AnimalFlags.HasClaws) {
console.log('animal has claws');
}
if (animalFlags & AnimalFlags.CanFly) {
console.log('animal can fly');
}
if (animalFlags == AnimalFlags.None) {
console.log('nothing');
}
}
var animal = { flags: AnimalFlags.None };
printAnimalAbilities(animal); // nothing
animal.flags |= AnimalFlags.HasClaws;
printAnimalAbilities(animal); // animal has claws
animal.flags &= ~AnimalFlags.HasClaws;
printAnimalAbilities(animal); // nothing
animal.flags |= AnimalFlags.HasClaws | AnimalFlags.CanFly;
printAnimalAbilities(animal); // animal has claws, animal can fly
```
在这里：
- 我们使用 `|=` 来添加一个标志；
- 组合使用 `&=` 和 `~` 来清理一个标志；
- `|` 来合并标志。
::: tip
你可以组合标志，用来在枚举类型中定义方便快捷的方式，如下 `EndangeredFlyingClawedFishEating`：
:::
```ts
enum AnimalFlags {
None = 0,
HasClaws = 1 << 0,
CanFly = 1 << 1,
EatsFish = 1 << 2,
Endangered = 1 << 3,
EndangeredFlyingClawedFishEating = HasClaws | CanFly | EatsFish | Endangered
}
```
## 字符串枚举
在上文中，我们只看到了数字类型的枚举，实际上，枚举类型的值，也可以是字符串类型。
```ts
export enum EvidenceTypeEnum {
UNKNOWN = '',
PASSPORT_VISA = 'passport_visa',
PASSPORT = 'passport',
SIGHTED_STUDENT_CARD = 'sighted_tertiary_edu_id',
SIGHTED_KEYPASS_CARD = 'sighted_keypass_card',
SIGHTED_PROOF_OF_AGE_CARD = 'sighted_proof_of_age_card'
}
```
这些可以更容易被处理和调试，因为它们提供有意义/可调试的字符串。
你可以使用它们用于简单的字符串比较：
```ts
// Where `someStringFromBackend` will be '' | 'passport_visa' | 'passport' ... etc.
const value = someStringFromBackend as EvidenceTypeEnum;
// Sample use in code
if (value === EvidenceTypeEnum.PASSPORT) {
console.log('You provided a passport');
console.log(value); // `passport`
}
```
## 常量枚举
```ts
enum Tristate {
False,
True,
Unknown
}
const lie = Tristate.False;
```
`const lie = Tristate.False` 会被编译成 JavaScript `let lie = Tristate.False` (是的，编译后与编译前，几乎相同)。这意味着在运行执行时，它将会查找变量 `Tristate` 和 `Tristate.False`。在此处获得性能提升的一个小技巧是使用常量枚举：
```ts
const enum Tristate {
False,
True,
Unknown
}
const lie = Tristate.False;
```
将会被编译成：
```js
let lie = 0;
```
编译器将会：
- 内联枚举的任何用法（`0` 而不是 `Tristate.False`）；
- 不会为枚举类型编译成任何 JavaScript（在这个例子中，运行时没有 `Tristate` 变量），因为它使用内联语法。
### 常量枚举 `preserveConstEnums` 选项
使用内联语法对性能有明显的提升作用。运行时没有 `Tristate` 变量的事实，是因为编译器帮助你把一些在运行时没有用到的不编译成 JavaScript。然而，你可能想让编译器仍然把枚举类型编译成 JavaScript，用于如上例子中从字符串到数字，或者是从数字到字符串的查找。在这种情景下，你可以使用编译选项 `--preserveConstEnums`，它会编译出 `var Tristate` 的定义，因此你在运行时，手动使用 `Tristate['False']` 和 `Tristate[0]`。并且这不会以任何方式影响内联。
## 有静态方法的枚举
你可以使用 `enum` + `namespace` 的声明的方式向枚举类型添加静态方法。如下例所示，我们将静态成员 `isBusinessDay` 添加到枚举上：
```ts
enum Weekday {
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
Sunday
}
namespace Weekday {
export function isBusinessDay(day: Weekday) {
switch (day) {
case Weekday.Saturday:
case Weekday.Sunday:
return false;
default:
return true;
}
}
}
const mon = Weekday.Monday;
const sun = Weekday.Sunday;
console.log(Weekday.isBusinessDay(mon)); // true
console.log(Weekday.isBusinessDay(sun));
```
## 开放式枚举
::: tip
你只有在不使用模块时，开放式的枚举才有意义，你应该使用模块，因此这部分在文章最后。
:::
让我们再一次看看编译成 JavaScript 的枚举是什么样子：
```ts
var Tristate;
(function(Tristate) {
Tristate[(Tristate['False'] = 0)] = 'False';
Tristate[(Tristate['True'] = 1)] = 'True';
Tristate[(Tristate['Unknown'] = 2)] = 'Unknown';
})(Tristate || (Tristate = {}));
```
我们已经解释了 `Tristate[Tristate['False'] = 0] = 'False'` 部分，现在我们来看看包裹函数 `(function (Tristate) { /* code here */})(Tristate || (Tristate = {}))`，特别是 `(Tristate || (Tristate = {}))` 部分。这捕获了一个局部变量 `TriState`，它要么指向已经定义的`TriState` 值，要么使用一个新的空对象来初始化它。
这意味着你可以跨多个文件拆分（和扩展）枚举定义，如下所示，你可以把 `Color` 的定义拆分至两个块中：
```ts
enum Color {
Red,
Green,
Blue
}
enum Color {
DarkRed = 3,
DarkGreen,
DarkBlue
}
```
::: tip
你应该在枚举的延续块中，重新初始化第一个成员（此处为 `DarkRed = 3`），使生成的代码不破坏先前定义的值（即0、1...等值）。如果您仍然不这样做，TypeScript 将会发出警告（错误信息：`In an enum with multiple declarations, only one declaration can omit an initializer for its first enum element.`）。
:::
================================================
FILE: docs/typings/exceptionsHanding.md
================================================
# 异常处理
JavaScript 有一个 `Error` 类，用于处理异常。你可以通过 `throw` 关键字来抛出一个错误。然后通过 `try/catch` 块来捕获此错误：
```ts
try {
throw new Error('Something bad happened');
} catch (e) {
console.log(e);
}
```
## 错误子类型
除内置的 `Error` 类外，还有一些额外的内置错误，它们继承自 `Error` 类：
### RangeError
当数字类型变量或者参数超出其有效范围时，出现 `RangeError` 的错误提示：
```ts
// 使用过多参数调用 console
console.log.apply(console, new Array(1000000000)); // RangeError: 数组长度无效
```
### ReferenceError
当引用无效时，会出现 `ReferenceError` 的错误提示：
```ts
'use strict';
console.log(notValidVar); // ReferenceError: notValidVar 未定义
```
### SyntaxError
当解析无效 JavaScript 代码时，会出现 `SyntaxError` 的错误提示：
```ts
1 *** 3 // SyntaxError: 无效的标记 *
```
### TypeError
变量或者参数不是有效类型时，会出现 `TypeError` 的错误提示：
```ts
'1.2'.toPrecision(1); // TypeError: '1.2'.toPrecision 不是函数。
```
### URIError
当传入无效参数至 `encodeURI()` 和 `decodeURI()` 时，会出现 `URIError` 的错误提示：
```ts
decodeURI('%'); // URIError: URL 异常
```
## 使用 `Error`
JavaScript 初学者可能有时候仅仅是抛出一个原始字符串：
```ts
try {
throw 'Something bad happened';
} catch (e) {
console.log(e);
}
```
**不要这么做**，使用 `Error` 对象的基本好处是，它能自动跟踪堆栈的属性构建以及生成位置。
原始字符串会导致极差的调试体验，并且在分析日志时，将会变得错综复杂。
## 你并不需要 `throw` 抛出一个错误
传递一个 `Error` 对象是没问题的，这种方式在 `Node.js` 回调函数中非常常见，它用第一个参数作为错误对象进行回调处理。
```ts
function myFunction (callback: (e: Error)) {
doSomethingAsync(function () {
if (somethingWrong) {
callback(new Error('This is my error'));
} else {
callback();
}
})
}
```
## 优秀的用例
「Exceptions should be exceptional」是计算机科学中常用用语。这里有一些原因说明在 JavaScript(TypeScript) 中也是如此。
### 不清楚从哪里抛出错误
考虑如下代码块：
```ts
try {
const foo = runTask1();
const bar = runTask2();
} catch (e) {
console.log('Error:', e);
}
```
下一个开发者可能并不清楚哪个函数可能会抛出错误。在没有阅读 `task1/task2` 代码以及他们可能会调用的函数时，对代码 `review` 的人员可能也不会知道错误会从哪里抛出。
### 优雅的捕获错误
你可以通过为每个可能抛出错误的代码显式捕获，来使其优雅：
```ts
try {
const foo = runTask1();
} catch (e) {
console.log('Error:', e);
}
try {
const bar = runTask2();
} catch (e) {
console.log('Error:', e);
}
```
但是现在，如果你想从第一个任务中传递变量到第二个任务中，代码会变的混乱（注意：foo 变量需要用 let 显式注解它，因为它不能从 `runTask1` 中返回出来）：
```ts
let foo: number; // Notice 使用 let 并且显式注明类型注解
try {
foo = runTask1();
} catch (e) {
console.log('Error:', e);
}
try {
const bar = runTask2(foo);
} catch (e) {
console.log('Error:', e);
}
```
### 没有在类型系统中很好的表示
考虑如下函数：
```ts
function validate(value: number) {
if (value < 0 || value > 100) {
throw new Error('Invalid value');
}
}
```
在这种情境下使用 `Error` 不是一个好的主意。因为没有用来验证函数的类型定义（如：`(value: number) => void`），取而代之一个更好的方式是创建一个验证方法：
```ts
function validate(
value: number
): {
error?: string;
} {
if (value < 0 || value > 100) {
return { error: 'Invalid value' };
}
}
```
现在它具有类型定义了。
::: tip
除非你想用以非常通用（try/catch）的方式处理错误，否则不要抛出错误。
:::
================================================
FILE: docs/typings/freshness.md
================================================
# Freshness
为了能让检查对象字面量类型更容易，TypeScript 提供 「[Freshness](https://github.com/Microsoft/TypeScript/pull/3823)」 的概念（它也被称为更严格的对象字面量检查）用来确保对象字面量在结构上类型兼容。
结构类型非常方便。考虑如下例子代码，它可以让你非常便利的从 JavaScript 迁移至 TypeScript，并且会提供类型安全：
```js
function logName(something: { name: string }) {
console.log(something.name);
}
const person = { name: 'matt', job: 'being awesome' };
const animal = { name: 'cow', diet: 'vegan, but has milk of own specie' };
const randow = { note: `I don't have a name property` };
logName(person); // ok
logName(animal); // ok
logName(randow); // Error: 没有 `name` 属性
```
但是，结构类型有一个缺点，它能误导你认为某些东西接收的数据比它实际的多。如下例，TypeScript 发出错误警告：
```ts
function logName(something: { name: string }) {
console.log(something.name);
}
logName({ name: 'matt' }); // ok
logName({ name: 'matt', job: 'being awesome' }); // Error: 对象字面量只能指定已知属性，`job` 属性在这里并不存在。
```
::: warning
请注意，这种错误提示，只会发生在对象字面量上。
:::
如果没有这种错误提示，我们可能会去寻找函数的调用 `logName({ name: 'matt', job: 'being awesome' })`，继而会认为 `logName` 可能会使用 `job` 属性做一些事情，然而实际上 `logName` 并没有使用它。
另外一个使用比较多的场景是与具有可选成员的接口一起使用，如果没有这样的对象字面量检查，当你输入错误单词的时候，并不会发出错误警告：
```ts
function logIfHasName(something: { name?: string }) {
if (something.name) {
console.log(something.name);
}
}
const person = { name: 'matt', job: 'being awesome' };
const animal = { name: 'cow', diet: 'vegan, but has milk of own species' };
logIfHasName(person); // okay
logIfHasName(animal); // okay
logIfHasName({ neme: 'I just misspelled name to neme' }); // Error: 对象字面量只能指定已知属性，`neme` 属性不存在。
```
之所以只对对象字面量进行类型检查，因为在这种情况下，那些实际上并没有被使用到的属性有可能会拼写错误或者会被误用。
## 允许额外的属性
一个类型能够包含索引签名，以明确表明可以使用额外的属性：
```ts
let x: { foo: number, [x: string]: any };
x = { foo: 1, baz: 2 }; // ok, 'baz' 属性匹配于索引签名
```
## 用例：React State
Facebook ReactJS 为对象的 Freshness 提供了一个很好的用例，通常在组件中，你只使用少量属性，而不是传入所有，来调用 `setState`：
```ts
// 假设
interface State {
foo: string;
bar: string;
}
// 你可能想做：
this.setState({ foo: 'Hello' }); // Error: 没有属性 'bar'
// 因为 state 包含 'foo' 与 'bar'，TypeScript 会强制你这么做：
this.setState({ foo: 'Hello', bar: this.state.bar });
```
如果你想使用 Freshness，你可能需要将所有成员标记为可选，这仍然会捕捉到拼写错误：
```ts
// 假设
interface State {
foo?: string;
bar?: string;
}
// 你可能想做
this.setState({ foo: 'Hello' }); // Yay works fine!
// 由于 Freshness，你也可以防止错别字
this.setState({ foos: 'Hello' }}; // Error: 对象只能指定已知属性
// 仍然会有类型检查
this.setState({ foo: 123 }); // Error: 无法将 number 类型赋值给 string 类型
```
================================================
FILE: docs/typings/functions.md
================================================
# 函数
函数类型在 TypeScript 类型系统中扮演着非常重要的角色，它们是可组合系统的核心构建块。
## 参数注解
你可以注解函数参数，就像你可以注解其他变量一样:
```ts
// variable annotation
let sampleVariable: { bar: number };
// function parameter annotation
function foo(sampleParameter: { bar: number }) {}
```
这里我们使用了内联类型注解，除此之外，你还可以使用接口等其他方式。
### 返回类型注解
你可以在函数参数列表之后使用与变量相同的样式来注解返回类型，如例子中 `：Foo`：
```ts
interface Foo {
foo: string;
}
// Return type annotated as `: Foo`
function foo(sample: Foo): Foo {
return sample;
}
```
我们在这里使用了一个 `interface`，但你可以自由地使用其他注解方式，例如内联注解。
通常，你不*需要*注解函数的返回类型，因为它可以由编译器推断：
```ts
interface Foo {
foo: string;
}
function foo(sample: Foo) {
return sample; // inferred return type 'Foo'
}
```
但是，添加这些注解以帮助解决错误提示通常是一个好主意，例如：
```ts
function foo() {
return { fou: 'John Doe' }; // You might not find this misspelling of `foo` till it's too late
}
sendAsJSON(foo());
```
如果你不打算从函数返回任何内容，则可以将其标注为：`void` 。你通常可以删除 `void`， TypeScript 能推导出来：
### 可选参数
你可以将参数标记为可选:
```ts
function foo(bar: number, bas?: string): void {
// ..
}
foo(123);
foo(123, 'hello');
```
或者，当调用者没有提供该参数时，你可以提供一个默认值（在参数声明后使用 `= someValue` ）：
```ts
function foo(bar: number, bas: string = 'hello') {
console.log(bar, bas);
}
foo(123); // 123, hello
foo(123, 'world'); // 123, world
```
### 重载
TypeScript 允许你声明函数重载。这对于文档 + 类型安全来说很实用。请思考以下代码：
```ts
function padding(a: number, b?: number, c?: number, d?: any) {
if (b === undefined && c === undefined && d === undefined) {
b = c = d = a;
} else if (c === undefined && d === undefined) {
c = a;
d = b;
}
return {
top: a,
right: b,
bottom: c,
left: d
};
}
```
如果仔细查看代码，就会发现 a，b，c，d 的值会根据传入的参数数量而变化。此函数也只需要 1 个，2 个或 4 个参数。可以使用函数重载来*强制*和*记录*这些约束。你只需多次声明函数头。最后一个函数头是在函数体内实际处于活动状态但不可用于外部。
如下所示:
```ts
// 重载
function padding(all: number);
function padding(topAndBottom: number, leftAndRight: number);
function padding(top: number, right: number, bottom: number, left: number);
// Actual implementation that is a true representation of all the cases the function body needs to handle
function padding(a: number, b?: number, c?: number, d?: number) {
if (b === undefined && c === undefined && d === undefined) {
b = c = d = a;
} else if (c === undefined && d === undefined) {
c = a;
d = b;
}
return {
top: a,
right: b,
bottom: c,
left: d
};
}
```
这里前三个函数头可有效调用 `padding`:
```ts
padding(1); // Okay: all
padding(1, 1); // Okay: topAndBottom, leftAndRight
padding(1, 1, 1, 1); // Okay: top, right, bottom, left
padding(1, 1, 1); // Error: Not a part of the available overloads
```
当然，最终声明（从函数内部看到的真正声明）与所有重载兼容是很重要的。这是因为这是函数体需要考虑的函数调用的真实性质。
::: tip
TypeScript 中的函数重载没有任何运行时开销。它只允许你记录希望调用函数的方式，并且编译器会检查其余代码。
:::
### 函数声明
> 快速开始：类型注解是你描述现有实现类型的一种方式
在没有提供函数实现的情况下，有两种声明函数类型的方式:
```ts
type LongHand = {
(a: number): number;
};
type ShortHand = (a: number) => number;
```
上面代码中的两个例子完全相同。但是，当你想使用函数重载时，只能用第一种方式:
```ts
type LongHandAllowsOverloadDeclarations = {
(a: number): number;
(a: string): string;
};
```
================================================
FILE: docs/typings/generices.md
================================================
# 泛型
设计泛型的关键目的是在成员之间提供有意义的约束，这些成员可以是：
- 类的实例成员
- 类的方法
- 函数参数
- 函数返回值
## 动机和示例
下面是对一个先进先出的数据结构——队列，在 `TypeScript` 和 `JavaScript` 中的简单实现。
```ts
class Queue {
private data = [];
push = item => this.data.push(item);
pop = () => this.data.shift();
}
```
在上述代码中存在一个问题，它允许你向队列中添加任何类型的数据，当然，当数据被弹出队列时，也可以是任意类型。在下面的示例中，看起来人们可以向队列中添加`string` 类型的数据，但是实际上，该用法假定的是只有 `number` 类型会被添加到队列里。
```ts
class Queue {
private data = [];
push = item => this.data.push(item);
pop = () => this.data.shift();
}
const queue = new Queue();
queue.push(0);
queue.push('1'); // Oops，一个错误
// 一个使用者，走入了误区
console.log(queue.pop().toPrecision(1));
console.log(queue.pop().toPrecision(1)); // RUNTIME ERROR
```
一个解决的办法（事实上，这也是不支持泛型类型的唯一解决办法）是为这些约束创建特殊类，如快速创建数字类型的队列：
```ts
class QueueNumber {
private data = [];
push = (item: number) => this.data.push(item);
pop = (): number => this.data.shift();
}
const queue = new QueueNumber();
queue.push(0);
queue.push('1'); // Error: 不能推入一个 `string` 类型，只能是 `number` 类型
// 如果该错误得到修复，其他将不会出现问题
```
当然，快速也意味着痛苦。例如当你想创建一个字符串的队列时，你将不得不再次修改相当大的代码。我们真正想要的一种方式是无论什么类型被推入队列，被推出的类型都与推入类型一样。当你使用泛型时，这会很容易：
```ts
// 创建一个泛型类
class Queue {
private data: T[] = [];
push = (item: T) => this.data.push(item);
pop = (): T | undefined => this.data.shift();
}
// 简单的使用
const queue = new Queue();
queue.push(0);
queue.push('1'); // Error：不能推入一个 `string`，只有 number 类型被允许
```
另外一个我们见过的例子：一个 `reverse` 函数，现在在这个函数里提供了函数参数与函数返回值的约束：
```ts
function reverse(items: T[]): T[] {
const toreturn = [];
for (let i = items.length - 1; i >= 0; i--) {
toreturn.push(items[i]);
}
return toreturn;
}
const sample = [1, 2, 3];
let reversed = reverse(sample);
reversed[0] = '1'; // Error
reversed = ['1', '2']; // Error
reversed[0] = 1; // ok
reversed = [1, 2]; // ok
```
在此章节中，你已经了解在*类*和*函数*上使用泛型的例子。一个值得补充一点的是，你可以为创建的成员函数添加泛型：
```ts
class Utility {
reverse(items: T[]): T[] {
const toreturn = [];
for (let i = items.length; i >= 0; i--) {
toreturn.push(items[i]);
}
return toreturn;
}
}
```
::: tip
你可以随意调用泛型参数，当你使用简单的泛型时，泛型常用 `T`、`U`、`V` 表示。如果在你的参数里，不止拥有一个泛型，你应该使用一个更语义化名称，如 `TKey` 和 `TValue` （通常情况下，以 `T` 作为泛型的前缀，在其他语言如 C++ 里，也被称为模板）
:::
## 误用的泛型
我见过开发者使用泛型仅仅是为了它的 hack。当你使用它时，你应该问问自己：你想用它来提供什么样的约束。如果你不能很好的回答它，你可能会误用泛型，如：
```ts
declare function foo(arg: T): void;
```
在这里，泛型完全没有必要使用，因为它仅用于单个参数的位置，使用如下方式可能更好：
```ts
declare function foo(arg: any): void;
```
## 设计模式：方便通用
考虑如下函数：
```ts
declare function parse(name: string): T;
```
在这种情况下，泛型 `T` 只在一个地方被使用了，它并没有在成员之间提供约束 `T`。这相当于一个如下的类型断言：
```ts
declare function parse(name: string): any;
const something = parse('something') as TypeOfSomething;
```
仅使用一次的泛型并不比一个类型断言来的安全。它们都给你使用 API 提供了便利。
另一个明显的例子是，一个用于加载 json 返回值函数，它返回你任何传入类型的 `Promise`：
```ts
const getJSON = (config: { url: string; headers?: { [key: string]: string } }): Promise => {
const fetchConfig = {
method: 'GET',
Accept: 'application/json',
'Content-Type': 'application/json',
...(config.headers || {})
};
return fetch(config.url, fetchConfig).then(response => response.json());
};
```
请注意，你仍然需要明显的注解任何你需要的类型，但是 `getJSON` 的签名 `config => Promise` 能够减少你一些关键的步骤（你不需要注解 `loadUsers` 的返回类型，因为它能够被推出来）：
```ts
type LoadUserResponse = {
user: {
name: string;
email: string;
}[];
};
function loaderUser() {
return getJSON({ url: 'https://example.com/users' });
}
```
与此类似：使用 `Promise` 作为一个函数的返回值比一些如：`Promise` 的备选方案要好很多。
### 配合 axios 使用
通常情况下，我们会把后端返回数据格式单独放入一个 interface 里：
```ts
// 请求接口数据
export interface ResponseData {
/**
* 状态码
* @type { number }
*/
code: number;
/**
* 数据
* @type { T }
*/
result: T;
/**
* 消息
* @type { string }
*/
message: string;
}
```
当我们把 API 单独抽离成单个模块时：
```ts
// 在 axios.ts 文件中对 axios 进行了处理，例如添加通用配置、拦截器等
import Ax from './axios';
import { ResponseData } from './interface.ts';
export function getUser() {
return Ax.get>('/somepath')
.then(res => res.data)
.catch(err => console.error(err));
}
```
接着我们写入返回的数据类型 `User`，这可以让 TypeScript 顺利推断出我们想要的类型：
```ts
interface User {
name: string;
age: number;
}
async function test() {
// user 被推断出为
// {
// code: number,
// result: { name: string, age: number },
// message: string
// }
const user = await getUser();
}
```
================================================
FILE: docs/typings/indexSignatures.md
================================================
# 索引签名
可以用字符串访问 JavaScript 中的对象（TypeScript 中也一样），用来保存对其他对象的引用。
例如：
```ts
let foo: any = {};
foo['Hello'] = 'World';
console.log(foo['Hello']); // World
```
我们在键 `Hello` 下保存了一个字符串 `World`，除字符串外，它也可以保存任意的 JavaScript 对象，例如一个类的实例。
```ts
class Foo {
constructor(public message: string) {}
log() {
console.log(this.message);
}
}
let foo: any = {};
foo['Hello'] = new Foo('World');
foo['Hello'].log(); // World
```
当你传入一个其他对象至索引签名时，JavaScript 会在得到结果之前会先调用 `.toString` 方法：
```ts
let obj = {
toString() {
console.log('toString called');
return 'Hello';
}
};
let foo: any = {};
foo[obj] = 'World'; // toString called
console.log(foo[obj]); // toString called, World
console.log(foo['Hello']); // World
```
::: tip
只要索引位置使用了 `obj`，`toString` 方法都将会被调用。
:::
数组有点稍微不同，对于一个 `number` 类型的索引签名，JavaScript 引擎将会尝试去优化（这取决于它是否是一个真的数组、存储的项目结构是否匹配等）。因此，`number` 应该被考虑作为一个有效的对象访问器（这与 `string` 不同），如下例子：
```ts
let foo = ['World'];
console.log(foo[0]); // World
```
因此，这就是 JavaScript。现在让我们看看 TypeScript 对这些概念更优雅的处理。
## TypeScript 索引签名
JavaScript 在一个对象类型的索引签名上会隐式调用 `toString` 方法，而在 TypeScript 中，为防止初学者砸伤自己的脚（我总是看到 stackoverflow 上有很多 JavaScript 使用者都会这样。），它将会抛出一个错误。
```ts
const obj = {
toString() {
return 'Hello';
}
};
const foo: any = {};
// ERROR: 索引签名必须为 string, number....
foo[obj] = 'World';
// FIX: TypeScript 强制你必须明确这么做：
foo[obj.toString()] = 'World';
```
强制用户必须明确的写出 `toString()` 的原因是：在对象上默认执行的 `toString` 方法是有害的。例如 v8 引擎上总是会返回 `[object Object]`
```ts
const obj = { message: 'Hello' };
let foo: any = {};
// ERROR: 索引签名必须为 string, number....
foo[obj] = 'World';
// 这里实际上就是你存储的地方
console.log(foo['[object Object]']); // World
```
当然，数字类型是被允许的，这是因为：
- 需要对数组 / 元组完美的支持；
- 即使你在上例中使用 `number` 类型的值来替代 `obj`，`number` 类型默认的 `toString` 方法实现的很友好（不是 `[object Object]`）。
如下所示：
```ts
console.log((1).toString()); // 1
console.log((2).toString()); // 2
```
因此，我们有以下结论：
::: tip
TypeScript 的索引签名必须是 `string` 或者 `number`。
`symbols` 也是有效的，TypeScript 支持它。在接下来我们将会讲解它。
:::
## 声明一个索引签名
在上文中，我们通过使用 `any` 来让 TypeScript 允许我们可以做任意我们想做的事情。实际上，我们可以明确的指定索引签名。例如：假设你想确认存储在对象中任何内容都符合 `{ message: string }` 的结构，你可以通过 `[index: string]: { message: string }` 来实现。
```ts
const foo: {
[index: string]: { message: string };
} = {};
// 储存的东西必须符合结构
// ok
foo['a'] = { message: 'some message' };
// Error, 必须包含 `message`
foo['a'] = { messages: 'some message' };
// 读取时，也会有类型检查
// ok
foo['a'].message;
// Error: messages 不存在
foo['a'].messages;
```
::: tip
索引签名的名称（如：`{ [index: string]: { message: string } }` 里的 `index` ）除了可读性外，并没有任何意义。例如：如果有一个用户名，你可以使用 `{ username: string}: { message: string }`，这有利于下一个开发者理解你的代码。
:::
`number` 类型的索引也支持：`{ [count: number]: 'SomeOtherTypeYouWantToStoreEgRebate' }`。
## 所有成员都必须符合字符串的索引签名
当你声明一个索引签名时，所有明确的成员都必须符合索引签名：
```ts
// ok
interface Foo {
[key: string]: number;
x: number;
y: number;
}
// Error
interface Bar {
[key: string]: number;
x: number;
y: string; // Error: y 属性必须为 number 类型
}
```
这可以给你提供安全性，任何以字符串的访问都能得到相同结果。
```ts
interface Foo {
[key: string]: number;
x: number;
}
let foo: Foo = {
x: 1,
y: 2
};
// 直接
foo['x']; // number
// 间接
const x = 'x';
foo[x]; // number
```
## 使用一组有限的字符串字面量
一个索引签名可以通过映射类型来使索引字符串为联合类型中的一员，如下所示：
```ts
type Index = 'a' | 'b' | 'c';
type FromIndex = { [k in Index]?: number };
const good: FromIndex = { b: 1, c: 2 };
// Error:
// `{ b: 1, c: 2, d: 3 }` 不能分配给 'FromIndex'
// 对象字面量只能指定已知类型，'d' 不存在 'FromIndex' 类型上
const bad: FromIndex = { b: 1, c: 2, d: 3 };
```
这通常与 `keyof/typeof` 一起使用，来获取变量的类型，在下一章节中，我们将解释它。
变量的规则一般可以延迟被推断：
```ts
type FromSomeIndex = { [key in K]: number };
```
## 同时拥有 `string` 和 `number` 类型的索引签名
这并不是一个常见的用例，但是 TypeScript 支持它。
`string` 类型的索引签名比 `number` 类型的索引签名更严格。这是故意设计，它允许你有如下类型：
```ts
interface ArrStr {
[key: string]: string | number; // 必须包括所用成员类型
[index: number]: string; // 字符串索引类型的子级
// example
length: number;
}
```
## 设计模式：索引签名的嵌套
::: tip
添加索引签名时，需要考虑的 API。
:::
在 JavaScript 社区你将会见到很多滥用索引签名的 API。如 JavaScript 库中使用 CSS 的常见模式：
```ts
interface NestedCSS {
color?: string; // strictNullChecks=false 时索引签名可为 undefined
[selector: string]: string | NestedCSS;
}
const example: NestedCSS = {
color: 'red',
'.subclass': {
color: 'blue'
}
};
```
尽量不要使用这种把字符串索引签名与有效变量混合使用。如果属性名称中有拼写错误，这个错误不会被捕获到：
```ts
const failsSilently: NestedCSS = {
colour: 'red' // 'colour' 不会被捕捉到错误
};
```
取而代之，我们把索引签名分离到自己的属性里，如命名为 `nest`（或者 `children`、`subnodes` 等）：
```ts
interface NestedCSS {
color?: string;
nest?: {
[selector: string]: NestedCSS;
};
}
const example: NestedCSS = {
color: 'red',
nest: {
'.subclass': {
color: 'blue'
}
}
}
const failsSliently: NestedCSS = {
colour: 'red' // TS Error: 未知属性 'colour'
}
```
## 索引签名中排除某些属性
有时，你需要把属性合并至索引签名（虽然我们并不建议这么做，你应该使用上文中提到的嵌套索引签名的形式），如下例子：
```ts
type FieldState = {
value: string;
};
type FromState = {
isValid: boolean; // Error: 不符合索引签名
[filedName: string]: FieldState;
};
```
TypeScript 会报错，因为添加的索引签名，并不兼容它原有的类型，使用交叉类型可以解决上述问题：
```ts
type FieldState = {
value: string;
};
type FormState = { isValid: boolean } & { [fieldName: string]: FieldState };
```
请注意尽管你可以声明它至一个已存在的 TypeScript 类型上，但是你不能创建如下的对象：
```ts
type FieldState = {
value: string;
};
type FormState = { isValid: boolean } & { [fieldName: string]: FieldState };
// 将它用于从某些地方获取的 JavaScript 对象
declare const foo: FormState;
const isValidBool = foo.isValid;
const somethingFieldState = foo['something'];
// 使用它来创建一个对象时，将不会工作
const bar: FormState = {
// 'isValid' 不能赋值给 'FieldState'
isValid: false
};
```
================================================
FILE: docs/typings/interfaces.md
================================================
# 接口
接口运行时的影响为 0。在 TypeScript 接口中有很多方式来声明变量的结构。
下面两个是等效的声明, 示例 A 使用内联注解，示例 B 使用接口形式：
```ts
// 示例 A
declare const myPoint: { x: number; y: number };
// 示例 B
interface Point {
x: number;
y: number;
}
declare const myPoint: Point;
```
示例 B 的好处在于，如果有人创建了一个基于 `myPoint` 的库来添加新成员, 那么他可以轻松将此成员添加到 `myPoint` 的现有声明中:
```ts
// Lib a.d.ts
interface Point {
x: number,
y: number
}
declare const myPoint: Point
// Lib b.d.ts
interface Point {
z: number
}
// Your code
myPoint.z // Allowed!
```
TypeScript 接口是开放式的，这是 TypeScript 的一个重要原则，它允许你使用接口来模仿 JavaScript 的可扩展性。
## 类可以实现接口
如果你希望在类中使用必须要被遵循的接口（类）或别人定义的对象结构，可以使用 `implements` 关键字来确保其兼容性：
```ts
interface Point {
x: number;
y: number;
}
class MyPoint implements Point {
x: number;
y: number; // Same as Point
}
```
基本上，在 `implements（实现）` 存在的情况下，该外部 `Point` 接口的任何更改都将导致代码库中的编译错误，因此可以轻松地使其保持同步：
```ts
interface Point {
x: number;
y: number;
z: number; // New member
}
class MyPoint implements Point {
// ERROR : missing member `z`
x: number;
y: number;
}
```
注意，`implements` 限制了类实例的结构，如下所示:
```ts
let foo: Point = new MyPoint();
```
但像 `foo: Point = MyPoint` 这样的代码，与其并不是一回事。
## 注意
### 并非每个接口都是很容易实现的
接口旨在声明 JavaScript 中可能存在的任意结构。
思考以下例子，可以使用 `new` 调用某些内容：
```ts
interface Crazy {
new (): {
hello: number;
};
}
```
你可能会有下面这样的代码：
```ts
class CrazyClass implements Crazy {
constructor() {
return { hello: 123 };
}
}
// Because
const crazy = new CrazyClass(); // crazy would be { hello:123 }
```
你可以使用接口声明所有“疯狂的”的 JavaScript 代码，甚至可以安全地在 TypeScript 中使用它们。但这并不意味着你可以使用 TypeScript 类来实现它们。
================================================
FILE: docs/typings/lib.md
================================================
# `lib.d.ts`
当你安装 `TypeScript` 时，会顺带安装一个 `lib.d.ts` 声明文件。这个文件包含 JavaScript 运行时以及 DOM 中存在各种常见的环境声明。
- 它自动包含在 TypeScript 项目的编译上下文中；
- 它能让你快速开始书写经过类型检查的 JavaScript 代码。
你可以通过指定 `--noLib` 的编译器命令行标志（或者在 `tsconfig.json` 中指定选项 `noLib: true`）从上下文中排除此文件。
## 使用例子
看如下例子：
```ts
const foo = 123;
const bar = foo.toString();
```
这段代码的类型检查正常，因为 `lib.d.ts` 为所有 JavaScript 对象定义了 `toString` 方法。
如果你在 `noLib` 选项下，使用相同的代码，这将会出现类型检查错误：
```ts
const foo = 123;
const bar = foo.toString(); // Error: 属性 toString 不存在类型 number 上
```
现在你已经理解了 `lib.d.ts` 的重要性，至于它的内容是怎么样的，我们接下来将会解释。
## 观察 `lib.d.ts` 的内容
`lib.d.ts` 的内容主要是一些变量声明（如：`window`、`document`、`math`）和一些类似的接口声明（如：`Window`、`Document`、`Math`）。
寻找代码类型（如：`Math.floor`）的最简单方式是使用 IDE 的 `F12`（跳转到定义）。
让我们来看一个变量声明的示例，如 `window` 被定义为：
```ts
declare var window: Window;
```
这只是一个简单的 `declare var`，后面跟一个变量名称（`window`）和一个用来类型注解的接口（`Window`），这些变量通常指向一些全局的接口，例如，以下是 `Window` 接口的一小部分：
```ts
interface Window
extends EventTarget,
WindowTimers,
WindowSessionStorage,
WindowLocalStorage,
WindowConsole,
GlobalEventHandlers,
IDBEnvironment,
WindowBase64 {
animationStartTime: number;
applicationCache: ApplicationCache;
clientInformation: Navigator;
closed: boolean;
crypto: Crypto;
// so on and so forth...
}
```
你可以在这些接口里看到大量的类型信息，当你不使用 TypeScript 时，你需要将它们保存在你的大脑里。现在你可以使用 `intellisense` 之类东西，从而可以减少对知识的记忆。
使用这些全局变量是有利的。在不更改 `lib.d.ts` 的情况下，它可以让你添加额外的属性。接下来，我们将介绍这些概念。
## 修改原始类型
在 TypeScript 中，接口是开放式的，这意味着当你想使用不存在的成员时，只需要将它们添加至 `lib.d.ts` 中的接口声明中即可，TypeScript 将会自动接收它。注意，你需要在[全局模块](../project/modules.md)中做这些修改，以使这些接口与 `lib.d.ts` 相关联。我们推荐你创建一个称为 `global.d.ts` 的特殊文件。
这里有我们需要添加至 `Window`，`Math`，`Date` 的一些例子：
### Window
仅仅是添加至 `Window` 接口：
```ts
interface Window {
helloWorld(): void;
}
```
这将允许你以类型安全的形式使用它：
```ts
// Add it at runtime
window.helloWorld = () => console.log('hello world');
// Call it
window.helloWorld();
// 滥用会导致错误
window.helloWorld('gracius'); // Error: 提供的参数与目标不匹配
```
### Math
全局变量 `Math` 在 `lib.d.ts` 中被定义为：
```ts
/** An intrinsic object that provides basic mathematics functionality and constants. */
declare var Math: Math;
```
即变量 `Math` 是 `Math` 的一个实例，`Math` 接口被定义为：
```ts
interface Math {
E: number;
LN10: number;
// others ...
}
```
当你想在 `Math` 全局变量上添加你需要的属性时，你只需要把它添加到 `Math` 的全局接口上即可，例如：在[`seedrandom Project`](https://www.npmjs.com/package/seedrandom)项目里，它添加了 `seedrandom` 函数至全局的 `Math` 对象上，这很容易被声明：
```ts
interface Math {
seedrandom(seed?: string): void;
}
```
你可以像下面一样使用它：
```ts
Math.seedrandom();
Math.seedrandom('Any string you want');
```
### Date
如果你在 `lib.d.ts` 中寻找 `Date` 定义的声明，你将会找到如下代码：
```ts
declare var Date: DateConstructor;
```
接口 `DateConstructor` 与上文中 `Math` 和 `Window` 接口一样，它涵盖了可以使用的 `Date` 全局变量的成员（如：`Date.now()`）。除此之外，它还包含了可以让你创建 `Date` 实例的构造函数签名（如：`new Date()`）。`DateConstructor` 接口的一部分代码如下所示：
```ts
interface DateConstructor {
new (): Date;
// 一些其他的构造函数签名
now(): number;
// 其他成员函数
}
```
在 [datejs](https://github.com/abritinthebay/datejs) 里，它在 `Date` 的全局变量以及 `Date` 实例上同时添加了成员，因此这个库的 TypeScript 定义看起来像如下所示（社区已经[定义](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/datejs/index.d.ts)好了）：
```ts
// DateJS 公开的静态方法
interface DateConstructor {
/** Gets a date that is set to the current date. The time is set to the start of the day (00:00 or 12:00 AM) */
today(): Date;
// ... so on and so forth
}
// DateJS 公开的实例方法
interface Date {
/** Adds the specified number of milliseconds to this instance. */
addMilliseconds(milliseconds: number): Date;
// ... so on and so forth
}
```
这允许你在类型安全的情况下做：
```ts
const today = Date.today();
const todayAfter1second = today.addMilliseconds(1000);
```
### string
如果你在 `lib.d.ts` 里寻找 `string`，你将会找到与 `Date` 相类似的内容（全局变量 `String`，`StringConstructor` 接口，`String` 接口）。但值得注意的是，`String` 接口也会影响字符串字面量，如下所示：
```ts
interface String {
endsWith(suffix: string): boolean;
}
String.prototype.endsWith = function(suffix: string): boolean {
const str: string = this;
return str && str.indexOf(suffix, str.length - suffix.length) !== -1;
};
console.log('foo bar'.endsWith('bas')); // false
console.log('foo bas'.endsWith('bas')); // true
```
### 终极 string
基于可维护性，我们推荐创建一个 `global.d.ts` 文件。然而，如果你愿意，你可以通过使用 `declare global { /* global namespace */ }`，从文件模块中进入全局命名空间：
```ts
// 确保是模块
export {};
declare global {
interface String {
endsWith(suffix: string): boolean;
}
}
String.prototype.endsWith = function(suffix: string): boolean {
const str: string = this;
return str && str.indexOf(suffix, str.length - suffix.length) !== -1;
};
console.log('foo bar'.endsWith('bas')); // false
console.log('foo bas'.endsWith('bas')); // true
```
## 使用你自己定义的 `lib.d.ts`
正如上文所说，使用 `--noLib` 编译选项会导致 TypeScript 排除自动包含的 `lib.d.ts` 文件。为什么这个功能是有效的，我例举了一些常见原因：
- 运行的 JavaScript 环境与基于标准浏览器运行时环境有很大不同；
- 你希望在代码里严格的控制全局变量，例如：`lib.d.ts` 将 `item` 定义为全局变量，你不希望它泄漏到你的代码里。
一旦你排除了默认的 `lib.d.ts` 文件，你就可以在编译上下文中包含一个命名相似的文件，TypeScript 将提取该文件进行类型检查。
::: tip
小心使用 `--noLib` 选项，一旦你使用了它，当你把你的项目分享给其他人时，它们也将被迫使用 `--noLib` 选项，更糟糕的是，如果将这些代码放入你的项目中，你可能需要将它们移植到基于你的代码的 `lib` 中。
:::
## 编译目标对 `lib.d.ts` 的影响
设置编译目标为 `es6` 时，能导致 `lib.d.ts` 包含更多像 Promise 现代（es6）内容的环境声明。编译器目标的这种作用，改变了代码的环境，这对某些人来说是理想的，但是这对另外一些人来说造成了困扰，因为它将编译出的代码与环境混为一谈。
当你想对环境进行更细粒的控制时，你应该使用我们接下来将要讨论的 `--lib` 选项。
## `--lib` 选项
有时，你想要解耦编译目标（即生成的 JavaScript 版本）和环境库支持之间的关系。例如对于 Promise，你的编译目标是 `--target es5`，但是你仍然想使用它，这时，你可以使用 `lib` 对它进行控制。
::: tip
使用 `--lib` 选项可以将任何 `lib` 与 `--target` 解耦。
:::
你可以通过命令行或者在 `tsconfig.json` 中提供此选项（推荐）：
### 命令行
```ts
tsc --target es5 --lib dom,es6
```
### config.json
```json
"compilerOptions": {
"lib": ["dom", "es6"]
}
```
`lib` 分类如下：
- JavaScript 功能
- es5
- es6
- es2015
- es7
- es2016
- es2017
- esnext
- 运行环境
- dom
- dom.iterable
- webworker
- scripthost
- ESNext 功能选项
- es2015.core
- es2015.collection
- es2015.generator
- es2015.iterable
- es2015.promise
- es2015.proxy
- es2015.reflect
- es2015.symbol
- es2015.symbol.wellknown
- es2016.array.include
- es2017.object
- es2017.sharedmemory
- esnext.asynciterable
::: tip NOTE
`--lib` 选项提供非常精细的控制，因此你最有可能从运行环境与 JavaScript 功能类别中分别选择一项，如果你没有指定 `--lib`，则会导入默认库：
- `--target` 选项为 es5 时，会导入 es5, dom, scripthost。
- `--target` 选项为 es6 时，会导入 es6, dom, dom.iterable, scripthost。
:::
我个人的推荐：
```json
"compilerOptions": {
"target": "es5",
"lib": ["es6", "dom"]
}
```
包括使用 Symbol 的 ES5 使用例子：
```json
"compilerOptions": {
"target": "es5",
"lib": ["es5", "dom", "scripthost", "es2015.symbol"]
}
```
## 在旧的 JavaScript 引擎时使用 Polyfill
> [关于此主题的一个视频](https://egghead.io/lessons/typescript-using-es6-and-esnext-with-typescript)
要使用一些新功能如 `Map`、`Set`、`Promise`（随着时间推移会变化），你可以使用现代的 `lib` 选项，并且需要安装 `core-js`：
```shell
npm install core-js --save-dev
```
接着，在你的项目里导入它：
```ts
import 'core-js';
```
================================================
FILE: docs/typings/literals.md
================================================
# 字面量类型
字面量是 JavaScript 本身提供的一个准确变量。
## 字符串字面量
你可以使用一个字符串字面量作为一个类型：
```ts
let foo: 'Hello';
```
在这里，我们创建了一个被称为 `foo` 变量，它仅接收一个字面量值为 `Hello` 的变量：
```ts
let foo: 'Hello';
foo = 'Bar'; // Error: 'bar' 不能赋值给类型 'Hello'
```
它们本身并不是很实用，但是可以在一个联合类型中组合创建一个强大的（实用的）抽象：
```ts
type CardinalDirection = 'North' | 'East' | 'South' | 'West';
function move(distance: number, direction: CardinalDirection) {
// ...
}
move(1, 'North'); // ok
move(1, 'Nurth'); // Error
```
## 其他字面量类型
TypeScript 同样也提供 `boolean` 和 `number` 的字面量类型：
```ts
type OneToFive = 1 | 2 | 3 | 4 | 5;
type Bools = true | false;
```
## 推断
通常，你会得到一个类似于 `Type string is not assignable to type 'foo'` 的错误，如下：
```ts
function iTakeFoo(foo: 'foo') {}
const test = {
someProp: 'foo'
};
iTakeFoo(test.someProp); // Error: Argument of type string is not assignable to parameter of type 'foo'
```
这是由于 `test` 被推断为 `{ someProp: string }`，我们可以采用一个简单的类型断言来告诉 TypeScript 你想推断的字面量：
```ts
function iTakeFoo(foo: 'foo') {}
const test = {
someProp: 'foo' as 'foo'
};
iTakeFoo(test.someProp); // ok
```
或者使用类型注解的方式，来帮助 TypeScript 推断正确的类型：
```ts
function iTakeFoo(foo: 'foo') {}
type Test = {
someProp: 'foo';
};
const test: Test = {
// 推断 `someProp` 永远是 'foo'
someProp: 'foo'
};
iTakeFoo(test.someProp); // ok
```
## 使用用例
TypeScript 枚举类型是基于数字的，你可以使用带字符串字面量的联合类型，来模拟一个基于字符串的枚举类型，就好像上文中提出的 `CardinalDirection`。你甚至可以使用下面的函数来生成 `key: value` 的结构：
```ts
// 用于创建字符串列表映射至 `K: V` 的函数
function strEnum(o: Array
## 最后
如果你和我一样对 TypeScript 充满兴趣，可以订阅（star）本项目，及时收到有关于此项目的更新。
如果你对文章有任何疑问，欢迎提交 [issues](https://github.com/jkchao/typescript-book-chinese/issues) 和我交流。
如果你认为有些地方翻译不够准确，或者你想补充一些文中没提到但是非常有意思的知识点，欢迎 [PR](https://github.com/jkchao/typescript-book-chinese/pulls)。
================================================
FILE: commitlint.config.js
================================================
const types = ['build', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test', 'chore', 'update'];
module.exports = {
// https://github.com/conventional-changelog/commitlint/blob/master/%40commitlint/config-angular/README.md
extends: ['@commitlint/config-angular'],
rules: {
'type-enum': [2, 'always', types]
}
};
================================================
FILE: docs/.vuepress/config.js
================================================
module.exports = {
base: '/typescript-book-chinese/',
title: '深入理解 TypeScript',
description: 'TypeScript Deep Dive 中文版',
head: [
['link', { rel: 'icon', href: `/logo.png` }],
['link', { rel: 'manifest', href: '/manifest.json' }],
['meta', { name: 'theme-color', content: '#3eaf7c' }],
['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
['meta', { name: 'msapplication-TileColor', content: '#000000' }]
],
plugins: [
// '@vuepress/pwa',
'@vuepress/back-to-top',
[
'@vuepress/google-analytics',
{
ga: 'UA-106861408-1' // UA-00000000-0
}
]
],
// theme: [],
themeConfig: {
repo: 'jkchao/typescript-book-chinese',
docsDir: 'docs',
editLinks: true,
editLinkText: '编辑此页',
activeHeaderLinks: false,
sidebarDepth: 3,
lastUpdated: '上次更新',
// algolia: {
// apiKey: 'fd0efd57c48824ceb1bcfa9690dba5b0',
// indexName: 'jkchao_typescript'
// },
adsConfig: [
{ title: '关注公众号', src: '/typescript-book-chinese/qrcode.jpg' },
{ title: '与我交流', src: '/typescript-book-chinese/contact.png' },
{
title: '购买此书',
src:
'https://static.jkchao.cn/2019-11-22/WechatIMG719.png?imageMogr2/auto-orient/thumbnail/80x/blur/1x0/quality/75|imageslim',
url: 'https://item.jd.com/12755624.html'
}
],
nav: [
{ text: '原书链接', link: 'https://basarat.gitbooks.io/typescript/content/docs/getting-started.html' },
{ text: 'Blog', link: 'https://jkchao.cn' }
],
sidebar: [
{
title: '写在前面',
collapsable: false,
children: ['/']
},
{
title: 'TypeScript 项目',
collapsable: false,
children: [
'/project/compilationContext',
'/project/declarationspaces',
'/project/modules',
'/project/namespaces',
'/project/dynamicImportExpressions'
]
},
{
title: 'TypeScript 类型系统',
collapsable: false,
children: [
'/typings/overview',
'/typings/migrating',
'/typings/types',
'/typings/ambient',
'/typings/interfaces',
'/typings/enums',
'/typings/lib',
'/typings/functions',
'/typings/callable',
'/typings/typeAssertion',
'/typings/freshness',
'/typings/typeGuard',
'/typings/literals',
'/typings/readonly',
'/typings/generices',
'/typings/typeInference',
'/typings/typeCompatibility',
'/typings/neverType',
'/typings/discrominatedUnion',
'/typings/indexSignatures',
'/typings/movingTypes',
'/typings/exceptionsHanding',
'/typings/mixins',
'/typings/thisType'
]
},
{
title: 'JSX',
collapsable: false,
children: ['/jsx/support', '/jsx/reactJSX', '/jsx/nonReactJSX']
},
{
title: 'TypeScript 错误提示',
collapsable: false,
children: ['/error/interpreting', '/error/common']
},
{
title: 'TIPs',
collapsable: false,
children: [
'/tips/stringBasedEmuns',
'/tips/nominalTyping',
'/tips/statefulFunctions',
'/tips/bind',
'/tips/curry',
'/tips/typeInstantiation',
'/tips/lazyObjectLiteralInitialization',
'/tips/classAreUseful',
'/tips/avoidExportDefault',
'/tips/limitPropertySetters',
'/tips/createArrays',
'/tips/outFileCaution',
'/tips/staticConstructors',
'/tips/singletonPatern',
'/tips/functionParameters',
'/tips/truthy',
'/tips/buildToggles',
'/tips/typesafeEventEmitter',
'/tips/metadata',
'/tips/covarianceAndContravariance',
'/tips/infer'
]
},
{
title: 'TypeScript 编译原理',
collapsable: false,
children: [
'/compiler/overview',
'/compiler/program',
'/compiler/ast',
'/compiler/scanner',
'/compiler/parser',
'/compiler/binder',
'/compiler/checker',
'/compiler/emitter'
]
},
{
title: 'TypeScript FAQs',
collapsable: false,
children: [
'./faqs/common-bug-not-bugs',
'./faqs/common-feature-request',
'./faqs/type-system-behavior',
'./faqs/function',
'./faqs/class',
'./faqs/generics',
'./faqs/modules',
'./faqs/enums',
'./faqs/type-guards',
'./faqs/jsx-and-react',
'./faqs/thing-that-dont-work',
'./faqs/commandline-behavior',
'./faqs/tsconfig-behavior'
]
},
{
title: 'TypeScript 更新',
collapsable: false,
children: ['/new/typescript-3.9', '/new/typescript-3.8', '/new/typescript-3.7']
}
// {
// title: 'TypeScript 更新',
// collapsable: false,
// children: ['/new/typescript-3.7']
// }
]
}
};
================================================
FILE: docs/.vuepress/public/manifest.json
================================================
{
"name": "TypeScriptBook",
"short_name": "TypeScriptBook",
"icons": [
{
"src": "/icons/android-chrome-36x36.png",
"sizes": "36x36",
"type": "image/png",
"density": 0.75
},
{
"src": "/icons/android-chrome-48x48.png",
"sizes": "48x48",
"type": "image/png",
"density": 1
},
{
"src": "/icons/android-chrome-72x72.png",
"sizes": "72x72",
"type": "image/png",
"density": 1.5
},
{
"src": "/icons/android-chrome-96x96.png",
"sizes": "96x96",
"type": "image/png",
"density": 2
},
{
"src": "/icons/android-chrome-144x144.png",
"sizes": "144x144",
"type": "image/png",
"density": 3
},
{
"src": "/icons/android-chrome-192x192.png",
"sizes": "192x192",
"type": "image/png",
"density": 4
}
],
"start_url": "/typescript-book-chinese/",
"display": "standalone",
"background_color": "#fff",
"theme_color": "#3eaf7c"
}
================================================
FILE: docs/.vuepress/theme/components/Ads.vue
================================================