JSDocでTypeScript型チェック｜@type・@paramタグ一覧

JSDocで型を書いた JavaScript は、TypeScript のコンパイラ（tsc）でそのまま型チェックできます。 ファイルの拡張子は .js のままで、/** @type {string} */ のようなコメントが型注釈の役目をします。ビルドの手順を増やさずに、打ち間違いや型の食い違いを事前に見つけられます。

この記事では、TypeScript が解釈する JSDoc タグを一覧表にまとめ、すべてのタグを .js ファイルに書いて tsc --checkJs --noEmit にかけた結果（TS番号つきのエラー全文）を載せます。TypeScript 7.0 で扱いが変わった @enum と @constructor の置き換え方、// @ts-check・checkJs・jsconfig.json の違い、.js から .d.ts を作るコマンドも扱います。

確認環境：Ubuntu 24.04、Node.js 22.22.2、TypeScript 7.0.2。版による違いは TypeScript 5.9.3・5.4.5・4.9.5 を別フォルダに入れて比べました。

JSDocタグの早見表

「確かめた版」は、後で載せるエラー用サンプル（ng.js）を各版の tsc にかけ、そのタグのエラーが出ることを見た結果です（4.9.5 と 5.4.5 では @import を @typedef {import(...)} に書き換えて実行）。@satisfies と @overload は TypeScript 5.0、@import は 5.5 のリリースノートに追加の記載があります。

型チェックを有効にする方法は3つあります。

最小の手順：3行で試す

npm init -y
npm i -D typescript
npx tsc --checkJs --noEmit plain.js

// plain.js
/** @type {number} */
let count = "3";

function add(a, b) {
  return a + b;
}
add(1);

plain.js(2,5): error TS2322: Type 'string' is not assignable to type 'number'.
plain.js(4,14): error TS7006: Parameter 'a' implicitly has an 'any' type.
plain.js(4,17): error TS7006: Parameter 'b' implicitly has an 'any' type.

--noEmit は「ファイルを出力せず、チェックだけする」指定です。TypeScript 7.0.2 は strict が既定で有効なので、型を書いていない引数（a と b）も TS7006 として知らせてくれます。

タグを全部使ったサンプル（エラー0件）

型の定義だけを集めた types.js と、それを使う ok.js です。2つを同じフォルダ（src）に置きます。

// src/types.js
/**
 * @typedef {object} Item
 * @property {string} name 品名
 * @property {number} price 単価
 * @property {number} [qty] 数量（省略可）
 */

/** @typedef {"todo" | "doing" | "done"} Status */

/**
 * @callback PriceFilter
 * @param {Item} item
 * @returns {boolean}
 */

export {};

// src/ok.js
/** @import { Item, Status, PriceFilter } from "./types.js" */

// @type：変数の型
/** @type {string} */
let title = "備品リスト";

/** @type {Item[]} */
const items = [
  { name: "ノート", price: 300, qty: 2 },
  { name: "ペン", price: 120 },
];

// @param / @returns：引数と戻り値
/**
 * @param {Item[]} list
 * @param {number} [taxRate=0.1] 税率（省略可）
 * @returns {number}
 */
function total(list, taxRate = 0.1) {
  const sum = list.reduce((acc, i) => acc + i.price * (i.qty ?? 1), 0);
  return Math.round(sum * (1 + taxRate));
}

// @callback で定義した関数型を @type で使う
/** @type {PriceFilter} */
const isCheap = (item) => item.price < 200;

// @template：ジェネリクス
/**
 * @template T
 * @param {T[]} list
 * @returns {T | undefined}
 */
function first(list) {
  return list[0];
}

// @satisfies：型に合うか確かめつつ、推論された型を保つ
const labels = /** @satisfies {Record<Status, string>} */ ({
  todo: "未着手",
  doing: "作業中",
  done: "完了",
});

// @overload：呼び出し方ごとの型
/**
 * @overload
 * @param {string} value
 * @returns {string}
 */
/**
 * @overload
 * @param {number} value
 * @returns {number}
 */
/**
 * @param {string | number} value
 * @returns {string | number}
 */
