Union order in TS is not guaranteed to be stable and can change due to completely unrelated changes. This beautiful example illustrates this idea clearly.

Here's another example:

type ArrayElement<T extends readonly unknown[]> = T[number];

declare const foo: 'b'; // Presence of this statement affects the union order in `T1` below

type T1 = ArrayElement<['a', 'b']>;
//   ^? type T1 = "b" | "a"

Playground: https://tsplay.dev/weGQ1m

type ArrayElement<T extends readonly unknown[]> = T[number];

// declare const foo: 'b';

type T1 = ArrayElement<['a', 'b']>;
//   ^? type T1 = "a" | "b" (Notice the order changed)

Notice how the order of T1 union changes even though the implementation of ArrayElement itself is unchanged.

This is problematic for our twoslash validator lint rule because it currently doesn't perform an order agnostic type validation. As a result, changes in one part of the codebase can cause twoslash types to fail in completely unrelated locations. And, this also makes the tests for the lint rule flaky.

Working

Currently, this lint rule performs two validations:

1. Validates that the specified twoslash type is correct.

   // ✅ Correct
   type T = string; 
   //=> string

   // ❌ Incorrect
   type T = string; 
   //=> number

2. Validates that the specified twoslash type is formatted correctly (for example, use of single quotes, spacing, indentation, etc.).

   // ✅ Correct
   type T = {a: 'a'}; 
   //=> {a: 'a'}

   // ❌ Incorrect
   type T = {a: 'a'}; 
   //=> { a: "a"; }

At the moment, both these validations are performed as part of a single check. The type returned by the getQuickInfoAtPosition API is converted into a properly formatted twoslash comment and then compared directly with the specified twoslash comment. This allows correctness and formatting to be validated in one pass.

With the updated implementation, however, these two validations can no longer be reliably performed in a single check. As a result, they are now handled in two steps. Below is a breakdown of the new approach.

Updated validation flow

1. Normalize and compare types

   Both the specified type and the actual type are normalized, and their normalized forms are compared. This ensures that validation does not depend on union order. For example, all of the following are treated as valid:

   // ✅ Correct
   type T = 'A' | 'B' | 'C';
   
   type T1 = T;
   //=> 'A' | 'B' | 'C'
   
   type T2 = T;
   //=> 'A' | 'C' | 'B'
   
   type T3 = T;
   //=> 'B' | 'A' | 'C'
   
   type T4 = T;
   //=> 'C' | 'B' | 'A'

   If validation fails at this stage, the fixer suggests the normalized form of the actual type. While it could suggest the raw actual type and defer formatting to the next step, using the normalized form felt more reasonable, as it avoids the need for two separate fixes.

2. Validate formatting
   Once the specified type is confirmed to be correct, we then validate its formatting.

   // ✅ Correct
   type T = {a: 'a'}; 
   //=> {a: 'a'}

   // ❌ Incorrect
   type T = {a: 'a'}; 
   //=> { a: "a"; }

   This step also enforces that numbers in unions are sorted in ascending order. So, numbers in unions cannot appear in any arbitrary order.

   // ✅ Correct
   type T = 1 | 2 | 3;
   
   type T1 = T;
   //=> 1 | 2 | 3

   ❌ Incorrect
   type T2 = T;
   //=> 1 | 3 | 2
   
   type T3 = T;
   //=> 2 | 1 | 3
   
   type T4 = T;
   //=> 3 | 2 | 1

   If this feels too restrictive, this requirement can be easily removed in the future.

   NOTE: Enforcing numeric ordering does not reintroduce the original issue of union-order dependence. The lint rule remains agnostic to union order because this check runs in a separate pass and is purely a formatting validation.

This PR also fixes the following issue:

In unions containing both numbers and non-numbers, the intent was to sort only the numbers while keeping the position of non-numbers intact. However, that wasn't happening correctly. For example:

type T = '1' | '2' | 'a';
//=> '2' | 'a' | '1'

The above twoslash type is considered valid, but it actually is not because the numbers are not sorted. The correct twoslash type in this case would be:

type T = '1' | '2' | 'a';
//=> '1' | 'a' | '2'

Credits to @taiyakihitotsu for pointing this out!

Related:

• https://devblogs.microsoft.com/typescript/announcing-typescript-6-0-beta/#the---stabletypeordering-flag