Salta al contenuto principale

06 - Tipi template literal: una chiave di archivio che il compilatore compone

Due parametri string concatenati sono due refusi che compilano. Come descrivere la forma di una chiave e farla verificare, con gli errori reali del compilatore.

Cosa ne pensi di questo articolo?

06 - Tipi template literal: una chiave di archivio che il compilatore compone
TypeScript Avanzatofedericocalo.dev

In Breve

Due parametri string concatenati sono due refusi che compilano. Come descrivere la forma di una chiave e farla verificare, con gli errori reali del compilatore.

Due parametri di tipo stringa, e nessuno che li controlla

In questo progetto l'accesso all'archivio del browser passa da un servizio dedicato, e per una ragione buona: le chiavi seguono una convenzione, fc:v1:dominio:identificativo, con un prefisso e un numero di versione che servono a cancellare in blocco i dati dell'applicazione senza toccare quelli di altri. Gli esempi scritti nella documentazione del servizio sono fc:v1:auth:user e fc:v1:gamification:profile_abc123.

Il metodo che le compone ha questa firma: get<T>(domain: string, id: string, fallback: T). Il dominio è una stringa qualunque. Quindi gamificazione invece di gamification compila. Anche Auth con la maiuscola compila. E il guasto che producono non è un errore: è una lettura che restituisce il valore di scorta, per sempre, perché la chiave scritta non è quella letta. Un dato che non si salva e non segnala nulla.

Il numero di domini in un'applicazione è piccolo e si conosce. Quello che manca non è la conoscenza, è un modo di comunicarla al compilatore. I tipi template literal, aggiunti in TypeScript 4.1, fanno esattamente questo: permettono di descrivere la forma di una stringa invece di accettarne una qualunque. Questo è l'ultimo articolo della serie, e usa l'unione di stringhe letterali che l'articolo 05 ha insegnato a derivare dal catalogo. Gli errori riportati sono quelli di TypeScript 7.0.2, la versione latest sul registro npm il 2026-11-13, provati con strict attivo; con la 5.9.3 i testi sono gli stessi.

Una chiave descritta come regola, non come esempio


// Una convenzione di esempio: fc:v1:<dominio>:<id>
export type Dominio = 'auth' | 'gamification' | 'preferenze';

export type ChiaveStorage = `fc:v1:${Dominio}:${string}`;

export function componiChiave(dominio: Dominio, id: string): ChiaveStorage {
  return `fc:v1:${dominio}:${id}`;
}

export function dominioDi(chiave: ChiaveStorage): Dominio {
  // split restituisce string[]: il terzo pezzo va riaffermato.
  const pezzi = chiave.split(':');
  return pezzi[2] as Dominio;
}

const k = componiChiave('gamification', 'profile_abc123');
console.log(k);
console.log(dominioDi(k));
console.log(dominioDi('fc:v1:auth:user:con:altri:due-punti'));

// Un id vuoto è una stringa, e il modello lo accetta.
export const vuota: ChiaveStorage = 'fc:v1:auth:';

// Uscita di tsc 7.0.2: nessun errore.

// Uscita di node 24.11.0:
// fc:v1:gamification:profile_abc123
// gamification
// auth
      

La riga centrale è type ChiaveStorage = `fc:v1:${Dominio}:${string}`, e va letta come un modello: una stringa che comincia con il prefisso letterale, continua con uno dei domini ammessi, un due punti, e poi qualunque testo. Tre cose su questa sintassi sono quelle che userai, e ognuna ha una conseguenza se la sbagli: gli apici inversi, i tipi (e non i valori) dentro l'interpolazione e la distribuzione sulle unioni. L'uscita di Node mostra anche che dominioDi funziona con un identificativo che contiene altri due punti, e che 'fc:v1:auth:', con identificativo vuoto, è una chiave valida per il tipo, perché la stringa vuota è una string.

Gli apici inversi sono obbligatori e non sono un dettaglio estetico: con le virgolette normali quella sarebbe una singola stringa letterale, cioè il tipo che contiene esattamente il testo fc:v1:${Dominio}:${string} con il simbolo del dollaro dentro. È un errore che non produce un messaggio utile, perché il tipo risultante è valido e semplicemente non combacia mai con nulla. Lo si vede con una chiave perfettamente valida:


type Dominio = 'auth' | 'gamification' | 'preferenze';

// Virgolette normali: non è un modello, è una stringa letterale con i simboli dentro.
type ChiaveSbagliata = 'fc:v1:${Dominio}:${string}';

