`ts-ignore`: Allow specifying maximum typescript version

[jtannas]

🔍 Search Terms

"ts-ignore", "version", "ts-expect-error"

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Allow @ts-ignore to specify the maximum version of typescript that it applies to.
Example:

// @ts-ignore version<4.0

Inequalities might also be worth implementing:

// @ts-ignore version>4.0
// @ts-ignore version!=4.0

📃 Motivating Example

This is inspired by the use case of ts-ignore detailed in the following article written by Evan Hahn:

https://evanhahn.com/ts-ignore-is-almost-always-the-worst-option/#the-once-edge-case-when-ts-ignore-might-be-optimal:~:text=The%20one%20edge,ts%2Dignore%20compelling.

For example, imagine you’re writing a library that supports old versions of TypeScript, before they added the unknown type. If you try to use unknown, you’ll get errors in old TypeScript versions but not new ones. @ts-ignore may be the right option here, because it’ll work in both versions (unlike the alternatives).

// Using `ts-expect-error`, this:
//   - fails on TS versions <3.9 (when `ts-expect-error` was introduced)
//   - works from versions 3.9 to <4.5
//   - fails for versions >=4.5 (when `Awaited`/`Promise` were introduced)
// @ts-expect-error
type A = Awaited<Promise<string>>;

// This works on all TS versions >=2.6 when `ts-ignore` was introduced:
// @ts-ignore 
type A = Awaited<Promise<string>>;

With this new extension to ts-ignore, library authors can get the type-safety of modern TypeScript without impacting users running older TS versions.

💻 Use Cases

What this helps with

For libraries supporting TS>=2.6 (when @ts-ignore was introduced), it allows using newer keywords without disabling TS on versions that support the new syntax:

// @ts-ignore version<3.0
const foo: unknown = {}

// @ts-ignore version<4.5
type A = Awaited<Promise<string>>;

Versions of TypeScript that support the ts-ignore but predate this new feature already just ignore the version specifier as if it were a comment. This ensures that no existing code will break.

What this does not help with

• Libraries that have to support TypeScript versions predating @ts-ignore (<2.6).
• New syntax that fails even when @ts-ignore is present. e.g.:
  • satisfies in versions < 4.9
  • template literal types in versions < 4.1
  • import type in versions < 3.8

Why not apply this to @ts-expect-error too?

Imagine you're writing a library which requires a TS version >=4.1.
You're personally developing on the latest version and it has the new feature introduced in 6.0.
You decide you want to use the v4.5 Awaited/Promise utility types but you know the people running TS 4.1 don't have them yet. You try out the new version specifier on @ts-expect-error. This happens:

// This
//   - works from versions 4.1 to <4.5 because the `ts-expect-error`
//   - fails for versions >=4.5 to <6.0 because it doesn't know to ignore those versions
//   - works for versions >=6.0 because it now correctly interprets the version tag
// @ts-expect-error version<4.1
type A = Awaited<Promise<string>>;

You end up making the problem worse instead of better 😖

This turns the @ts-expect-error version into a footgun for as long as people are commonly running TS versions that don't support the feature.

Related Issues

• Allow specifying diagnostic code in ts-expect-error #45937
• Support @ts-ignore for specific errors #19139

It seems there is a general appetite to have more nuanced control over ts-ignore and ts-expect-error.
It might be worth considering a syntax that allows for different flags.
Off the top of my head... Something based on JS object notation feels like it has potential: @ts-ignore-{}

// TS2322: Type 'string' is not assignable to type 'number'.

// @ts-ignore-{version: "<4.1", codes: ["TS2322"]}
const a: number = 'foo'

Note

This could be used as an alternative to @ts-expect-error.
An unused expect error generates TS2578: Unused '@ts-expect-error' directive.
By not including TS2578 in the ignore codes, you replicate the effect of @ts-expect-error using the @ts-ignore-{} syntax.

[MartinJohns]

What this does not help with

• Libraries that have to support TypeScript versions predating @ts-ignore (<2.6).

Why would a library need to support a TypeScript version that's over 8 years old? Heck, even still supporting 4.9 is questionable.

IMO this sounds like a solution to a problem that doesn't exist. If you really need to support ancient versions, then you should provide dedicated declaration files using typesVersions.

[jtannas]

Why would a library need to support a TypeScript version that's over 8 years old? Heck, even still supporting 4.9 is questionable.

Agreed, but I figured I'd mention it for the sake of completeness.

IMO this sounds like a solution to a problem that doesn't exist. If you really need to support ancient versions, then you should provide dedicated declaration files using typesVersions.

I used the older features as examples, but this can be applied to newer features as well.

e.g. `Set.union` added in v5.5

TS Playground

const apples = new Set(["apples"]);
const oranges = new Set(["oranges"]);

// @ts-ignore version<5.5
const applesAndOranges = apples.union(oranges)

e.g. `Iterator` added in v5.6

TS Playground

// @ts-ignore version<5.6
class Zeroes extends Iterator<number> {
    next() {
        return { value: 0, done: false } as const;
    }
}

This is my first time seeing typesVersions. It does look like a viable solution for those willing to put in that extra effort 🤔