TypeScript 3.7

空值合并（Nullish Coalescing）

空值合并运算符 是另一个即将到来的 ECMAScript 特性（与可选链一起），我们的团队也参与了 TC39 的的讨论工作。

你可以考虑使用 ?? 运算符来实现：当字段是 null 或 undefined 时，“回退”到默认值。比如我们可以这样写代码：

let x = foo ?? bar();

这种新方式的意思是，当 foo “存在”时 x 等于 foo；但假如 foo 是 null 或 undefined ，x 等于 bar() 的计算结果。

同样的，上面的代码可以写出等价代码。

let x = (foo !== null && foo !== undefined) ?
    foo :
    bar();

当尝试使用默认值时，?? 运算符可以代替 || 的作用。例如，下面的代码片段尝试获取上一次储存在 localStorage 中的 volume（如果它已保存）; 但是因为使用了 || ，留下一个 bug。

function initializeAudio() {
    let volume = localStorage.volume || 0.5

    // ...
}

如果 localStorage.volume 的值是 0，这段代码将会把 volume 的值设置为 0.5，这是一个意外情况。而 ?? 避免了将 0、NaN 和 "" 视为假值的意外情况。

我们非常感谢社区成员 Wenlu Wang 和 Titian Cernicova Dragomir 实现了这个特性！想了解更多细节，你可以查看他们的 PR 和空值合并草案的 Repo。

`--declaration` 和 `--allowJs`

--declaration 选项允许我们从 TypeScript 源文件（诸如 .ts 和 .tsx 文件）生成 .d.ts 文件（声明文件）。 .d.ts 文件的重要性有几个方面：

首先，它们使得 TypeScript 能够对外部项目进行类型检查，同时避免重复检查其源代码。另一方面，它们使得 TypeScript 能够与现存的 JavaScript 库相互配合，即使这些库构建时并未使用 TypeScript。最后，还有一个通常被忽略的好处：在使用支持 TypeScript 的编辑器时，TypeScript 和 JavaScript 使用者都可以从这些文件中受益，例如更高级的自动完成。

不幸的是，--declaration 不能与 --allowJs 选项一起使用，--allowJs 选项允许混合使用 TypeScript 和 JavaScript 文件。这是一个令人沮丧的限制，因为它意味着使用者在迁移代码库时无法使用 --declaration 选项，即使代码包含了 JSDoc 注释。 TypeScript 3.7 对此进行了改进，允许这两个选项一起使用！

这个功能最大的影响可能比较微妙：在 TypeScript 3.7 中，编写带有 JSDoc 注释的 JavaScript 库，也能帮助 TypeScript 的使用者。

它的实现原理是，在启用 allowJs 时，TypeScript 会尽可能地分析并理解常见的 JavaScript 模式；然而，用 JavaScript 表达的某些模式看起来不一定像它们在 TypeScript 中的等效形式。启用 declaration 选项后，TypeScript 会尽力识别 JSDoc 注释和 CommonJS 形式的模块输出，并转换为有效的类型声明输出到 .d.ts 文件上。

比如下面这个代码片段

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 文件