// Una chiave perfettamente valida non è assegnabile.
export const k: ChiaveSbagliata = 'fc:v1:auth:user';

// Uscita di tsc 7.0.2:
// 03-apici.ts(7,14): error TS2322: Type '"fc:v1:auth:user"' is not assignable to type '"fc:v1:${Dominio}:${string}"'.
      

Il compilatore rifiuta 'fc:v1:auth:user' e nel messaggio ristampa il tipo atteso con le graffe e il dollaro, "fc:v1:${Dominio}:${string}" tra virgolette doppie: è il segno che il modello non è stato interpretato. Se vedi un messaggio così, controlla gli apici.

Dentro l'interpolazione vanno tipi, non valori. Ho provato i principali, e le conseguenze sono nell'uscita:


type ConString = `evento:${string}`;
type ConAny = `evento:${any}`;
type ConBoolean = `attivo:${boolean}`;
type ConNumber = `pagina-${number}`;
type ConBigint = `conto:${bigint}`;

// Queste compilano: stesso insieme di testi per string e per any.
export const a: ConString = 'evento:qualunque cosa';
export const b: ConAny = 'evento:qualunque cosa';
export const c: ConNumber = 'pagina-12';
export const d: ConBigint = 'conto:12';

// Queste no: any non toglie il prefisso, number e bigint pretendono cifre.
export const e: ConAny = 'altro:x';
export const f: ConNumber = 'pagina-dodici';
export const g: ConBigint = 'conto:1.5';

// boolean si espande in due stringhe letterali: lo dice una sonda.
export const sonda: never = null as unknown as ConBoolean;

// Uscita di tsc 7.0.2:
// 08-interpolazioni.ts(14,14): error TS2322: Type '"altro:x"' is not assignable to type '`evento:${any}`'.
// 08-interpolazioni.ts(15,14): error TS2322: Type '"pagina-dodici"' is not assignable to type '`pagina-${number}`'.
// 08-interpolazioni.ts(16,14): error TS2322: Type '"conto:1.5"' is not assignable to type '`conto:${bigint}`'.
// 08-interpolazioni.ts(19,14): error TS2322: Type '"attivo:false" | "attivo:true"' is not assignable to type 'never'.
//   Type '"attivo:false"' is not assignable to type 'never'.
      

Con string e con any il modello accetta lo stesso insieme di testi, ma il prefisso resta: 'altro:x' è rifiutato (riga 14). number e bigint pretendono che il testo sia un numero di quel tipo: 'pagina-dodici' e 'conto:1.5' non passano. boolean, che è già un'unione di due valori, si espande in "attivo:false" | "attivo:true". E questo è il punto da cui parte la parte interessante: quando interpoli un'unione il compilatore distribuisce, e il tipo diventa l'unione di tutte le combinazioni possibili. L'Handbook lo dice così: per ogni posizione interpolata le unioni vengono moltiplicate fra loro. Si vede nel messaggio d'errore più sotto.

La funzione componiChiave è la ragione pratica per cui tutto questo non è un esercizio. Il suo tipo di ritorno è ChiaveStorage, e il compilatore verifica che il modello interpolato lo soddisfi: non è un cast, è un controllo. Lo provo cambiando il prefisso nel corpo, e passando un dominio che è una string qualunque:


type Dominio = 'auth' | 'gamification' | 'preferenze';
type ChiaveStorage = `fc:v1:${Dominio}:${string}`;

// Il prefisso nel corpo non coincide con il tipo di ritorno.
export function componiVecchia(dominio: Dominio, id: string): ChiaveStorage {
  return `fc:v2:${dominio}:${id}`;
}

// Un dominio che arriva come string semplice non basta.
export function componiLarga(dominio: string, id: string): ChiaveStorage {
  return `fc:v1:${dominio}:${id}`;
}

// Uscita di tsc 7.0.2:
// 04-prefisso-nel-corpo.ts(6,3): error TS2322: Type '`fc:v2:auth:${string}` | `fc:v2:gamification:${string}` | `fc:v2:preferenze:${string}`' is not assignable to type '`fc:v1:auth:${string}` | `fc:v1:gamification:${string}` | `fc:v1:preferenze:${string}`'.
//   Type '`fc:v2:auth:${string}`' is not assignable to type '`fc:v1:auth:${string}` | `fc:v1:gamification:${string}` | `fc:v1:preferenze:${string}`'.
// 04-prefisso-nel-corpo.ts(11,3): error TS2322: Type '`fc:v1:${string}:${string}`' is not assignable to type '`fc:v1:auth:${string}` | `fc:v1:gamification:${string}` | `fc:v1:preferenze:${string}`'.
      