function double(value) {
  return typeof value === "string" ? value + value : value * 2;
}

// 定数の集まりを型にする（as const と typeof の組み合わせ）
const Priority = /** @type {const} */ ({ LOW: 1, MIDDLE: 2, HIGH: 3 });
/** @typedef {typeof Priority[keyof typeof Priority]} PriorityValue */

/** @param {PriorityValue} p */
function priorityLabel(p) {
  return p === Priority.HIGH ? "高" : "通常";
}

// @this：this の型
/**
 * @this {HTMLElement}
 * @param {Event} e
 */
function onClick(e) {
  console.log(this.tagName, e.type);
}

// クラス：@extends・@implements・アクセス修飾子・@override
/**
 * @template T
 */
class Box {
  /** @param {T} value */
  constructor(value) {
    /** @readonly */
    this.value = value;
    /** @private */
    this.secret = "s";
    /** @protected */
    this.count = 0;
  }
  /** @returns {string} */
  describe() {
    return `Box(${this.value})`;
  }
}

/** @extends {Box<number>} */
class NumberBox extends Box {
  /** @override */
  describe() {
    return `NumberBox(${this.value.toFixed(1)})`;
  }
}

/** @typedef {{ print(): string }} Printable */
/** @implements {Printable} */
class Report {
  print() {
    return "report";
  }
}

// 型アサーション（キャスト）
const raw = /** @type {unknown} */ (JSON.parse('{"name":"消しゴム","price":80}'));
const parsed = /** @type {Item} */ (raw);

/** @deprecated total を使ってください */
function sum(/** @type {number[]} */ nums) {
  return nums.reduce((a, b) => a + b, 0);
}

console.log(title, total(items), items.filter(isCheap).length, first(items)?.name);
console.log(labels.done, double("ab"), double(21), priorityLabel(Priority.HIGH));
console.log(new NumberBox(3).describe(), new Report().print(), parsed.name, sum([1, 2]));
console.log(typeof onClick);

設定ファイル（jsconfig.json）と、package.json です。

{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "checkJs": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}

{ "type": "module" }

$ npx tsc -p jsconfig.json
$ node src/ok.js
備品リスト 792 1 ノート
完了 abab 42 高
NumberBox(3.0) report 消しゴム 3
function

tsc は何も表示せずに終わり（エラー0件）、同じファイルを Node.js でそのまま実行できました。コメントで型を書いているだけなので、変換の工程が要らないのが JSDoc 方式の持ち味です。

各タグの要点

分割代入・可変長引数・Promise の例も、動く形で載せておきます。

// src/more.js
// @ts-check
/** @typedef {import("./types.js").Item} Item */

/**
 * @param {object} options
 * @param {string} options.name 名前
 * @param {number} [options.limit] 上限（省略可）
 * @param {...number} scores 点数（可変長）
 * @returns {Promise<Item>}
 */
async function build({ name, limit = 10 }, ...scores) {
  const price = Math.min(limit, scores.reduce((a, b) => a + b, 0));
  return { name, price };
}

/** @type {(a: number, b: number) => number} */
const add = (a, b) => a + b;

/** @type {Map<string, Item>} */
const stock = new Map();

build({ name: "ノート" }, 3, 4).then((item) => {
  stock.set(item.name, item);
  console.log(item, add(1, 2), stock.size);
});

$ npx tsc --checkJs --noEmit --strict --target es2022 --module nodenext src/more.js
$ node src/more.js
{ name: 'ノート', price: 7 } 3 1

1行目の @typedef {import("./types.js").Item} Item は、@import が入る前から使える書き方です。TypeScript 5.5 のリリースノートでは、この書き方を置き換えるものとして @import が紹介されています。

型エラーの全文：タグごとにわざと間違える

次の ng.js は、タグごとに1か所ずつ型に合わないコードを書いたものです。import している lib.js は「.jsから.d.tsを生成する」の節に全文があります。

// src/ng.js
/** @import { Item, Status, PriceFilter } from "./types.js" */
import { Box, NumberBox, total, first, double } from "./lib.js";

/** @type {string} */
let title = 123;

/** @type {Item} */
const item = { name: "ノート", price: "300" };

