TypeScript Template Literal-typer för typsäkra API:er

TypeScript template literal-typer är en kraftfull funktion som introducerades i TypeScript 4.1 och som låter dig utföra strängmanipulation på typnivå. De öppnar upp en värld av möjligheter för att skapa mycket typsäkra och underhållbara API:er, vilket gör att du kan fånga fel vid kompileringstid som annars bara skulle dyka upp vid körning. Detta leder i sin tur till en förbättrad utvecklarupplevelse, enklare refaktorering och mer robust kod.

Vad är Template Literal-typer?

I grund och botten är template literal-typer strängliteral-typer som kan konstrueras genom att kombinera strängliteral-typer, union-typer och typvariabler. Tänk på dem som stränginterpolering för typer. Detta gör att du kan skapa nya typer baserat på befintliga, vilket ger en hög grad av flexibilitet och uttrycksfullhet.

Här är ett enkelt exempel:

type Greeting = "Hello, World!";

type PersonalizedGreeting<T extends string> = `Hello, ${T}!`;

type MyGreeting = PersonalizedGreeting<"Alice">; // type MyGreeting = "Hello, Alice!"

I detta exempel är PersonalizedGreeting en template literal-typ som tar en generisk typparameter T, som måste vara en sträng. Den konstruerar sedan en ny typ genom att interpolera strängliteralen "Hello, " med värdet av T och strängliteralen "!". Den resulterande typen, MyGreeting, är "Hello, Alice!".

Fördelar med att använda Template Literal-typer

Förbättrad typsäkerhet: Fånga fel vid kompileringstid istället för vid körning.
Förbättrad kodunderhållbarhet: Gör din kod enklare att förstå, ändra och refaktorera.
Bättre utvecklarupplevelse: Ger mer exakt och hjälpsam autofyllning och felmeddelanden.
Kodgenerering: Möjliggör skapandet av kodgeneratorer som producerar typsäker kod.
API-design: Tvingar fram begränsningar för API-användning och förenklar parameterhantering.

Användningsfall från verkligheten

1. Definition av API-slutpunkter

Template literal-typer kan användas för att definiera typer för API-slutpunkter, vilket säkerställer att korrekta parametrar skickas till API:et och att svaret hanteras korrekt. Tänk dig en e-handelsplattform som stöder flera valutor, som USD, EUR och JPY.

type Currency = "USD" | "EUR" | "JPY";
type ProductID = string; //I praktiken skulle detta kunna vara en mer specifik typ

type GetProductEndpoint<C extends Currency> = `/products/${ProductID}/${C}`;

type USDEndpoint = GetProductEndpoint<"USD">; // type USDEndpoint = "/products/${string}/USD"

Detta exempel definierar en GetProductEndpoint-typ som tar en valuta som en typparameter. Den resulterande typen är en strängliteral-typ som representerar API-slutpunkten för att hämta en produkt i den angivna valutan. Med detta tillvägagångssätt kan du säkerställa att API-slutpunkten alltid konstrueras korrekt och att rätt valuta används.

2. Datavalidering

Template literal-typer kan användas för att validera data vid kompileringstid. Till exempel kan du använda dem för att validera formatet på ett telefonnummer eller en e-postadress. Föreställ dig att du behöver validera internationella telefonnummer som kan ha olika format baserat på landskoden.

type CountryCode = "+1" | "+44" | "+81"; // USA, Storbritannien, Japan
type PhoneNumber<C extends CountryCode, N extends string> = `${C}-${N}`;

type ValidUSPhoneNumber = PhoneNumber<"+1", "555-123-4567">; // type ValidUSPhoneNumber = "+1-555-123-4567"

//Obs: Mer komplex validering kan kräva att man kombinerar template literal-typer med villkorliga typer.

Detta exempel visar hur du kan skapa en grundläggande telefonnummertyp som tvingar fram ett specifikt format. Mer sofistikerad validering kan innebära användning av villkorliga typer och reguljära uttrycksliknande mönster inom template literal-typen.

3. Kodgenerering

Template literal-typer kan användas för att generera kod vid kompileringstid. Till exempel kan du använda dem för att generera namn på React-komponenter baserat på namnet på den data de visar. Ett vanligt mönster är att generera komponentnamn som följer mönstret <Entitet>Detaljer.

type Entity = "User" | "Product" | "Order";
type ComponentName<E extends Entity> = `${E}Details`;

type UserDetailsComponent = ComponentName<"User">; // type UserDetailsComponent = "UserDetails"

Detta gör att du automatiskt kan generera komponentnamn som är konsekventa och beskrivande, vilket minskar risken för namnkonflikter och förbättrar kodens läsbarhet.

4. Händelsehantering

Template literal-typer är utmärkta för att definiera händelsenamn på ett typsäkert sätt, vilket säkerställer att händelselyssnare registreras korrekt och att händelsehanterare tar emot förväntad data. Tänk dig ett system där händelser kategoriseras efter modul och händelsetyp, separerade med ett kolon.

type Module = "user" | "product" | "order";
type EventType = "created" | "updated" | "deleted";
type EventName<M extends Module, E extends EventType> = `${M}:${E}`;

type UserCreatedEvent = EventName<"user", "created">; // type UserCreatedEvent = "user:created"

interface EventMap {
  [key: EventName<Module, EventType>]: (data: any) => void; //Exempel: Typen för händelsehantering
}

Detta exempel demonstrerar hur man skapar händelsenamn som följer ett konsekvent mönster, vilket förbättrar den övergripande strukturen och typsäkerheten i händelsesystemet.

Avancerade tekniker

1. Kombinera med villkorliga typer

