breaking changes for 3.1 (#235)

README.md

@@ -96,6 +96,7 @@
   * [TypeScript 1.3](./doc/release-notes/TypeScript%201.3.md)
   * [TypeScript 1.1](./doc/release-notes/TypeScript%201.1.md)
 * [Breaking Changes](./doc/breaking-changes/breaking-changes.md)
+  * [TypeScript 3.1](./doc/breaking-changes/TypeScript%203.1.md)
   * [TypeScript 2.8](./doc/breaking-changes/TypeScript%202.8.md)
   * [TypeScript 2.7](./doc/breaking-changes/TypeScript%202.7.md)
   * [TypeScript 2.6](./doc/breaking-changes/TypeScript%202.6.md)

SUMMARY.md

@@ -80,6 +80,10 @@
   * [TypeScript 1.3](./doc/release-notes/TypeScript 1.3.md)
   * [TypeScript 1.1](./doc/release-notes/TypeScript 1.1.md)
 * [Breaking Changes](./doc/breaking-changes/breaking-changes.md)
+  * [TypeScript 3.1](./doc/breaking-changes/TypeScript 3.1.md)
+  * [TypeScript 2.8](./doc/breaking-changes/TypeScript 2.8.md)
+  * [TypeScript 2.7](./doc/breaking-changes/TypeScript 2.7.md)
+  * [TypeScript 2.6](./doc/breaking-changes/TypeScript 2.6.md)
   * [TypeScript 2.4](./doc/breaking-changes/TypeScript 2.4.md)
   * [TypeScript 2.3](./doc/breaking-changes/TypeScript 2.3.md)
   * [TypeScript 2.2](./doc/breaking-changes/TypeScript 2.2.md)

doc/breaking-changes/TypeScript 3.1.md

@@ -0,0 +1,205 @@
+# TypeScript 3.1
+
+## 一些vendor特定的类型从`lib.d.ts`中被移除
+
+TypeScript内置的`.d.ts`库(`lib.d.ts`等)现在会部分地从DOM规范的Web IDL文件中生成。
+因此有一些vendor特定的类型被移除了。
+
+<details><summary>点击这里查看被移除类型的完整列表：</summary><p>
+
+* `CanvasRenderingContext2D.mozImageSmoothingEnabled`
+* `CanvasRenderingContext2D.msFillRule`
+* `CanvasRenderingContext2D.oImageSmoothingEnabled`
+* `CanvasRenderingContext2D.webkitImageSmoothingEnabled`
+* `Document.caretRangeFromPoint`
+* `Document.createExpression`
+* `Document.createNSResolver`
+* `Document.execCommandShowHelp`
+* `Document.exitFullscreen`
+* `Document.exitPointerLock`
+* `Document.focus`
+* `Document.fullscreenElement`
+* `Document.fullscreenEnabled`
+* `Document.getSelection`
+* `Document.msCapsLockWarningOff`
+* `Document.msCSSOMElementFloatMetrics`
+* `Document.msElementsFromRect`
+* `Document.msElementsFromPoint`
+* `Document.onvisibilitychange`
+* `Document.onwebkitfullscreenchange`
+* `Document.onwebkitfullscreenerror`
+* `Document.pointerLockElement`
+* `Document.queryCommandIndeterm`
+* `Document.URLUnencoded`
+* `Document.webkitCurrentFullScreenElement`
+* `Document.webkitFullscreenElement`
+* `Document.webkitFullscreenEnabled`
+* `Document.webkitIsFullScreen`
+* `Document.xmlEncoding`
+* `Document.xmlStandalone`
+* `Document.xmlVersion`
+* `DocumentType.entities`
+* `DocumentType.internalSubset`
+* `DocumentType.notations`
+* `DOML2DeprecatedSizeProperty`
+* `Element.msContentZoomFactor`
+* `Element.msGetUntransformedBounds`
+* `Element.msMatchesSelector`
+* `Element.msRegionOverflow`
+* `Element.msReleasePointerCapture`
+* `Element.msSetPointerCapture`
+* `Element.msZoomTo`
+* `Element.onwebkitfullscreenchange`
+* `Element.onwebkitfullscreenerror`
+* `Element.webkitRequestFullScreen`
+* `Element.webkitRequestFullscreen`
+* `ElementCSSInlineStyle`
+* `ExtendableEventInit`
+* `ExtendableMessageEventInit`
+* `FetchEventInit`
+* `GenerateAssertionCallback`
+* `HTMLAnchorElement.Methods`
+* `HTMLAnchorElement.mimeType`
+* `HTMLAnchorElement.nameProp`
+* `HTMLAnchorElement.protocolLong`
+* `HTMLAnchorElement.urn`
+* `HTMLAreasCollection`
+* `HTMLHeadElement.profile`
+* `HTMLImageElement.msGetAsCastingSource`
+* `HTMLImageElement.msGetAsCastingSource`
+* `HTMLImageElement.msKeySystem`
+* `HTMLImageElement.msPlayToDisabled`
+* `HTMLImageElement.msPlayToDisabled`
+* `HTMLImageElement.msPlayToPreferredSourceUri`
+* `HTMLImageElement.msPlayToPreferredSourceUri`
+* `HTMLImageElement.msPlayToPrimary`
+* `HTMLImageElement.msPlayToPrimary`
+* `HTMLImageElement.msPlayToSource`
+* `HTMLImageElement.msPlayToSource`
+* `HTMLImageElement.x`
+* `HTMLImageElement.y`
+* `HTMLInputElement.webkitdirectory`
+* `HTMLLinkElement.import`
+* `HTMLMetaElement.charset`
+* `HTMLMetaElement.url`
+* `HTMLSourceElement.msKeySystem`
+* `HTMLStyleElement.disabled`
+* `HTMLSummaryElement`
+* `MediaQueryListListener`
+* `MSAccountInfo`
+* `MSAudioLocalClientEvent`
+* `MSAudioLocalClientEvent`
+* `MSAudioRecvPayload`
+* `MSAudioRecvSignal`
+* `MSAudioSendPayload`
+* `MSAudioSendSignal`
+* `MSConnectivity`
+* `MSCredentialFilter`
+* `MSCredentialParameters`
+* `MSCredentials`
+* `MSCredentialSpec`
+* `MSDCCEvent`
+* `MSDCCEventInit`
+* `MSDelay`
+* `MSDescription`
+* `MSDSHEvent`
+* `MSDSHEventInit`
+* `MSFIDOCredentialParameters`
+* `MSIceAddrType`
+* `MSIceType`
+* `MSIceWarningFlags`
+* `MSInboundPayload`
+* `MSIPAddressInfo`
+* `MSJitter`
+* `MSLocalClientEvent`
+* `MSLocalClientEventBase`
+* `MSNetwork`
+* `MSNetworkConnectivityInfo`
+* `MSNetworkInterfaceType`
+* `MSOutboundNetwork`
+* `MSOutboundPayload`
+* `MSPacketLoss`
+* `MSPayloadBase`
+* `MSPortRange`
+* `MSRelayAddress`
+* `MSSignatureParameters`
+* `MSStatsType`
+* `MSStreamReader`
+* `MSTransportDiagnosticsStats`
+* `MSUtilization`
+* `MSVideoPayload`
+* `MSVideoRecvPayload`
+* `MSVideoResolutionDistribution`
+* `MSVideoSendPayload`
+* `NotificationEventInit`
+* `PushEventInit`
+* `PushSubscriptionChangeInit`
+* `RTCIdentityAssertionResult`
+* `RTCIdentityProvider`
+* `RTCIdentityProviderDetails`
+* `RTCIdentityValidationResult`
+* `Screen.deviceXDPI`
+* `Screen.logicalXDPI`
+* `SVGElement.xmlbase`
+* `SVGGraphicsElement.farthestViewportElement`
+* `SVGGraphicsElement.getTransformToElement`
+* `SVGGraphicsElement.nearestViewportElement`
+* `SVGStylable`
+* `SVGTests.hasExtension`
+* `SVGTests.requiredFeatures`
+* `SyncEventInit`
+* `ValidateAssertionCallback`
+* `WebKitDirectoryEntry`
+* `WebKitDirectoryReader`
+* `WebKitEntriesCallback`
+* `WebKitEntry`
+* `WebKitErrorCallback`
+* `WebKitFileCallback`
+* `WebKitFileEntry`
+* `WebKitFileSystem`
+* `Window.clearImmediate`
+* `Window.msSetImmediate`
+* `Window.setImmediate`
+
+</p></details>
+
+### 推荐：
+
+如果你的运行时能够保证这些名称是可用的（比如一个仅针对IE的应用），那么可以在本地添加那些声明，例如：
+
+对于`Element.msMatchesSelector`，在本地的`dom.ie.d.ts`文件里添加如下代码：
+
+```ts
+interface Element {
+    msMatchesSelector(selectors: string): boolean;
+}
+```
+
+相似地，若要添加`clearImmediate`和`setImmediate`，你可以在本地的`dom.ie.d.ts`里添加`Window`声明：
+
+```ts
+interface Window {
+    clearImmediate(handle: number): void;
+    setImmediate(handler: (...args: any[]) => void): number;
+    setImmediate(handler: any, ...args: any[]): number;
+}
+```
+
+## 细化的函数现在会使用`{}`，`Object`和未约束的泛型参数的交叉类型
+
+下面的代码如今会提示`x`不能被调用：
+
+```ts
+function foo<T>(x: T | (() => string)) {
+    if (typeof x === "function") {
+        x();
+//      ~~~
+// Cannot invoke an expression whose type lacks a call signature. Type '(() => string) | (T & Function)' has no compatible call signatures.
+    }
+}
+```
+
+这是因为，不同于以前的`T`会被细化掉，如今`T`会被扩展成`T & Function`。
+然而，因为这个类型没有声明调用签名，类型系统无法找到通用的调用签名可以适用于`T & Function`和`() => string`。
+
+因此，考虑使用一个更确切的类型，而不是`{}`或`Object`，并且考虑给`T`添加额外的约束条件。

doc/breaking-changes/breaking-changes.md

@@ -1,5 +1,6 @@
 # Breaking Changes
 
+* [TypeScript 3.1](./TypeScript 3.1.md)
 * [TypeScript 2.8](./TypeScript 2.8.md)
 * [TypeScript 2.7](./TypeScript 2.7.md)
 * [TypeScript 2.6](./TypeScript 2.6.md)

preface.md

@@ -102,6 +102,10 @@ TypeScript目前还在积极的开发完善之中，不断地会有新的特性
   * [TypeScript 1.3](./doc/release-notes/TypeScript 1.3.html)
   * [TypeScript 1.1](./doc/release-notes/TypeScript 1.1.html)
 * [Breaking Changes](./doc/breaking-changes/breaking-changes.html)
+  * [TypeScript 3.1](./doc/breaking-changes/TypeScript 3.1.html)
+  * [TypeScript 2.8](./doc/breaking-changes/TypeScript 2.8.html)
+  * [TypeScript 2.7](./doc/breaking-changes/TypeScript 2.7.html)
+  * [TypeScript 2.6](./doc/breaking-changes/TypeScript 2.6.html)
   * [TypeScript 2.4](./doc/breaking-changes/TypeScript 2.4.html)
   * [TypeScript 2.3](./doc/breaking-changes/TypeScript 2.3.html)
   * [TypeScript 2.2](./doc/breaking-changes/TypeScript 2.2.html)