total([item], "0.1");

/** @type {PriceFilter} */
const isCheap = (item) => item.price;

/** @type {string | undefined} */
const s = first([1, 2, 3]);

const labels = /** @satisfies {Record<Status, string>} */ ({
  todo: "未着手",
  doing: "作業中",
});

double(true);

const box = new NumberBox(3);
box.value = 5;
box.secret;
box.count;

/** @typedef {{ print(): string }} Printable */
/** @implements {Printable} */
class Report {}

class Child extends Box {
  /** @override */
  descride() {
    return "";
  }
}

/**
 * @this {HTMLElement}
 */
function onClick() {
  console.log(this.tagNme);
}

/**
 * @param {string} nmae
 * @returns {number}
 */
function len(name) {
  return name;
}

/** @type {Status} */
const st = "finished";

$ npx tsc -p jsconfig.json
src/ng.js(5,5): error TS2322: Type 'number' is not assignable to type 'string'.
src/ng.js(8,29): error TS2322: Type 'string' is not assignable to type 'number'.
src/ng.js(10,15): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
src/ng.js(13,27): error TS2322: Type 'number' is not assignable to type 'boolean'.
src/ng.js(16,7): error TS2322: Type 'number | undefined' is not assignable to type 'string | undefined'.
  Type 'number' is not assignable to type 'string'.
src/ng.js(18,21): error TS2741: Property 'done' is missing in type '{ todo: string; doing: string; }' but required in type 'Record<Status, string>'.
src/ng.js(23,8): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'boolean' is not assignable to parameter of type 'number'.
src/ng.js(26,5): error TS2540: Cannot assign to 'value' because it is a read-only property.
src/ng.js(27,5): error TS2341: Property 'secret' is private and only accessible within class 'Box<T>'.
src/ng.js(28,5): error TS2445: Property 'count' is protected and only accessible within class 'Box<T>' and its subclasses.
src/ng.js(32,7): error TS2420: Class 'Report' incorrectly implements interface 'Printable'.
  Property 'print' is missing in type 'Report' but required in type 'Printable'.
src/ng.js(34,21): error TS8026: Expected Box<T> type arguments; provide these with an '@extends' tag.
src/ng.js(36,3): error TS4123: This member cannot have a JSDoc comment with an 'override' tag because it is not declared in the base class 'Box<any>'. Did you mean 'describe'?
src/ng.js(45,20): error TS2551: Property 'tagNme' does not exist on type 'HTMLElement'. Did you mean 'tagName'?
src/ng.js(49,20): error TS8024: JSDoc '@param' tag has name 'nmae', but there is no parameter with that name.
src/ng.js(52,14): error TS7006: Parameter 'name' implicitly has an 'any' type.
src/ng.js(57,7): error TS2322: Type '"finished"' is not assignable to type 'Status'.

npx tsc -p jsconfig.json --locale ja を付けると日本語で表示されます。たとえば5行目と18行目は次のとおりです。

src/ng.js(5,5): error TS2322: 型 'number' を型 'string' に割り当てることはできません。
src/ng.js(18,21): error TS2741: プロパティ 'done' は型 '{ todo: string; doing: string; }' にありませんが、型 'Record<Status, string>' では必須です。

TS8024 は JSDoc ならではのエラーです。コメントの @param の名前が実際の引数名と合っていないと、その引数は型なしの扱いになり、続けて TS7006 も出ます。引数名を変えたときはコメントも一緒に直します。

TypeScript 7.0で扱いが変わったタグ：@enumと@constructor

@enum と @constructor は、TypeScript 5.9.3 と 7.0.2 で結果が変わりました。同じファイルを両方の版にかけます。

// src/legacy.js
// @ts-check
/** @enum {number} */
const Priority = { LOW: 1, MIDDLE: "2", HIGH: 3 };

/** @param {Priority} p */
function setPriority(p) {}
setPriority("HIGH");

/**
 * @constructor
 * @param {string} name
 */
function Person(name) {
  this.name = name;
}
const person = new Person("佐藤");
person.nmae;

TypeScript 5.9.3 の結果：

