Template Literal Types

## The idea A template literal type looks exactly like a template string, but it lives in type position and describes a *set of strings* rather than producing one: ```ts type Greeting = `hello ${string}`; ``` Read it as a pattern: the literal text `hello ` followed by a hole that any string may fill. The compiler uses it purely as an assignability rule — given a candidate type, does it match the pattern? ## What is assignable ```ts const a: Greeting = "hello world"; // ok const b: Greeting = "hello "; // ok — the hole may be empty const c: Greeting = "hello, world"; // ok — the hole may contain anything const d: Greeting = "Hello world"; // error — patterns are case-sensitive const e: Greeting = "hi"; // error — prefix missing ``` The matching is literal and case-sensitive. The hole is unconstrained: it can be empty, contain spaces, punctuation, newlines, anything. A common wrong instinct is to read `${string}` as "one word" or "no slashes"; it means *any string whatsoever*. ## It is a subtype, and assignment is one-way `` `hello ${string}` `` is a subtype of `string`. That direction works: ```ts declare let g: Greeting; const s: string = g; // ok — every Greeting is a string ``` The reverse does not: ```ts declare let raw: string; const g2: Greeting = raw; // error — string is not narrow enough ``` This is the same relationship a string literal type has to `string`: `"a"` is assignable to `string`, `string` is not assignable to `"a"`. A template literal type just describes a bigger, pattern-shaped subset instead of a single value. ## Where the literal type comes from matters Because the check runs on *types*, not values, how a string reaches the call site decides whether it compiles: ```ts declare function greet(g: `hello ${string}`): void; const name = "world"; // inferred as the literal type "world" greet(`hello ${name}`); // ok greet("hello " + name); // error — `+` on strings produces `string` let mutable = "hello world"; // `let` widens to string greet(mutable); // error ``` Two mechanics are visible here. First, a template *string expression* that is contextually typed by a template literal type is itself given a template literal type, so `` `hello ${name}` `` checks. Second, ordinary string concatenation with `+` produces plain `string`, and `let` bindings widen their literal type to `string`, so both lose the information the pattern needs. ## What goes in the hole The placeholder is not restricted to `string`. `number`, `bigint`, `boolean`, `null`, `undefined`, string/number literal types, unions of literals, and other template literal types are all legal: ```ts type Version = `v${number}`; const v1: Version = "v2"; // ok const v2: Version = "v2.1"; // ok — a decimal is still a number literal const v3: Version = "vNext"; // error — does not look like a number ``` `` `${number}` `` accepts strings whose text is shaped like a numeric literal. That is a syntactic check on the string, not arithmetic: nothing is parsed at runtime. ## Types are erased — the guarantee has an edge Nothing survives compilation. `type Greeting = ...` emits no JavaScript, and `greet(x)` emits a bare call with no prefix test. So the pattern constrains code the checker can see and nothing else. A string that arrives from `JSON.parse`, a network response, `process.env`, or a DOM input is typed `string` (or `any`), and pushing it into a template-literal-typed slot needs either a real runtime check or an assertion. An assertion here is a promise, not a verification: ```ts function isGreeting(s: string): s is Greeting { return s.startsWith("hello "); // a real check you wrote yourself } ``` ## When to reach for it The pattern earns its keep where strings carry structure that used to be documented only in a comment: route paths, CSS custom properties, event names, prefixed keys, semantic-version strings. It gives autocomplete and a red squiggle at the point where the string is *built*, which is where the mistake actually happens. It is not a validator, and treating it as one is the mistake to avoid.