Stolperfallen

Die meisten Probleme haben eine Ursache: Ein Typ, den VS Code nicht kennt, wird ohne Typprüfung still zu any. Die Annotation sieht dann richtig aus, prüft aber nichts. Diese Fälle treten in DOCUMENTS-Projekten typischerweise auf:

1. Typnamen, die es nicht gibt. Ein Mappentyp heißt in fileTypes.d.ts wie sein technischer Name, nicht wie seine Bezeichnung in der Oberfläche. Ein @type {Projekt} für den Mappentyp crmProject ergibt "Cannot find name 'Projekt'". Typnamen also immer per Autovervollständigung einfügen. Handgeschriebene Typen, etwa ein gemeinsamer Typ für mehrere Mappentypen, passen nicht automatisch zu den generierten: Was die API liefert, wird per Cast eingegrenzt (DocFile & MeinTyp).

2. Doku, die nicht zum Code passt. Typisch ist eine Funktion, die bei Fehlern false zurückgibt, aber nur den Erfolgsfall deklariert:

// Falsch
 * @returns {SystemUser} System user object or false
// Richtig
 * @returns {SystemUser | false} System user object or false if not found

Nur mit der richtigen Variante erinnert VS Code die Aufrufer an die false-Prüfung. Optionale Parameter gehören außerdem in eckige Klammern: @param {boolean} [caseSensitive=false].

3. Echte Fehler, die checkJs meldet. Häufig sind Variablen, die nirgends definiert sind (z.B. nach einem vergessenen Import), und Felder, die der Mappentyp nicht kennt (ein Tippfehler im Feldnamen oder ein Feld, das nur ein anderer Mappentyp hat). Auf dem Server fallen beide erst zur Laufzeit auf, als ReferenceError oder als leerer Wert.

4. Bibliotheken ohne paths-Eintrag. Wird eine eigene Bibliothek per Name geladen (require("MeineLib") oder import … from "MeineLib"), braucht sie einen Eintrag unter paths. Sonst ist alles daraus any und ungeprüft (siehe "Voraussetzung: Modulnamen auflösen").

5. @ts-ignore ohne Begründung. Ein @ts-ignore unterdrückt jeden Fehler der nächsten Zeile, auch künftige. Deshalb immer den Grund dazuschreiben:

// @ts-ignore - document ist ein Browser-Global, lib.dom ist in der
// jsconfig.json bewusst nicht eingebunden
roots.push(document);

6. @typedef statt @type. /** @typedef {GadgetContext} gadgetContext */ legt nur einen neuen Typnamen an. Die Variable gadgetContext bleibt untypisiert. Richtig ist /** @type {GadgetContext} */ var gadgetContext;.

7. Gleiche Namen in mehreren Skripten. Skripte ohne import/export teilen sich für VS Code einen globalen Namensraum. Deklarieren zwei Skripte auf oberster Ebene z.B. const gAPI = require(...), erscheint "Cannot redeclare block-scoped variable 'gAPI'", obwohl beide auf dem Server korrekt laufen. Abhilfe: Den Skriptcode in eine Funktion packen (z.B. function main() { ... }), damit die Variablen lokal sind.

8. Fehler in der generierten fileTypes.d.ts. Referenzfelder, die ihre Auswahl über ein Skript beziehen, erzeugt der Generator als ungültiges TypeScript, z.B. "Kunde": runscript:MeinReferenzSkript;. Der Rest der Datei funktioniert, nur diese Felder haben keinen brauchbaren Typ. Nicht von Hand korrigieren, das Problem an otris melden.

9. return auf oberster Ebene. Portalskripte dürfen auf dem Server direkt mit return enden. TypeScript meldet das als "A 'return' statement can only be used within a function body". Abhilfe wie bei Punkt 7: Code in eine Funktion packen und nur noch einmal am Ende zurückgeben, mit Begründung: // @ts-ignore - Portalskript-Rückgabe auf oberster Ebene über return main();.