Entrambe le funzioni non compilano. La prima, perché fc:v2: non coincide con il prefisso del tipo, e il compilatore elenca le tre alternative con il prefisso sbagliato. La seconda, perché dominio: string produce fc:v1:${string}:${string}, un tipo più largo di quello atteso: per ottenere la garanzia, il parametro deve essere il tipo Dominio, non string. È il punto in cui la convenzione smette di essere un commento e diventa una cosa che il compilatore fa rispettare.

Il messaggio del compilatore, che spiega il meccanismo

Questi sono gli errori veri su un dominio scritto male, su una versione vecchia del prefisso e su un dominio con la maiuscola:


type Dominio = 'auth' | 'gamification' | 'preferenze';
type ChiaveStorage = `fc:v1:${Dominio}:${string}`;

// 'gamificazione' non è nella unione: la chiave non è assegnabile.
export const chiave: ChiaveStorage = 'fc:v1:gamificazione:profilo';

// Anche la versione sbagliata del prefisso viene rifiutata.
export const chiaveVecchia: ChiaveStorage = 'fc:v0:auth:user';

// Con la maiuscola nel dominio: stessa sorte.
export const maiuscola: ChiaveStorage = 'fc:v1:Auth:user';

// Uscita di tsc 7.0.2:
// 02-errori.ts(5,14): error TS2322: Type '"fc:v1:gamificazione:profilo"' is not assignable to type '`fc:v1:auth:${string}` | `fc:v1:gamification:${string}` | `fc:v1:preferenze:${string}`'.
// 02-errori.ts(8,14): error TS2322: Type '"fc:v0:auth:user"' is not assignable to type '`fc:v1:auth:${string}` | `fc:v1:gamification:${string}` | `fc:v1:preferenze:${string}`'.
// 02-errori.ts(11,14): error TS2322: Type '"fc:v1:Auth:user"' is not assignable to type '`fc:v1:auth:${string}` | `fc:v1:gamification:${string}` | `fc:v1:preferenze:${string}`'.
      

Il tipo atteso che il compilatore stampa non è il modello che ho scritto: è l'unione di tre modelli, uno per dominio. È la distribuzione di cui sopra, resa visibile. La conseguenza pratica vale la pena notarla: la precisione di questo controllo dipende da quanto è piccola l'unione. Tre domini danno tre modelli e un messaggio leggibile; venti domini danno venti modelli e un messaggio d'errore lungo, che resta corretto ed è molto meno comodo. C'è poi un limite duro, che si può misurare:


type Cifra = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
type DaZeroAOtto = Exclude<Cifra, '9'>;

// 9 x 10^4 = 90.000 combinazioni: il compilatore le regge.
export type Novantamila = `${DaZeroAOtto}${Cifra}${Cifra}${Cifra}${Cifra}`;
export const a: Novantamila = '00000';

// 10^5 = 100.000 combinazioni: il compilatore rinuncia.
export type Centomila = `${Cifra}${Cifra}${Cifra}${Cifra}${Cifra}`;
export const b: Centomila = '00000';

// Uscita di tsc 7.0.2:
// 06-limite.ts(9,25): error TS2590: Expression produces a union type that is too complex to represent.
      

Il prodotto di unioni è accettato fino a 90.000 combinazioni e rifiutato a 100.000, con l'errore TS2590, «Expression produces a union type that is too complex to represent». Non so dire dove stia la soglia esatta fra i due valori: so che 90.000 passa e 100.000 no, con la versione 7.0.2 e con la 5.9.3. L'Handbook, nella pagina sui tipi template literal, raccomanda la generazione anticipata per le grandi unioni di stringhe, e questa misura spiega perché. Con tre domini sei lontano dal limite; tre unioni da cinquanta elementi moltiplicate fra loro danno 125.000 combinazioni, cioè più della soglia che ho misurato.

Il punto in cui la precisione si perde, e va riaffermata

La funzione dominioDi del primo blocco contiene un cast, e l'ho lasciato di proposito perché è onesto e istruttivo. Il metodo split della libreria standard dichiara di restituire string[], e questo non dipende dalla precisione del tipo in ingresso: il compilatore non sa che una stringa che corrisponde a quel modello, spezzata sui due punti, ha il terzo pezzo in Dominio. Non sa nemmeno quanti pezzi risultino: l'identificativo può contenere altri due punti, come mostra l'uscita del primo blocco, e il terzo pezzo resta il dominio comunque.

