TypeScript Exact Types: Strikt Object Shape Matching voor Robuuste Code

TypeScript, een superset van JavaScript, brengt statische typing naar de dynamische wereld van webontwikkeling. Hoewel TypeScript aanzienlijke voordelen biedt op het gebied van typeveiligheid en code-onderhoudbaarheid, kan het structurele typesysteem soms leiden tot onverwacht gedrag. Hier komt het concept van "exacte types" om de hoek kijken. Hoewel TypeScript geen ingebouwde functie heeft die expliciet "exacte types" heet, kunnen we vergelijkbaar gedrag bereiken door een combinatie van TypeScript-functies en -technieken. Deze blogpost zal ingaan op hoe je striktere object shape matching in TypeScript kunt afdwingen om code-robuustheid te verbeteren en veelvoorkomende fouten te voorkomen.

TypeScript's Structurele Typing Begrijpen

TypeScript maakt gebruik van structurele typing (ook bekend als duck typing), wat betekent dat typecompatibiliteit wordt bepaald door de leden van de types, in plaats van hun gedeclareerde namen. Als een object alle eigenschappen heeft die een type vereist, wordt het als compatibel met dat type beschouwd, ongeacht of het extra eigenschappen heeft.

Bijvoorbeeld:

interface Point {
  x: number;
  y: number;
}

const myPoint = { x: 10, y: 20, z: 30 };

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}

printPoint(myPoint); // Dit werkt prima, hoewel myPoint de 'z'-eigenschap heeft

In dit scenario staat TypeScript toe dat `myPoint` wordt doorgegeven aan `printPoint` omdat het de vereiste `x` en `y` eigenschappen bevat, ook al heeft het een extra `z` eigenschap. Hoewel deze flexibiliteit handig kan zijn, kan het ook leiden tot subtiele bugs als je per ongeluk objecten met onverwachte eigenschappen doorgeeft.

Het Probleem met Overmatige Eigenschappen

De mildheid van structureel typen kan soms fouten maskeren. Beschouw een functie die een configuratieobject verwacht:

interface Config {
  apiUrl: string;
  timeout: number;
}

function setup(config: Config) {
  console.log(`API URL: ${config.apiUrl}`);
  console.log(`Timeout: ${config.timeout}`);
}

const myConfig = { apiUrl: "https://api.example.com", timeout: 5000, typo: true };

setup(myConfig); // TypeScript klaagt hier niet!

console.log(myConfig.typo); //print true. De extra eigenschap bestaat in stilte

In dit voorbeeld heeft `myConfig` een extra eigenschap `typo`. TypeScript genereert geen foutmelding omdat `myConfig` nog steeds voldoet aan de `Config` interface. De typo wordt echter nooit opgemerkt en de applicatie gedraagt zich mogelijk niet zoals verwacht als de typo bedoeld was als `typoo`. Deze schijnbaar onbeduidende problemen kunnen uitgroeien tot grote hoofdpijn bij het debuggen van complexe applicaties. Een ontbrekende of verkeerd gespelde eigenschap kan bijzonder moeilijk te detecteren zijn bij het omgaan met objecten die in objecten zijn genest.

Benaderingen om Exacte Types in TypeScript af te dwingen

Hoewel echte "exacte types" niet direct beschikbaar zijn in TypeScript, zijn hier verschillende technieken om vergelijkbare resultaten te bereiken en een striktere object shape matching af te dwingen:

1. Type Asserties Gebruiken met `Omit`

Met het utility type `Omit` kun je een nieuw type maken door bepaalde eigenschappen uit een bestaand type uit te sluiten. In combinatie met een type assertion kan dit overmatige eigenschappen helpen voorkomen.

interface Point {
  x: number;
  y: number;
}

const myPoint = { x: 10, y: 20, z: 30 };

// Maak een type dat alleen de eigenschappen van Point bevat
const exactPoint: Point = myPoint as Omit & Point;

