Node.js + Express + TypeScript マニュアル（VS Code / 初心者向け）

1. Visual Studio Codeで新規プロジェクトを作成する方法

1-1. VS Codeでフォルダーを開く

1. 作業用フォルダーを作る（例：C:\work\my-api）。
2. VS Code → File → Open Folder... でそのフォルダーを開く。
3. VS Code のターミナルを開く：Terminal → New Terminal

1-2. npmでプロジェクト初期化（package.json作成）

package.json は「依存ライブラリ」「実行スクリプト」「プロジェクト名」などを保持する設定ファイルです。

npm init -y

1-3. 必要パッケージのインストール

ここでは「Express + TypeScript をコンパイルして実行する」ための最小構成を作ります。

npm i express
npm i -D typescript ts-node nodemon @types/node @types/express

1-4. TypeScript設定ファイル（tsconfig.json）作成

tsconfig.json は TypeScript コンパイラ（tsc）の設定ファイルです。

npx tsc --init

このマニュアルの推奨設定例（必要最低限 + 実用）

tsconfig.json

my-api/
├─ src/
├─ dist/
├─ package.json
├─ tsconfig.json   ← ここ
  

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "sourceMap": true
  },
  "include": ["src"]
}

1-5. エントリーファイルを作る

src フォルダーを作成し、src/index.ts を作ります。

import express, { Request, Response } from "express";

const app = express();
app.use(express.json()); // JSON のリクエストボディを読むため

app.get("/health", (req: Request, res: Response) => {
  res.json({ ok: true, time: new Date().toISOString() });
});

const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => {
  console.log(`[server] listening on http://localhost:${port}`);
});

PORT=8080 npm start

1-6. package.json にスクリプトを追加

npm scripts は「よく使うコマンド」を短い名前で登録する仕組みです。

{
  "name": "my-api",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "dev": "nodemon --watch src --ext ts --exec ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
  },
  "dependencies": {
    "express": "^4.19.0"
  },
  "devDependencies": {
    "@types/express": "^4.17.0",
    "@types/node": "^20.0.0",
    "nodemon": "^3.0.0",
    "ts-node": "^10.9.0",
    "typescript": "^5.0.0"
  }
}

2. 一般的なフォルダー構成

小〜中規模の API サーバーでよく見る、理解しやすい構成例です。

my-api/
  ├─ src/                # TypeScriptのソース
  │   ├─ index.ts        # エントリ（起動点）
  │   ├─ app.ts          # Expressの設定（任意で分離）
  │   ├─ routes/         # ルーティング（URL→処理の割当）
  │   ├─ controllers/    # HTTPの入出力を扱う層（任意）
  │   ├─ services/       # 業務ロジック（任意）
  │   ├─ repositories/   # DBアクセス（任意）
  │   ├─ middlewares/    # 認証など共通処理（任意）
  │   └─ types/          # 自前の型定義（任意）
  ├─ dist/               # build（tsc）で生成されるJS（配布物）
  ├─ package.json
  ├─ package-lock.json   # 依存の固定（自動生成）
  ├─ tsconfig.json
  └─ node_modules/       # 依存（自動生成・通常Git管理しない）

役割の考え方（初心者が迷いやすいポイント）

• src：あなたが読む／書く。TypeScriptの世界。
• dist：機械が作る。Node.js が直接実行する JavaScript の世界。
• index.ts：起動点。「サーバーを立ち上げる」最初の1ファイル。
• routes：URLと処理の対応表を置く場所になりがち。
• services：HTTPと関係ない “本質の処理” を置く（テストもしやすい）。

3. コンパイル、実行方法

3-1. 開発モード（保存したら自動再起動）

ts-node で TypeScript を直接実行し、nodemon で変更検知して再起動します。

npm run dev

動作確認（ブラウザ or curl）

http://localhost:3000/health

3-2. ビルド（TypeScript → JavaScript）

npm run build

dist/index.js が作成されます。

3-3. 実行（生成されたJavaScriptをNodeで動かす）

npm start

3-4. よくあるエラーと原因

4. リリースビルド、配布

4-1. “配布物” とは何か

Node.js アプリは「単一exeに固めて配布」よりも、通常は以下の形になります。

• dist/（ビルド成果物の JavaScript）
• package.json（依存と起動コマンド）
• package-lock.json（依存の固定。再現性のため重要）

4-2. リリース手順（標準）

1. 開発PCでビルド

   npm run clean
   npm run build

2. 配布先フォルダーへファイルをコピー（例）

   dist/
   package.json
   package-lock.json

3. 配布先で依存をインストール

   npm ci --omit=dev

   npm ci：lockファイル（package-lock.json）どおりに機械的にインストールするコマンド。再現性が高い。
   --omit=dev：devDependenciesを入れない（本番に不要なものを省く）。
4. 起動

   npm start

4-3. 環境変数でポートなどを切り替える

環境変数 は、コードを書き換えずに設定を変える仕組みです（例：ポート、DB接続先、APIキー）。

# Windows PowerShell
$env:PORT="8080"
npm start

# macOS / Linux
PORT=8080 npm start

4-4. 配布の形の例

• 社内配布（zip）：上記ファイルをzip → 配布先で npm ci → npm start
• サーバー配置：dist + package*.json を配置 → CI/CD で npm ci → PM2等で常駐
• Docker：Dockerfileで build → イメージ配布（再現性が高い）

5. TypeScriptの型、文法（if, switch, while, for, foreach など）

5-1. 基本の型

5-2. 配列・タプル

const nums: number[] = [1, 2, 3];
const names: Array<string> = ["a", "b"];

// タプル（要素数と各要素の型が固定）
const pair: [number, string] = [1, "one"];

5-3. オブジェクト型（interface / type）

API開発では最重要です（リクエストやレスポンスの形を型で固定できる）。

// interface：主に「形」を定義する（拡張もしやすい）
interface User {
  id: number;
  name: string;
  email?: string;  // ?: あってもなくてもよい（optional）
}

// type：unionなど「型の合成」に強い
type Id = number | string;

const u: User = { id: 1, name: "mao" };

interface User {
  id: number;
  name: string;
}

const u: User = { id: 1, name: "mao" }; // ← ただのJSオブジェクト

class User {
  constructor(
    public id: number,
    public name: string
  ) {}

  greet(): string {
    return `hello ${this.name}`;
  }
}

const u = new User(1, "mao");
u.greet();

enum Status {
  Pending,
  Paid,
  Canceled
}

const s: Status = Status.Paid;

// 実行時にも存在する
console.log(Status.Paid); // 1

enum Role {
  Admin = "admin",
  User = "user"
}

const enum Mode {
  Dev,
  Prod
}

// Mode.Dev → 0 に変換される

abstract class Repository {
  abstract findById(id: number): unknown;

  log(msg: string) {
    console.log(msg);
  }
}

class UserRepository extends Repository {
  findById(id: number) {
    return { id, name: "mao" };
  }
}

interface User {
  id: number;
  name: string;
}

interface UserDto {
  id: number;
  name: string;
}

class UserService {
  create(user: UserDto) {
    // 処理を書く
  }
}

// データの「形」だけを定義
interface User {
  id: number;
  name: string;
  email?: string; // あってもなくてもよい
}

// 普通の JavaScript オブジェクト
const u: User = {
  id: 1,
  name: "mao"
};

type Point = {
  x: number;
  y: number;
};

const p: Point = { x: 10, y: 20 };

type Id = number | string;

function find(id: Id) {
  // id は number か string
}

type Point = {
  readonly x: number;
  readonly y: number;
};

const p: Point = { x: 10, y: 20 };
// p.x = 30; ❌ コンパイルエラー

const Status = {
  Pending: "pending",
  Paid: "paid",
  Canceled: "canceled"
} as const;

class User {
  constructor(
    public id: number,
    public name: string
  ) {}

  greet() {
    return `hello ${this.name}`;
  }
}

const u = new User(1, "mao");

// 構造体相当（API / DB / DTO）
interface UserDto {
  id: number;
  name: string;
}

// 処理・ロジック担当
class UserService {
  create(user: UserDto) {
    // user はただのデータ
  }
}

5-4. Union（合併型）と型ガード（絞り込み）

type Input = string | number;

function toNumber(x: Input): number {
  if (typeof x === "string") {
    return Number(x);
  }
  return x; // ここでは number と分かっている
}

function addOne(x) {
  return x + 1;
}

addOne("10"); // "101"
addOne(10);   // 11

type Input = string | number;

type Input = string | number;

function f(x: Input) {
  return x + 1; // ❌ コンパイルエラー
}

typeof x === "string"

function f(x: string | number) {
  if (typeof x === "string") {
    // この中では x は string
    x.toUpperCase(); // OK
  } else {
    // この中では x は number
    x.toFixed(2); // OK
  }
}

type Input = string | number;

function toNumber(x: Input): number {
  if (typeof x === "string") {
    return Number(x);
  }
  return x; // ここでは number と分かっている
}

function parse(v: unknown): number {
  if (typeof v === "number") {
    return v;
  }
  if (typeof v === "string") {
    return Number(v);
  }
  throw new Error("invalid input");
}

5-5. if / switch

const status = "paid";

if (status === "paid") {
  // ...
} else if (status === "pending") {
  // ...
} else {
  // ...
}

switch (status) {
  case "paid":
    // ...
    break;
  case "pending":
    // ...
    break;
  default:
    // ...
    break;
}

5-6. while / for

let i = 0;
while (i < 3) {
  console.log(i);
  i++;
}

for (let j = 0; j < 3; j++) {
  console.log(j);
}

5-7. “foreach” に相当するもの（for...of / forEach）

TypeScript に foreach キーワードはありません。代わりに以下を使います。

const arr = ["a", "b", "c"];

// 1) for...of（おすすめ：break/continueが使える）
for (const x of arr) {
  console.log(x);
}

// 2) Array.forEach（関数で回す。breakできない）
arr.forEach((x) => {
  console.log(x);
});

5-8. 関数・戻り値・型注釈

// 引数と戻り値に型を付ける
function add(a: number, b: number): number {
  return a + b;
}

// アロー関数（よく使う）
const add2 = (a: number, b: number): number => a + b;

