ts-toolkit für TypeScript: Das vollständige Handbuch

1. Was ist ts-toolkit und warum braucht man es?

ts-toolkit ist eine leistungsstarke Utility-Bibliothek für TypeScript, die den Entwickleralltag vereinfacht. Sie bietet eine Sammlung fertiger Funktionen, Typen und Klassen, um mit Objekten, Arrays, Strings, Funktionen und Datentypen effizienter und sicherer zu arbeiten. Anders als die Standard-JavaScript-Bibliothek liefert ts-toolkit streng typisierte Lösungen, die vollständig mit dem TypeScript-Typsystem kompatibel sind.

Warum diese Bibliothek? In der modernen TypeScript-Entwicklung fallen oft wiederkehrende Aufgaben an: tiefes Kopieren von Objekten, sicheres Navigieren in verschachtelten Strukturen, Laufzeit-Typprüfungen, Arbeiten mit Option/Result (Monaden zur Fehlerbehandlung) und vieles mehr. ts-toolkit übernimmt die Implementierung dieser Patterns, sodass du dich auf die Geschäftslogik konzentrieren kannst. Die Bibliothek ist besonders nützlich in Projekten, die hohe Zuverlässigkeit und strenge Typisierung erfordern.

Der entscheidende Vorteil von ts-toolkit ist die Typsicherheit (type safety). Jede Funktion ist so konzipiert, dass sie die Möglichkeiten von TypeScript voll ausschöpft: Conditional Types, Mapped Types, Infer und andere fortgeschrittene Konstrukte. Das bedeutet, dass viele Fehler, die erst zur Laufzeit auftreten würden, bereits während der Kompilierung erkannt werden.

2. Installation

Die Installation erfolgt über den Paketmanager npm:

npm install @tool-belt/ts-toolkit

Oder mit yarn:

yarn add @tool-belt/ts-toolkit

Nach der Installation importierst du die benötigten Funktionen in dein Projekt:

import { deepClone, safeGet, pipe } from '@tool-belt/ts-toolkit';

3. Schnellstart

Ein minimales Arbeitsbeispiel, das die wichtigsten Funktionen der Bibliothek zeigt:

import { deepClone, isObject, pipe } from '@tool-belt/ts-toolkit';

// Beispiel 1: Tiefes Kopieren
const original = { a: 1, b: { c: 2 } };
const cloned = deepClone(original);
cloned.b.c = 42;
console.log(original.b.c); // 2 (Original bleibt unverändert)

// Beispiel 2: Typprüfung
console.log(isObject({}));   // true
console.log(isObject(null)); // false

// Beispiel 3: Funktionskomposition
const addOne = (x: number) => x + 1;
const double = (x: number) => x * 2;
const addOneThenDouble = pipe(addOne, double);
console.log(addOneThenDouble(5)); // 12

4. Wichtige Methoden und Funktionen

4.1. `deepClone`

Signatur: function deepClone<T>(value: T): T

Beschreibung: Führt eine tiefe Kopie eines beliebigen Werts durch, einschließlich verschachtelter Objekte, Arrays, Datumsangaben, Map, Set und anderer Strukturen. Unterstützt zirkuläre Referenzen.

import { deepClone } from '@tool-belt/ts-toolkit';

const user = {
  name: 'Alice',
  address: { city: 'NYC', zip: 10001 },
  hobbies: ['reading', 'coding']
};

const clonedUser = deepClone(user);
clonedUser.address.city = 'LA';
console.log(user.address.city); // 'NYC'

4.2. `safeGet`

Signatur: function safeGet<T, K extends keyof T>(obj: T, key: K): T[K] | undefined

Beschreibung: Greift sicher auf den Wert einer Objekteigenschaft zu. Gibt undefined zurück, wenn die Eigenschaft fehlt oder das Objekt null/undefined ist, anstatt einen Fehler zu werfen.

import { safeGet } from '@tool-belt/ts-toolkit';

const data = { user: { name: 'Bob' } };
const name = safeGet(data, 'user')?.name; // 'Bob'
const missing = safeGet(null, 'anything'); // undefined