src/legacy.js(3,28): error TS2322: Type 'string' is not assignable to type 'number'.
src/legacy.js(7,13): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
src/legacy.js(17,8): error TS2339: Property 'nmae' does not exist on type 'Person'.

TypeScript 7.0.2 の結果：

src/legacy.js(5,13): error TS2749: 'Priority' refers to a value, but is being used as a type here. Did you mean 'typeof Priority'?
src/legacy.js(14,3): error TS2683: 'this' implicitly has type 'any' because it does not have a type annotation.
src/legacy.js(16,16): error TS7009: 'new' expression, whose target lacks a construct signature, implicitly has an 'any' type.

公式ブログの TypeScript 7.0 の告知にも、JavaScript ファイルの解析を TypeScript ファイルと同じ考え方にそろえた結果として、@enum は認識されなくなり @typedef を使うこと、@class を付けた関数はコンストラクタとして扱われなくなり class 宣言を使うことが書かれています。7.0.2 での置き換え方は次のとおりです。

// src/enum7.js
// @ts-check
const Priority = /** @type {const} */ ({ LOW: 1, MIDDLE: 2, HIGH: 3 });
/** @typedef {typeof Priority[keyof typeof Priority]} PriorityValue */

/** @param {PriorityValue} p */
function setPriority(p) {
  console.log("priority:", p);
}
setPriority(Priority.HIGH);
setPriority(4);

class Person {
  /** @param {string} name */
  constructor(name) {
    this.name = name;
  }
}
new Person("佐藤").nmae;

$ npx tsc --checkJs --noEmit --strict --target es2022 --module nodenext src/enum7.js
src/enum7.js(10,13): error TS2345: Argument of type '4' is not assignable to parameter of type 'PriorityValue'.
src/enum7.js(18,18): error TS2339: Property 'nmae' does not exist on type 'Person'.

/** @type {const} */ (...) は TypeScript の as const にあたり、PriorityValue は 1 | 2 | 3 になります。5.9.3 の @enum {number} では number なら何でも通りましたが、この書き方は 定義した値だけを受け付けるので、setPriority(4) も知らせてくれます。

版による違い：@satisfies・@overload・@import

同じファイルを、以前の版の tsc にもかけて比べました。

// src/old.js
// @ts-check
const labels = /** @satisfies {Record<"todo" | "done", string>} */ ({
  todo: "未着手",
});

/**
 * @overload
 * @param {string} value
 * @returns {string}
 */
/**
 * @overload
 * @param {number} value
 * @returns {number}
 */
/**
 * @param {string | number} value
 * @returns {string | number}
 */
function double(value) {
  return typeof value === "string" ? value + value : value * 2;
}
/** @type {number} */
const n = double("ab");

4.9.5 では @overload が読まれず、実装の型（string | number）がそのまま戻り値になっています。5.9.3 と 7.0.2 では「文字列を渡したら文字列が返る」ことまで伝わっています。7.0.2 の出力全文です。

src/old.js(2,21): error TS2741: Property 'done' is missing in type '{ todo: string; }' but required in type 'Record<"done" | "todo", string>'.
src/old.js(24,7): error TS2322: Type 'string' is not assignable to type 'number'.

@import は、次のファイルで比べました。

// src/imp.js
// @ts-check
/** @import { Item } from "./types.js" */

/** @type {Item} */
const item = { name: "ノート", price: 300 };
console.log(item.name);

5.4 以前の TypeScript を使っている場合は、/** @typedef {import("./types.js").Item} Item */ と書けば同じことができます。

ts-check・checkJs・jsconfig.jsonの違い

最初の plain.js（// @ts-check なし）と、先頭に // @ts-check を足した checked.js、// @ts-nocheck を足した nocheck.js を、オプションを変えてチェックしました。

何も付けない場合のメッセージは次のとおりです（1件分）。

error TS6504: File 'plain.js' is a JavaScript file. Did you mean to enable the 'allowJs' option?
  The file is in the program because:
    Root file specified for compilation

1ファイルずつ始めるなら // @ts-check、全体に広げるなら checkJs ＋ 例外に // @ts-nocheck という使い分けができます。型を書く量を抑えて始めたいときは、strict を外すと「書いた型と食い違っている箇所」だけに絞れます。