5-9. 例外（throw）と try/catch と型

JavaScript/TypeScript には 例外（Exception） があり、throw で発生させ、 try/catch で捕まえます。
TypeScript で増えるポイントは「catch で受け取る値の型がどう扱われるか」です。

1) throw の基本（不正な値を拒否する）

function mustBePositive(n: number): number {
  if (n <= 0) throw new Error("n must be positive");
  return n;
}

// 呼び出し側が catch しないと、例外は呼び出し元へ伝播していく

2) try/catch の基本（投げられた例外を処理する）

try {
  const x = mustBePositive(-3);
  console.log("OK:", x);
} catch (e) {
  console.log("NG: must be positive");
}

3) TypeScript的に重要：catch の e は何型？

JavaScript では throw できる値は Error とは限らず、 文字列やオブジェクトなど何でも投げられます。
そのため TypeScript では catch の変数 e は基本的に unknown 扱いになります（安全側）。

try {
  throw new Error("boom");
} catch (e) {
  // e は unknown だと考える（いきなり e.message は使えない）
  if (e instanceof Error) {
    console.log(e.message); // OK（ここで Error に絞り込めた）
  } else {
    console.log("Unknown error");
  }
}

4) finally（必ず実行したい後処理）

try {
  // 例：ファイル/通信/ロックなど、後で必ず解放したい処理
  console.log("start");
  const x = mustBePositive(10);
  console.log("value:", x);
} catch (e) {
  console.log("error");
} finally {
  console.log("cleanup"); // 成功でも失敗でも必ず実行
}

5) 実務での典型：HTTP API（Express）ではどうする？

Node.js/Express では「例外を投げる」よりも、
HTTP ステータスと JSON を返してエラーを表現するのが一般的です。
ただし、入力チェックなどで throw して、上位でまとめて catch する設計もあります。

// 例：入力チェックをして、ダメなら 400 を返す（throw を使わない）
app.post("/items", (req, res) => {
  const n = Number(req.body.amount);
  if (!Number.isFinite(n) || n <= 0) {
    return res.status(400).json({ error: "amount must be positive" });
  }
  res.json({ ok: true });
});

5-10. 非同期処理（Promise / async / await）— Node.jsで最重要

Node.js では、HTTP・ファイル・DB などの I/O（入出力）は 非同期 が基本です。
理由は単純で、I/O は「待ち時間（通信やディスク待ち）」が長く、そこで処理を止めると 1つのプロセスが何もできない時間が増え、同時にさばけるリクエスト数が減ってしまうからです。

1) まず「同期」と「非同期」の違いを体感する

I/O を同期で書くと（概念的には）こうなります：

// （説明用の擬似コード）同期処理のイメージ
// request を送る → 応答が来るまで止まる → 受け取ったら次へ
const data = httpGetSync("https://example.com"); // 終わるまで待つ
console.log("data:", data);
console.log("次の処理");

これだと待っている間、CPU がヒマになります。
Node.js は「待ち時間に別の処理を進める」設計なので、I/O は非同期が基本です。

// 非同期処理のイメージ（Promise）
const p = httpGetAsync("https://example.com"); // すぐ返る（結果は未来）
console.log("次の処理（待たずに進む）");

// あとで結果を受け取る
p.then((data) => console.log("data:", data))
 .catch((err) => console.error("error:", err));

2) Promise とは何か（Android Java経験者向けの対応づけ）

Promise は「将来完了する処理」を表すオブジェクトです。
Android Java で例えると、ざっくり次のどれかに近いです（完全一致ではありません）。

• Future / CompletableFuture：未来の結果を保持する（かなり近い）
• Callback（コールバック）：完了時に呼ばれる関数を渡す（Promiseの内部はこれを整理したもの）
• Coroutine（Kotlin）：awaitの見た目は coroutine にかなり近い

ただし Node.js では、こうした非同期が「標準の書き方」として組み込まれており、 ファイル・HTTP・DB などが最初から Promise を返す設計が多いです。

3) Promise の基本：then/catch（素の書き方）

function fetchTextThenStyle(): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    setTimeout(() => {
      const ok = true; // 失敗させたいなら false にする
      if (ok) resolve("hello");
      else reject(new Error("failed"));
    }, 100);
  });
}

fetchTextThenStyle()
  .then((text) => {
    console.log("success:", text);
  })
  .catch((err) => {
    console.error("error:", err.message);
  });

4) async / await：Promise を「同期っぽく」書く糖衣構文

then/catch は慣れると便利ですが、処理が長くなると読みにくくなりがちです。
そこで async/await を使うと、同期処理に近い形で書けます。

// Promise を返す関数（上の例と同じことをする）
function fetchText(): Promise<string> {
  return new Promise<string>((resolve) => {
    setTimeout(() => resolve("hello"), 100);
  });
}

// async/await で「待って値を受け取る」ように見せる
async function main(): Promise<void> {
  const text = await fetchText(); // ここで Promise の完了を待つ
  console.log("text:", text);
}

main();

5) 例外（throw）と await（ここで try/catch が重要になる）

Promise が失敗（reject）したとき、await はその失敗を 例外として投げます。
つまり await は throw を発生させうるので、必要なら try/catch で捕まえます。

async function mayFail(): Promise<string> {
  return new Promise((resolve, reject) => {
    setTimeout(() => reject(new Error("network error")), 100);
  });
}

async function run(): Promise<void> {
  try {
    const v = await mayFail(); // reject されたらここで例外になる
    console.log("OK:", v);
  } catch (e) {
    // Java と同じく「失敗時の処理」をここに書く
    if (e instanceof Error) console.log("NG:", e.message);
    else console.log("NG: unknown error");
  }
}

run();

6) 実務：HTTP（fetch）— 外部APIを呼ぶ典型

Node.js では HTTP 呼び出しは非同期が基本です。
（Node のバージョンや環境によっては fetch を使います。ここでは概念が目的です。）

// 概念例：HTTP で JSON を取る（Promise → await）
async function fetchJson(url: string): Promise<unknown> {
  const res = await fetch(url);              // HTTP待ち
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return await res.json();                   // JSON変換も非同期
}

返ってくる JSON は信用できないため、unknown として受け、 型ガードで絞る（5-4 の内容）に繋がります。

7) 実務：ファイル（fs/promises）— ファイルI/Oも await

// 概念例：ファイル読み込み（Nodeでは非同期が基本）
import { readFile } from "node:fs/promises";

async function loadText(path: string): Promise<string> {
  const buf = await readFile(path);   // ディスク待ち
  return buf.toString("utf-8");
}

8) 実務：並列処理（Promise.all）— 待ち時間を短くする

非同期は「順番に await する」だけでなく、同時に走らせることも重要です。
例えば 3 つの HTTP を順番に待つと遅くなります。

// 悪い例：順番に await（合計時間が長くなる）
const a = await fetchJson(urlA);
const b = await fetchJson(urlB);
const c = await fetchJson(urlC);

// 良い例：同時に開始して、全部終わるのを待つ
const [aa, bb, cc] = await Promise.all([
  fetchJson(urlA),
  fetchJson(urlB),
  fetchJson(urlC),
]);

9) Android Java と比べて何が違うのか（感覚を揃える）

• スレッドを自分で作る感覚が薄い
  Android Java だと Thread / Executor / Handler などを意識しますが、Node はイベントループ中心です。
  ただし「非同期＝並列にCPUで実行」ではなく、「待ち時間の間に他の処理を進める」が基本です。
• 戻り値が Future ではなく Promise
  役割は似ていますが、書き方の主流が async/await になっている点が大きな違いです。
• 例外の扱い
  Java の checked exception のような仕組みはありません。
  しかし await で reject は例外になるので、必要なら try/catch で捕まえます。

10) ありがちな落とし穴（初心者が最初に踏む）

• await を付け忘れる
  const data = fetchJson(url) は data が Promise になり、値ではありません。
• forEach で await しようとする
  array.forEach(async ...) は待ち合わせできません。必要なら for...of か Promise.all を使います。
• エラー処理をしない
  await は例外を投げるので、外部I/Oでは必ず失敗パスを考えます。

サンプル：/user/get/all → 他サーバーGET → JSON解析 → 必要項目だけ返す

この節でやること（概要）：

1. Express の Router で GET /user/get/all を受ける
2. Router から Controller を呼ぶ
3. Controller の中で「他サーバーへ HTTP GET」して JSON を受け取る
4. 受け取った JSON の中から userid, username, email だけを抜き出す
5. クライアントへ id,name,email の一覧を JSON で返す
6. 同じ処理を async/await 版と .then().catch() 版で見比べる

{
  "users": [
    { "userid": 1, "username": "john", "email": "john@company.com", "tel": "080-1721-0000", "nickname": "yobochan" },
    { "userid": 2, "username": "alice", "email": "alice@company.com", "tel": "090-0000-1111", "nickname": "ali" }
  ]
}

まず「全体コード」を先に見せます（async/await 版）

フォルダ構成（例）：

src/
  app.ts
  routes/
    userRoutes.ts
  controllers/
    userController.ts
  services/
    externalUserService.ts
  types/
    externalUserTypes.ts

src/types/externalUserTypes.ts（型定義：受け取るJSONと返すJSON）

export interface ExternalUser {
  userid: number;
  username: string;
  email: string;
  tel: string;
  nickname: string;
}

export interface ExternalUsersResponse {
  users: ExternalUser[];
}

export interface PublicUser {
  id: number;
  name: string;
  email: string;
}

src/services/externalUserService.ts（他サーバーへHTTP GETしてJSONを返す）

import type { ExternalUsersResponse } from "../types/externalUserTypes";

// NOTE: Node 18+ なら fetch が標準で使えることが多いです。
// もし fetch が使えない環境なら、node-fetch を入れる/axios を使う等に置き換えます。
export async function fetchExternalUsers(baseUrl: string): Promise<ExternalUsersResponse> {
  const url = `${baseUrl}/api/users`; // ← 他サーバーのAPIパス（例）
  const res = await fetch(url, { method: "GET" });

  if (!res.ok) {
    // await では reject が「例外」になるので、ここで throw すると caller が catch できます
    throw new Error(`External API failed. status=${res.status}`);
  }

  // ここでは「外部入力は信用しない」ので、本当は unknown で受けて検証したい。
  // まずは学習用に、型アサーションで簡略化します。
  const data = (await res.json()) as ExternalUsersResponse;

  // 最低限の形チェック（雑にでもやると安全度が上がります）
  if (!data || !Array.isArray(data.users)) {
    throw new Error("External API JSON shape is invalid (users not found).");
  }

  return data;
}