// Fout: Type '{ x: number; y: number; z: number; }' is niet toewijsbaar aan type 'Point'.
// Object literal mag alleen bekende eigenschappen specificeren, en 'z' bestaat niet in type 'Point'.

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}


//Fix
const myPointCorrect = { x: 10, y: 20 };
const exactPointCorrect: Point = myPointCorrect as Omit & Point;
printPoint(exactPointCorrect);

Deze aanpak genereert een fout als `myPoint` eigenschappen heeft die niet zijn gedefinieerd in de `Point` interface.

Uitleg: `Omit` maakt een type dat alle sleutels die aanwezig zijn in `Point` weglaat uit het type van `myPoint`. De `& Point` snijdt dit type vervolgens met het `Point` type, wat in wezen vereist dat het object voldoet aan het `Point` type. Door het object te asserteren naar dit gecombineerde type, controleert de compiler op extra eigenschappen en genereert een fout als er worden gevonden. Dit dwingt ons om de juiste vorm te declareren bij het definiëren van ons object.

2. Een Functie Gebruiken om Objecten te Maken

Je kunt een factory-functie maken die alleen de in de interface gedefinieerde eigenschappen accepteert. Deze aanpak biedt sterke type checking op het moment van objectcreatie.

interface Config {
  apiUrl: string;
  timeout: number;
}

function createConfig(config: Config): Config {
  return {
    apiUrl: config.apiUrl,
    timeout: config.timeout,
  };
}

const myConfig = createConfig({ apiUrl: "https://api.example.com", timeout: 5000 });

//Dit compileert niet:
//const myConfigError = createConfig({ apiUrl: "https://api.example.com", timeout: 5000, typo: true });
//Argument van type '{ apiUrl: string; timeout: number; typo: true; }' is niet toewijsbaar aan parameter van type 'Config'.
// Object literal mag alleen bekende eigenschappen specificeren, en 'typo' bestaat niet in type 'Config'.

Door een object terug te geven dat is geconstrueerd met alleen de eigenschappen die zijn gedefinieerd in de `Config` interface, zorg je ervoor dat er geen extra eigenschappen in kunnen sluipen. Dit maakt het veiliger om de configuratie te maken.

3. Type Guards Gebruiken

Type guards zijn functies die het type van een variabele binnen een specifiek bereik beperken. Hoewel ze overmatige eigenschappen niet direct voorkomen, kunnen ze je helpen ze expliciet te controleren en de juiste actie te ondernemen.

interface User {
  id: number;
  name: string;
}

function isUser(obj: any): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj && typeof obj.id === 'number' &&
    'name' in obj && typeof obj.name === 'string' &&
    Object.keys(obj).length === 2 //controleer op het aantal sleutels. Opmerking: breekbaar en is afhankelijk van het exacte aantal sleutels van de gebruiker.
  );
}

const potentialUser1 = { id: 123, name: "Alice" };
const potentialUser2 = { id: 456, name: "Bob", extra: true };

if (isUser(potentialUser1)) {
  console.log("Geldige Gebruiker:", potentialUser1.name);
} else {
  console.log("Ongeldige Gebruiker");
}

if (isUser(potentialUser2)) {
  console.log("Geldige Gebruiker:", potentialUser2.name); //Zal hier niet komen
} else {
  console.log("Ongeldige Gebruiker");
}

In dit voorbeeld controleert de `isUser` type guard niet alleen op de aanwezigheid van vereiste eigenschappen, maar ook op hun typen en het *exacte* aantal eigenschappen. Deze aanpak is explicieter en stelt je in staat om ongeldige objecten op een elegante manier af te handelen. De controle op het aantal eigenschappen is echter kwetsbaar. Wanneer `User` eigenschappen krijgt/verliest, moet de controle worden bijgewerkt.

4. `Readonly` en `as const` Benutten

Hoewel `Readonly` voorkomt dat bestaande eigenschappen worden gewijzigd, en `as const` een read-only tuple of object maakt waarbij alle eigenschappen diep read-only zijn en letterlijke types hebben, kunnen ze worden gebruikt om een striktere definitie en type checking te creëren in combinatie met andere methoden. Hoewel geen van beide op zichzelf overmatige eigenschappen voorkomt.

