TypeScript-Codierung

Was macht TypeScript-Codierung?

Arbeitsablauf

1. Orientieren. Lesen Sie die Quellen der Wahrheit des Projekts, bevor Sie schreiben: package.json (type, engines, packageManager, exports, scripts, installierte Hauptversionen), die Lockdatei, jedes tsconfig*.json entlang seiner extends-Kette, den Workspace des Roots, Framework-, Lint- und Format-Konfigurationen (pnpm-workspace.yaml, turbo.json, next.config.ts, biome.json, .oxlintrc.json) und CI für die kanonischen Prüfbefehle. Führen Sie tsc --showConfig aus, um die extends-Kette aufzulösen; es lässt Optionen weg, die auf ihrem Standardwert belassen wurden, lesen Sie diese daher aus references/modules.md (TypeScript 6 und 7 haben sie geändert). Lesen Sie das Modul, das Sie ändern, und seine Nachbarn; verwenden Sie deren Hilfsfunktionen, Fehlertypen, Schemata und Muster wieder. Erledigt, wenn: Sie den Paketmanager, die TypeScript-Hauptversion, module und moduleResolution, die strikten Flags über strict hinaus (noUncheckedIndexedAccess, exactOptionalPropertyTypes, erasableSyntaxOnly), die Lint- und Format-Toolchain sowie die Prüfbefehle des Projekts benennen können.

2. Die Typen modellieren. Entwerfen Sie Daten vor dem Kontrollfluss, gemäß Typen. Eingabe von außerhalb des Prozesses: lesen Sie references/zod.md. Ändern der öffentlichen API eines Pakets: lesen Sie references/api.md. Erledigt, wenn: jede Invariante, auf die sich die Änderung stützt, in einem Typ codiert ist und jeder Wert, der eine Vertrauensgrenze überschreitet, vor der Verwendung von einem Schema geparst wird.

3. In einer engen Schleife implementieren. Arbeiten Sie in kleinen Schritten und führen Sie nach jedem Schritt tsc --noEmit (tsc -b mit Projekt-Referenzen) aus. Lesen Sie die gesamte Diagnose; ihr Code (TS2742) ist der Suchschlüssel in den Tabellen in references/modules.md und references/types.md. Für die API einer Abhängigkeit lesen Sie deren .d.ts unter node_modules/<pkg>/ in der installierten Version. Fehlerbehebung: Schreiben Sie zuerst den Regressionstest und sehen Sie zu, wie er rot wird. Erledigt, wenn: die Änderung ohne neue Diagnosen typgeprüft ist und jeder Regressionstest vor der Korrektur rot und danach grün war.

4. Überprüfen. Führen Sie die Befehle des Projekts aus Schritt 1 über seinen Paketmanager aus (pnpm exec, npx, bunx); andernfalls für die Toolchain, die das Projekt verwendet:

   tsc --noEmit                                           # tsc -b, wenn tsconfig.json nur Referenzen auflistet
   biome ci                                               # Biome
   oxfmt --check && oxlint --type-aware --deny-warnings   # oxlint + oxfmt
   vitest run --typecheck                                 # oder der Test-Runner des Projekts
   

   • Ein root tsconfig.json mit "files": [] und references bewirkt, dass tsc --noEmit nichts prüft; verwenden Sie tsc -b. In einem Workspace ohne root tsconfig führen Sie die Prüfungen pro Paket über den Task-Runner aus (turbo run check-types test).
   • Behalten Sie tsc in der Schleife mit jedem Linter: Biomes Typinferenz und oxlints typbewusste Regeln ergänzen es, ersetzen es aber nie.
   • Formatierungsfehler: Wenden Sie den Formatierer an (biome check --write, oxfmt), anstatt manuell zu bearbeiten.
   • Beheben Sie Diagnosen an der Ursache. Wenn eine Unterdrückung angemessen ist, beschränken Sie sie auf eine Zeile und geben Sie den Grund an: // biome-ignore lint/<group>/<rule>: Grund, // oxlint-disable-next-line <rule> -- Grund, // @ts-expect-error Grund.
   • Lint- oder Format-Konfiguration berührt: Prüfen Sie sie gegen references/lints.md, führen Sie dann den Linter und Formatierer über das gesamte Repository aus, nicht nur über geänderte Dateien.
   • Öffentliche API eines veröffentlichten Pakets berührt: Führen Sie references/api.md aus. Erledigt, wenn: jeder Befehl mit Exit-Code 0 beendet wird, von Ihnen geänderte Zeilen keine Warnungen erzeugen und jede neue Unterdrückung einen Grund trägt.