src/controllers/userController.ts（受け取ったJSONを解析し、必要項目だけ返す）

import type { Request, Response, NextFunction } from "express";
import { fetchExternalUsers } from "../services/externalUserService";
import type { PublicUser } from "../types/externalUserTypes";

const EXTERNAL_BASE_URL = process.env.EXTERNAL_BASE_URL ?? "https://other.example.com";

export async function getAllUsers(req: Request, res: Response, next: NextFunction) {
  try {
    // 1) 他サーバーへ GET
    const external = await fetchExternalUsers(EXTERNAL_BASE_URL);

    // 2) 必要項目だけに変換
    const list: PublicUser[] = external.users.map(u => ({
      id: u.userid,
      name: u.username,
      email: u.email,
    }));

    // 3) 自サーバーのAPIレスポンスとして返す
    res.json({ users: list });

  } catch (err) {
    // Controller 内で catch して HTTP 500/502 等で返しても良いし、
    // next(err) で「エラーハンドリングミドルウェア」に任せても良いです。
    next(err);
  }
}

src/routes/userRoutes.ts（Router：/user/get/all を Controller に接続）

import { Router } from "express";
import { getAllUsers } from "../controllers/userController";

export const userRouter = Router();

// router で /user/get/all を受ける想定
userRouter.get("/get/all", getAllUsers);

userRouter.get("/get/all", getAllUsers);

app.use("/user", userRouter);

userRouter.get("/get/all", getAllUsers);

GET /user/get/all

ブラウザ / クライアント
        |
        | GET /user/get/all
        v
+-------------------+
| app.use("/user")  |  ← /user を剥がす
+-------------------+
        |
        | /get/all
        v
+-------------------+
| userRouter        |
| .get("/get/all")  |
+-------------------+
        |
        v
  getAllUsers()

userRouter.get("/", handler);

@RequestMapping("/user")
public class UserController {

  @GetMapping("/get/all")
  public Response getAll() { ... }
}

src/app.ts（Expressアプリ：Router登録とエラーハンドリング）

import express from "express";
import { userRouter } from "./routes/userRoutes";

const app = express();
app.use(express.json());

// /user/... を userRouter に委譲
app.use("/user", userRouter);

// エラーハンドリングミドルウェア（next(err) が来たらここに来る）
app.use((err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
  // 実務ではログ出しや err の種類判定（外部API失敗=502など）を行います
  const message = err instanceof Error ? err.message : "Unknown error";
  res.status(500).json({ error: message });
});

const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => {
  console.log(`[server] listening on http://localhost:${port}`);
});

const res = await fetch(url, { method: "GET" });

const res = await fetch(url);

const json = await res.json();

fetch(url) 開始
   ↓
[ 通信中… ]
   ↓
レスポンスヘッダ受信   ← await fetch() はここで完了
   ↓
本文受信中（ストリーム）
   ↓
JSON パース完了        ← await res.json() はここまで待つ

const res = await fetch(url);

if (!res.ok) {
  // ステータスコードはこの時点で確認できる
  throw new Error(`HTTP ${res.status}`);
}

// 本文を最後まで読むのはここ
const data = await res.json();

await fetch(url);
// ここで JSON はまだ読まれていない

Response res = client.newCall(request).execute();

同じ処理を .then().catch() で書くとどうなる？（対応関係が見える版）

async/await は「Promise を then/catch で書けるものを、同期っぽく書ける構文」です。
つまり、さっきの await fetchExternalUsers(...) は、Promise で言うと .then(...) に対応します。
そして try/catch は .catch(...) に対応します。

Controller を then/catch で書いた版（同じ機能）

import type { Request, Response, NextFunction } from "express";
import { fetchExternalUsers } from "../services/externalUserService";
import type { PublicUser } from "../types/externalUserTypes";

const EXTERNAL_BASE_URL = process.env.EXTERNAL_BASE_URL ?? "https://other.example.com";

export function getAllUsersThen(req: Request, res: Response, next: NextFunction) {
  fetchExternalUsers(EXTERNAL_BASE_URL)
    .then((external) => {
      const list: PublicUser[] = external.users.map(u => ({
        id: u.userid,
        name: u.username,
        email: u.email,
      }));
      res.json({ users: list });
    })
    .catch((err) => {
      next(err);
    });
}

try {
  const external = await fetchExternalUsers(...);
  res.json(...);
} catch (err) {
  next(err);
}

fetchExternalUsers(...)
  .then((external) => {
    res.json(...);
  })
  .catch((err) => {
    next(err);
  });

実務で「Router/Controller/Service」を分ける理由（要約ではなく理由を明確に）

• Router：URL と処理（Controller）を結びつけるだけにする。
  ルーティングが増えても見通しが良い。
• Controller：HTTP の世界（req/res）を扱う場所。
  「入力を受ける」「サービスを呼ぶ」「レスポンスを返す」に集中する。
• Service：外部API/DB/ファイルなどの I/O をまとめる場所。
  Controller から切り離すとテストや再利用がしやすい。

このサンプルの入出力（何が返るのか）

他サーバーから受け取る JSON（例）：

{
  "users": [
    { "userid": 1, "username": "john", "email": "john@company.com", "tel": "080-1721-0000", "nickname": "yobochan" },
    { "userid": 2, "username": "alice", "email": "alice@company.com", "tel": "090-0000-1111", "nickname": "ali" }
  ]
}

自サーバーが返す JSON（必要項目だけにした結果）：

{
  "users": [
    { "id": 1, "name": "john",  "email": "john@company.com" },
    { "id": 2, "name": "alice", "email": "alice@company.com" }
  ]
}

6. ファイルI/O と DBアクセス（SQLite3）— Node.js/Express/TypeScript 実務入門

この章では、Node.js バックエンドで避けて通れない ファイルI/O と DBアクセスを、 初心者でも「何を・なぜ・どう書くか」が分かるように、コードを多めに示しながら説明します。

6-1. ファイルI/O（File Input/Output）とは

ファイルI/O とは「ファイルを読む/書く」ことです。Node.js ではディスクアクセスは遅い（待ち時間がある）ため、 基本的に 非同期 で扱います。

6-2. まずは基本：テキストファイルの読み書き（fs/promises）

6-2-1. 文字列として読む（小さめのファイル向け）

import { readFile } from "node:fs/promises";

async function loadText(path: string): Promise<string> {
  // encoding を指定すると string で返る
  const text = await readFile(path, { encoding: "utf-8" });
  return text;
}

6-2-2. 文字列として書く（上書き）

import { writeFile } from "node:fs/promises";

async function saveText(path: string, text: string): Promise<void> {
  await writeFile(path, text, { encoding: "utf-8" });
}

6-2-3. 追記する（ログなど）

import { appendFile } from "node:fs/promises";

async function appendLog(path: string, line: string): Promise<void> {
  await appendFile(path, line + "\n", { encoding: "utf-8" });
}

6-2-4. ファイルが存在するか（例外で判定しない書き方）

import { access } from "node:fs/promises";
import { constants } from "node:fs";

async function exists(path: string): Promise<boolean> {
  try {
    await access(path, constants.F_OK);
    return true;
  } catch {
    return false;
  }
}

6-3. パス操作：Windows/Linux で壊れない書き方

文字列連結で "dir/" + file を作ると、区切り文字の違い（Windowsは \）などで壊れやすいです。
必ず node:path を使います。

import path from "node:path";

// __dirname の代わり（ESM/TS設定によって変わるが、例として）
const dataDir = path.resolve(process.cwd(), "data");
const filePath = path.join(dataDir, "users.json");

6-4. JSONファイルを読む（型とセットで）

外部入力（ファイル内容）は「信用しない」が基本です。本来は unknown で受けて検証します。
ここでは学習用に「最低限の形チェック」を入れた例を示します。

import { readFile } from "node:fs/promises";

type UserJson = {
  userid: number;
  username: string;
  email: string;
};

function isUserJson(x: any): x is UserJson {
  return x
    && typeof x.userid === "number"
    && typeof x.username === "string"
    && typeof x.email === "string";
}

export async function loadUsersJson(path: string): Promise<UserJson[]> {
  const text = await readFile(path, { encoding: "utf-8" });
  const raw: unknown = JSON.parse(text);

  if (!Array.isArray(raw)) throw new Error("JSON is not an array");

  const list: UserJson[] = [];
  for (const item of raw) {
    if (!isUserJson(item)) throw new Error("Invalid user item in JSON");
    list.push(item);
  }
  return list;
}

7. SQLite3 DBアクセス（Node.js/Express/TypeScript）

SQLite は「DBサーバーが不要」で、アプリと同じPC内の 1つのファイル（例：app.db）に保存します。
配布が簡単で、小〜中規模のアプリやローカル用途に強いです。

7-1. 使用ライブラリ方針（初心者向けのおすすめ）

SQLite を Node.js から使う方法はいくつかあります。学習のしやすさ重視で以下を採用します。

• sqlite3（公式に近い定番）＋ sqlite（Promiseラッパー）

これにより await db.get() / await db.all() のように書けます。

npm i express
npm i -D typescript ts-node-dev @types/express

npm i sqlite3 sqlite

7-2. フォルダ構成（DB層を分ける）

src/
  app.ts
  routes/
    userRoutes.ts
  controllers/
    userController.ts
  services/
    externalUserService.ts
  db/
    sqlite.ts
    userRepository.ts
    migrate.ts
  types/
    userTypes.ts

7-3. DB接続（sqlite.ts）

SQLiteはDBサーバーへ接続するのではなく、DBファイルを開きます。
代表的には「アプリ起動時に開いて、使い回す」設計にします。

// src/db/sqlite.ts
import path from "node:path";
import sqlite3 from "sqlite3";
import { open, type Database } from "sqlite";

let db: Database<sqlite3.Database, sqlite3.Statement> | null = null;