interface Options {
  width: number;
  height: number;
}

//Maak het Readonly type
type ReadonlyOptions = Readonly;

const options: ReadonlyOptions = { width: 100, height: 200 };

//options.width = 300; //fout: Kan niet toewijzen aan 'width' omdat het een read-only eigenschap is.

//as const gebruiken
const config = { api_url: "https://example.com", timeout: 3000 } as const;

//config.timeout = 5000; //fout: Kan niet toewijzen aan 'timeout' omdat het een read-only eigenschap is.

//Overmatige eigenschappen zijn echter nog steeds toegestaan:
const invalidOptions: ReadonlyOptions = { width: 100, height: 200, depth: 300 }; //geen fout. Staat nog steeds overmatige eigenschappen toe.


interface StrictOptions {
  readonly width: number;
  readonly height: number;
}

//Dit geeft nu een fout:
//const invalidStrictOptions: StrictOptions = { width: 100, height: 200, depth: 300 };
//Type '{ width: number; height: number; depth: number; }' is niet toewijsbaar aan type 'StrictOptions'.
//  Object literal mag alleen bekende eigenschappen specificeren, en 'depth' bestaat niet in type 'StrictOptions'.

Dit verbetert de onveranderlijkheid, maar voorkomt alleen mutatie, niet het bestaan van extra eigenschappen. In combinatie met `Omit`, of de functie-aanpak, wordt het effectiever.

5. Bibliotheken Gebruiken (bijv. Zod, io-ts)

Bibliotheken zoals Zod en io-ts bieden krachtige runtime typevalidatie en schema-definitiemogelijkheden. Met deze bibliotheken kun je schema's definiëren die precies de verwachte vorm van je gegevens beschrijven, inclusief het voorkomen van overmatige eigenschappen. Hoewel ze een runtime-afhankelijkheid toevoegen, bieden ze een zeer robuuste en flexibele oplossing.

Voorbeeld met Zod:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

type User = z.infer;

const validUser = { id: 1, name: "John" };
const invalidUser = { id: 2, name: "Jane", extra: true };

const parsedValidUser = UserSchema.parse(validUser);
console.log("Parsed Valid User:", parsedValidUser);

try {
  const parsedInvalidUser = UserSchema.parse(invalidUser);
  console.log("Parsed Invalid User:", parsedInvalidUser); // Dit wordt niet bereikt
} catch (error) {
  console.error("Validatiefout:", error.errors);
}

De `parse`-methode van Zod genereert een fout als de invoer niet voldoet aan het schema, waardoor overmatige eigenschappen effectief worden voorkomen. Dit biedt runtime validatie en genereert ook TypeScript-types vanuit het schema, waardoor consistentie wordt gewaarborgd tussen je typdefinities en runtime validatie logica.

Best Practices voor het Afdwingen van Exacte Types

Hier zijn enkele best practices om te overwegen bij het afdwingen van striktere objectvormovereenkomst in TypeScript:

• Kies de juiste techniek: De beste aanpak is afhankelijk van je specifieke behoeften en projectvereisten. Voor eenvoudige gevallen kunnen type assertions met `Omit` of factory-functies volstaan. Overweeg voor complexere scenario's of wanneer runtime-validatie vereist is, om bibliotheken zoals Zod of io-ts te gebruiken.
• Wees consistent: Pas je gekozen aanpak consequent toe in je codebase om een uniform niveau van typeveiligheid te behouden.
• Documenteer je types: Documenteer je interfaces en types duidelijk om de verwachte vorm van je gegevens aan andere ontwikkelaars te communiceren.
• Test je code: Schrijf unit tests om te verifiëren dat je typebeperkingen werken zoals verwacht en dat je code ongeldige gegevens op een elegante manier afhandelt.
• Overweeg de afwegingen: Het afdwingen van striktere objectvormovereenkomst kan je code robuuster maken, maar het kan ook de ontwikkelingstijd verlengen. Weeg de voordelen af tegen de kosten en kies de aanpak die het meest geschikt is voor je project.
• Geleidelijke acceptatie: Als je aan een grote bestaande codebase werkt, overweeg dan om deze technieken geleidelijk te adopteren, te beginnen met de meest kritieke delen van je applicatie.
• Geef de voorkeur aan interfaces boven typealiassen bij het definiëren van objectvormen: Interfaces hebben over het algemeen de voorkeur omdat ze declaratiesamenvoeging ondersteunen, wat handig kan zijn voor het uitbreiden van types over verschillende bestanden.