Qui il cast afferma qualcosa di vero, che è dimostrabile dalla forma del tipo, e dichiara dove sta il salto. È la categoria che l'articolo 01 chiamava «cast che dichiara un buco noto», e la differenza con un cast bugiardo è che questo si può verificare rileggendo il tipo. L'alternativa senza cast esiste, e non è un tipo condizionale ma un controllo a tempo di esecuzione: una guardia di tipo, come quelle dell'articolo 03, che verifica il pezzo contro l'elenco dei domini. Il file seguente la mostra, insieme al tipo condizionale con infer che, per una chiave scritta come letterale, estrae il dominio a tempo di compilazione.


export const DOMINI = ['auth', 'gamification', 'preferenze'] as const;
export type Dominio = (typeof DOMINI)[number];
export type ChiaveStorage = `fc:v1:${Dominio}:${string}`;

// Il controllo a tempo di esecuzione sostituisce il cast.
function èDominio(testo: string): testo is Dominio {
  return (DOMINI as readonly string[]).includes(testo);
}

export function dominioDi(chiave: ChiaveStorage): Dominio {
  const candidato = chiave.split(':')[2];
  if (candidato === undefined || !èDominio(candidato)) {
    throw new Error(`Dominio non valido in ${chiave}`);
  }
  return candidato;
}

// A tempo di compilazione, per una chiave letterale, il dominio si estrae con infer.
export type DominioDelModello<C extends string> =
  C extends `fc:v1:${infer D extends Dominio}:${string}` ? D : never;

console.log(dominioDi('fc:v1:preferenze:tema'));
try {
  dominioDi('fc:v1:auth:x'.replace('auth', 'altro') as ChiaveStorage);
} catch (e) {
  console.log((e as Error).message);
}

export const sonda: never = null as unknown as DominioDelModello<'fc:v1:auth:user'>;

// Uscita di tsc 7.0.2:
// 05-senza-cast.ts(29,14): error TS2322: Type '"auth"' is not assignable to type 'never'.

// Uscita di node 24.11.0:
// preferenze
// Dominio non valido in fc:v1:altro:x
      

DOMINI è la fonte di verità, un elenco as const da cui Dominio si deriva con un accesso indicizzato, la tecnica dell'articolo 05. èDominio è la guardia, e dominioDi la usa per restituire il pezzo senza nessun cast: se il pezzo non è un dominio, solleva, come mostra l'ultima riga di Node. Il tipo DominioDelModello è un tipo condizionale: per una chiave letterale come 'fc:v1:auth:user' la sonda mostra che il risultato è "auth". La scelta fra cast e guardia è un compromesso fra righe scritte e garanzie, non fra giusto e sbagliato: in un servizio applicativo il cast dichiarato basta, su una libreria conviene la guardia.

Dove conviene e dove non conviene

Lo schema dà il massimo quando una stringa ha una struttura e un insieme chiuso di parti. Questi sono i casi in cui lo uso, e sono indipendenti l'uno dall'altro.

  • Chiavi di archivio con un prefisso e una versione, cioè il caso di questo articolo: un refuso nel dominio diventa un errore di compilazione invece di un dato che non si salva.
  • Nomi di eventi con un namespace, come analytics:click o form:submit, dove il verbo e l'oggetto vengono da due elenchi noti.
  • Identificativi di contenuto con una lingua, come articolo-it e articolo-en, che in un progetto a due lingue impediscono di comporre un codice di lingua inesistente.
  • Nomi di variabili CSS personalizzate, per legare i token dichiarati nel foglio di stile ai nomi usati nel codice, che è un disallineamento che non produce nessun errore a tempo di esecuzione.
  • Rotte con un prefisso di lingua, dove il segmento iniziale appartiene a un'unione chiusa e il resto è libero.

Cinque casi, una sola forma: una parte della stringa appartiene a un insieme che conosci, e il resto è libero. Se riesci a dire quale parte è chiusa e quale è aperta, il modello si scrive da sé; se non riesci, il problema non è del tipo ma della convenzione, che non è ancora una convenzione.