export async function getDb(): Promise<Database<sqlite3.Database, sqlite3.Statement>> {
  if (db) return db;

  const dbPath = path.resolve(process.cwd(), "app.db"); // 配布しやすいようプロジェクト直下に置く例
  db = await open({
    filename: dbPath,
    driver: sqlite3.Database,
  });

  // 実務では推奨される設定：外部キー制約を有効化
  await db.exec("PRAGMA foreign_keys = ON;");

  return db;
}

7-4. テーブル作成（migrate.ts）

SQLiteは最初にテーブルを作らないと使えません。学習では「起動時にCREATEしておく」でも良いですが、
実務では「マイグレーション」として分けることが多いです。

// src/db/migrate.ts
import { getDb } from "./sqlite";

export async function migrate(): Promise<void> {
  const db = await getDb();

  await db.exec(`
    CREATE TABLE IF NOT EXISTS users (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      email TEXT NOT NULL UNIQUE
    );
  `);
}

app.ts 側で起動時に呼びます：

// src/app.ts（抜粋）
import express from "express";
import { migrate } from "./db/migrate";
import { userRouter } from "./routes/userRoutes";

const app = express();
app.use(express.json());

await migrate(); // 起動時にDB準備（学習用に分かりやすい）

app.use("/user", userRouter);

app.listen(3000);

7-5. Repository（SQLをまとめる層）

ControllerにSQLが散らばると読みにくくなります。
そこで「DBアクセスはRepositoryに集約」するのが一般的です。

// src/types/userTypes.ts
export type UserRow = {
  id: number;
  name: string;
  email: string;
};

export type NewUser = {
  name: string;
  email: string;
};

// src/db/userRepository.ts
import { getDb } from "./sqlite";
import type { NewUser, UserRow } from "../types/userTypes";

export async function insertUser(u: NewUser): Promise<number> {
  const db = await getDb();

  // パラメータバインド：SQL注入対策 + 型の安全性
  const result = await db.run(
    "INSERT INTO users (name, email) VALUES (?, ?)",
    u.name,
    u.email
  );

  // sqliteのrunは lastID を返す
  return result.lastID as number;
}

export async function getAllUsers(): Promise<UserRow[]> {
  const db = await getDb();
  return await db.all<UserRow[]>("SELECT id, name, email FROM users ORDER BY id");
}

export async function getUserById(id: number): Promise<UserRow | null> {
  const db = await getDb();
  const row = await db.get<UserRow>("SELECT id, name, email FROM users WHERE id = ?", id);
  return row ?? null;
}

7-6. トランザクション（複数更新をまとめる）

たとえば「2件のINSERTが両方成功したらOK。1件でも失敗したら全部取り消す」という場面があります。
これをトランザクションで書きます。

// src/db/userRepository.ts（追記例）
import type { NewUser } from "../types/userTypes";
import { getDb } from "./sqlite";

export async function insertTwoUsers(a: NewUser, b: NewUser): Promise<void> {
  const db = await getDb();
  await db.exec("BEGIN");

  try {
    await db.run("INSERT INTO users (name, email) VALUES (?, ?)", a.name, a.email);
    await db.run("INSERT INTO users (name, email) VALUES (?, ?)", b.name, b.email);

    await db.exec("COMMIT");
  } catch (e) {
    await db.exec("ROLLBACK");
    throw e;
  }
}

7-7. Express ルート（Router → Controller → Repository → Response）

// src/controllers/userController.ts
import type { Request, Response, NextFunction } from "express";
import * as repo from "../db/userRepository";

export async function getAllUsers(req: Request, res: Response, next: NextFunction) {
  try {
    const users = await repo.getAllUsers();
    res.json({ users });
  } catch (e) {
    next(e);
  }
}

export async function createUser(req: Request, res: Response, next: NextFunction) {
  try {
    // 外部入力なので本来は unknown → 検証が理想。学習用に最小チェックだけ。
    const name = String(req.body?.name ?? "");
    const email = String(req.body?.email ?? "");

    if (!name || !email) {
      return res.status(400).json({ error: "name and email are required" });
    }

    const id = await repo.insertUser({ name, email });
    res.status(201).json({ id });
  } catch (e) {
    next(e);
  }
}

// src/routes/userRoutes.ts
import { Router } from "express";
import { getAllUsers, createUser } from "../controllers/userController";

export const userRouter = Router();

userRouter.get("/get/all", getAllUsers);
userRouter.post("/create", createUser);

7-8. SQLiteの「コネクションプール」はどう考える？

Oracle/MySQL/PostgreSQL/SQL Server のようなDBサーバーでは、 接続（コネクション）を作るのが重いので コネクションプールが重要です。
一方で SQLite は「ファイルを開く」イメージに近く、一般的な意味でのプールは通常使いません。

• SQLite：アプリ起動時に 1つ開いて使い回す（この章の設計）
• サーバーDB：プールを作って使い回す（後述）

8. どのDBに接続するか・プール・主要DBの違い

8-1. DBを選ぶ観点（初心者向け）

• 配布の簡単さ：SQLite（DBファイル1個）
• 同時アクセス/高負荷：PostgreSQL / MySQL / SQL Server / Oracle（サーバーDB）
• 運用（バックアップ/監視/冗長化）：サーバーDBが強い
• クラウド連携：PostgreSQL/MySQL は選択肢が多い

8-2. サーバーDBのコネクションプール（雰囲気だけでも掴む）

サーバーDBは「毎回 connect すると遅い」ので、起動時にプールを作り、クエリごとに借りて返します。

PostgreSQL（pg）

import { Pool } from "pg";

const pool = new Pool({
  host: "localhost",
  port: 5432,
  user: "app",
  password: "secret",
  database: "appdb",
  max: 10, // プール内コネクション数
});

export async function query(sql: string, params: any[]) {
  return await pool.query(sql, params);
}

MySQL（mysql2）

import mysql from "mysql2/promise";

const pool = mysql.createPool({
  host: "localhost",
  user: "app",
  password: "secret",
  database: "appdb",
  connectionLimit: 10,
});

export async function query(sql: string, params: any[]) {
  const [rows] = await pool.execute(sql, params);
  return rows;
}

Oracle（oracledb）

import oracledb from "oracledb";

// 起動時にプールを作る
const pool = await oracledb.createPool({
  user: "app",
  password: "secret",
  connectString: "localhost/XEPDB1",
  poolMin: 1,
  poolMax: 10,
});

export async function query(sql: string, binds: any[] = []) {
  const conn = await pool.getConnection();
  try {
    const result = await conn.execute(sql, binds, { outFormat: oracledb.OUT_FORMAT_OBJECT });
    return result.rows;
  } finally {
    await conn.close();
  }
}

SQL Server（mssql）

import sql from "mssql";

const pool = await sql.connect({
  server: "localhost",
  user: "app",
  password: "secret",
  database: "appdb",
  options: { encrypt: false },
  pool: { max: 10, min: 1 },
});

export async function query(text: string, params: Record<string, any> = {}) {
  const req = pool.request();
  for (const [k, v] of Object.entries(params)) req.input(k, v);
  const result = await req.query(text);
  return result.recordset;
}

8-3. Oracle / MySQL / PostgreSQL / SQL Server の違い（初心者向けまとめ）

9. SQL以外でアクセスできる？（Spring Boot の @Entity 的なもの）

はい、できます。Node/TypeScript の世界では、 ORM（Object-Relational Mapping）や Query Builder を使うと、 SQLを直接書かず（または最小限で）DB操作できます。

9-1. TypeORM（デコレータで @Entity っぽく書ける）

TypeORM は @Entity のようなデコレータで定義します（Springの感覚に近い）。
※ 環境・設定が増えるため、学習初期は「存在を知る」程度でもOKです。

// 例：TypeORMの雰囲気（概念）
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column()
  name!: string;

  @Column({ unique: true })
  email!: string;
}

9-2. Prisma（型安全が強い・実務人気）

Prisma は schema ファイルから型を生成し、TypeScriptから安全に操作できます。
「SQLを全く書かない」より「必要ならSQLも使える」方向の設計です。

// Prismaの雰囲気（概念）
const users = await prisma.user.findMany({
  select: { id: true, name: true, email: true }
});

9-3. Sequelize（歴史が長いORM） / Knex（Query Builder）

Sequelize は ORM、Knex は Query Builder の代表格です。
「SQLを減らしたい」「複数DBに対応したい」場合の候補になります。

10. 章のまとめ

• ファイルI/Oは fs/promises が基本。大きいファイルはストリーム。
• SQLiteは「DBファイル」で配布が簡単。起動時に開いて使い回す設計が分かりやすい。
• サーバーDB（Oracle/MySQL/PostgreSQL/SQL Server）はプールが重要。
• SQLを減らしたいならORM/Query Builder（TypeORM/Prisma等）が選択肢。

11. HTMLからのファイルアップロード / ダウンロード（大きい画像ファイル想定）

ここでは「ブラウザのHTMLフォームから画像をアップロードし、サーバー側で保存し、 後でダウンロード（または表示）できる」までを、Router から順に説明します。
画像は大きいファイルを想定するため、Node.js では メモリに丸ごと載せない（ストリーミング）設計が重要です。

11-1. 方針（大きいファイルで重要なこと）

• アップロードはメモリに載せない：memoryStorage は避け、disk保存する
• サイズ制限を必ず付ける：無制限だとDoS（大容量連打）で落ちる
• 拡張子を信用しない：最低限 mime-type を見る（より厳密には「内容判定」）
• ダウンロードはストリームで返す：readFile で丸読みしない

11-2. 事前準備（ライブラリ）

# 画像アップロード処理に multer を使う
npm i multer
npm i -D @types/multer

11-3. まず Router から（/file/upload, /file/download/:id）

ルーティングは次の2つを用意します：

• POST /file/upload：HTMLフォームから画像を受け取って保存
• GET /file/download/:id：保存したファイルをダウンロード（または画像表示）

// src/routes/fileRoutes.ts
import { Router } from "express";
import { uploadSingleImage, downloadById } from "../controllers/fileController";

export const fileRouter = Router();

// HTMLフォームからのアップロード
fileRouter.post("/upload", uploadSingleImage);

