もうTypeScriptの補助輪を外そう 明日は//@ts-checkを使う

※近所（同じ港区内）のあのIT企業さんからお声をかけていただきました。登壇予定です。
※某商業誌さんから執筆依頼がありましたが、有料ですと気が引けるのでお断りしました。

---

Vimで書いている人はもういないから、そろそろTypeScript（自転車の補助輪）を外していこうという話。

Visual Studio Code は下のリンクからインストールできる。これが前提。
https://azure.microsoft.com/ja-jp/products/visual-studio-code/
VS Code で // @ts-check が利用できる。
　
※Denoの話を知らない人は、これを読むと良い。
DenoがTypeScriptの使用をやめる5つの理由
https://startfunction.com/deno-will-stop-using-typescript/
（Denoは、Node.jsの作者であるライアン・ダールによって作成され、V8 JavaScriptエンジン及びRustプログラミング言語に基づいた、JavaScript及びTypeScriptのランタイム環境である。セキュリティと生産性に焦点を当てている）
　
※TypeScriptのESMについては、これを読むと良い。
TypeScript 4.5 以降で ESM 対応はどうなるのか？
https://zenn.dev/teppeis/articles/2021-10-typescript-45-esm
（とてもタイムリーな話題だ）
　
これらは氷山の一角に過ぎない。
あなたのリーダーにこの話をしたとき、言葉を濁されたり、笑い飛ばされるようだったら、あなたのプロジェクトは破滅への道を進んでいるのかもしれない。
SNSでの注意点だが、情報商材屋が組織を作っているので、気をつけてほしい（エンジニア採用で問題となっている）。
　
銀の弾丸と呼ばれた補助輪に暗雲が立ち込めている。今後、脱TypeScriptの加速は避けられないが、段階を踏んで安全に進むべきである。

TypeScriptを活用したJSプロジェクト

明日からはJavaScriptファイルにおける //@ts-check を使用してほしい。

JSDocを使ってJSで型ヒントを提供する

.jsファイルでは、多くの場合型を推測することが可能。型が推測できない場合、JSDoc構文を使って指定することができる。

宣言の前でJSDocのアノテーションを使い、その宣言の型を設定する。

例えば

/** @type {number} */
var x;
 
x = 0; // OK
x = false; // OK?!

前述のコードサンプルの最後の行はTypeScriptではエラーとなりるが、JSプロジェクトのデフォルトではエラーを発生しない。
JavaScriptファイルでエラーを有効化するには、.jsファイルの最初の行に //@ts-check を追加して、TypeScriptにエラーを発生させるようにする。

// @ts-check
/** @type {number} */
var x;
 
x = 0; // OK
x = false; // エラー
Type 'boolean' is not assignable to type 'number'.

エラーを追加したいJavaScriptファイルがたくさんある場合は、jsconfig.jsonを使用するように変更する。 ファイルに //@ts-nocheck コメントをつけることで、ファイルのチェックを省略することができる。

納得できないようなエラーは前の行に //@ts-ignore または //@ts-expect-error を追加すれば良い。

// @ts-check
/** @type {number} */
var x;
 
x = 0; // OK
// @ts-expect-error
x = false; // エラー

JSDocリファレンス

以下のリストは、JavaScriptファイルの型情報を提供する JSDocアノテーションにおいて、現在サポートされている構文の概要。以下に明示的にリストに入っていないタグ(@asyncなど)はまだサポートされていないことに注意。

• @type
• @param (or @arg or @argument)
• @returns (or @return)
• @typedef
• @callback
• @template
• @class (or @constructor)
• @this
• @extends (or @augments)
• @enum

class拡張
プロパティ修飾子 @public、@private、@protected、@readonly
タグの意味は通常、jsdoc.appで与えられたものと同じか、あるいはそのスーパーセットになる。

@type

“@type”タグを使用すれば、型名(プリミティブ、TypeScript宣言やJSDocの”@typedef”タグで定義されたもの)を参照することができる。ほとんどのJSDoc型と、stringのような最も基本的なものからConditional Typesのような高度なものまで、あらゆるTypeScriptの型を使うことができる。

/**
 * @type {string}
 */
var s;
 
/** @type {Window} */
var win;
 
