【Javascript】 JSDocでの型の種類

jsdocで仮引数などを定義する際に、必ずと言って良いほど型を書きます。

配列の型書き方、連想配列の型の書き方、nullableやデフォルト引数など、詰まりやすい部分も紹介します。

一覧

プリミティブ型

/**
 * @type {String}
 * @type {Number}
 * @type {BigInt}
 * @type {Boolean}
 * @type {Symbol}
 */

殆どはStringとNumberだと思います。

クラス

クラスインスタンスの場合はそのクラス名をそのまま書きます。ここで、asyncな関数の場合、戻り値はPromise<returnの型>になります。

/**
 * @return {Promise<Number>}
 */
async function f() {
    return 5;
}

配列と連想配列

配列は次の2種類あります。

/**
 * @type {Array<Number>}
 * @type {Number[]}
 */

多次元配列では[]を複数つけるか、<>の中にそのまま型を重ねます。

/**
 * @type {Array<Array<Number>}
 * @type {Number[][]}
 */

連想配列では、{ [key: 型]: valueの型 }と書きます。

/**
 * @type { {[key: String]: Number} }
 */

特定のキーを持つオブジェクト

普通の連想配列と同じように{ key: value }を並べます。

/**
 * @type {{
 *  foo: "hoge",
 *  bar: 100,
 *  [key: String]: Number,
 * }}
 */

複数の型

複数の型がありえる場合は|で区切ります。

/**
 * @type { String | Number } 
 */

nullable

nullableなら?型, non nullableなら!型と書きます。

/**
 * @type { ?String } 
 * @type { !String } 
 */

デフォルト引数

デフォルト引数がある場合、型=とするか、型 [引数名]とします。

/**
 * @param { String= } arg
 * @param { String } [arg2]
 * @param { String } [arg3="hige"]
 */
function f(arg = "hoge", arg2 = "fuga", arg3 = "hige") {
    // ...
}

VSCodeの場合、1つ目はうまく解釈してくれず、arg?: string | undefinedのような表記になります。

大文字と小文字どちらが良いか

しばしば、{ Number }だったり、{ number }だったりします。

型に関しては小文字を推奨します。入力補完自体は大文字でも動作するのですが、numberとNumberはそもそも別物です。

const i1 = 100;
const i2 = new Number(100);

console.log("i1 type is " + typeof(i1));
console.log("i2 type is " + typeof(i2));

i1 type is number
i2 type is object

const s1 = "hoge";
const s2 = new String("hoge");

console.log("s1 type is " + typeof(s1));
console.log("s2 type is " + typeof(s2));

s1 type is string
s2 type is object

これらのプリミティブ型でnewして使うということは基本的にほぼないと思いますので、小文字を推奨します。

ただ、numberとNumberは別物とは言えインターフェースは同じであるため、実際に使用する際は実質同一視されます。

まとめ

VSCodeで連想配列を書く際にうまく補完してくれないのは、しばしば引っかかるポイントです。

JSDocを書く際は多くの開発環境がVSCodeだと思います。その場合、型を大文字にしたり、特定の書き方に絞らないとうまく解釈してくれない場合があるので注意しましょう。