Template literal-typer kan kombineras med villkorliga typer för att skapa ännu mer sofistikerade typomvandlingar. Villkorliga typer låter dig definiera typer som beror på andra typer, vilket gör att du kan utföra komplex logik på typnivå.

type ToUpperCase<S extends string> = S extends Uppercase<S> ? S : Uppercase<S>;

type MaybeUpperCase<S extends string, Upper extends boolean> = Upper extends true ? ToUpperCase<S> : S;

type Example = MaybeUpperCase<"hello", true>; // type Example = "HELLO"
type Example2 = MaybeUpperCase<"world", false>; // type Example2 = "world"

I detta exempel tar MaybeUpperCase en sträng och en boolean. Om boolean-värdet är sant, omvandlar den strängen till versaler; annars returnerar den strängen som den är. Detta visar hur du villkorligt kan modifiera strängtyper.

2. Använda med mappade typer

Template literal-typer kan användas med mappade typer för att omvandla nycklarna i en objekttyp. Mappade typer låter dig skapa nya typer genom att iterera över nycklarna i en befintlig typ och tillämpa en omvandling på varje nyckel. Ett vanligt användningsfall är att lägga till ett prefix eller suffix till objektnycklar.

type MyObject = {
  name: string;
  age: number;
};

type AddPrefix<T, Prefix extends string> = {
  [K in keyof T as `${Prefix}${string & K}`]: T[K];
};

type PrefixedObject = AddPrefix<MyObject, "data_">;
// type PrefixedObject = {
//    data_name: string;
//    data_age: number;
// }

Här tar AddPrefix en objekttyp och ett prefix. Den skapar sedan en ny objekttyp med samma egenskaper, men med prefixet tillagt på varje nyckel. Detta kan vara användbart för att generera dataöverföringsobjekt (DTOs) eller andra typer där du behöver ändra namnen på egenskaperna.

3. Inbyggda strängmanipulationstyper

TypeScript tillhandahåller flera inbyggda strängmanipulationstyper, såsom Uppercase, Lowercase, Capitalize och Uncapitalize, som kan användas tillsammans med template literal-typer för att utföra mer komplexa strängomvandlingar.

type MyString = "hello world";

type CapitalizedString = Capitalize<MyString>; // type CapitalizedString = "Hello world"

type UpperCasedString = Uppercase<MyString>;   // type UpperCasedString = "HELLO WORLD"

Dessa inbyggda typer gör det enklare att utföra vanliga strängmanipulationer utan att behöva skriva anpassad typlogik.

Bästa praxis

Håll det enkelt: Undvik alltför komplexa template literal-typer som är svåra att förstå och underhålla.
Använd beskrivande namn: Använd beskrivande namn för dina typvariabler för att förbättra kodens läsbarhet.
Testa noggrant: Testa dina template literal-typer noggrant för att säkerställa att de beter sig som förväntat.
Dokumentera din kod: Dokumentera din kod tydligt för att förklara syftet och beteendet hos dina template literal-typer.
Tänk på prestanda: Även om template literal-typer är kraftfulla kan de också påverka prestandan vid kompilering. Var medveten om komplexiteten i dina typer och undvik onödiga beräkningar.

Vanliga fallgropar

Överdriven komplexitet: Alltför komplexa template literal-typer kan vara svåra att förstå och underhålla. Bryt ner komplexa typer i mindre, mer hanterbara delar.
Prestandaproblem: Komplexa typberäkningar kan sakta ner kompileringstider. Profilera din kod och optimera där det behövs.
Problem med typinferens: TypeScript kan inte alltid härleda den korrekta typen för komplexa template literal-typer. Ange explicita typannoteringar vid behov.
Sträng-unions vs. literaler: Var medveten om skillnaden mellan sträng-unions och strängliteraler när du arbetar med template literal-typer. Att använda en sträng-union där en strängliteral förväntas kan leda till oväntat beteende.

Alternativ

Även om template literal-typer erbjuder ett kraftfullt sätt att uppnå typsäkerhet i API-utveckling, finns det alternativa tillvägagångssätt som kan vara mer lämpliga i vissa situationer.

Validering vid körning: Att använda valideringsbibliotek för körning som Zod eller Yup kan ge liknande fördelar som template literal-typer, men vid körning istället för vid kompilering. Detta kan vara användbart för att validera data som kommer från externa källor, såsom användarinmatning eller API-svar.
Kodgenereringsverktyg: Kodgenereringsverktyg som OpenAPI Generator kan generera typsäker kod från API-specifikationer. Detta kan vara ett bra alternativ om du har ett väldefinierat API och vill automatisera processen för att generera klientkod.
Manuella typdefinitioner: I vissa fall kan det vara enklare att definiera typer manuellt istället för att använda template literal-typer. Detta kan vara ett bra alternativ om du har ett litet antal typer och inte behöver flexibiliteten hos template literal-typer.

Slutsats

TypeScript template literal-typer är ett värdefullt verktyg för att skapa typsäkra och underhållbara API:er. De låter dig utföra strängmanipulation på typnivå, vilket gör att du kan fånga fel vid kompileringstid och förbättra den övergripande kvaliteten på din kod. Genom att förstå de koncept och tekniker som diskuteras i denna artikel kan du utnyttja template literal-typer för att bygga mer robusta, tillförlitliga och utvecklarvänliga API:er. Oavsett om du bygger en komplex webbapplikation eller ett enkelt kommandoradsverktyg kan template literal-typer hjälpa dig att skriva bättre TypeScript-kod.

Överväg att utforska fler exempel och experimentera med template literal-typer i dina egna projekt för att fullt ut förstå deras potential. Ju mer du använder dem, desto bekvämare blir du med deras syntax och kapacitet, vilket gör att du kan skapa verkligt typsäkra och robusta applikationer.