TypeScript 型システム実践：基礎から高度なユーティリティ型まで

なぜツールサイトに TypeScript が必要か？

ToolsKu には 200 以上のツールページ、4 言語の i18n、複雑なツールクライアント設定があります。純粋な JavaScript では以下の場面でエラーが起きやすくなります：

• ツール設定オブジェクトのフィールド名の typo
• 存在しない i18n key がエラーにならない
• API レスポンス構造が期待と一致しない
• リファクタリング時に参照の更新漏れ

TypeScript はこれらのエラーをコンパイル時に検出し、実行時ではありません。

---

基本的な型テクニック

1. 型推論 vs 明示的な注釈

// ✅ TS に推論させる（簡潔）
const tools = [{ href: '/pdf/merge', name: 'PDF合并' }] as const;

// ✅ 制約が必要な場合は明示的に注釈
function getTool(href: string): ToolItem | undefined {
  return ALL_TOOLS.find(t => t.href === href);
}

2. ジェネリック制約

function encode<T extends string | ArrayBuffer>(
  input: T
): T extends string ? string : ArrayBuffer {
  // 入力型に応じて異なる結果を返す
}

3. ユニオン型と型ガード

type ProcessResult =
  | { status: 'success'; data: Blob }
  | { status: 'error'; message: string };

function handleResult(result: ProcessResult) {
  if (result.status === 'success') {
    downloadBlob(result.data); // TS は data の存在を認識
  }
}

---

高度なユーティリティ型

Partial、Required、Pick、Omit

type ToolConfig = {
  href: string;
  name: string;
  blurb: string;
  i18nKey?: string;
};

type ToolUpdate = Partial<ToolConfig>;        // すべてのフィールドがオプション
type ToolRequired = Required<ToolConfig>;      // すべてのフィールドが必須
type ToolPreview = Pick<ToolConfig, 'name' | 'blurb'>; // 一部のみ取得

条件型

type IsString<T> = T extends string ? true : false;
type A = IsString<'hello'>;  // true
type B = IsString<42>;       // false

マップ型

type Readonly<T> = { readonly [K in keyof T]: T[K] };
type Nullable<T> = { [K in keyof T]: T[K] | null };

---

JSON → TypeScript 生成

ToolsKu の JSON から TypeScript ツールの実装ロジック：

function jsonToTypeScript(json: unknown, name = 'Root'): string {
  if (Array.isArray(json)) {
    return `${name}[]`;
  }
  if (typeof json === 'object' && json !== null) {
    const fields = Object.entries(json).map(([key, value]) => {
      const type = jsonToTypeScript(value, capitalize(key));
      return `  ${key}: ${type};`;
    });
    return `interface ${name} {\n${fields.join('\n')}\n}`;
  }
  return typeof json; // string | number | boolean
}

API レスポンス JSON を入力するだけで TypeScript interface をワンクリック生成——手動での型定義の手間を削減します。

---

実用的なパターン

satisfies 演算子（TS 4.9+）

const config = {
  locales: ['zh-CN', 'en'],
  defaultLocale: 'zh-CN',
} satisfies RoutingConfig; // リテラル型を保持しつつ構造を検証

const 型パラメータ（TS 5.0+）

function createTool<const T extends string>(href: T) {
  return { href } as const;
}
const tool = createTool('/pdf/merge'); // href の型は string ではなく '/pdf/merge'

---

まとめ

TypeScript の型システムは単なる「型注釈の追加」ではなく、コンパイル時プログラミング言語です。ジェネリック、条件型、ユーティリティ型をマスターすることで、自己文書化されリファクタリングに安全なコードベースを構築できます。ToolsKu の JSON から TypeScript ツールは、型駆動開発の実用的な出発点です。