5. Den Diff selbst überprüfen. Lesen Sie den vollständigen git diff erneut (git add -A && git diff --cached, wenn Dateien neu sind), nicht aus dem Gedächtnis, gegen Regeln und die Regeln jeder Referenzdatei, deren Zweig der Diff berührt. Erledigt, wenn: jeder Hunk für die Aufgabe erforderlich ist, console.log, debugger, .only und auskommentierter Code entfernt sind, Dokumentationskommentare zum Verhalten passen und jede anwendbare Regel für jeden Hunk gilt.

Den Code eines anderen überprüfen: Führen Sie Schritt 1 aus, führen Sie die Befehle aus Schritt 4 aus, wenn möglich, und wenden Sie dann Schritt 5 auf dessen Diff an. Melden Sie jeden Befund als path:line, die Regel und die Korrektur.

Regeln

Typen

• Mit Beweisen eingrenzen: typeof, instanceof, in, eine Diskriminantenprüfung, ein Typ-Prädikat oder eine Schema-Parsing. any, das Non-Null ! und as T sind verboten, auch in Tests; as const und satisfies bleiben erlaubt. Wenn die Typen einer Bibliothek falsch sind, korrigieren Sie sie an der Quelle mit Modulerweiterung (references/types.md).
• Illegale Zustände nicht darstellbar machen: eine diskriminierte Union mit einem literalen kind-Feld, anstelle von boolean-Flags plus optionalen Feldern. Markieren Sie IDs, Einheiten und validierte Werte durch ein Schema (z.string().brand<"UserId">()) oder ein Typ-Prädikat, niemals as.
• Parsen, nicht validieren: JSON.parse, Response.json(), Umgebungsvariablen, Speicher, URL-Parameter und postMessage-Daten sind unknown, bis ein Zod-Schema sie an der Grenze parst; geben Sie den geparsten Typ nach innen weiter.
• Unions, die Sie besitzen, erschöpfend switchen: enden Sie mit default: x satisfies never; throw new Error(...), oder verwenden Sie eine Record<Union, V>-Nachschlagetabelle, die bei einem neu hinzugefügten Member nicht kompiliert.
• Indizierter Zugriff ist T | undefined unter noUncheckedIndexedAccess: Behandeln Sie das undefined (Guard, ?? fallback, for...of), anstatt es wegzuassertieren.
• Exportierte Funktionen deklarieren ihren Rückgabetyp; lokale bleiben inferiert.
• interface für Objektformen, extends über &-Schnittmengen; type für Unions, gemappte und konditionale Typen.
• Akzeptieren Sie readonly T[] und Readonly<T> für Eingaben, die die Funktion nicht mutiert.
• Eine String-Literal-Union oder ein as const-Objekt, über enum und Namespaces mit Laufzeitcode (beide verboten unter erasableSyntaxOnly).

Fehler und asynchron

• Erwartete Fehler, die der Aufrufer behandeln muss, geben ein diskriminiertes Ergebnis zurück; Bugs und nicht wiederherstellbare Zustände werfen eine Error-Unterklasse mit { cause }. Details: references/errors.md.
• Jedes Promise wird awaited, returned oder an einen Handler übergeben, der seine Zurückweisung beobachtet.

Aktuelle Idiome

