-
Notifications
You must be signed in to change notification settings - Fork 12.4k
API Breaking Changes
- The
tsserverlibrary.js
entrypoint is now a thin wrapper around the normaltypescript.js
entrypoint. It's recommended to switch to the latter where possible. If you were relying on being able to loadtsserverlibrary.js
in a non-CJS context (e.g., as a browser global),tsserverlibrary.js
will throw, as it's unable to generically load another script into the page; you should switch to usingtypescript.js
.
- The TypeScript package now targets ES2020 and requires Node 14.17 or newer. Note that Node 14 is EOL at the end of April 2023.
-
Occurrences
is request handling ontsserver
andLanguageService .getOccurrencesAtPosition
are removed now that they have been deprecated for a long time. UsedocumentHighlights
request ontsserver
andLanguageService.getDocumentHighlights
instead.
- TypeScript is now itself implemented using modules (though, the package still contains bundled outputs).
- The exported API is no longer defined as a "configurable" object, so operations which attempt to modify the package at runtime such as
const ts = require("ts"); ts.readJson = ...
will throw. - The output files have changed significantly; if you are patching TypeScript, you will definitely need to change your patches.
- The exported API is no longer defined as a "configurable" object, so operations which attempt to modify the package at runtime such as
-
typescriptServices.js
has been removed; this file was identical totypescript.js
, the entrypoint for our npm package. -
protocol.d.ts
is no longer included in the package; usetsserverlibrary.d.ts
'sts.server.protocol
namespace instead.- Some elements of the protocol are not actually exported by the
ts.server.protocol
namespace, but were emitted in the oldprotocol.d.ts
file, and may need to be accessed off of thets
namespace instead. See https://github.com/microsoft/vscode/pull/163365 for an potential way to minimize changes to protocol-using codebases.
- Some elements of the protocol are not actually exported by the
- The TypeScript package now targets ES2018 and requires Node 12.20 or newer. Prior to 5.0, our package targeted ES5 syntax and the ES2015 library.
-
ts.Map
,ts.Set
,ts.ESMap
,ts.Iterator
, and associated types have been removed. The nativeMap
,Set
,Iterator
and associated types should be used instead. - The
ts.Collection
andts.ReadonlyCollection
types have been removed. These types were unused in our public API, and were declared with the oldMap
/Set
types (also removed in 5.0). - The
ts.Push
type has been removed. This type was only used twice in our API, and its uses have been replaced with arrays for consistency with other parts of our API. -
BuilderProgramHost
no longer requires methoduseCaseSensitiveFileNames
since its used fromprogram
. - The TypeScript compiler is now compiled with
strictFunctionTypes
; to allow this, certain public AST visitor APIs have been modified to better reflect their underlying guarantees, as well as various corrections. The resulting API should be one that is more compatible with projects which also enablestrictFunctionTypes
(a recommended option enabled bystrict
).- The
VisitResult
type is no longerundefined
by default; if you have writtenVisitResult<Node>
, you may need to rewrite it asVisitResult<Node | undefined>
to reflect that your visitor may return undefined. - Visitor-using APIs now correctly reflect the type of the output, including whether it passed a given type guard test, and whether or not it may be undefined. In order to get the type you expect, you may need to pass a
test
parameter to verify your expectations and then check the result forundefined
(or, modify your visitor to return a more specific type).
- The
-
typingOptions
along with its propertyenableAutoDiscovery
which was deprecated for a long time is not supported any more intsconfig.json
andjsconfig.json
. UsetypeAcquisition
in the config instead. - This release removes many long-deprecated parts of our public API, including (but not limited to):
- The top-level Node factory functions (deprecated since TS 4.0) such as
ts.createIdentifier
; use the factory provided in yourTransformationContext
orts.factory
instead. - The
isTypeAssertion
function (deprecated since TS 4.0); useisTypeAssertionExpression
. - The overloads of
createConstructorTypeNode
andupdateConstructorTypeNode
which do not accept modifiers (deprecated since TS 4.2). - The overloads of
createImportTypeNode
andupdateImportTypeNode
which do not accept assertions (deprecated since TS 4.6). - The overloads of
createTypeParameterDeclaration
andupdateTypeParameterDeclaration
which do not accept modifiers (deprecated since TS 4.6). - Node properties and factory function overloads which predate the merger of decorators and modifiers (deprecated since TS 4.8).
- The top-level Node factory functions (deprecated since TS 4.0) such as
As part of an optimization on substitution types, SubstitutionType
objects no longer contain the substitute
property representing the effective substitution (usually an intersection of the base type and the implicit constraint) - instead, they just contain the constraint
property.
For more details, read more on the original pull request.
The current direction of decorators in TC39 means that TypeScript will have to handle a break in terms of placement of decorators. Previously, TypeScript assumed decorators would always be placed prior to all keywords/modifiers. For example
@decorator
export class Foo {
// ...
}
Decorators as currently proposed do not support this syntax.
Instead, the export
keyword must precede the decorator.
export @decorator class Foo {
// ...
}
Unfortunately, TypeScript's trees are concrete rather than abstract, and our architecture expects syntax tree node fields to be entirely ordered before or after each other. To support both legacy decorators and decorators as proposed, TypeScript will have to gracefully parse, and intersperse, modifiers and decorators.
To do this, it exposes a new type alias called ModifierLike
which is a Modifier
or a Decorator
.
export type ModifierLike = Modifier | Decorator;
Decorators are now placed in the same field as modifiers
which is now a NodeArray<ModifierLike>
when set, and the entire field is deprecated.
- readonly modifiers?: NodeArray<Modifier> | undefined;
+ /**
+ * @deprecated ...
+ * Use `ts.canHaveModifiers()` to test whether a `Node` can have modifiers.
+ * Use `ts.getModifiers()` to get the modifiers of a `Node`.
+ * ...
+ */
+ readonly modifiers?: NodeArray<ModifierLike> | undefined;
All existing decorators
properties have been marked as deprecated and will always be undefined
if read.
The type has also been changed to undefined
so that existing tools know to handle them correctly.
- readonly decorators?: NodeArray<Decorator> | undefined;
+ /**
+ * @deprecated ...
+ * Use `ts.canHaveDecorators()` to test whether a `Node` can have decorators.
+ * Use `ts.getDecorators()` to get the decorators of a `Node`.
+ * ...
+ */
+ readonly decorators?: undefined;
To avoid all deprecation warnings and other issues, TypeScript now exposes four new functions. There are individual predicates for testing whether a node has support modifiers and decorators, along with respective accessor functions for grabbing them.
function canHaveModifiers(node: Node): node is HasModifiers;
function getModifiers(node: HasModifiers): readonly Modifier[] | undefined;
function canHaveDecorators(node: Node): node is HasDecorators;
function getDecorators(node: HasDecorators): readonly Decorator[] | undefined;
As an example of how to access modifiers off of a node, you can write
const modifiers = canHaveModifiers(myNode) ? getModifiers(myNode) : undefined;
With the note that each call to getModifiers
and getDecorators
may allocate a new array.
For more information, see changes around
-
resolveTypeReferenceDirectives
(both the services and global ts version) now accept an array ofFileReference
s as a first argument. If you reimplementresolveTypeReferenceDirectives
, you need to handle both thestring[]
andFileReference[]
cases now.
-
factory.createImportSpecifier
andfactory.updateImportSpecifier
now take anisTypeOnly
parameter:- createImportSpecifier(propertyName: Identifier | undefined, name: Identifier): ImportSpecifier; + createImportSpecifier(isTypeOnly: boolean, propertyName: Identifier | undefined, name: Identifier): ImportSpecifier; - updateImportSpecifier(node: ImportSpecifier, propertyName: Identifier | undefined, name: Identifier): ImportSpecifier; + updateImportSpecifier(node: ImportSpecifier, isTypeOnly: boolean, propertyName: Identifier | undefined, name: Identifier): ImportSpecifier;
You can read more about this change at the implementing PR.
-
visitNode
'slift
Takes areadonly Node[]
Instead of aNodeArray<Node>
The
lift
function in thevisitNode
API now takes areadonly Node[]
. You can see details of the change here.
-
Type Arguments in JavaScript Are Not Parsed as Type Arguments
Type arguments were already not allowed in JavaScript, but in TypeScript 4.1, the parser will parse them in a more spec-compliant way. So when writing the following code in a JavaScript file:
f<T>(100)
TypeScript will parse it as the following JavaScript:
(f < T) > (100)
This may impact you if you were leveraging TypeScript's API to parse type constructs in JavaScript files, which may have occurred when trying to parse Flow files.
-
TypeScript provides a set of "factory" functions for producing syntax tree nodes; however, TypeScript 4.0 provides a new node factory API. For TypeScript 4.0 we've made the decision to deprecate these older functions in favor of the new ones. For more details, read up on the relevant pull request for this change.
-
TupleTypeNode.elementTypes
renamed toTupleTypeNode.elements
. -
KeywordTypeNode
is no longer used to representthis
andnull
types.null
now gets aLiteralTypeNode
,this
now always gets aThisTypeNode
. -
TypeChecker.typeToTypeNode
now correctly produces aLiteralTypeNode
fortrue
andfalse
types, which matches the behavior in the parser. Prior to this the checker was incorrectly returning thetrue
andfalse
tokens themselves, which are indistinguishable from expressions when traversing a tree.
- The mutable property
disableIncrementalParsing
has been removed. It was untested and, at least on GitHub, unused by anyone. Incremental parsing can no longer be disabled.
-
the
typeArguments
property has been removed from theTypeReference
interface, and thegetTypeArguments
method onTypeChecker
instances should be used instead. This change was necessary to defer resolution of type arguments in order to support recursive type references.As a workaround, you can define a helper function to support multiple versions of TypeScript.
function getTypeArguments(checker: ts.TypeChecker, typeRef: ts.TypeReference) { return checker.getTypeArguments?.(typeRef) ?? (typeRef as any).typeArguments; }
-
SymbolFlags.JSContainer
has been renamed toSymbolFlags.Assignment
to reflect that Typescript now supports expando assignments to functions.
- The deprecated internal method
LanguageService#getSourceFile
has been removed. See #24540. - The deprecated function
TypeChecker#getSymbolDisplayBuilder
and associated interfaces have been removed. See #25331. The emitter and node builder should be used instead. - The deprecated functions
escapeIdentifier
andunescapeIdentifier
have been removed. Due to changing how the identifier name API worked in general, they have been identity functions for a few releases, so if you need your code to behave the same way, simply removing the calls should be sufficient. Alternatively, the typesafeescapeLeadingUnderscores
andunescapeLeadingUnderscores
should be used if the types indicate they are required (as they are used to convert to or from branded__String
andstring
types). - The
TypeChecker#getSuggestionForNonexistentProperty
,TypeChecker#getSuggestionForNonexistentSymbol
, andTypeChecker#getSuggestionForNonexistentModule
methods have been made internal, and are no longer part of our public API. See #25520.
-
getJsxIntrinsicTagNames
has been removed and replaced withgetJsxIntrinsicTagNamesAt
, which requires a node to use as the location to look up the valid intrinsic names at (to handle locally-scoped JSX namespaces).
- Some services methods (
getCompletionEntryDetails
andgetCompletionEntrySymbols
) have additional parameters. Plugins that wrap the language service must pass these parameters along to the original implementation. See #19507
-
Symbol.name
,Symbol.getName()
, andIdentifier.text
are all now of type__String
. This is a special branded string to help track where strings are appropriately escaped and prevent their misuse.escapeIdentifier
andunescapeIdentifier
has been renamed toescapeLeadingUnderscores
andunescapeLeadingUnderscores
and had their types updated accordingly. Deprecated versions ofescapeIdentifier
andunescapeIdentifier
still exist with the old name and type signature, however they will be removed in a future version. See #16915.
-
The following types/namespaces are now string enums:
ts.Extension
,ts.ScriptElementKind
,ts.HighlightSpanKind
,ts.ClassificationTypeNames
,protocol.CommandTypes
,protocol.IndentStyle
,protocol.JsxEmit
,protocol.ModuleKind
,protocol.ModuleResolutionKind
,protocol.NewLineKind
, andprotocol.ScriptTarget
. Also,ts.CommandNames
is now an alias forprotocol.CommandTypes
. See #15966 and #16425. -
The type
EnumLiteralType
was removed andLiteralType
is used instead.LiteralType
also replaces.text
with a.value
which may be either a number or string. See String valued members in enums. -
Declaration
does not have aname
property. TypeScript now recognize assignments in .js files as declarations in certain contexts, e.g.func.prototype.method = function() {..}
will be a declaration of membermethod
onfunc
. As a resultDeclaration
is not guaranteed to have aname
property as before. A new type was introducedNamedDeclaration
to take the place ofDeclaration
, andDeclaration
moved to be the base type of bothNamedDeclaration
andBinaryExpression
. Casting toNamedDeclaration
should be safe for non .js declarations. See #15594 for more details.
-
ts.Map<T>
is now a nativeMap<string, T>
or a shim. This affects theSymbolTable
type, exposed bySymbol.members
,Symbol.exports
, andSymbol.globalExports
.
-
ParseConfigHost
now requires a new memberreadFile
to support configuration inheritance.
-
LanguageService.getSourceFile
has been removed;LanguageService.getProgram().getSourceFile
should be used instead.
-
ts.parseConfigFile
has been renamed tots.parseJsonConfigFileContent
-
return type of
CompilerHost.resolveModuleNames
was changed fromstring[]
toResolvedModule[]
. Extra optional propertyisExternalLibraryImport
in ResolvedModule interface denotes ifProgram
should apply some particular set of policies to the resolved file. For example if Node resolver has resolved non-relative module name to the file in 'node_modules', then this file:- should be a 'd.ts' file
- should be an external module
- should not contain tripleslash references.
Rationale: files containing external typings should not pollute global scope (to avoid conflicts between different versions of the same package). Also such files should never be added to the list of compiled files (otherwise compiled .ts file might overwrite actual .js file with implementation of the package)
-
TypeChecker.emitFiles
is no longer available; useProgram.emit
instead. - Getting diagnostics are now all centralized on Program,
- for Syntactic diagnostics for a single file use:
Program.getSyntacticDiagnostics(sourceFile)
- for Syntactic diagnostics for all files use:
Program.getSyntacticDiagnostics()
- for Semantic diagnostics for a single file use:
Program.getSemanticDiagnostics(sourceFile)
- for Semantic diagnostics for all files use:
Program.getSemanticDiagnostics()
- for compiler options and global diagnostics use:
Program.getGlobalDiagnostics()
- for Syntactic diagnostics for a single file use:
Tip: use ts.getPreEmitDiagnostics(program) to get syntactic, semantic, and global diagnostics for all files
Here are the details:
-
CompilerHost.getDefaultLibFilename
=>CompilerHost.getDefaultLibFileName
-
SourceFile.filename
=>SourceFile.fileName
-
FileReference.filename
=>FileReference.fileName
-
LanguageServiceHost.getDefaultLibFilename
=>LanguageServiceHost.getDefaultLibFileName
-
LanguageServiceShimHost.getDefaultLibFilename
=>LanguageServiceShimHost.getDefaultLibFileName
The full list of APIs can be found in this commit
The syntacticClassifierAbsent
parameter for the Classifier.getClassificationsForLine is now required
See Pull Request #2051 for more details.
TextChange.start
and TextChange.length
became properties instead of methods.
SourceFile.getLineAndCharacterFromPosition
became SourceFile.getLineAndCharacterOfPosition
We did some cleanup to the public interfaces, here is the full list of changes:
- Commit 2ee134c6b3c0ec
- Commit 35dde28d44122c
- Commit c9ef4db99ac93bb1c166a
- Commit b4e5d5b0b460cc88a10db
The two files exposed helpers in the past that were not part of the supported TypeScript API. If you were using any of these APIs please file an issue to re-expose them; requests for exposing helper APIs will be triaged on a case-by-case basis.
For more information please see the full change.
News
Debugging TypeScript
- Performance
- Performance-Tracing
- Debugging-Language-Service-in-VS-Code
- Getting-logs-from-TS-Server-in-VS-Code
- JavaScript-Language-Service-in-Visual-Studio
- Providing-Visual-Studio-Repro-Steps
Contributing to TypeScript
- Contributing to TypeScript
- TypeScript Design Goals
- Coding Guidelines
- Useful Links for TypeScript Issue Management
- Writing Good Design Proposals
- Compiler Repo Notes
- Deployment
Building Tools for TypeScript
- Architectural Overview
- Using the Compiler API
- Using the Language Service API
- Standalone Server (tsserver)
- TypeScript MSBuild In Depth
- Debugging Language Service in VS Code
- Writing a Language Service Plugin
- Docker Quickstart
FAQs
The Main Repo