Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Unnormalized template literal types

See original GitHub issue

Search Terms

template literal types, normalization, string validation


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.


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?


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.

Issue Analytics

  • State:open
  • Created 3 years ago
  • Reactions:7
  • Comments:7 (4 by maintainers)

github_iconTop GitHub Comments

tpictcommented, Sep 25, 2020

That’s a really neat idea. It’s syntactically way clearer than either of my suggestions, and I think TS in general would benefit from having an inference mechanism like that for assignments. Thanks for sharing this!

andrewbranchcommented, Sep 25, 2020

“Conditional Assignability” discussed in the design meeting today ( would subsume this proposal.

Read more comments on GitHub >

github_iconTop Results From Across the Web

Documentation - Template Literal Types - TypeScript
When used with concrete literal types, a template literal produces a new string literal type by concatenating the contents.
Read more >
Template Literal Types in TypeScript - Maina Wycliffe
Template Literal Types build on this, allowing you to build new types using a template and can expand to many different string using...
Read more >
WebGPU Shading Language - W3C
Otherwise, the literal denotes a value one of the abstract numeric types defined below. In either case, the value denoted by the literal...
Read more >
Metal Shading Language Specification - Apple Developer
Metal supports templates, as defined by section 14 of the C++14 Specification. ... the u or U suffix for unsigned integer literals.
Read more >
PTX ISA :: CUDA Toolkit Documentation
decimal literal {nonzero-digit}{digit}*U? Integer literals are non-negative and have a type determined by their magnitude and optional type suffix as follows: ...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found