// ID を指定してダウンロード（または表示）
fileRouter.get("/download/:id", downloadById);

app.ts 側でベースパスを付けるなら：

// src/app.ts（抜粋）
import express from "express";
import { fileRouter } from "./routes/fileRoutes";

const app = express();
app.use(express.json());

// /file/... を fileRouter に委譲
app.use("/file", fileRouter);

app.listen(3000);

11-4. アップロード設定（multer：ディスク保存、サイズ制限、ファイル名）

大きい画像を扱うため、メモリ保存（memoryStorage）ではなく diskStorage を使います。
また、攻撃や事故を防ぐため、ファイルサイズ上限も必ず設定します。

// src/middlewares/upload.ts
import multer from "multer";
import path from "node:path";
import crypto from "node:crypto";
import { mkdirSync } from "node:fs";

const uploadDir = path.resolve(process.cwd(), "uploads");

// 起動時に uploads フォルダが無ければ作る
mkdirSync(uploadDir, { recursive: true });

function safeExt(originalName: string): string {
  // 拡張子は信用しすぎない（ここでは最低限）
  const ext = path.extname(originalName).toLowerCase();
  if (ext === ".png" || ext === ".jpg" || ext === ".jpeg" || ext === ".webp") return ext;
  return ".bin";
}

const storage = multer.diskStorage({
  destination: (_req, _file, cb) => cb(null, uploadDir),
  filename: (_req, file, cb) => {
    // ファイル名衝突を避けるためランダムID + 拡張子
    const id = crypto.randomUUID();
    cb(null, `${id}${safeExt(file.originalname)}`);
  },
});

export const uploadImage = multer({
  storage,
  // 大きい画像想定：例として 50MB（必要に応じて調整）
  limits: { fileSize: 50 * 1024 * 1024 },
  fileFilter: (_req, file, cb) => {
    // MIME type チェック（完全ではないが最低限）
    const ok = ["image/png", "image/jpeg", "image/webp"].includes(file.mimetype);
    if (!ok) return cb(new Error("Only png/jpeg/webp are allowed"));
    cb(null, true);
  },
});

11-5. Controller（アップロード：受け取って保存し、IDを返す）

multer は Express のミドルウェアとして動き、
ファイルは保存済みの状態で req.file に情報が入ります。

// src/controllers/fileController.ts
import type { Request, Response, NextFunction } from "express";
import path from "node:path";
import { uploadImage } from "../middlewares/upload";
import { stat } from "node:fs/promises";
import { createReadStream } from "node:fs";

type UploadResponse = {
  id: string;
  originalName: string;
  storedName: string;
  size: number;
  mime: string;
  downloadUrl: string;
};

// ここがポイント：Router から直接 controller を呼ぶと multer が挟めないので、
// controller 側で「upload.single(...) を1回呼ぶ」形にします。
// （もちろん Router 側で upload.single(...) を挟んでもOKです）
export function uploadSingleImage(req: Request, res: Response, next: NextFunction) {
  const middleware = uploadImage.single("image"); // HTML側 input name="image" と合わせる

  middleware(req, res, async (err: any) => {
    try {
      if (err) return next(err);
      if (!req.file) return res.status(400).json({ error: "file is required (image)" });

      // 保存ファイル名（例: UUID.jpg）
      const storedName = req.file.filename;
      const id = path.parse(storedName).name; // UUID 部分だけ取り出す

      const fileStat = await stat(req.file.path);

      const body: UploadResponse = {
        id,
        originalName: req.file.originalname,
        storedName,
        size: fileStat.size,
        mime: req.file.mimetype,
        downloadUrl: `/file/download/${id}`,
      };

      res.status(201).json(body);
    } catch (e) {
      next(e);
    }
  });
}

function resolveStoredPath(id: string): string {
  // uploads/ の中から「idで始まるファイル」を探す…などもあるが、
  // 学習用に「id + 任意拡張子」を許すため、ここでは簡単化します。
  // 実務では DB か メタ情報ファイルで id→filename を管理するのが確実です。
  const uploadDir = path.resolve(process.cwd(), "uploads");

  // ここではよくある拡張子を順番に試す（簡易版）
  // ※ 本格的には「アップロード時に id と storedName を SQLite に保存」するのが正解です。
  const candidates = [".png", ".jpg", ".jpeg", ".webp", ".bin"].map(ext => path.join(uploadDir, `${id}${ext}`));
  return candidates[0]; // ダウンロード側で実際に存在確認しつつ探す
}

export async function downloadById(req: Request, res: Response, next: NextFunction) {
  try {
    const id = String(req.params.id ?? "");

    if (!id) return res.status(400).json({ error: "id is required" });

    // 簡易：拡張子候補を探す
    const uploadDir = path.resolve(process.cwd(), "uploads");
    const exts = [".png", ".jpg", ".jpeg", ".webp", ".bin"];

    let foundPath: string | null = null;
    let foundExt: string | null = null;

    for (const ext of exts) {
      const p = path.join(uploadDir, `${id}${ext}`);
      try {
        await stat(p);
        foundPath = p;
        foundExt = ext;
        break;
      } catch {
        // not found
      }
    }

    if (!foundPath) return res.status(404).json({ error: "file not found" });

    // Content-Type（画像表示 or ダウンロードのヒント）
    const contentType =
      foundExt === ".png" ? "image/png" :
      foundExt === ".webp" ? "image/webp" :
      (foundExt === ".jpg" || foundExt === ".jpeg") ? "image/jpeg" :
      "application/octet-stream";

    res.setHeader("Content-Type", contentType);

    // ダウンロードさせたい場合は Content-Disposition を付ける
    // 画像をブラウザ表示させたいなら "inline"、保存させたいなら "attachment"
    res.setHeader("Content-Disposition", `attachment; filename="${id}${foundExt}"`);

    // 大きいファイル対応：ストリームで返す（readFileで全部読まない）
    const stream = createReadStream(foundPath);
    stream.on("error", next);
    stream.pipe(res);

  } catch (e) {
    next(e);
  }
}

11-6. Router で multer を挟む書き方（別解：こちらの方が一般的）

さっきは controller 内で uploadImage.single(...) を呼びましたが、
実務では Router 側でミドルウェアとして挟む方が読みやすいことが多いです。

// src/routes/fileRoutes.ts（別案）
import { Router } from "express";
import { uploadImage } from "../middlewares/upload";
import { uploadSingleImage, downloadById } from "../controllers/fileController";

export const fileRouter = Router();

// Routerで multer を挟む（この形が一般的）
fileRouter.post("/upload", uploadImage.single("image"), uploadSingleImage);

fileRouter.get("/download/:id", downloadById);

この場合、Controller の uploadSingleImage は「保存済みファイル情報を返すだけ」になります：

// src/controllers/fileController.ts（uploadSingleImage を簡略化できる）
export async function uploadSingleImage(req: Request, res: Response, next: NextFunction) {
  try {
    if (!req.file) return res.status(400).json({ error: "file is required (image)" });

    const storedName = req.file.filename;
    const id = path.parse(storedName).name;

    const fileStat = await stat(req.file.path);

    res.status(201).json({
      id,
      originalName: req.file.originalname,
      storedName,
      size: fileStat.size,
      mime: req.file.mimetype,
      downloadUrl: `/file/download/${id}`,
    });
  } catch (e) {
    next(e);
  }
}

11-7. HTML（ブラウザ側）：アップロードフォームの例

HTMLからファイルを送るときは enctype="multipart/form-data" が必須です。
また <input type="file" name="image"> の name はサーバー側の single("image") と一致させます。

<form action="/file/upload" method="post" enctype="multipart/form-data">
  <label>画像を選択：</label>
  <input type="file" name="image" accept="image/png,image/jpeg,image/webp" />

  <button type="submit">アップロード</button>
</form>

11-7-1. fetch で送る版（進捗表示やUI制御に向く）

HTMLフォーム送信は簡単ですが、送信完了後に画面が遷移します。
UIを作るなら JavaScript の fetch と FormData を使うと便利です。

    <input id="file" type="file" accept="image/*" />
<button id="send">送信</button>

<script>
document.getElementById("send").addEventListener("click", async () => {
  const fileInput = document.getElementById("file");
  const file = fileInput.files?.[0];
  if (!file) {
    alert("ファイルを選択してください");
    return;
  }

  const fd = new FormData();
  fd.append("image", file); // multer.single("image") と合わせる

  const res = await fetch("/file/upload", { method: "POST", body: fd });
  const json = await res.json();

  if (!res.ok) {
    alert("失敗: " + (json?.error ?? "unknown"));
    return;
  }

  alert("成功。ダウンロードURL: " + json.downloadUrl);
});
</script>

11-8. 大きいファイルで必須の安全策（実務の現実）

• サイズ制限：limits.fileSize
• 拡張子/ MIME の制限：fileFilter
• 保存先の固定：ユーザー入力で保存パスを作らない（パストラバーサル対策）
• ファイル名のランダム化：衝突防止 + 悪意ある名前対策
• メタ情報の保存：本当は「id → filename / mime / size」をDBに保存する（次節で強化可能）

11-9. ここまでの動作確認（手順）

1. サーバー起動（例：npm run dev）
2. ブラウザでアップロードフォームを開く
3. 画像を選択して送信 → JSONで id と downloadUrl が返る
4. downloadUrl（例：/file/download/<id>）にアクセスするとファイルが落ちる

1. ルーターはどこに増やす？

ルーターは URLのまとまり単位で増やします。 迷ったら「URLの第1階層」を基準にします。

src/
  routes/
    user.router.ts
    auth.router.ts
    file.router.ts
  app.ts

app.ts では、ルーターを「マウント」するだけにします。

// app.ts
app.use("/user", userRouter);
app.use("/auth", authRouter);
app.use("/file", fileRouter);

2. Controller / Service / Repository の分け方

最初から完璧に分ける必要はありません。
「HTTPの話」と「業務処理」が混ざり始めたら分離が合図です。

src/
  controllers/
    user.controller.ts
  services/
    user.service.ts
  repositories/
    user.repository.ts

• Controller：req / res を扱う（HTTPの世界）
• Service：業務ロジック（ルール・判断）
• Repository：DBアクセスのみ