Voorbeelden uit de Praktijk

Laten we kijken naar enkele praktijkscenario's waar exacte types nuttig kunnen zijn:

• API-verzoek payloads: Bij het verzenden van gegevens naar een API is het cruciaal om ervoor te zorgen dat de payload voldoet aan het verwachte schema. Het afdwingen van exacte types kan fouten voorkomen die worden veroorzaakt door het verzenden van onverwachte eigenschappen. Veel API's voor betalingsverwerking zijn bijvoorbeeld uiterst gevoelig voor onverwachte gegevens.
• Configuratiebestanden: Configuratiebestanden bevatten vaak een groot aantal eigenschappen en typefouten komen vaak voor. Door exacte types te gebruiken, kun je deze typefouten al vroeg opsporen. Als je serverlocaties instelt in een cloudimplementatie, zal een typefout in een locatie-instelling (bijv. eu-west-1 vs. eu-wet-1) extreem moeilijk te debuggen worden als deze niet van tevoren wordt opgemerkt.
• Pijplijnen voor gegevenstransformatie: Bij het transformeren van gegevens van het ene formaat naar het andere is het belangrijk om ervoor te zorgen dat de uitvoergegevens voldoen aan het verwachte schema.
• Berichtenwachtrijen: Bij het verzenden van berichten via een berichtenwachtrij is het belangrijk om ervoor te zorgen dat de berichtpayload geldig is en de juiste eigenschappen bevat.

Voorbeeld: Internationalisering (i18n) Configuratie

Stel je voor dat je vertalingen beheert voor een meertalige applicatie. Je hebt mogelijk een configuratieobject zoals dit:

interface Translation {
  greeting: string;
  farewell: string;
}

interface I18nConfig {
  locale: string;
  translations: Translation;
}

const englishConfig: I18nConfig = {
  locale: "en-US",
  translations: {
    greeting: "Hello",
    farewell: "Goodbye"
  }
};


//Dit zal een probleem zijn, omdat er een overmatige eigenschap bestaat, die in stilte een bug introduceert.
const spanishConfig: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós",
    typo: "onbedoelde vertaling"
  }
};

//Oplossing: Omit gebruiken
const spanishConfigCorrect: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós"
  } as Omit & Translation
};

Zonder exacte types kan een typefout in een vertalingssleutel (zoals het toevoegen van een `typo` veld) onopgemerkt blijven, wat leidt tot ontbrekende vertalingen in de gebruikersinterface. Door een striktere object shape matching af te dwingen, kun je deze fouten tijdens de ontwikkeling opsporen en voorkomen dat ze de productie bereiken.

Conclusie

Hoewel TypeScript geen ingebouwde "exacte types" heeft, kun je vergelijkbare resultaten bereiken met behulp van een combinatie van TypeScript-functies en -technieken zoals type assertions met `Omit`, factory-functies, type guards, `Readonly`, `as const` en externe bibliotheken zoals Zod en io-ts. Door een striktere object shape matching af te dwingen, kun je de robuustheid van je code verbeteren, veelvoorkomende fouten voorkomen en je applicaties betrouwbaarder maken. Vergeet niet de aanpak te kiezen die het beste bij je behoeften past en deze consequent toe te passen in je hele codebase. Door deze benaderingen zorgvuldig te overwegen, kun je meer controle krijgen over de types van je applicatie en de onderhoudbaarheid op de lange termijn vergroten.