typescript-advanced-types

TypeScript で、型そのものに仕事をさせたいときに効きます。ライブラリの公開する型、API の呼び出し口、設定オブジェクトなど、間違った使い方を型の段階で止めたい場面です。

中心に据える型の道具

5 つ

例に出る組み込みの型

9 個

同梱の文書にある応用の型

6 つ

同梱ファイル（2026-10-22 時点）

1 件

本文が挙げる場面

SKILL.md は使う場面を 8 つ挙げています。主なものは次のとおりです。

• 型の安全なライブラリや枠組みを作る
• 使い回すジェネリクスの部品を作る
• 型の安全な API の呼び出し口を設計する
• 型のきつい設定オブジェクトや状態管理を作る
• JavaScript のコードを TypeScript に移す

中心の 5 つ

• ジェネリクス型を引数に取る。extends で制約を付け、複数の型引数も扱う
• 条件型T extends U ? X : Y。infer で戻り値の型を取り出す。合併型には分配して効く
• マップ型既存の型のキーを回して変える。as でキーの名前を変え、条件でキーを絞る
• テンプレートリテラル型文字列の型を組み立てる。"server.port" のような経路の型も作れる
• 組み込みの型の道具Partial、Pick、Omit、Record など 9 個を例つきで

それぞれ、短いコードと「この型はこうなる」という注釈がセットになっています。組み込みの型の例は Partial・Required・Readonly・Pick・Omit・Exclude・Extract・NonNullable・Record の 9 個です。

文字列の型を変える 4 つ

テンプレートリテラル型の節には、文字列の型を変える組み込みの 4 つ（Uppercase・Lowercase・Capitalize・Uncapitalize）の例もあります。"click" | "focus" | "blur" から "onClick" | "onFocus" | "onBlur" を作る例や、マップ型と組み合わせて name から getName という取り出し役の名前を作る例が載っています。イベント名や設定のキーを、手で書き並べずに型から作りたいときに使えます。

同梱の文書に応用の型

references/details.md に、応用の型が 6 つと、型の推論の技法が 3 つあります。本文の要約で足りないときに読め、と SKILL.md に書かれています。

• 型の安全なイベントイベント名ごとに渡す値の型が決まる発行の仕組み
• 型の安全な API の呼び出し口経路と HTTP の方法から、引数と戻り値の型が決まる
• 型の安全な組み立て役必須の項目が全部そろうまで build() を呼べない
• 深い読み取り専用・深い省略可入れ子の奥まで readonly や省略可にする
• 型の安全なフォームの検証項目ごとの規則と、誤りの一覧の型
• 判別できる合併型status の値で型を絞り、状態の移り変わりを書く

推論の技法は、infer での取り出し、型ガード（value is string）、表明の関数（asserts value is string）の 3 つです。

型のテスト

型が思ったとおりかを確かめる書き方が載っています。2 つの型が等しいかを true か false で返す AssertEqual と、誤りになるべき型を確かめる ExpectError です。最善の手の 10 番目にも「型をテストせよ」とあります。

型を足すだけで済む普通のコード

本文のよくある失敗に「型を複雑にしすぎるとコンパイルが遅くなる」があり、性能の節は「できるだけ単純な型を使え」と書いています。画面の部品に引数の型を付ける程度なら、このスキルの道具は大きすぎます。

実行時の入力の検証

このスキルが扱うのは、コンパイルの時点で間違いを止める型です。外から来た JSON が本当にその形かは、型だけでは確かめられません。同梱の文書にフォームの検証の例はありますが、規則は自分で書く形です。実行時の型ガードや表明の関数を使う場面も、同梱の文書に例があります。

型の設計の前に、モジュールの切り方を決めたいとき

どこからどこへ import してよいかの決まりを入れたいなら setup-ts-deep-modules の担当です。テストを先に書く進め方なら tdd が向きます。

解析で見つかった記述

SKILL.md に、外部との通信、シェルでの実行、ファイルの書き換えの手順はありません。中身はすべて TypeScript のコード例と説明です。同梱ファイルは references/details.md の 1 件です（2026-10-22 時点）。

組み込みと同じ名前の型を定義している

説明のために、ReturnType、Readonly、Partial、Parameters を自分で定義し直す例があります。同梱の文書の判別できる合併型の例は、Error という名前の型も定義しています。

最善の手と、よくある失敗

最善の手は 10 項目あります。主なものは次のとおりです。

• any より unknown を使う
• オブジェクトの形は interface、合併型や複雑な型は type
• 型の表明（as）は避け、型ガードを使う
• strict のすべての設定を有効にする

よくある失敗は 7 項目です。any の使いすぎ、null の厳しい検査を無視する、判別できる合併型を使わない、readonly の付け忘れ、型の循環参照などが挙がっています。

型を重くしない

性能の節には 5 つの目安があります。深く入れ子にした条件型を避ける、単純な型で済むならそうする、複雑な型の計算は一度まとめておく、再帰する型は深さを抑える、本番の組み立てでは型の検査を飛ばす道具を使う、です。

大きな集まりの一部

このスキルは wshobson/agents のプラグイン javascript-typescript に入っています。同じプラグインに、ほかのスキルが 3 件、エージェントの定義が 2 件（javascript-pro と typescript-pro）、命令が 1 件あります（2026-10-22 時点）。リポジトリの README は、Claude Code と Codex の両方での導入の手順を載せています。

型のテストはどう書きますか

本文の AssertEqual は、2 つの型が互いに当てはまるかを調べて true か false を返す型です。これに確かめたい型を渡し、結果の型を見ます。誤りになるべき組み合わせは ExpectError に渡し、コンパイルで止まることを確かめます。

interface と type はどちらを使えばいいですか

本文の最善の手では、オブジェクトの形は interface（誤りの表示が分かりやすい）、合併型や複雑な型は type（より柔軟）と分けています。どちらかに統一せよ、という書き方ではありません。

型が複雑すぎてエディタが重くなりました

よくある失敗に「複雑すぎる型はコンパイルを遅くする」が挙がっています。性能の節は、深い入れ子の条件型を避ける、再帰の深さを抑える、単純な型で済むならそうする、と書いています。

応用の型の例はどこにありますか

同梱の references/details.md です。イベントの発行、API の呼び出し口、組み立て役、深い読み取り専用、フォームの検証、判別できる合併型の 6 つと、推論の技法 3 つが載っています。