Trainingsdaten stammen von vor TypeScript 6 und 7: TypeScript 7 ist der Go-native Compiler, strict ist standardmäßig aktiviert, types hat standardmäßig [], und baseUrl, outFile, target: "ES5" und moduleResolution: "node10" wurden entfernt (references/modules.md). Bevorzugen Sie die aktuelle Form, einschließlich Standardbibliotheks-APIs nach lib-Level, wenn die installierten Versionen dies zulassen. Wo eine Referenz mit der installierten .d.ts oder CHANGELOG des Pakets nicht übereinstimmt, gewinnt die installierte Version.

Bevorzugen	Über	Seit
const config = { ... } satisfies Config	const config: Config (verbreitert), as Config	4.9
function f<const T>(x: T)	as const an jeder Aufrufstelle	5.0
import type { T } mit verbatimModuleSyntax	importsNotUsedAsValues (entfernt)	5.0
using / await using mit [Symbol.dispose]	try / finally Aufräumen	5.2, lib esnext
import data from "./d.json" with { type: "json" }	assert { type: "json" } (Fehler seit 6.0)	5.3
NoInfer<T>	T & {} Inferenzblocker	5.4
inferierte Prädikate: xs.filter((x) => x !== undefined)	handgeschriebene (x): x is T => Guards	5.5

Dokumentation und Kommentare

• Exportierte Elemente erhalten /** */-Dokumentation, die den Vertrag angibt: @throws für geworfene Fehler, @deprecated mit Nennung des Ersatzes, @example, wenn die Verwendung aus der Signatur nicht offensichtlich ist.

Abhängigkeiten

• Verwenden Sie wieder, was package.json bereits auflistet, und bevorzugen Sie die Plattform, wenn sie den Bedarf abdeckt: fetch, structuredClone, crypto.randomUUID, AbortSignal.timeout, node:-präfixierte Builtins.
• Fügen Sie mit dem Paketmanager des Projekts hinzu, wobei @types/* auf die Hauptversion des Laufzeitpakets gepinnt wird (@types/node: die niedrigste Node in engines).

Referenzen

Laden Sie diejenige, die zu dem Zweig passt, an dem Sie arbeiten:

• references/types.md: Generics, konditionale und gemappte Typen, Typ-Prädikate, Modulerweiterung, Type-Level-Fehler.
• references/errors.md: Definieren von Fehlertypen, Ergebnis-Unions, cause, Fehlergrenzen zwischen Schichten.
• references/async.md: Promises, Abbruch mit AbortSignal, Nebenläufigkeit, using, asynchrone Iteration.
• references/modules.md: tsconfig.json, package.json, Modulauflösung, ESM und CommonJS, TypeScript 6 und 7 Migration, Konfigurationsfehler.
• references/zod.md: Parsen von nicht vertrauenswürdigen Eingaben, Schemata, Zod 4 API.
• references/react.md: React-Komponenten, Hooks, React 19 APIs, React Compiler.
• references/nextjs.md: Next.js App Router, Server-Komponenten und -Funktionen, "use cache", Routentypen.
• references/recharts.md: Recharts-Diagramme, typisierte dataKey, benutzerdefinierte Tooltips und Formen, Diagrammgrößen.
• references/lints.md: Einrichten oder Ändern von Biome, oxlint oder oxfmt.
• references/testing.md: Schreiben von Tests, Typtests, React-Komponententests, Mocks.
• references/perf.md: Langsame Typüberprüfung, Editor-Verzögerung, Bundle-Größe, ein gemessener Hot Path.
• references/api.md: Entwerfen oder Ändern der öffentlichen API eines veröffentlichten Pakets, exports, Deklarationsdateien, Semver; Werkzeuge, die typescript als Bibliothek importieren.
• references/runtimes.md: Ausführen von .ts direkt auf Node, Bun oder Deno.
• references/monorepo.md: pnpm Workspaces, Turborepo, Pakete, die voneinander abhängen.
• references/jsdoc.md: .js-Dateien, die mit checkJs geprüft werden, JSDoc-Typen, Migration von JavaScript zu TypeScript.