Flag Deprecation Plan · Issue #51000 · microsoft/TypeScript (original) (raw)

TypeScript Flag Deprecation Plan

(This is a proposal, but written in terms of a blog post for clarity)

As we think about the long-term future of TypeScript and its place in the JavaScript ecosystem, it's clear that many things TypeScript 0.8 users in 2012 needed aren't things that TypeScript users in 2024 are going to need. For example, in 2012, Internet Explorer 8 (which only supports ECMAScript 3) had enough marketshare to warrant serious compatibility concern. Today, thankfully, it doesn't.

While we still consider long-term language stability to be an absolutely paramount concern, having a well-defined deprecation policy in place also makes it easier for us to be slightly less risk-averse when adding new features to the language.

To that end, starting with TypeScript 5.0, we will begin the process of removing certain flags, features, and/or behaviors which we think the language or ecosystem have largely evolved past the need for.

Schedule

The deprecation schedule is based on our existing version += 0.1 versioning cadence, aligned with ones-place-incrementing versions for clarity.

The cycle repeats again with TypeScript 6.0 also introducing whatever new deprecation warnings deemed appropriate at that time.

Phase 1: ❔ Deprecation Warnings

In phase 1 (e.g. TypeScript 5.0), using a deprecated flags will produce a commandline error:

TS9998: Flag 'keyofStringsOnly' is deprecated and will stop functioning in TypeScript 5.5. Specify 'ignoreDeprecations: "5.0"' to silence this error

As hinted to in the error, you can supply a new flag value to silence this error:

    ignoreDeprecations: "5.0"

All other behavior is unchanged.

This gives people an immediate warning of impending deprecation, but won't block them from upgrading to TypeScript 5.0.

Phase 2: ⚠ Flags Start Doing Nothing

In phase 2 (e.g. TypeScript 5.5), deprecated flags can still be specified in tsconfig / commandline settings, but no longer have any effect. This allows users to have tsconfig.json files that work on both sides of the deprecation cycle (as you might have in a monorepo with a "shared" tsconfig settings file).

Phase 3: ❌ Flags Removed

In phase 3 (e.g. TypeScript 6.0), it is an error to specify a deprecated flag.

At this point, it also becomes illegal to have ignoreDeprecations: "5.0, since this setting doesn't do anything (it's illegal to specify those flags in the first place, and they've done nothing for 5 versions).

In 6.0, the only legal value of ignoreDeprecations will then be "6.0", per its Phase 1.

5.0 Deprecation Candidates

This list is provisional; please leave comments if you are depending on these in a serious way.

Removed entirely:

• charset - already deprecated since approximately the beginning of time
• noImplicitUseStrict - non-strict-mode code is extremely rare in modern JS
• noStrictGenericChecks - this flag is broadly a bad idea, and improvements to the type system have rendered its original use cases largely moot
• out - already deprecated since approximately the beginning of time (use outFile instead)
• keyofStringsOnly - according to a rumor, we only wanted to ship this for three releases (2.9, 3.0, 3.1) when we added this!
• suppressExcessPropertyErrors - improvements in not performing subtype reduction have rendered its original use cases largely moot
• suppressImplicitAnyIndexErrors - the use cases here have been supplanted by better recognition of literal-typed keys
• noFallthroughCasesInSwitch - style concern; use a linter if this is not allowed in your coding style

Removed possible values:

• target - remove ES3 - no known extant software runs ES3 (this will be even more true in 2 years), and we don't have lib support for it anyway
• module - remove umd, system, and amd - the ecosystem is rapidly converging, and better downlevelers exist for each of these should you still need them by 2024