TypeScript Assertion Signatures: Validazione del Tipo a Runtime per un Codice Robusto

TypeScript offre un eccellente controllo statico dei tipi durante lo sviluppo, individuando potenziali errori prima del runtime. Tuttavia, a volte è necessario garantire la type safety a runtime. È qui che entrano in gioco le assertion signatures. Consentono di definire funzioni che non solo controllano il tipo di un valore, ma informano anche TypeScript che il tipo del valore è stato ristretto in base al risultato del controllo.

Cosa sono le Assertion Signatures?

Un'assertion signature è un tipo speciale di firma di funzione in TypeScript che utilizza la parola chiave asserts. Indica a TypeScript che se la funzione restituisce senza lanciare un errore, allora una specifica condizione sul tipo di un argomento è garantita essere vera. Ciò consente di affinare i tipi in un modo che il compilatore comprende, anche quando non è in grado di inferire automaticamente il tipo in base al codice.

La sintassi di base è:

            function assertsCondition(argument: Type): asserts argument is NarrowedType {
  // ... implementazione che controlla la condizione e lancia un errore se è falsa ...
}

            

              
                Copy
              
            
          

• assertsCondition: Il nome della tua funzione.
• argument: Type: L'argomento di cui vuoi controllare il tipo.
• asserts argument is NarrowedType: Questa è l'assertion signature. Indica a TypeScript che se assertsCondition(argument) restituisce senza lanciare un errore, allora TypeScript può trattare argument come se avesse il tipo NarrowedType.

Perché usare le Assertion Signatures?

Le assertion signatures offrono diversi vantaggi:

• Validazione del Tipo a Runtime: Consentono di validare il tipo di un valore a runtime, prevenendo errori imprevisti che potrebbero derivare da dati errati.
• Migliore Sicurezza del Codice: Applicando i vincoli di tipo a runtime, è possibile ridurre il rischio di bug e migliorare l'affidabilità complessiva del codice.
• Type Narrowing: Le assertion signatures consentono a TypeScript di restringere il tipo di una variabile in base all'esito di un controllo a runtime, abilitando un controllo dei tipi più preciso nel codice successivo.
• Leggibilità Migliorata del Codice: Rendono il codice più esplicito riguardo ai tipi attesi, facilitandone la comprensione e la manutenzione.

Esempi Pratici

Esempio 1: Controllo di una Stringa

Creiamo una funzione che asserisce che un valore sia una stringa. Se non è una stringa, lancia un errore.

            function assertIsString(value: any): asserts value is string {
  if (typeof value !== 'string') {
    throw new Error(`Atteso una stringa, ma ricevuto ${typeof value}`);
  }
}

function processString(input: any) {
  assertIsString(input);
  // TypeScript ora sa che 'input' è una stringa
  console.log(input.toUpperCase());
}

processString("hello"); // Funziona correttamente
// processString(123); // Lancia un errore a runtime

            

              
                Copy
              
            
          

In questo esempio, assertIsString controlla se il valore di input è una stringa. Se non lo è, lancia un errore. Se restituisce senza lanciare un errore, TypeScript sa che input è una stringa, consentendo di chiamare in modo sicuro metodi di stringa come toUpperCase().

Esempio 2: Controllo di una Struttura Oggetto Specifica

Supponiamo di lavorare con dati recuperati da un'API e di voler garantire che essi aderiscano a una struttura oggetto specifica prima di elaborarli. Diciamo che ci aspettiamo un oggetto con proprietà name (stringa) e age (numero).

            interface Person {
  name: string;
  age: number;
}

function assertIsPerson(value: any): asserts value is Person {
  if (typeof value !== 'object' || value === null) {
    throw new Error(`Atteso un oggetto, ma ricevuto ${typeof value}`);
  }

  if (!('name' in value) || typeof value.name !== 'string') {
    throw new Error(`Attesa proprietà 'name' di tipo stringa`);
  }

  if (!('age' in value) || typeof value.age !== 'number') {
    throw new Error(`Attesa proprietà 'age' di tipo numero`);
  }
}

function processPerson(data: any) {
  assertIsPerson(data);
  // TypeScript ora sa che 'data' è una Person
  console.log(`Nome: ${data.name}, Età: ${data.age}`);
}

processPerson({ name: "Alice", age: 30 }); // Funziona correttamente
// processPerson({ name: "Bob", age: "30" }); // Lancia un errore a runtime
// processPerson({ name: "Charlie" }); // Lancia un errore a runtime

            

              
                Copy
              
            
          

Qui, assertIsPerson controlla se il valore di input è un oggetto con le proprietà e i tipi richiesti. Se un controllo fallisce, lancia un errore. Altrimenti, TypeScript tratta data come un oggetto Person.

Esempio 3: Controllo di un Valore Enum Specifico

Consideriamo un enum che rappresenta diversi stati dell'ordine.

            enum OrderStatus {
  PENDING = "PENDING",
  PROCESSING = "PROCESSING",
  SHIPPED = "SHIPPED",
  DELIVERED = "DELIVERED",
}

function assertIsOrderStatus(value: any): asserts value is OrderStatus {
  if (!Object.values(OrderStatus).includes(value)) {
    throw new Error(`Atteso OrderStatus, ma ricevuto ${value}`);
  }
}

function processOrder(status: any) {
  assertIsOrderStatus(status);
  // TypeScript ora sa che 'status' è un OrderStatus
  console.log(`Stato ordine: ${status}`);
}

