Grundlagen: Typen mit JSDoc

In JavaScript schreiben wir Typen nicht in den Code, sondern in JSDoc-Kommentare (/** ... */). VS Code liest sie genauso wie TypeScript-Typen. Ein normaler Kommentar (/* ... */ oder //) wird ignoriert, es braucht immer zwei Sternchen.

Funktionen: @param und @returns

Jede Funktion bekommt einen Satz Beschreibung, ihre Parameter und den Rückgabetyp. Beispiel aus Gadget_DexRecordCategory_FiletypeFilter.js:

/**
 * Builds the filter properties of a file type: one field comparison and one value
 * comparison per data field, sorted by label so that both variants stay adjacent.
 *
 * @param {string} fileTypeName technical name of the referenced file type
 * @returns {FilterProperty[]}
 */
function buildFilterProperties(fileTypeName) {
    const properties = /** @type {FilterProperty[]} */ ([]);

Beim Aufruf von buildFilterProperties( zeigt VS Code jetzt Parameter und Beschreibung an. Das Ergebnis ist als Array von FilterProperty bekannt.

Optionale Parameter und Standardwerte

Optionale Parameter stehen in eckigen Klammern, ein Standardwert folgt nach =. Aus DexRecordReference.mjs:

/**
 * @param {DexDossier & DocFile} dossierFile
 * @param {boolean} [initiate=true] - Default: true. constructor calls function to get record references for given file
 */
constructor(dossierFile, initiate = true) {

Variablen typisieren und Casts

@type direkt über einer Variablen legt ihren Typ fest. Steht @type vor einem geklammerten Ausdruck, ist es ein Cast: "Behandle diesen Wert als Typ X". Die runden Klammern sind Pflicht, sonst wird der Cast ignoriert.

// Leeres Array: ohne Cast wäre es any[]
const properties = /** @type {FilterProperty[]} */ ([]);

// catch-Variable ist unbekannt (unknown) -> als Error behandeln
} catch (e) {
    let err = /** @type {Error} */ (e);
    context.errorMessage = err.message;
    context.returnValue = -1;
}

(Aus Gadget_DexRecordCategory_FiletypeFilter.js und DexDossier_OnFileView.js)

Spickzettel: Typ-Syntax

Was	Schreibweise
Grundtypen	`{string}`, `{number}`, `{boolean}`
Arrays	`{string[]}` oder `{Array<string \| RegExp>}`
Dictionary (Schlüssel → Wert)	`{Object<string, string>}` oder `{Record<string, string>}`
Kann auch null sein	`{string \| null}`
Feste Werteliste	`{"info" \| "warning" \| "error"}`
Inline-Objekt	`{{text: string, id?: number}}`
Funktion	`{(data: Object, record: any) => boolean}`
Kombination zweier Typen	`{DocFile & dexRecord}`
Typ aus einer anderen Datei	`{import("./eTreeLib").TreeResult}`
Bewusst ungeprüft	`{any}` oder `{*}`, nur mit Begründung