Projekt-Setup

Damit VS Code die Typings findet, braucht unser Workspace drei Dinge: eine jsconfig.json im Root, den Ordner typings/ mit den .d.ts-Dateien von otris und den Ordner typings_dexpro/ mit unseren eigenen Deklarationen. jsconfig.json und typings/ legt die DOCUMENTS-Extension (vscode-documentsos) beim Einrichten des Projekts an, typings_dexpro/ pflegen wir selbst.

jsconfig.json

Die jsconfig.json sagt VS Code, welche Dateien zum Projekt gehören und welche JavaScript-Version gilt. Unsere aktuelle Konfiguration:

{
  "compilerOptions": {
    "checkJs": true,
    "alwaysStrict": true,
    "target": "es2016",
    "lib": ["es2016", "scripthost"],
    "baseUrl": ".",
    "paths": {
      // ... weitere Bibliotheken
    },
    "typeRoots": ["./typings"]
  },
  "include": [
    "node_modules/@types/**/*.d.ts",
    "src/**/*.js",
    "src/**/*.mjs",
    "typings/**/*.d.ts",
    "typings_dexpro/**/*.d.ts"
  ]
}

• include bindet unsere Skripte (.js und .mjs in src/), die otris-Typings (typings/) und unsere eigenen (typings_dexpro/) ein. Nur was hier steht, kennt IntelliSense.
• lib lässt bewusst dom weg. Sonst kollidieren die Browser-Klassen File und Document mit den gleichnamigen DOCUMENTS-Klassen.
• target: es2016 schaltet Autovervollständigung für ES6-Features wie Map oder for...of frei. Achtung: Nicht alles davon unterstützt der DOCUMENTS-Server.
• checkJs: true prüft jede Datei aus include auf Typfehler, nicht nur für IntelliSense. Die Meldungen erscheinen in der Problems-Ansicht.
• alwaysStrict: true prüft jede Datei so, als stünde "use strict" darüber. Das ist nur Linting: Auf dem Server läuft ein Skript erst strikt, wenn "use strict"; im Skript selbst steht.
• baseUrl + paths ordnen Modulnamen Dateien zu: unsere Bibliotheken (DexRecordLib → src/…) und Typings, deren Dateiname vom Modulnamen abweicht (gadgetAPI → gadgetApi.d.ts).
• typeRoots sorgt dafür, dass Typings mit gleichem Datei- und Modulnamen (otrAssert, util.otrLogger) auch ohne paths-Eintrag gefunden werden.

Der Ordner typings/

Wichtig: Die Dateien in typings/ werden nicht von Hand bearbeitet, denn die Extension überschreibt sie beim nächsten Aktualisieren. Eigene Typen gehören in JSDoc-Kommentare im Skript oder in unseren Ordner typings_dexpro/ (siehe "Bibliotheken und eigene .d.ts-Dateien").

Aktualisiert werden die Typings über die Befehlspalette (Cmd/Strg+Shift+P) oder per Rechtsklick auf den Ordner typings/ im Explorer:

• documentsOS: Install Typings installiert die Standard-Typings der API (Rechtsklick auf das Projekt-Root).
• documentsOS: Get Typings lädt die API-Typings passend zur Serverversion.
• documentsOS: Get File Type Typings erzeugt fileTypes.d.ts neu aus den Mappentypen des Servers. Nach jeder Änderung an Mappentypen oder Feldern ausführen.

Typprüfung

In unserem Workspace ist die Prüfung projektweit an: checkJs und alwaysStrict stehen auf true. Das empfehlen wir für jeden DOCUMENTS-Workspace. Ein // @ts-check am Dateianfang ist damit nicht nötig.

• Einzelne Datei ausnehmen: // @ts-nocheck als erste Zeile. Nur als Übergang für Altskripte und mit Kommentar, warum.
• Was alwaysStrict zusätzlich findet: Code, der im Strict Mode verboten ist, z.B. delete auf einer Variablen (4 Stellen in DEXPRO__DbLib.js), Oktal-Literale wie 010 oder doppelte Parameternamen.