processOrder(OrderStatus.SHIPPED); // Funziona correttamente
// processOrder("CANCELLED"); // Lancia un errore a runtime

            

              
                Copy
              
            
          

In questo esempio, assertIsOrderStatus assicura che il valore di input sia un valore enum OrderStatus valido. Se non lo è, lancia un errore. Ciò aiuta a prevenire l'elaborazione di stati ordine non validi.

Esempio 4: Utilizzo di predicati di tipo con funzioni di asserzione

È possibile combinare predicati di tipo e funzioni di asserzione per una maggiore flessibilità.

            function isString(value: any): value is string {
    return typeof value === 'string';
}

function assertString(value: any): asserts value is string {
    if (!isString(value)) {
        throw new Error(`Atteso una stringa, ma ricevuto ${typeof value}`);
    }
}

function processValue(input: any) {
    assertString(input);
    console.log(input.toUpperCase());
}

processValue("TypeScript"); // Funziona
// processValue(123); // Lancia un errore

            

              
                Copy
              
            
          

Best Practices

• Mantieni le Assertion Concise: Concentrati sulla validazione delle proprietà o condizioni essenziali richieste per il corretto funzionamento del tuo codice. Evita assertion troppo complesse che potrebbero rallentare la tua applicazione.
• Fornisci Messaggi di Errore Chiari: Includi messaggi di errore informativi che aiutino gli sviluppatori a identificare rapidamente la causa dell'errore e come risolverlo. Utilizza un linguaggio specifico che guidi l'utente. Ad esempio, invece di dire "Dati non validi", dì "Atteso un oggetto con proprietà 'name' e 'age'.".
• Usa Predicati di Tipo per Controlli Complessi: Se la logica di validazione è complessa, considera l'utilizzo di predicati di tipo per incapsulare la logica di controllo dei tipi e migliorare la leggibilità del codice.
• Considera le Implicazioni sulle Prestazioni: La validazione dei tipi a runtime aggiunge overhead alla tua applicazione. Usa le assertion signatures con giudizio e solo quando necessario. Il controllo statico dei tipi dovrebbe essere preferito ove possibile.
• Gestisci gli Errori in Modo Grazioso: Assicurati che la tua applicazione gestisca gli errori lanciati dalle funzioni di asserzione in modo grazioso, prevenendo crash e offrendo una buona esperienza utente. Considera di racchiudere il codice potenzialmente fallimentare in blocchi try-catch.
• Documenta le Tue Assertion: Documenta chiaramente lo scopo e il comportamento delle tue funzioni di asserzione, spiegando le condizioni che controllano e i tipi attesi. Ciò aiuterà altri sviluppatori a comprendere e utilizzare correttamente il tuo codice.

Casi d'Uso in Diverse Industrie

Le assertion signatures possono essere vantaggiose in vari settori:

• E-commerce: Validare l'input dell'utente durante il checkout per garantire che indirizzi di spedizione, informazioni di pagamento e dettagli dell'ordine siano corretti.
• Finanza: Verificare dati finanziari da fonti esterne, come prezzi delle azioni o tassi di cambio, prima di utilizzarli in calcoli o report.
• Sanità: Garantire che i dati del paziente siano conformi a formati e standard specifici, come cartelle cliniche o risultati di laboratorio.
• Produzione: Validare dati da sensori e macchinari per garantire che i processi di produzione funzionino in modo fluido ed efficiente.
• Logistica: Controllare che i dati di spedizione, come numeri di tracciamento e indirizzi di consegna, siano accurati e completi.

Alternative alle Assertion Signatures

Sebbene le assertion signatures siano uno strumento potente, esistono anche altri approcci alla validazione dei tipi a runtime in TypeScript:

• Type Guards: I type guards sono funzioni che restituiscono un valore booleano che indica se un valore è di un tipo specifico. Possono essere utilizzati per restringere il tipo di una variabile all'interno di un blocco condizionale. Tuttavia, a differenza delle assertion signatures, non lanciano errori quando il controllo del tipo fallisce.
• Librerie di Controllo dei Tipi a Runtime: Librerie come io-ts, zod e yup forniscono funzionalità complete di controllo dei tipi a runtime, inclusa la validazione dello schema e la trasformazione dei dati. Queste librerie possono essere particolarmente utili quando si lavora con strutture dati complesse o API esterne.

Conclusione

Le assertion signatures di TypeScript offrono un meccanismo potente per applicare la validazione dei tipi a runtime, migliorando l'affidabilità del codice e prevenendo errori imprevisti. Definendo funzioni che asseriscono il tipo di un valore, è possibile migliorare la type safety, restringere i tipi e rendere il codice più esplicito e manutenibile. Sebbene esistano alternative, le assertion signatures offrono un modo leggero ed efficace per aggiungere controlli di tipo a runtime ai progetti TypeScript. Seguendo le best practice e considerando attentamente le implicazioni sulle prestazioni, è possibile sfruttare le assertion signatures per creare applicazioni più robuste e affidabili.

Ricorda che le assertion signatures sono più efficaci se utilizzate in combinazione con le funzionalità di controllo statico dei tipi di TypeScript. Dovrebbero essere utilizzate per integrare, non per sostituire, il controllo statico dei tipi. Combinando la validazione statica e quella a runtime, è possibile ottenere un elevato livello di sicurezza del codice e prevenire molti errori comuni.