TypeScript ベストプラクティス

{
  "compilerOptions": {
    // --- 型チェックの厳格化 ---
    "strict": true,                          // strictNullChecks, noImplicitAny などを一括有効化
    "noUncheckedIndexedAccess": true,        // arr[i] / obj[key] を T | undefined として扱う
    "exactOptionalPropertyTypes": true,      // `prop?: T` に undefined を明示代入するのを禁止
    "noImplicitOverride": true,              // オーバーライド時に override キーワードを必須化
    "noImplicitReturns": true,               // すべてのコードパスで return を要求
    "noFallthroughCasesInSwitch": true,      // switch の fallthrough を禁止
    "noPropertyAccessFromIndexSignature": true,
 
    // --- モジュール ---
    "module": "NodeNext",                    // バンドラ利用時は "ESNext" + "moduleResolution": "Bundler"
    "moduleResolution": "NodeNext",
    "verbatimModuleSyntax": true,            // import type を強制し、出力を予測可能に
    "isolatedModules": true,                 // esbuild / swc などの単一ファイル変換と互換に
    "esModuleInterop": true,
    "resolveJsonModule": true,
 
    // --- 出力 ---
    "target": "ES2022",
    "sourceMap": true,
    "declaration": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

// ❌ 冗長
const count: number = 0;
const names: string[] = ["a", "b"];
 
// ✅ 推論に任せる
const count = 0;
const names = ["a", "b"];

// ✅ 公開関数の戻り値は明示する
export function parseUser(input: string): User {
  // ...
}

type Route = { path: string; auth: boolean };
 
// ❌ 型注釈だとキーの情報が失われる
const routes: Record<string, Route> = {
  home: { path: "/", auth: false },
};
routes.typo; // エラーにならない
 
// ✅ satisfies なら型チェックしつつ具体的な型を保持
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;
routes.typo; // ❌ コンパイルエラー

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

// ❌ any は型安全性を破壊し、伝播する
function handle(data: any) {
  data.foo.bar(); // 実行時エラーの可能性
}
 
// ✅ unknown は使う前に絞り込みが必要
function handle(data: unknown) {
  if (typeof data === "object" && data !== null && "foo" in data) {
    // ...
  }
}

// ❌
const user = JSON.parse(text) as User;
 
// ✅ 検証してから使う（→ 14章参照）
const user = UserSchema.parse(JSON.parse(text));

// type が必要なケース
type Status = "idle" | "loading" | "success" | "error";
type Pair<T> = [T, T];
 
// interface が適するケース
interface User {
  id: string;
  name: string;
}
 
interface Admin extends User {
  permissions: string[];
}

// ❌ 不正な状態が表現できてしまう（loading なのに data がある等）
type State = {
  loading: boolean;
  data?: User;
  error?: Error;
};
 
// ✅ 不正な状態を型レベルで排除
type State =
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: Error };

function render(state: State): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.name;
    case "error":
      return state.error.message;
    default: {
      const _exhaustive: never = state; // ケース追加漏れでコンパイルエラー
      return _exhaustive;
    }
  }
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    typeof value.id === "string"
  );
}

// ❌ count が 0 のとき 10 になってしまう
const value = count || 10;
 
// ✅ null / undefined のときだけデフォルト値
const value = count ?? 10;
 
const city = user?.address?.city ?? "不明";

// ❌ 引数の順番を間違えやすい
function createUser(name: string, email: string, age: number, isAdmin: boolean) {}
 
// ✅ 名前付き引数のように使える
function createUser(params: {
  name: string;
  email: string;
  age: number;
  isAdmin?: boolean;
}) {}

// ❌ 呼び出し側で意味が分からない
fetchUsers(true);
 
// ✅
fetchUsers({ includeInactive: true });

// 引数は readonly で受けると、可変・不変どちらの配列も渡せる
function sum(values: readonly number[]): number {
  return values.reduce((a, b) => a + b, 0);
}

// ❌ 制約がなく、T について何も分からない
function getProp<T>(obj: T, key: string) {}
 
// ✅ キーの存在を型で保証
function getProp<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

// ❌ T が引数に1回しか出てこない
function log<T>(value: T): void {
  console.log(value);
}
 
// ✅
function log(value: unknown): void {
  console.log(value);
}

interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}
 
type CreateUserInput = Omit<User, "id" | "createdAt">;
type UpdateUserInput = Partial<CreateUserInput>;
type UserPreview = Pick<User, "id" | "name">;

interface Config {
  readonly apiUrl: string;
  readonly retries: number;
}
 
function process(items: readonly string[]) {
  items.push("x"); // ❌ コンパイルエラー
}
 
// 新しい配列を返すメソッドを優先
const sorted = items.toSorted();   // sort() は元配列を変更する
const reversed = items.toReversed();
const updated = items.with(0, "new");

// ❌ enum
enum Direction {
  Up,
  Down,
}
 
// ✅ ユニオン型（最もシンプル）
type Direction = "up" | "down";
 
// ✅ 値の一覧も必要なら as const オブジェクト
const Direction = {
  Up: "up",
  Down: "down",
} as const;
type Direction = (typeof Direction)[keyof typeof Direction]; // "up" | "down"

try {
  await save();
} catch (error) {
  if (error instanceof Error) {
    logger.error(error.message);
  } else {
    logger.error("Unknown error", { error });
  }
}

class NotFoundError extends Error {
  override readonly name = "NotFoundError";
  constructor(public readonly resource: string, options?: ErrorOptions) {
    super(`${resource} not found`, options);
  }
}
 
// cause でエラーの連鎖を保持
throw new NotFoundError("User", { cause: originalError });

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };
 
function parseAge(input: string): Result<number, string> {
  const n = Number(input);
  if (!Number.isInteger(n) || n < 0) {
    return { ok: false, error: "年齢は0以上の整数で入力してください" };
  }
  return { ok: true, value: n };
}

// ❌ 直列実行で遅い
const user = await fetchUser(id);
const posts = await fetchPosts(id);
 
// ✅ 並列実行
const [user, posts] = await Promise.all([fetchUser(id), fetchPosts(id)]);
 
// 一部の失敗を許容するなら allSettled
const results = await Promise.allSettled(tasks);

import { z } from "zod";
 
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().int().nonnegative().optional(),
});
 
type User = z.infer<typeof UserSchema>; // スキーマから型を導出
 
async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return UserSchema.parse(await res.json()); // 不正なら例外
}

import type { User } from "./types";
import { createUser, type CreateUserInput } from "./user";

class UserService {
  readonly #repo: UserRepository;
 
  constructor(repo: UserRepository) {
    this.#repo = repo;
  }
 
  async findById(id: string): Promise<User | undefined> {
    return this.#repo.find(id);
  }
}

// package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "test": "vitest run"
  }
}

// 意図的にエラーになることをテスト
// @ts-expect-error - 数値は受け付けない
createUser({ name: 123 });