/** @type {PromiseLike<string>} */
var promisedString;
 
// DOMプロパティを使ってHTML要素を指定することができる。
/** @type {HTMLElement} */
var myElement = document.querySelector(selector);
element.dataset.myData = "";

@param @returns

@paramは@typeと同じ型の構文を使用するが、パラメータ名を追加する。また、パラメータ名を角括弧で囲むことで、パラメータを任意のものとして宣言することもできる。

// パラメータは様々な構文形式で宣言することができる
/**
 * @param {string}  p1 - 文字列パラメータ
 * @param {string=} p2 - 任意のパラメータ(Closure構文)
 * @param {string} [p3] - 任意のパラメータ(JSDoc構文).
 * @param {string} [p4="test"] - デフォルト値を持つ任意のパラメータ
 * @return {string} 結果
 */
function stringsStringStrings(p1, p2, p3, p4) {
  // TODO
}

@typedef @callback @param

複雑な型を定義するために@typedefを使うことができる。@paramを使った同様の構文でも動作する。

/**
 * @typedef {Object} SpecialType - 'SpecialType'という名前の新しい型を作成
 * @property {string} prop1 - SpecialTypeの文字列プロパティ
 * @property {number} prop2 - SpecialTypeの数値プロパティ
 * @property {number=} prop3 - SpecialTypeの任意の数値プロパティ
 * @prop {number} [prop4] - SpecialTypeの任意の数値プロパティ
 * @prop {number} [prop5=42] - SpecialTypeのデフォルト値を持つ任意の数値プロパティ
 */
 
/** @type {SpecialType} */
var specialTypeObject;
specialTypeObject.prop3;

@template

ジェネリクス関数は@templateタグを使って宣言することができる。

/**
 * @template T
 * @param {T} x - 戻り値に流用するジェネリクスパラメータ
 * @return {T}
 */
function id(x) {
  return x;
}
 
const a = id("string");
const b = id(123);
const c = id({});

@constructor

コンパイラはthisプロパティの代入に基づいてコンストラクタ関数を推測するが、@constructorタグを追加すればより厳密なチェックとより良い提案を受けることができる。

/**
 * @constructor
 * @param {number} data
 */
function C(data) {
  // プロパティの型は推測される
  this.name = "foo";
 
  // あるいは、明示的に設定することもできる
  /** @type {string | null} */
  this.title = null;
 
  // また、他のところで設定されている場合は、単に型注釈をつけることもできる
  /** @type {number} */
  this.size;
 
  this.initialize(data);
Argument of type 'number' is not assignable to parameter of type 'string'.
}
/**
 * @param {string} s
 */
C.prototype.initialize = function (s) {
  this.size = s.length;
};
 
var c = new C(0);
c.size;
 
var result = C(1);
Value of type 'typeof C' is not callable. Did you mean to include 'new'?

@this

コンパイラは通常、thisが用いられるコンテクストからthisの型を推測することができる。推測できない場合、@thisを使って明示的にthisの型を指定することができる。

/**
 * @this {HTMLElement}
 * @param {*} e
 */
function callbackForLater(e) {
  this.clientHeight = parseInt(e);
}

@extends

JavaScriptクラスがジェネリクスの基底クラスを拡張するとき、型パラメータが何であるべきかを指定するところはない。@extendsタグはそのような型パラメータを指定する方法を提供している。

/**
 * @template T
 * @extends {Set<T>}
 */
class SortableSet extends Set {
  // ...
}

@enum

@enumタグを使うと、すべてのメンバが指定された型であるオブジェクトリテラルを作成することができる。JavaScriptのたいていのオブジェクトリテラルとは異なり、明示されていないメンバは使用できない。

/** @enum {number} */
const JSDocState = {
  BeginningOfLine: 0,
  SawAsterisk: 1,
  SavingComments: 2,
};
 
JSDocState.SawAsterisk;

サポートされていないタグ

TypeScriptはサポートされていないJSDocタグを無視する。以下のタグは、サポート目標。

@const
@inheritdoc
@memberof
@yields
{@link …}

---

さあ、補助輪を外そう。

※せっかくコメントをいただいたのに、Zennの運営が勝手に削除したようです。とても残念です。