Unnormalized template literal types

Search Terms

template literal types, normalization, string validation

Suggestion

An unnormalized keyword that can be applied to template literal types to opt out of normalization. Instead of producing a union representing the cross product of each variable in the template, the original declaration is preserved. The template literal type is partially expanded when compared to another type, so the checker can avoid calculating the complete cross product. For example:

type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
type Zip = unnormalized `${Digit}${Digit}${Digit}${Digit}${Digit}`;

For an assignment where the second digit is invalid, this would reduce the number of comparisons by orders of magnitude and spare the memory overhead of calculating the cross product:

const example: Zip = "9F999"; // checker reports error after only ~11 comparisons

I believe a feature of this sort is warranted as the current template literal syntax has a curious disconnect with the "pattern literal" syntax. The Zip example above is currently unfeasible because it produces a very large union for a relatively simple constraint. In comparison, something like

type Hello = `hello ${string}`;

has no such problem in spite of having infinitely more permutations.

I'm completely open to nomenclature*, syntax & behaviour suggestions, but I feel strongly that this should be an opt-in behaviour and not implicit in any way, as it represents the user selecting one feature set (string validation) as opposed to another (type unions).

*emphasis here–whichever way this syntax is expressed, it should communicate to the user that the result will not be a type union, which is the typical behaviour. Maybe validate would be better.

Use Cases

This would be useful for cases where the type is intended for validation only of a string, and the user doesn't require the type to be compatible with features of union types such as mapped types, distributive types, type narrowing. The examples below show a common topic in relevant PRs: validating that a string matches a 24 bit hex value. I believe that users who want to strictly type strings with millions of permutations are unlikely to need to apply features of union types to them... though I would love to see what 16.7 million grouped if/else statements look like.

Examples

type Hex = 0 | 1 | 2 | ... "F";
type HexColor = unnormalized `#${Hex}${Hex}${Hex}${Hex}${Hex}${Hex};`

// Compare types on assignment
const valid: HexColor = "#FFFFFF";
const invalid: HexColor = "#FFGFFF";

// unnormalized keyword propagates to template literal types:
type Template = `${"red | "blue"} ${HexColor}`;
// equivalent:
type Template = unnormalized `${"red" | "blue"} #${Hex}${Hex}${Hex}${Hex}${Hex}${Hex}`;

// likewise when the union is taken with another template literal:
type Template = `${"red" | "blue"}` | HexColor;
// equivalent:
type Template = unnormalized `${"red" | "blue" | `#${Hex}${Hex}${Hex}${Hex}${Hex}${Hex}`}`;

// For distributive types, comparing an unnormalized template literal always produces the RHS...
type Filter<T, U> = T extends U ? T : never;
type Filtered = Filter<HexColor, "#FFFFFF">;  // equivalent to HexColor
// ...unless compared to itself:
type Filtered = Filter<HexColor, HexColor>;  // equivalent to never

// Type narrowing behaves as it does with string, number etc:
if (valid === "#FFFFFF") {
  // valid is of type "#FFFFFF" in this context
} else {
  // valid is still of type HexColor in this context
}

// No-op on types where the cross product is of length one:
type Simple = unnormalized `${string}`;
// equivalent:
type Simple = `${string}`;

Pain Points

• What happens if you take the intersection of an unnormalized template literal type with another template literal type?
• How do we communicate the difference between normalized and unnormalized template literal types?
• How do we put an upper bound on the complexity of unnormalized template literal types?

Checklist

My suggestion meets these guidelines:

• 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, etc.)
• (?) This feature would agree with the rest of TypeScript's Design Goals.

Start by reviewing the proposed unnormalized template literal behavior and the unresolved intersection, propagation, distributive-type, and narrowing cases in this issue. No implementation files or tests are named, so the work first requires locating the checker and existing template literal type tests, then defining the semantics and adding coverage for the examples before implementation.