Type alias in TypeScript: la parola chiave type con esempi

Un type alias dà un nome a un tipo. Scrivi type Name = ... e da quel momento Name si può usare ovunque sia atteso un tipo. A differenza di un'interface, un alias può dare un nome a qualsiasi tipo, non solo alle forme degli oggetti.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Gli alias esistono solo in fase di compilazione. Il JavaScript generato non contiene nessuna di queste righe type.

Sintassi

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

Per convenzione i nomi sono in PascalCase. Il lato destro è una qualsiasi espressione di tipo, e un alias può usare altri alias, compreso se stesso (vedi i tipi ricorsivi più avanti). L'alias è disponibile in tutto lo scope in cui è dichiarato, anche sopra la riga della dichiarazione, perché i tipi vengono controllati in fase di compilazione e non eseguiti in ordine come const o let.

Tipi oggetto

Per la forma di un oggetto, un alias e un'interface si scrivono quasi allo stesso modo. L'alias usa = e di solito termina con un punto e virgola.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

Un alias non può usare extends; quel ruolo lo svolge l'intersezione &. I controlli sulle proprietà in eccesso e le proprietà opzionali e readonly funzionano esattamente come nelle interface. Quale dei due scegliere per le forme degli oggetti è spiegato nella pagina interface vs type.

Union, tuple e funzioni

Questi sono i casi a cui solo un alias può dare un nome, e il motivo principale per cui type esiste. Un alias di union elenca le alternative, un alias di tuple fissa la lunghezza e i tipi degli elementi di un array, e un alias di funzione descrive una firma.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

In scale i parametri non hanno bisogno di annotazioni: i loro tipi li fornisce l'alias Transform. La sintassi delle tuple è spiegata in tuple, e il restringimento delle union nella pagina sugli union types.

Type alias generici

I parametri di tipo fanno funzionare un solo alias con molti tipi. Possono avere valori predefiniti, proprio come i parametri delle funzioni.

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> usa il valore predefinito E = string. Piccoli alias generici come type Nullable<T> = T | null o type Dict<T> = Record<string, T> sono comuni nel codice reale. Anche gli utility type integrati (Partial<T>, Pick<T, K>, ReturnType<F>) sono alias generici, dichiarati nella libreria standard.

Gli alias sono nomi, non tipi nuovi

Un alias non crea un tipo distinto. È un secondo nome per il tipo a destra, e il compilatore tratta i due come identici. Due alias di string sono del tutto intercambiabili:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

Questo stampa cancelling u_42 senza alcun errore, ed è proprio il bug che un alias non può impedire. L'alias aiuta comunque chi legge (un parametro tipizzato OrderId dice più di string), ma se confondere due id deve essere un errore di compilazione, usa un branded type come string & { readonly __brand: "OrderId" }.

Type alias ricorsivi

Un alias può riferirsi a se stesso, ed è così che descrivi alberi, liste annidate e JSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

L'alias Json rifiuta i valori che JSON non può rappresentare: { when: new Date() } o { f: undefined } assegnati a Json sono errori di compilazione (TS2322).

Tipi dai valori: typeof

Quando un valore esiste già, puoi dare un nome al suo tipo invece di scriverlo per intero. L'operatore di tipo typeof legge il tipo di una variabile e si combina con altri operatori:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

Il valore resta l'unica fonte di verità: aggiungi una proprietà a defaults e Options si adegua. Approfondisci in typeof.

Esportare e importare gli alias

Gli alias si esportano e si importano come i valori. import type rende esplicito che viene importato solo un tipo, quindi l'import viene sempre rimosso dall'output JavaScript:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };