Flag Deprecation Plan

[RyanCavanaugh]

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.

Release / Phase	Description
TypeScript 5.0 - Phase 1	❔ Deprecation warnings introduced
TypeScript 5.5 - Phase 2	⚠ Flags start doing nothing
TypeScript 6.0 - Phase 3	❌ Flags removed entirely

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

[fatcerberus]

non-strict-mode code is extremely rare in modern JS

While absolutely true, devil’s advocate argument is that there’s still a difference in JS today between a (non-module) file with a "use strict" at the top and one without—and TS is meant to be spec-compliant outside of type annotations as a design goal.

[RyanCavanaugh]

One reason I advocate for removing noImplicitUseStrict is that no one ever can remember what it actually does, which based on reading the description I wrote up there, includes me 😬

[MartinJohns]

Considering the current release cycle of 3 months, I think two and a half years quite too long for this. But otherwise I'm all for deprecating stuff. 👍

[robpalme]

This sounds great. Freedom to evolve is important and this plan increases it whilst decreasing tech debt (entropy).

I recommend updating column 1 of the table to switch the order and say "Phase 1 (e.g. TypeScript 5.0)". Right now it looks like you are mandating 5 minors releases between each phase whereas the description that follows indicates it is only an example duration.

3.5 years (10 releases) to complete an entire deprecation cycle seems excessive. I'd suggest 2-4 releases for the full cycle would normally be fine.

[RyanCavanaugh]

Summarizing decisions from the meeting:

Queued for deprecation: noImplicitUseStrict , target: es3, keyofStringsOnly, suppressExcessPropertyErrors, suppressImplicitAnyIndexErrors, noStrictGenericChecks, charset, out

Still alive: All module targets (usage of these, based on GitHub queries, is higher than I anticipated). We'll investigate top repos using these targets (especially umd and systemjs) to see what their build systems are and try to evaluate their likelihood to adopt new TS versions (e.g. are these projects effectively archived?), new build system (e.g. do they seem to be wanting to move to a newer target), or whether these config settings are even active (e.g. are they actually using a different emitter?)

Also still alive, for now: noFallthroughCasesInSwitch - while we don't want to add any new lint-like rules to TS, this one is still high-value for what it does and asking folks to pick up a linter if they're happy with our limited lint-y offerings seems a bit much.

Possibly gone sooner?: I'm proposing that we just remove charset and out entirely in 5.0. Since these haven't worked anytime in recent memory, they're effectively already deprecated and any runway seems unneeded.

[Jack-Works]

non-strict-mode code is extremely rare in modern JS

While absolutely true, devil’s advocate argument is that there’s still a difference in JS today between a (non-module) file with a "use strict" at the top and one without—and TS is meant to be spec-compliant outside of type annotations as a design goal.

So instead, add a new type check error for non-module files:

TS____: This file requires a "use strict" directive.

[Jack-Works]

Add a new --legacyDecorator flag and deprecates --experimentalDecorator

[MartinJohns]

@styfle See #47572 for this.

[Bessonov]

Just my 2 cents: If it helps ship more features/bugfixes, I would vote for removement of already deprecated flags in 5.0. Additionally, I vote for faster removement of new deprecated flags. For example, not more than one year after deprecation. Or even in 2 ts releases.

[Ikaer]

I'm still using module "amd" with requirejs in some of my old projects :/. Is that so old school ?

[coolCucumber-cat]

I'm still using module "amd" with requirejs in some of my old projects :/. Is that so old school ?

Yes. We have modules now so there's no reason why you would ever need this after 2015. It's just increased complexity and dead code to support something no one uses or should use. We should deprecate CJS too, it's only used in old code, doubt anyone is compiling any new code with it.

[reporter123]

cjs is the only one I actually learned when I studied javascript programming a couple years back. Nodejs at that time still had a few big debug frameworks that needed it. I think even they now have stable es model support. Separate tools like Babel can make the conversion if its still needed.