3. 例外処理と HTTP エラーの考え方

原則： Service / Repository では例外を投げるだけ。 HTTP に変換するのは Controller より後です。

HTTPエラー用の型

export class HttpError extends Error {
  constructor(
    public status: number,
    message: string
  ) {
    super(message);
  }
}

Service 側

if (!user) {
  throw new HttpError(404, "user not found");
}

async route の例外をまとめて拾う

// error middleware
app.use((err, req, res, next) => {
  if (err instanceof HttpError) {
    res.status(err.status).json({ error: err.message });
    return;
  }

  console.error(err);
  res.status(500).json({ error: "internal server error" });
});

4. 入力バリデーション（型は実行時に消える）

TypeScript の型は コンパイル時だけ存在します。
HTTP body は「信用してはいけません」。

最低限のやり方

function isUser(x: unknown): x is { name: string } {
  return typeof x === "object"
    && x !== null
    && typeof (x as any).name === "string";
}

zod を使う場合（おすすめ）

const UserSchema = z.object({
  name: z.string(),
  email: z.string().email()
});

const user = UserSchema.parse(req.body);

5. 環境変数と .env

開発と本番で値が変わるものは、 コードに書かないのが原則です。

// .env（開発用）
PORT=3000
DB_PATH=./data/app.db

// 読み込み
import "dotenv/config";
const port = process.env.PORT;

• .env は .gitignore に入れる
• 本番では OS / Kubernetes / CI の環境変数を使う

6. 最低限のセキュリティ

• CORS：どのサイトから呼べるか制御
• helmet：安全な HTTP ヘッダを自動付与
• rate limit：総当たり攻撃対策

app.use(helmet());
app.use(cors());
app.use(rateLimit({ windowMs: 60000, max: 100 }));

7. VS Code デバッグ（launch.json）

sourceMap: true を設定しているので、 TypeScript のままデバッグできます。

{
  "type": "node",
  "request": "launch",
  "name": "Debug API",
  "program": "${workspaceFolder}/src/app.ts",
  "runtimeArgs": ["-r", "ts-node/register"]
}

• ブレークポイントを置く
• 変数をその場で確認

8. 最小のテスト（GET /health）

it("health check", async () => {
  await request(app)
    .get("/health")
    .expect(200);
});

これがあるだけで、 「壊れていない」保証が手に入ります。

1. ファイルは分けるのが普通か？

結論から言うと：

よくある構成例

src/
  models/
    user.ts           // interface User
  entities/
    user.entity.ts    // class UserEntity
  enums/
    user-role.ts     // enum UserRole
  services/
    user.service.ts  // class UserService

理由はシンプルです：

• ファイル名＝中身が分かる
• import が明確になる
• 差分（git）が追いやすい
• 肥大化を防げる

2. interface / type / enum はどこに置く？

判断基準は「どの層の概念か」です。

// models/user.ts
export interface User {
  id: number;
  name: string;
}

// enums/user-role.ts
export enum UserRole {
  Admin = "admin",
  User = "user"
}

3. public / protected / private はある？

はい、あります。
TypeScript の class は Java や C# とほぼ同じアクセス修飾子を持ちます。

class UserService {
  public findAll() {
    return this.load();
  }

  protected load() {
    return [];
  }

  private validate() {
    // 内部処理
  }
}

4. Java / C# との違い（重要）

TypeScript のアクセス修飾子は：

つまり：

• コンパイル時：アクセス違反はエラー
• 実行時：理論上は触れてしまう

それでも使う理由は：

• 設計意図を明確にする
• IDE 補完を制御できる
• 誤用を早期に防げる

5. 初心者向けおすすめルール

このルールを守ると：

• ファイル構成で迷わない
• 依存関係が破綻しにくい
• 後からリファクタしやすい

Node.js に DI（Dependency Injection）はあるのか？

結論から言うと：

1. DI（Dependency Injection）とは

DI とは：

「クラスや関数が必要とする依存物を、
自分で new せず、外から渡す設計」

目的は次の3つです。

• テストしやすくする
• 実装の差し替えを容易にする
• 依存関係を見える化する

2. Node.js で最も一般的な DI（手動DI）

Node.js では、コンストラクタ引数で依存を渡すのが王道です。

// repository
export class UserRepository {
  findAll() {
    return [];
  }
}

// service
export class UserService {
  constructor(private repo: UserRepository) {}

  findAll() {
    return this.repo.findAll();
  }
}

// controller
const repo = new UserRepository();
const service = new UserService(repo);

3. interface を使った DI

TypeScript では、interface + DI が強力です。

// repository interface
export interface UserRepository {
  findAll(): User[];
}

// 実装
export class SqliteUserRepository implements UserRepository {
  findAll() { return []; }
}

// service
export class UserService {
  constructor(private repo: UserRepository) {}
}

これにより：

• SQLite → PostgreSQL に差し替え可能
• テスト用の Mock に差し替え可能

4. Node.js に DI コンテナはある？

あります。ただし 必須ではありません。

5. Spring Boot との違い

Node.js では：

「魔法は少ないが、
依存関係がコードから読める」

6. 初心者向けおすすめ

このやり方は：

• 小規模〜中規模で十分スケールする
• テストが簡単
• 学習コストが低い

publicの実務での正しいルール

TypeScriptでクラスを外部に見えるようにするには、export を使います。
しかし、実務では public はメソッドやプロパティに使い、クラス自体には付けないのが一般的です。

TypeScript では、 class 宣言は 常に public 扱いです。

// 良い例
export class UserService {
  public findAll() {}
  private validate() {}
}

import { UserService } from "./user.service";

const service = new UserService();
service.findAll();

例外処理（Exception Handling）

Node.js + Express + TypeScript では、 「どこで例外を投げ、どこで HTTP エラーにするか」 を決めておかないと、コードがすぐに壊れます。

このセクションでは、実務で最も一般的な考え方として：

• Controller / Service / Repository の責務分担
• Express の error middleware による一括処理
• HTTP エラー専用の型 HttpError

を 順番に説明します。

1. なぜ例外処理を決める必要があるのか

初心者が書きがちなコードでは、次のような問題が起きます。

• どこかで throw された例外が突然 500 になる
• 同じエラー処理が Controller ごとにコピペされる
• ログが出たり出なかったりする

原因はシンプルで：

「誰が、何の責任で例外を処理するのか」 が決まっていない

そこで、レイヤーごとに 責務を明確に分けます。

2. レイヤーごとの例外責務

3. HTTP エラーを表す型 HttpError

業務的な失敗（404 / 400 / 403 など）は、 普通の Error とは区別したくなります。

そのために、HTTP ステータスを持つエラー型を作ります。

// errors/http-error.ts
export class HttpError extends Error {
  public readonly status: number;

  constructor(status: number, message: string) {
    super(message);
    this.status = status;
  }
}

これにより、

• 「これは 404」
• 「これは 400」

を 例外そのものに意味として持たせることができます。

4. Service で意味のある例外を投げる

// services/user.service.ts
import { HttpError } from "../errors/http-error";

export class UserService {
  async findById(id: number) {
    const user = null; // 仮

    if (!user) {
      throw new HttpError(404, "User not found");
    }

    return user;
  }
}

ここでは：

• HTTP レスポンスは返していない
• 「見つからない」という意味だけを表現

という点が重要です。

5. Controller は例外を捕まえない

// controllers/user.controller.ts
import { Request, Response } from "express";
import { UserService } from "../services/user.service";

const service = new UserService();

export async function getUser(req: Request, res: Response) {
  const id = Number(req.params.id);

  const user = await service.findById(id);
  res.json(user);
}

ここには try/catch がありません。

throw された例外は、 Express が自動で error middleware に渡します。

6. error middleware で例外を一括処理

Express では、 引数が4つある middleware がエラー専用です。

// app.ts
import express, { Request, Response, NextFunction } from "express";
import { HttpError } from "./errors/http-error";

const app = express();

app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof HttpError) {
    res.status(err.status).json({ error: err.message });
    return;
  }

  // 想定外の例外
  console.error("Unexpected error:", err);
  res.status(500).json({ error: "Internal Server Error" });
});

7. 例外処理の全体像

1. Repository が技術的エラーを throw
2. Service が意味のある失敗を HttpError として throw
3. Controller は例外を触らない
4. error middleware が HTTP レスポンスに変換

用語集（このマニュアル内で使う Node/TS 専門用語）

仕様書セクション

1. 概要

このサンプルは、実際に存在しそうな小さな Web APIを題材に、

• DB（SQLite）
• ファイル I/O（画像アップロード）
• 外部 HTTP API

2. エンドポイント仕様

3. 処理フロー図（例外の流れ）

[HTTP Request]
      |
      v
[Controller]
  (HTTP入出力のみ)
      |
      v
[Service]
  (業務判断)
  ├─ 不正な入力 → HttpError(400)
  ├─ データなし → HttpError(404)
      |
      v
[Repository]
  ├─ DBエラー
  ├─ File I/O エラー
  ├─ 外部 HTTP エラー
      |
      v
[throw Error / HttpError]
      |
      v
[Error Middleware]
  ├─ HttpError → 指定 status
  └─ 想定外 → 500 + ログ
  

4. フォルダ構成

src/
 ├─ app.ts
 ├─ routes/
 │    └─ user.router.ts
 ├─ controllers/
 │    └─ user.controller.ts
 ├─ services/
 │    └─ user.service.ts
 ├─ repositories/
 │    ├─ user.repository.ts
 │    └─ external.repository.ts
 ├─ errors/
 │    └─ http-error.ts
 └─ middlewares/
      └─ error.middleware.ts
  

サンプルコードセクション

app.ts

// Express を読み込む
import express from "express";
// ルーターを読み込む
import { userRouter } from "./routes/user.router";
// エラーミドルウェアを読み込む
import { errorMiddleware } from "./middlewares/error.middleware";

// Express アプリを作成
const app = express();

// JSON body を読む設定
app.use(express.json());

// ヘルスチェック
app.get("/health", (_req, res) => {
  res.json({ ok: true, time: new Date().toISOString() });
});

// /users 配下を userRouter に委譲
app.use("/users", userRouter);

// 例外を最後にまとめて処理
app.use(errorMiddleware);