/**
 * 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 标记的函数，也支持其他情形, 请看下面这个例子：

/**
 * @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 文件：

/**
 * @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。

`useDefineForClassFields` 编译选项和 `declare` 属性修饰符

当在 TypeScript 中写类公共字段时，我们尽力保证以下代码

class C {
    foo = 100;
    bar: string;
}

等价于构造函数中的相似语句

class C {
    constructor() {
        this.foo = 100;
    }
}

不幸的是，虽然这符合该提案早期的发展方向，但类公共字段极有可能以不同的方式进行标准化。所以取而代之的，原始代码示例可能需要进行脱糖处理，变成类似下面的代码：

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 访问器不再被触发——它们将被完全覆写。

class Base {
    set data(value: string) {
        console.log("data changed to " + value);
    }
}

class Derived extends Base {
    // 当启用 'useDefineForClassFields' 时
    // 不再触发 'console.log'
    data = 10;
}

其次，基类中的属性设定也将不起作用。

interface Animal { animalStuff: any }
interface Dog extends Animal { dogStuff: any }

class AnimalHouse {
    resident: Animal;
    constructor(animal: Animal) {
        this.resident = animal;
    }
}

class DogHouse extends AnimalHouse {
    // 当启用 'useDefineForClassFields' 时
    // 调用 'super()' 后
    // 'resident' 只会被初始化成 'undefined'！
    resident: Dog;

    constructor(dog: Dog) {
        super(dog);
    }
}

这两个问题归结为，继承时混合覆写属性与访问器，以及属性不带初始值的重新声明。

为了检测这个访问器的问题，TypeScript 3.7 现在可以在 .d.ts 文件中编译出 get/set，这样 TypeScript 就能检查出访问器覆写的情况。

对于改变类字段的代码，将字段初始化写成构造函数内的语句，就可以解决此问题。

class Base {
    set data(value: string) {
        console.log("data changed to " + value);
    }
}

class Derived extends Base {
    constructor() {
        data = 10;
    }
}

而解决第二个问题，你可以显式地提供一个初始值，或添加一个declare 修饰符来表示这个属性不要被编译。

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 查看这些改动。

我们强烈建议使用者尝试 useDefineForClassFields，并在 issues 或下面的评论区域中提供反馈。应该碰到编译选项在使用难度上的反馈，这样我们就能够了解如何使迁移变得更容易。

利用项目引用实现无构建编辑

TypeScript 的项目引用功能，为我们提供了一种简单的方法来分解代码库，从而使编译速度更快。遗憾的是，当我们编辑一个依赖未曾构建（或者构建结果过时）的项目时，体验不好。

在 TypeScript 3.7 中，当打开一个带有依赖的项目时，TypeScript 将自动切换为使用依赖中的 .ts/.tsx 源码文件。这意味着在带有外部引用的项目中，代码的修改会即时同步和生效，编码体验会得到提升。你也可以适当地打开编译器选项 disableSourceOfProjectReferenceRedirect 来禁用这个引用的功能，因为在超大型项目中这个功能可能会影响性能。

你可以阅读这个 PR 来了解这个改动的更多细节。

检查未调用的函数

一个常见且危险的错误是：忘记调用一个函数，特别是当该函数不需要参数，或者它的命名容易被误认为是一个属性而不是函数时。

interface User {
    isAdministrator(): boolean;
    notify(): void;
    doNotDisturb?(): boolean;
}

// 之后…

// 有问题的代码，别用！
function doAdminThing(user: User) {
    // 糟了！
    if (user.isAdministrator) {
        sudo();
        editTheConfiguration();
    }
    else {
        throw new AccessDeniedError("User is not an admin");
    }
}

在这段代码中，我们忘了调用 isAdministrator，导致该代码错误地允许非管理员用户修改配置！

在 TypeScript 3.7 中，它会被识别成一个潜在的错误：

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 的代码块中有被调用，在这些情况下不会被视为错误：

interface User {
    isAdministrator(): boolean;
    notify(): void;
    doNotDisturb?(): boolean;
}

function issueNotification(user: User) {
    if (user.doNotDisturb) {
        // OK，属性是可选的
    }
    if (user.notify) {
        // OK，调用了该函数
        user.notify();
    }
}

如果你打算对该函数进行测试但不调用它，你可以修改它的类型定义，让它可能是 undefined/null，或使用 !! 来编写类似 if (!!user.isAdministrator) 的代码，表示代码逻辑确实是这样的。

我们非常感谢社区成员 @jwbay 提出了这个问题的概念并持续跟进实现了这个需求的当前版本。

TypeScript 文件中的 `// @ts-nocheck`

TypeScript 3.7 允许我们在 TypeScript 文件的顶部添加一行 // @ts-nocheck 注释来关闭语义检查。这个注释原本只在 checkJs 选项启用时的 JavaScript 源文件中有效，但我们扩展了它，让它能够支持 TypeScript 文件，这样所有使用者在迁移的时候会更方便。

分号格式化选项

JavaScript 有一个自动分号插入（ASI，automatic semicolon insertion）规则，TypeScript 内置的格式化程序现在能支持在可选的尾分号位置插入或删除分号。该设置现在在 Visual Studio Code Insiders ，以及 Visual Studio 16.4 Preview 2 中的“工具选项”菜单中可用。

New semicolon formatter option in VS Code

将值设定为 “insert” 或 “remove” 同时也会影响自动导入、类型提取、以及其他 TypeScript 服务提供的自动生成代码的格式。将设置保留为默认值 “ignore” 可以使生成代码的分号自动配置匹配当前文件的风格。

3.7 的破坏性变更

DOM 变更

lib.dom.d.ts 中的类型声明已更新。这些变更大部分是与空值检查有关的检测准确性变更，最终的影响取决于你的代码库。

类字段处理

正如上文提到的，TypeScript 3.7 现在能够在 .d.ts 文件中编译出 get/set，这可能对 3.5 和更低版本的 TypeScript 使用者来说是破坏性变更。 TypeScript 3.6 的使用者不会受影响，因为该版本对这个功能已经进行了预兼容。

useDefineForClassFields 选项虽然自身没有破坏性变更，但不排除以下情形：

在派生类中用属性声明覆盖了基类的访问器
覆盖声明属性，但是没有初始值

要了解全部的影响，请查看上面关于 useDefineForClassFields 的章节。

函数真值检查

正如上文提到的，现在当函数在 if 条件语句中未被调用时 TypeScript 会报错。当 if 条件语句中判断的是函数时将会报错，除非符合以下情形：

该函数是可选属性
未开启 strictNullChecks 选项
该函数在 if 的代码块中有被调用

本地和导入的类型声明现在会产生冲突

TypeScript 之前有一个 bug，导致允许以下代码结构：

// ./someOtherModule.ts
interface SomeType {
    y: string;
}

// ./myModule.ts
import { SomeType } from "./someOtherModule";
export interface SomeType {
    x: number;
}

function fn(arg: SomeType) {
    console.log(arg.x); // Error! 'x' doesn't exist on 'SomeType'
}

这里，SomeType 同时来源于 import 声明和本地 interface 声明。出人意料的是，在模块内部，SomeType 只会指向 import 的定义，而本地声明的 SomeType 仅在另一个文件的导入中起效。这很令人困惑，我们对类似的个例进行的调查表明，广大开发者通常理解的情况不一样。

在 TypeScript 3.7 中，这个问题中的重复声明现在可以被正确地识别为一个错误。合理的修复方案取决于开发者的原始意图，并应该逐案解决。通常，命名冲突不是故意的，最好的办法是重命名导入的那个类型。如果是要扩展导入的类型，则可以编写模块扩展（module augmentation）来代替。

3.7 API 变化

为了实现上文中提到的递归的类型别名模式，TypeReference 接口已经移除了 typeArguments 属性。开发者应该在 TypeChecker 实例上使用 getTypeArguments 函数来代替。

TypeScript 使用指南手册