ts-morph für TypeScript: Komplettguide mit Beispielen

Einführung in ts-morph: Was ist das und wozu braucht man es?

ts-morph ist eine leistungsstarke Bibliothek zur programmatischen Arbeit mit dem abstrakten Syntaxbaum (AST) von TypeScript. Sie bietet eine benutzerfreundliche und intuitive API zum Analysieren, Modifizieren und Generieren von TypeScript-Code. Im Gegensatz zur direkten Nutzung des TypeScript-Compiler-API bietet ts-morph eine höherwertige Schnittstelle, die viele alltägliche Aufgaben deutlich vereinfacht.

Wofür wird diese Bibliothek benötigt? Stellen Sie sich vor, Sie müssen:

• Code-Refactoring: Automatisch alle Vorkommen einer Funktion umbenennen, die Signatur einer Methode ändern oder eine Klasse in eine andere Datei verschieben.
• Statische Analyse: Alle ungenutzten Variablen finden, die Einhaltung unternehmensweiter Codierungsrichtlinien prüfen oder Metadaten über die Projektstruktur sammeln.
• Code-Generierung: Typen basierend auf einem JSON-Schema erstellen, CRUD-Operationen für eine Datenbank generieren oder automatisch Dokumentation hinzufügen.
• Entwicklung von Entwickler-Tools: Ein Plugin für einen Linter schreiben, einen benutzerdefinierten Dokumentationsgenerator oder ein Tool zur Code-Migration erstellen.

ts-morph abstrahiert die Komplexität des TypeScript-Compiler-API und bietet einen objektorientierten Ansatz. Sie arbeiten mit Projekten, Dateien, Klassen, Funktionen und anderen Code-Elementen wie mit normalen Objekten, nicht mit Low-Level-AST-Knoten.

Installation von ts-morph

Die Installation der Bibliothek erfolgt über npm oder yarn. Sie ist als Paket für Node.js verfügbar.

npm install ts-morph

oder, wenn Sie yarn verwenden:

yarn add ts-morph

Nach der Installation können Sie die Bibliothek in Ihr Projekt importieren:

import { Project } from 'ts-morph';

Für die Arbeit mit ts-morph wird TypeScript benötigt (es ist als peer dependency angegeben). Stellen Sie sicher, dass TypeScript in Ihrem Projekt installiert ist:

npm install typescript

Schnellstart mit einem Code-Beispiel

Schreiben wir ein einfaches Skript, das eine neue TypeScript-Datei erstellt, eine Funktion hinzufügt und dann den generierten Code ausgibt.

import { Project, SyntaxKind } from 'ts-morph';

// Neues Projekt erstellen
const project = new Project({
    useInMemoryFileSystem: true, // Arbeitet im Speicher, ohne auf die Festplatte zu speichern
});

// Neue Datei erstellen
const sourceFile = project.createSourceFile('example.ts', '');

// Funktion hinzufügen
const functionDeclaration = sourceFile.addFunction({
    name: 'greet',
    parameters: [{ name: 'name', type: 'string' }],
    returnType: 'string',
    statements: [
        `return \`Hallo, \${name}!\`;`,
    ],
});

// JSDoc-Kommentar hinzufügen
functionDeclaration.addJsDoc({
    description: 'Begrüßt den Benutzer',
    tags: [{ tagName: 'param', text: 'name - Der Name des Benutzers' }],
});

// Generierten Code ausgeben
console.log(sourceFile.getText());

Ergebnis der Skriptausführung:

/**
 * Begrüßt den Benutzer
 * @param name - Der Name des Benutzers
 */
function greet(name: string): string {
    return `Hallo, ${name}!`;
}

Wie Sie sehen, haben wir programmatisch eine vollständige Funktion mit JSDoc-Dokumentation erstellt. Dies ist nur ein kleiner Teil der Möglichkeiten von ts-morph.

Wichtige Methoden und Funktionen von ts-morph

Betrachten wir 10 Schlüsselmethoden der Bibliothek mit detaillierter Beschreibung und Beispielen.

1. Project.createSourceFile()

Was es macht: Erstellt eine neue TypeScript-Quelldatei im Projekt. Die Datei kann leer sein oder initialen Code enthalten.

Parameter:

• filePath: string — Pfad zur Datei (relativ zum Projektstamm).
• sourceText?: string — Initialer Inhalt der Datei (optional).
• overwrite?: boolean — Ob eine vorhandene Datei überschrieben werden soll (Standard: false).