// ポート番号を決定
const port = Number(process.env.PORT ?? 3000);

// サーバー起動
app.listen(port, () => {
  console.log(`listening on http://localhost:${port}`);
});

errors/http-error.ts

// HTTP 用のエラー型
export class HttpError extends Error {
  // HTTP ステータス
  public readonly status: number;

  // コンストラクタ
  constructor(status: number, message: string) {
    super(message);      // Error に message を渡す
    this.status = status; // status を保存
  }
}

repositories/user.repository.ts

// DB アクセスを担当する Repository
export class UserRepository {
  async findAll() {
    // 本来は SQLite だが、ここでは簡略化
    return [
      { id: 1, name: "john", email: "john@test.com" }
    ];
  }
}

repositories/external.repository.ts

// 外部 HTTP API を呼び出す Repository
export class ExternalRepository {
  async fetchExtraInfo(id: number) {
    // 疑似的に外部 API 失敗を再現
    if (id === 0) {
      throw new Error("external api failed");
    }
    return { score: 42 };
  }
}

services/user.service.ts

// Service は業務ロジックを担当
import { UserRepository } from "../repositories/user.repository";
import { ExternalRepository } from "../repositories/external.repository";
import { HttpError } from "../errors/http-error";

// Service クラス
export class UserService {
  // Repository を保持
  constructor(
    private userRepo = new UserRepository(),
    private externalRepo = new ExternalRepository()
  ) {}

  // ユーザー一覧取得
  async getUsers() {
    return this.userRepo.findAll();
  }

  // 外部情報取得
  async getExternalInfo(id: number) {
    if (id <= 0) {
      throw new HttpError(400, "invalid user id");
    }
    try {
      return await this.externalRepo.fetchExtraInfo(id);
    } catch {
      throw new HttpError(502, "external service error");
    }
  }
}

controllers/user.controller.ts

// Controller は HTTP 入出力のみ担当
import { Request, Response } from "express";
import { UserService } from "../services/user.service";

// Service を生成
const service = new UserService();

// ユーザー一覧
export async function getUsers(_req: Request, res: Response) {
  const users = await service.getUsers();
  res.json(users);
}

// 外部情報取得
export async function getExternal(req: Request, res: Response) {
  const id = Number(req.params.id);
  const info = await service.getExternalInfo(id);
  res.json(info);
}

routes/user.router.ts

// Router 定義
import { Router } from "express";
import { getUsers, getExternal } from "../controllers/user.controller";

// Router を作成
export const userRouter = Router();

// 一覧取得
userRouter.get("/", getUsers);

// 外部情報取得
userRouter.get("/:id/external", getExternal);

middlewares/error.middleware.ts

// エラーミドルウェア
import { Request, Response, NextFunction } from "express";
import { HttpError } from "../errors/http-error";

// error middleware
export function errorMiddleware(
  err: unknown,
  _req: Request,
  res: Response,
  _next: NextFunction
) {
  if (err instanceof HttpError) {
    res.status(err.status).json({ error: err.message });
    return;
  }
  console.error("unexpected error:", err);
  res.status(500).json({ error: "internal server error" });
}

仕様説明セクション：注文・請求ルールエンジン

1. このサンプルで学ぶこと

このサンプルは、Webアプリの「通信」よりも、 TypeScript の文法を業務ロジックの中でどう使うかに焦点を当てています。

• const / let の使い分け
• 基本型（number, string, boolean）
• interface / type
• enum（業務上の区分）
• for...of による配列処理
• switch による条件分岐
• map / reduce による集計

「文法の説明」ではなく、 実際の業務ルールの中で文法がどう使われるか を理解するのが目的です。

2. 業務の概要

ユーザーから渡された「注文データ」を元に、 以下を計算します。

• 商品ごとの金額と税額
• 顧客ランクやクーポンによる割引
• 配送地域による送料
• 最終的な請求金額

3. 入力データの考え方

入力は JavaScript オブジェクト（JSON 相当）です。 実務では HTTP body に相当します。

重要なポイント：

• 配列（注文行）を for...of で処理する
• 区分値は enum で表現する
• 計算途中の値は const で保持する

4. 主な業務ルール

税計算

• STANDARD：10%
• REDUCED：8%
• EXEMPT：0%

割引

• GOLD 会員：小計の 5%
• WELCOME10 クーポン：小計の 10%

送料

• TOKYO：500円
• OTHER：800円
• 小計 10,000円以上で送料無料

5. 入力 / 出力データ仕様（コメント付き）

入力（注文データ）

業務ロジックに渡される入力データです。
実務では HTTP リクエストの body（JSON）に相当します。

// ※ 説明用のためコメント付き（実際の JSON ではコメント不可）
{
  "customerRank": "GOLD",        // 顧客ランク（enum: BRONZE / SILVER / GOLD）
  "region": "TOKYO",             // 配送地域（enum: TOKYO / OTHER）

  "items": [                     // 注文行の配列
    {
      "sku": "A001",              // 商品コード
      "unitPrice": 980,           // 単価（number）
      "qty": 2,                   // 数量（number）
      "tax": "STANDARD"           // 税区分（enum）
    },
    {
      "sku": "B777",
      "unitPrice": 1500,
      "qty": 1,
      "tax": "REDUCED"
    }
  ],

  "coupon": "WELCOME10"          // クーポンコード（任意・optional）
}

出力（計算結果）

業務ロジックが返す計算結果です。
API のレスポンスや画面表示用データにそのまま使えます。

// 計算結果（出力）
{
  "subtotal": 3460,        // 税抜小計（全行の subtotal 合計）
  "taxTotal": 292,         // 税額合計
  "discount": 346,         // 割引合計（会員 + クーポン）
  "shipping": 500,         // 送料
  "grandTotal": 3906       // 最終請求金額
}

コードセクション：文法サンプル集（業務ロジック）

1. enum 定義（業務区分）

// 顧客ランクを表す enum
enum CustomerRank {
  BRONZE = "BRONZE",
  SILVER = "SILVER",
  GOLD = "GOLD"
}

// 税区分を表す enum
enum TaxType {
  STANDARD = "STANDARD",
  REDUCED = "REDUCED",
  EXEMPT = "EXEMPT"
}

// 配送地域
enum Region {
  TOKYO = "TOKYO",
  OTHER = "OTHER"
}

2. データ構造（interface）

// 注文行
interface OrderItem {
  sku: string;          // 商品コード
  unitPrice: number;   // 単価
  qty: number;         // 数量
  tax: TaxType;        // 税区分
}

// 注文全体
interface Order {
  customerRank: CustomerRank; // 顧客ランク
  items: OrderItem[];         // 注文行の配列
  coupon?: string;            // クーポン（任意）
  region: Region;             // 配送地域
}

3. 税計算（switch / enum）

// 税額を計算する関数
function calcTax(amount: number, taxType: TaxType): number {
  switch (taxType) {
    case TaxType.STANDARD:
      return Math.floor(amount * 0.10);
    case TaxType.REDUCED:
      return Math.floor(amount * 0.08);
    case TaxType.EXEMPT:
      return 0;
  }
}

4. 注文明細計算（for...of）

// 注文明細を計算する
function calcLines(items: OrderItem[]) {
  const results = []; // 結果配列

  // 配列を1件ずつ処理
  for (const item of items) {
    const subtotal = item.unitPrice * item.qty; // 行小計
    const tax = calcTax(subtotal, item.tax);    // 税額
    const total = subtotal + tax;                // 行合計

    results.push({
      sku: item.sku,
      subtotal,
      tax,
      total
    });
  }

  return results;
}

5. 割引計算（if / enum）

// 割引額を計算する
function calcDiscount(subtotal: number, rank: CustomerRank, coupon?: string): number {
  let discount = 0;

  // 会員ランク割引
  if (rank === CustomerRank.GOLD) {
    discount += Math.floor(subtotal * 0.05);
  }

  // クーポン割引
  if (coupon === "WELCOME10") {
    discount += Math.floor(subtotal * 0.10);
  }

  return discount;
}

6. 送料計算

// 送料を計算する
function calcShipping(subtotal: number, region: Region): number {
  if (subtotal >= 10000) {
    return 0;
  }

  return region === Region.TOKYO ? 500 : 800;
}

7. 全体処理（map / reduce）

// 注文全体を処理する
function processOrder(order: Order) {
  const lines = calcLines(order.items);

  // 小計を集計
  const subtotal = lines.reduce((sum, l) => sum + l.subtotal, 0);

  // 税合計を集計
  const taxTotal = lines.reduce((sum, l) => sum + l.tax, 0);

  // 割引計算
  const discount = calcDiscount(subtotal, order.customerRank, order.coupon);

  // 送料計算
  const shipping = calcShipping(subtotal, order.region);

  // 最終合計
  const grandTotal = subtotal + taxTotal + shipping - discount;

  return {
    subtotal,
    taxTotal,
    discount,
    shipping,
    grandTotal
  };
}

TypeScript の List / Map / Set / 配列 と 基本型のメソッド

1. TypeScript に「List」はある？

TypeScript（JavaScript）には、 Java や C# のような List クラスはありません。

その代わり、配列（Array） が List の役割を担います。

// List の代わりになる配列
const list: number[] = [1, 2, 3];

2. 配列（Array）

2-1. 配列はサイズ変更可能か？

はい、可能です。
JavaScript の配列は 可変長（動的配列）です。

const arr: number[] = [1, 2];

// 要素を追加
arr.push(3);        // [1, 2, 3]

// 要素を削除
arr.pop();          // [1, 2]

// 途中に追加
arr.splice(1, 0, 99); // [1, 99, 2]

2-2. よく使う配列メソッド

const nums = [1, 2, 3];

// map: 各要素を変換
const doubled = nums.map(n => n * 2); // [2, 4, 6]

// filter: 条件に合うものだけ
const even = nums.filter(n => n % 2 === 0); // [2]

// reduce: 集計
const sum = nums.reduce((a, b) => a + b, 0); // 6

3. Map（キーと値の集合）

Map は「キー → 値」の対応を持つコレクションです。

const userMap = new Map();

userMap.set(1, "john");
userMap.set(2, "alice");

userMap.get(1); // "john"

オブジェクトとの違い

• キーに number や object を使える
• 順序が保証される
• サイズ取得が簡単（map.size）

4. Set（重複しない集合）

Set は 重複を許さない コレクションです。

const ids = new Set();

ids.add(1);
ids.add(1);
ids.add(2);

ids.size; // 2

「既にあるか？」の判定が高速です。

5. string / number にメソッドはある？

あります。
プリミティブ型でも、内部的にはオブジェクトとして扱われます。

5-1. string の主なメソッド

const s = "hello world";

s.length;               // 11
s.includes("world");    // true
s.split(" ");            // ["hello", "world"]

5-2. number の主なメソッド

const n = 3.14159;

n.toFixed(2);   // "3.14"
n.toString();   // "3"

6. 正規表現の使い方

正規表現は RegExp オブジェクトとして使います。

const email = "john@test.com";
const regex = /^(.+)@(.+)$/;

const match = email.match(regex);

6-1. グループの値を取る

if (match) {
  match[0]; // "john@test.com"（全体）
  match[1]; // "john"（1番目のグループ）
  match[2]; // "test.com"（2番目のグループ）
}

7. まとめ

• 配列は List の代わりで、サイズ変更可能
• Map はキー付きデータ、Set は重複防止
• string / number にも豊富なメソッドがある
• 正規表現で文字列を構造的に扱える

TypeScript の文法は、 データを安全に・読みやすく扱うための道具です。

// 配列.reduce( (acc, cur, index, array) => 次のacc, 初期acc )
const result = array.reduce((acc, cur, index, arr) => {
  // acc : 途中経過（累積値）
  // cur : 今処理している要素
  // index : 何番目か
  // arr : 元配列
  return acc; // 次のループに渡す累積値
}, initialValue);

const nums = [10, 20, 30];

// acc は number、初期値 0 から開始
const sum = nums.reduce((acc, cur) => {
  return acc + cur;
}, 0);

console.log(sum); // 60

type Line = { subtotal: number; tax: number };

const lines: Line[] = [
  { subtotal: 1960, tax: 196 },
  { subtotal: 1500, tax: 96 }
];

// 小計合計
const subtotal = lines.reduce((acc, line) => acc + line.subtotal, 0);

// 税合計
const taxTotal = lines.reduce((acc, line) => acc + line.tax, 0);

console.log(subtotal); // 3460
console.log(taxTotal); // 292

type User = { id: number; name: string };

const users: User[] = [
  { id: 1, name: "john" },
  { id: 2, name: "alice" }
];

// Record<number, User> はキーが number の辞書型
const byId = users.reduce((acc, u) => {
  acc[u.id] = u;         // 辞書に登録
  return acc;            // 次のaccに渡す
}, {} as Record<number, User>);

console.log(byId[2].name); // "alice"

const map = users.reduce((acc, u) => {
  acc.set(u.id, u);
  return acc;
}, new Map<number, User>());

console.log(map.get(2)?.name); // "alice"

type Item = { tax: "STANDARD" | "REDUCED"; amount: number };

const items: Item[] = [
  { tax: "STANDARD", amount: 1000 },
  { tax: "STANDARD", amount: 500 },
  { tax: "REDUCED", amount: 1500 }
];

// taxごとに合計を集計する
const sumByTax = items.reduce((acc, it) => {
  acc[it.tax] = (acc[it.tax] ?? 0) + it.amount;
  return acc;
}, {} as Record<"STANDARD" | "REDUCED", number>);

console.log(sumByTax); // { STANDARD: 1500, REDUCED: 1500 }

type Line = { subtotal: number; tax: number };

const lines: Line[] = [
  { subtotal: 1960, tax: 196 },
  { subtotal: 1500, tax: 96 }
];

const summary = lines.reduce((acc, line) => {
  acc.subtotal += line.subtotal;
  acc.taxTotal += line.tax;
  acc.count += 1;
  return acc;
}, { subtotal: 0, taxTotal: 0, count: 0 });

console.log(summary); // { subtotal: 3460, taxTotal: 292, count: 2 }

追補：immutable（不変）・配列操作の実務アンチパターン・Map/Setの使い分け

8. immutable（不変）に書くとは？

「immutable（不変）」とは、元のデータを直接書き換えず、 新しいデータを作って返す書き方です。

なぜ重要か：

• 副作用（意図しない書き換え）が減る
• バグの原因を追いやすい
• React などのUIフレームワークと相性が良い

8-1. const と immutable は別物

const は「変数に別の値を再代入できない」だけで、 オブジェクトや配列の中身は変更できます。

// const でも中身は変えられる
const a = [1, 2];
a.push(3); // OK（中身が変わる）

8-2. 配列を immutable に扱う例（おすすめ）

// 追加（push しない）
const a = [1, 2];
const b = [...a, 3];           // [1, 2, 3]（aは変わらない）

// 先頭追加
const c = [0, ...a];           // [0, 1, 2]

// 置き換え（index 1 を 99 に）
const d = a.map((x, i) => i === 1 ? 99 : x);  // [1, 99]

// 削除（index 1 を削除）
const e = a.filter((_, i) => i !== 1);        // [1]

8-3. オブジェクトを immutable に扱う例

const user = { id: 1, name: "john", email: "a@b.com" };

// 変更（元は変えない）
const user2 = { ...user, email: "new@b.com" };

9. 配列操作の実務アンチパターン（やりがち注意）

9-1. forEach で return しても止まらない

初心者が混乱しやすい点です。forEach の return は 「コールバックから戻る」だけで、ループを止めません。

// ❌ 止まらない
[1, 2, 3].forEach(n => {
  if (n === 2) return; // 2のときだけスキップ（中断ではない）
  console.log(n);
});

// ✅ 中断したいなら for...of
for (const n of [1, 2, 3]) {
  if (n === 2) break;  // ここで中断できる
  console.log(n);
}

9-2. map で副作用だけやる

map は「変換して新しい配列を返す」ための関数です。 返り値を捨てて副作用だけに使うのは避けます。

// ❌ map の結果を使っていない
items.map(x => console.log(x));

// ✅ 副作用なら for...of / forEach
for (const x of items) {
  console.log(x);
}

9-3. ループ中に splice で削除して index が崩壊

途中削除は index がずれてバグりやすいです。基本は filter。

// ❌ バグりがち（削除でindexがずれる）
for (let i = 0; i < arr.length; i++) {
  if (arr[i] < 0) arr.splice(i, 1);
}

// ✅ filter で新配列
const cleaned = arr.filter(x => x >= 0);

9-4. sort は元配列を破壊する

sort は in-place（元配列を書き換え）なので注意です。

const a = [3, 1, 2];

// ❌ a が書き換わる
a.sort();

// ✅ コピーしてから sort（immutable）
const b = [...a].sort();

9-5. == を使う（型変換の罠）

// ❌ 型変換が起きる
0 == "0" // true

// ✅ ふつうは厳密比較
0 === "0" // false

10. Map / Set を使うべきケース・使わないケース

10-1. まずは配列で十分なケース

• 要素数が小さい（数十〜数百）
• 順番に処理するだけ（for...of）
• 検索がたまにしか発生しない

10-2. Map を使うべきケース（キー検索が中心）

「id を渡したら一発で見つけたい」ケースは Map が強いです。 配列の find は毎回先頭から探すため、件数が増えると遅くなります。

// 配列で探す（毎回O(n)）
const users = [{ id: 1, name: "john" }, { id: 2, name: "alice" }];
const u = users.find(x => x.id === 2);

// Map にする（検索O(1)に近い）
const userMap = new Map();
for (const x of users) {
  userMap.set(x.id, x);
}
const u2 = userMap.get(2);

10-3. Set を使うべきケース（重複排除・存在チェック）

// 重複排除
const ids = [1, 1, 2, 3, 3];
const unique = [...new Set(ids)]; // [1, 2, 3]

// 存在チェック
const allowed = new Set(["jpg", "png", "webp"]);
allowed.has("png"); // true

10-4. Map/Set を使う時の注意（参照同一性）

オブジェクトを Set/Map のキーにする場合は、 「同じ内容」ではなく「同じ参照」かどうかで判定されます。

const a = { x: 1 };
const b = { x: 1 };

const s = new Set<object>();
s.add(a);

s.has(a); // true
s.has(b); // false（内容が同じでも別オブジェクト）

11. string / number メソッドの実務的まとめ（追加）

「一覧」と言うと膨大になるため、実務で頻出のものを目的別に整理します。 ここに載っていないメソッドもありますが、まずはこれで十分です。

11-1. string（検索・切り出し・整形）

const s = "  Hello,World  ";

const trimmed = s.trim();               // "Hello,World"
const parts = trimmed.split(",");        // ["Hello", "World"]
const hello = parts[0].toLowerCase();    // "hello"
const world = parts[1].toUpperCase();    // "WORLD"

11-2. number（表示・丸め・変換）

const n = 3.14159;

const s1 = n.toFixed(2); // "3.14"（文字列）
const s2 = n.toString(); // "3"

変換はメソッド以外にも頻出です：

Number("123"); // 123
String(123);   // "123"
parseInt("10", 10); // 10
parseFloat("3.14"); // 3.14

12. 正規表現：グループ取得までを体系的に

12-1. 基本：match とグループ

const text = "john@company.com";

// () がキャプチャグループ
const re = /^(.+)@(.+)$/;

const m = text.match(re);

if (m) {
  m[0]; // "john@company.com"（全体）
  m[1]; // "john"（1番目のグループ）
  m[2]; // "company.com"（2番目のグループ）
}

12-2. 名前付きグループ（取る側が読みやすい）

const text = "2026-02-15";

// (?<name>...) が名前付きグループ
const re = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/;

const m = text.match(re);

if (m && m.groups) {
  m.groups.year;  // "2026"
  m.groups.month; // "02"
  m.groups.day;   // "15"
}

12-3. 複数ヒット：matchAll

const log = "id=1 name=john; id=2 name=alice;";
const re = /id=(\d+)\s+name=([a-z]+)/g;

// matchAll はイテレータなので for...of と相性が良い
for (const m of log.matchAll(re)) {
  const id = Number(m[1]);
  const name = m[2];
  console.log(id, name);
}