In TypeScript, given `type Shade = 'light' | 'dark'` and `type Color = 'red' | 'blue'`, what type is `` `${Shade}-${Color}` `` and what rule produces it?

## The distribution rule When a placeholder in a template literal type holds a union, the compiler builds one result per member and unions the results. With more than one such placeholder it does this for every combination: ```ts type Shade = "light" | "dark"; type Color = "red" | "blue"; type Token = `${Shade}-${Color}`; // "light-red" | "light-blue" | "dark-red" | "dark-blue" ``` Four members from two-by-two. Add a third placeholder and the count multiplies again: two shades × two colors × three weights is twelve literal members. This is a cross-product, not a zip — there is no pairing by position. ## Why this is the feature people actually use Before template literal types, a vocabulary of structured strings had to be spelled out: ```ts type Token = "light-red" | "light-blue" | "dark-red" | "dark-blue"; ``` That list has to be maintained by hand and drifts the moment someone adds a color. Deriving it keeps one source of truth per axis: ```ts type Color = "red" | "blue" | "green"; type Token = `${Shade}-${Color}`; // six members, updated automatically ``` The derived union is a real union of literal types, so everything that works on literal unions works here: assignability checks reject `"light-green"` if `green` is not in `Color`, editors autocomplete the full list, and exhaustive `switch` handling behaves normally. ## Prefixes and suffixes count too Literal text around the placeholders is fixed, so you can generate namespaced vocabularies: ```ts type Entity = "user" | "order"; type Action = "created" | "deleted"; type EventName = `app:${Entity}.${Action}`; // "app:user.created" | "app:user.deleted" // | "app:order.created" | "app:order.deleted" ``` A single placeholder with a union and no other variation simply maps over the members: ```ts type Handler = `on${"Click" | "Focus"}`; // "onClick" | "onFocus" ``` ## Union placeholder versus primitive placeholder The distribution only happens when there is a finite set to distribute over. A primitive placeholder produces a *pattern* type instead, which stays unexpanded: ```ts type A = `${Shade}-${Color}`; // enumerated union of 4 literals type B = `${Shade}-${string}`; // pattern: `light-${string}` | `dark-${string}` type C = `${string}-${string}`; // a single pattern type, nothing enumerated ``` That difference matters in practice. An enumerated union gives autocomplete and rejects typos; a pattern type only checks the fixed segments. Choosing between them is a modelling decision: enumerate when the vocabulary is genuinely closed, use a pattern when the tail is open-ended. ## The explosion, and why it bites Because the sizes multiply, the union gets large quickly. Four placeholders of twenty members each is 160,000 combinations. The compiler builds these unions eagerly and refuses past an internal ceiling on the order of 100,000 constituents, reporting that the expression produces a union type that is too complex to represent. Even well under the ceiling, a union of tens of thousands of literals is slow to check and produces error messages that print an unreadable wall of members. Practical mitigations, in rough order of preference: - Keep the source unions small and the number of placeholders low; two or three axes is the comfortable range. - Replace an axis that is effectively open with a primitive placeholder — `` `${Shade}-${string}` `` costs nothing to build. - Constrain at the use site with a generic parameter instead of materialising the whole product up front, so the compiler only checks the combination actually passed. ## What it is not The expansion is a compile-time construction. No array of strings is generated, nothing is iterable, and you cannot loop over the members at runtime — the union is erased along with the rest of the type layer. If you need the actual list of tokens at runtime, declare the values (for instance with an `as const` array) and derive the type from them rather than the other way round.