Non conviene in due situazioni, e riconoscerle fa risparmiare tempo. La prima è quando l'insieme delle parti è aperto o molto grande: un modello che interpola un'unione di cinquanta elementi produce cinquanta combinazioni, i messaggi diventano illeggibili e, moltiplicando più unioni, si arriva al limite del compilatore misurato sopra. La seconda è quando la stringa viene composta altrove e arriva al programma già formata: là non c'è niente da verificare a tempo di compilazione, e serve una guardia che controlli la forma a tempo di esecuzione, perché un tipo non controlla i dati che non ha visto nascere.

Che cosa sai fare adesso, e che cosa hai in mano alla fine della serie

Adesso sai descrivere la forma di una stringa invece di accettarne una qualunque, e sai che la sintassi vuole gli apici inversi e dei tipi dentro l'interpolazione. Sai che interpolare un'unione distribuisce il modello su tutte le combinazioni, che questo rende il messaggio d'errore preciso con tre domini e ingombrante con venti, e che oltre le 100.000 combinazioni il compilatore rinuncia. Sai anche dove la precisione si interrompe, cioè in split, che restituisce string[] qualunque sia il tipo in ingresso, e che hai due uscite: il cast dichiarato o la guardia.

La serie finisce qui, e i sei articoli sono un solo ragionamento: quanta informazione il tipo conserva, e dove la butta via. L'articolo 01 misura le vie di fuga che strict lascia aperte. L'02 mette unknown al posto di any nel punto in cui i dati entrano. Il 03 insegna al compilatore un tipo con una guardia, e quando quella guardia mente. Il 04 rende gli stati impossibili non scrivibili, con il controllo di esaustività. Il 05 controlla un catalogo senza perdere le sue chiavi. Questo, il 06, descrive la forma di una stringa. Se devi cominciare da uno solo, comincia dal tuo codice: cerca una funzione che accetta due o tre parametri di tipo string per poi concatenarli. Ogni volta che li trovi, hai un posto in cui un refuso compila.

Domande frequenti

Che cos'è un tipo template literal?

Un tipo che descrive la forma di una stringa invece di accettarne una qualunque. Si scrive fra apici inversi, con parti letterali e interpolazioni che contengono tipi, per esempio fc:v1:${Dominio}:${string}. Il compilatore verifica che una stringa corrisponda al modello.

Perché il mio tipo template literal non combacia mai?

Quasi sempre perché è scritto con le virgolette normali invece degli apici inversi. In quel caso non è un modello ma una singola stringa letterale che contiene i caratteri dell'interpolazione, dollaro e graffe compresi: un tipo valido che non corrisponde a nulla.

Che cosa si può mettere dentro l'interpolazione?

Tipi, non valori: string, number, bigint, boolean, o un tipo che si risolva in stringhe letterali come un'unione. Interpolando un'unione il compilatore distribuisce il modello su tutte le combinazioni, ed è il motivo per cui il messaggio d'errore elenca un modello per membro.

Perché split perde la precisione del tipo?

Perché la libreria standard dichiara split con tipo di ritorno string[], indipendentemente da quanto è preciso il tipo in ingresso. Il compilatore non deduce che una stringa conforme al modello, spezzata sui due punti, produce un pezzo che appartiene all'unione dei domini.

Quando conviene evitare questo schema?

Quando l'insieme delle parti è aperto o molto grande, perché le combinazioni si moltiplicano, i messaggi d'errore diventano illeggibili e oltre le 100.000 combinazioni il compilatore rinuncia con TS2590. E quando la stringa arriva già formata da fuori: in quel caso serve una guardia a tempo di esecuzione.

Fonti

  • TypeScript Handbook - Template Literal Types: la moltiplicazione delle unioni in ogni posizione interpolata e la raccomandazione di generare in anticipo le grandi unioni, letto; consultata il 2026-11-13.
  • TypeScript 4.1 - note di rilascio: solo l'intestazione della sezione che introduce i tipi template literal, verificata; consultata il 2026-11-13.
  • Announcing TypeScript 7.0: la natura del compilatore usato per le prove (porta nativa), solo l'apertura letta; consultata il 2026-11-13.
  • Gli errori, compreso TS2590 e la soglia fra 90.000 e 100.000 combinazioni, e le uscite sono prodotti da tsc --noEmit --strict --noImplicitReturns --target ES2022 --module ESNext --moduleResolution bundler file.ts (typescript 7.0.2, npm view typescript version il 2026-11-13, e 5.9.3) e da node file.ts (Node 24.11).

Prova Questi Strumenti

Strumenti gratuiti correlati a questo argomento.

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti