なぜ TypeScript ではなく JSDoc なのですか。

ファイルが JavaScript のままだからです。`checkJs` を有効にすれば、TypeScript のコンパイラがこの typedef を読み、編集画面で同じ誤りを教えてくれます。ビルドも `.ts` の拡張子も変換器も要りません。Node の小さなスクリプトや、そのまま配るライブラリなら、型の利点だけを取り、費用を払わずに済みます。

ハイフンを含む鍵が引用符付きで出ました。これは妥当ですか。

厳密には妥当ではなく、この出力の正直な限界です。`@property {string} "content-type"` は鍵を読める形に保ちますが、識別子でないプロパティ名を書く構文は JSDoc にありません。引用符はどの仕様にも基づいていません。そうした鍵は元で改名するか、typedef の隣に文章で書き添えるのが確実です。

生成された typedef はどう使いますか。

名前で参照します。変数には `/** @type {Root} */`、関数には `@param {Root} payload` です。別のファイルにある場合は `/** @typedef {import("./types.js").Root} Root */` で取り込んでください。編集画面は同じように解決します。

JSONをJSDocに変換｜素のJSでも補完が効くようにする

JSONのサンプルをJSDocのtypedefに変換します。オブジェクトごとに名前付きの @typedef ができ、素のJavaScriptのままエディタの補完が効くようになります。

高速プライベート Cookieゼロ

ルート名

JSON 入力

JSDoc 出力

このツールの動作

JSON の標本が JSDoc の typedef になります。オブジェクト一つにつき一区画です。

{ "id": 1, "name": "Ada", "address": { "city": "Paris" } }

/**
 * @typedef {Object} Root
 * @property {number} id
 * @property {string} name
 * @property {Address} address
 */

/**
 * @typedef {Object} Address
 * @property {string} city
 */

.js ファイルの先頭に置けば、そのファイル内の @type {Root} はすべて検査されます。編集画面が検査し、走らせるなら tsc --checkJs も検査します。

根の一覧にも名前がつく

/**
 * @typedef {Array<UsersItem>} Users
 */

この区画は以前ありませんでした。配列の標本からは要素の typedef だけが出て、設定した根の名前はどこにも現れませんでした。本物の欠陥で、この文章を書く過程で見つけ、直しました。

配列は …[] ではなく常に Array<…> と書きます。どちらも妥当ですが、要素の型が合併や * のとき、長い形のほうが読めます。

識別子でない鍵

{ "content-type": "text/html" }

 * @property {string} "content-type"

引用符は鍵を読める形に保ちますが、標準の JSDoc ではありません。妥当な識別子でないプロパティ名を書く構文が存在しないからです。黙らずに述べておきます。出力は何も警告せず、編集画面はその行をただ無視するかもしれません。この種の鍵は、元で改名するのが最善です。

標本が決められないこと

どのプロパティも「ある」ものとして書かれます。文書が見せたのがそれだからです。JSDoc では省略可能を @property {string} [name]、null を許すものを {?string} と書きます。どちらも API を知ってから行う手入れであり、荷ひとつに含まれる事実ではありません。

分からない値は * になります。JSDoc の「任意の型」です。標本が黙っているところに現れます。空の配列は Array<*> になります。

プライバシー

すべての処理はブラウザ内のJavaScriptだけで完結します。データがアップロードされることはないため、機密情報でも安心して利用でき、オフラインでも動作します。

よくある質問

なぜ TypeScript ではなく JSDoc なのですか。: ファイルが JavaScript のままだからです。`checkJs` を有効にすれば、TypeScript のコンパイラがこの typedef を読み、編集画面で同じ誤りを教えてくれます。ビルドも `.ts` の拡張子も変換器も要りません。Node の小さなスクリプトや、そのまま配るライブラリなら、型の利点だけを取り、費用を払わずに済みます。
ハイフンを含む鍵が引用符付きで出ました。これは妥当ですか。: 厳密には妥当ではなく、この出力の正直な限界です。`@property {string} "content-type"` は鍵を読める形に保ちますが、識別子でないプロパティ名を書く構文は JSDoc にありません。引用符はどの仕様にも基づいていません。そうした鍵は元で改名するか、typedef の隣に文章で書き添えるのが確実です。
生成された typedef はどう使いますか。: 名前で参照します。変数には `/** @type {Root} */`、関数には `@param {Root} payload` です。別のファイルにある場合は `/** @typedef {import("./types.js").Root} Root */` で取り込んでください。編集画面は同じように解決します。