jsconfig.jsonはtscでは-pで指定する

jsconfig.json は JavaScript プロジェクト用の設定ファイルで、中身の書き方は tsconfig.json と同じです。tsc を引数なしで実行したときに自動で読まれるのは tsconfig.json のほうで、jsconfig.json だけを置いたフォルダで npx tsc を実行すると、チェックは行われずヘルプが表示されました。-p で指定するとチェックされます。

$ npx tsc -p jsconfig.json
plain.js(2,5): error TS2322: Type 'string' is not assignable to type 'number'.
plain.js(4,14): error TS7006: Parameter 'a' implicitly has an 'any' type.
plain.js(4,17): error TS7006: Parameter 'b' implicitly has an 'any' type.

package.json の scripts に "typecheck": "tsc -p jsconfig.json" と書いておくと、npm run typecheck で呼べます。

1行だけ除外する：@ts-expect-errorと@ts-ignore

// sup.js
// @ts-check
/** @type {number} */
let a = 1;

// @ts-expect-error 文字列を入れるテスト
a = "x";

// @ts-ignore
a = "y";

// @ts-expect-error
a = 2;

$ npx tsc --allowJs --noEmit sup.js
sup.js(11,1): error TS2578: Unused '@ts-expect-error' directive.

@ts-expect-error は、コードが直ってエラーが無くなると「もう要りません」と教えてくれるので、除外のコメントが残り続けません。

.jsから.d.tsを生成する

JSDoc を書いた .js からは、型定義ファイル（.d.ts）を tsc で作れます。ライブラリとして配るときに、利用する側の TypeScript が型を読めるようになります。

// src/lib.js
/** @import { Item } from "./types.js" */

/**
 * @param {Item[]} list
 * @param {number} [taxRate=0.1]
 * @returns {number}
 */
export function total(list, taxRate = 0.1) {
  const sum = list.reduce((acc, i) => acc + i.price * (i.qty ?? 1), 0);
  return Math.round(sum * (1 + taxRate));
}

/**
 * @template T
 * @param {T[]} list
 * @returns {T | undefined}
 */
export function first(list) {
  return list[0];
}

/**
 * @overload
 * @param {string} value
 * @returns {string}
 */
/**
 * @overload
 * @param {number} value
 * @returns {number}
 */
/**
 * @param {string | number} value
 * @returns {string | number}
 */
export function double(value) {
  return typeof value === "string" ? value + value : value * 2;
}

export const Priority = /** @type {const} */ ({ LOW: 1, MIDDLE: 2, HIGH: 3 });
/** @typedef {typeof Priority[keyof typeof Priority]} PriorityValue */

/**
 * @template T
 */
export class Box {
  /** @param {T} value */
  constructor(value) {
    /** @readonly */
    this.value = value;
    /** @private */
    this.secret = "s";
    /** @protected */
    this.count = 0;
  }
  /** @returns {string} */
  describe() {
    return `Box(${this.value})`;
  }
}

/** @extends {Box<number>} */
export class NumberBox extends Box {
  /** @override */
  describe() {
    return `NumberBox(${this.value.toFixed(1)})`;
  }
}

/** @deprecated total を使ってください */
export function sum(/** @type {number[]} */ nums) {
  return nums.reduce((a, b) => a + b, 0);
}

npx tsc src/lib.js src/types.js --allowJs --declaration --emitDeclarationOnly --outDir dts --target es2022 --module nodenext

出力された dts/lib.d.ts：

/** @import { Item } from "./types.js" */
import type { Item } from "./types.js";
/**
 * @param {Item[]} list
 * @param {number} [taxRate=0.1]
 * @returns {number}
 */
export declare function total(list: Item[], taxRate?: number): number;
/**
 * @template T
 * @param {T[]} list
 * @returns {T | undefined}
 */
export declare function first<T>(list: T[]): T | undefined;
export declare function double(value: string): string;
export declare function double(value: number): number;
export declare const Priority: {
    readonly LOW: 1;
    readonly MIDDLE: 2;
    readonly HIGH: 3;
};
export type PriorityValue = typeof Priority[keyof typeof Priority];
/** @typedef {typeof Priority[keyof typeof Priority]} PriorityValue */
/**
 * @template T
 */
export declare class Box<T> {
    /** @readonly */
    value: T;
    /** @private */
    secret;
    /** @protected */
    count: number;
    /** @param {T} value */
    constructor(value: T);
    /** @returns {string} */
    describe(): string;
}
/** @extends {Box<number>} */
export declare class NumberBox extends Box<number> {
    /** @override */
    describe(): string;
}
/** @deprecated total を使ってください */
export declare function sum(/** @type {number[]} */ nums: number[]): number;

出力された dts/types.d.ts：

/**
 * @typedef {object} Item
 * @property {string} name 品名
 * @property {number} price 単価
 * @property {number} [qty] 数量（省略可）
 */
export type Item = {
    /**
     * 品名
     */
    name: string;
    /**
     * 単価
     */
    price: number;
    /**
     * 数量（省略可）
     */
    qty?: number;
};
export type Status = "todo" | "doing" | "done";
export type PriceFilter = (item: Item) => boolean;
/** @typedef {"todo" | "doing" | "done"} Status */
/**
 * @callback PriceFilter
 * @param {Item} item
 * @returns {boolean}
 */
export {};

• @import は import type に、@template T は型引数つきの宣言（first や Box の直後に T が付いた形）に変わっている
• @overload の2つのコメントは、2行の export declare function double になっている
• [taxRate=0.1] は taxRate?: number、@property {number} [qty] は qty?: number になっている
• @typedef と @callback は export type になり、@property の説明文もコメントとして残っている

JSDocと.tsのどちらを選ぶか

JSDoc で書いた型は .d.ts にもそのまま変換できるので、あとから .ts へ移す場合も、書いた型の情報はそのまま活かせます。

よくある質問

Q. JSDoc の型チェックに TypeScript のインストールは必要ですか？ A. コマンドでチェックするには npm i -D typescript で tsc を入れます。.js ファイル自体は変換せずにそのまま動くので、実行時に TypeScript は要りません。

Q. // @ts-check と checkJs はどちらを使えばよいですか？ A. 1ファイルずつ試すなら // @ts-check、フォルダ全体をチェックするなら設定ファイルに "checkJs": true を書きます。両方を同時に使っても問題ありません。

Q. @enum を書いたら TS2749 になりました。 A. TypeScript 7.0.2 では @enum が型名として扱われません。/** @type {const} */ ({...}) で定数を作り、@typedef {typeof X[keyof typeof X]} で型を作る形に置き換えると、定義した値だけを受け付ける型になります。

Q. 型を別ファイルにまとめるにはどうしますか？ A. @typedef と @callback を1つの .js にまとめ、最後に export {}; を書きます。使う側は /** @import { Item } from "./types.js" */ で読み込みます（TypeScript 5.5 以降）。

まとめ

• JSDoc で型を書いた .js は tsc --checkJs --noEmit でそのまま型チェックできる
• 基本は @type・@param・@returns・@typedef の4つ。関数の型は @callback、ジェネリクスは @template
• @satisfies と @overload は 5.0 以降、@import は 5.5 以降。以前の版では検査されないかエラーになる
• @enum と @constructor は 7.0.2 で扱いが変わった。@typedef と class に置き換える
• 1ファイルなら // @ts-check、全体なら checkJs。jsconfig.json は tsc -p jsconfig.json で指定する
• コメントの引数名が実際と違うと TS8024。引数名を変えたらコメントも直す
• tsc --allowJs --declaration --emitDeclarationOnly で .js から .d.ts を作れる

参考・出典

• TypeScript 公式ハンドブック「JSDoc Reference」 https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
• TypeScript 公式ハンドブック「JS Projects Utilizing TypeScript」 https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html
• TypeScript 5.0 リリースノート（@satisfies / @overload Support in JSDoc） https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html
• TypeScript 5.5 リリースノート（The JSDoc @import Tag） https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html
• Announcing TypeScript 7.0（TypeScript 公式ブログ） https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。