TypeScriptでJSONを扱う: JSON.parse の型とインターフェース化

JSON.parse は any を返すので、TypeScriptは結果を代入した先のどんな型も受け入れます。そのためパースした JSON への型付けは1行で済みますが、その型はあなたがした約束であって、コンパイラーがチェックしたものではありません:

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

const text = '{"name":"Ada","age":36}';
const user: User = JSON.parse(text); // JSON.parse returns any

console.log(user.name.toUpperCase(), user.age + 1); // ADA 37

// The annotation is a promise, not a check:
const wrong: User = JSON.parse('{"name":"Bob","age":"41"}');
console.log(wrong.age + 1); // 411, a string concatenation

2つ目のオブジェクトの age は文字列 "41" です。any は何にでも代入できるので、TypeScriptはそれでも number とみなし、プログラムは 411 と出力します。直前に自分のコードが書いた JSON なら型注釈で十分です。リクエスト、ファイル、ローカルストレージから来るデータは検証しましょう。

unknown にパースする

結果を unknown として型付けすると、プロパティを使う前にチェックすることをコンパイラーが要求します:

// This does not compile: unknown must be narrowed before use.
const data: unknown = JSON.parse('{"name":"Ada"}');

console.log(data.name);

エラーは index.ts(4,13): error TS18046: 'data' is of type 'unknown'. です。そのあと書くチェックのひとつひとつが、data を少しずつ絞り込んでいきます。

型ガードで検証する

型ガードは value is User を返す関数です。true を返すと、TypeScriptはそれ以降その値を User として扱います。中のチェックは本物の実行時のチェックです:

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

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

function parseUser(text: string): User {
  const data: unknown = JSON.parse(text);
  if (!isUser(data)) {
    throw new Error("Not a valid user: " + text);
  }
  return data; // narrowed to User
}

console.log(parseUser('{"name":"Ada","age":36}')); // { name: 'Ada', age: 36 }
try {
  parseUser('{"name":"Bob","age":"41"}');
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Not a valid user: {"name":"Bob","age":"41"}
}

JSON.parse 自体も不正なテキストには SyntaxError を投げるので、実際のコードでは try/catch でも囲みます。大きなデータや入れ子のデータでは手書きの型ガードが長くなります。Zod や Valibot のようなスキーマライブラリを使えば、形を一度宣言するだけで、バリデーターとTypeScriptの型の両方をそこから導けます。

JSON から TypeScriptのインターフェースへ

JSON のサンプルを型に変換するのは機械的な作業です。次のレスポンスがあるとします:

{
    "id": 42,
    "title": "Learn TypeScript",
    "done": false,
    "owner": { "id": 7, "name": "Ada" },
    "tags": ["study", "ts"],
    "dueDate": "2024-03-15T10:30:00Z",
    "notes": null
}

各値をその型に対応させ、入れ子のオブジェクトには独自のインターフェースを与え、変わりうるものに印を付けます:

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

interface Task {
  id: number;
  title: string;
  done: boolean;
  owner: Owner;         // nested object: its own interface
  tags: string[];       // array of strings
  dueDate: string;      // JSON has no dates: it is an ISO string
  notes: string | null; // null in this sample, text in others
  priority?: number;    // missing in this sample, present in others
}

const task: Task = {
  id: 42,
  title: "Learn TypeScript",
  done: false,
  owner: { id: 7, name: "Ada" },
  tags: ["study", "ts"],
  dueDate: "2024-03-15T10:30:00Z",
  notes: null,
};

console.log(task.owner.name, task.tags.length, task.priority ?? "none"); // Ada 2 none

サンプルがひとつだけでは、どのフィールドが省略可能か、null になりうるかはわかりません。? と | null を決める前に、複数のレスポンスや API のドキュメントを確認しましょう。

日付と reviver

JSON には日付の型がないので、日付は文字列として届きます。JSON.parse の2番目の引数である reviver はキーごとに呼ばれ、日付を作り直せます:

interface Order {
  id: number;
  placedAt: Date;
}

const text = '{"id":7,"placedAt":"2024-03-15T10:30:00.000Z"}';

const order: Order = JSON.parse(text, (key, value) =>
  key === "placedAt" ? new Date(value) : value
);

console.log(order.placedAt instanceof Date, order.placedAt.getUTCHours()); // true 10
console.log(JSON.stringify(order, null, 2));

reviver の value パラメーターは any で、結果も any なので、Order 型はチェックされたのではなく信頼されているだけです。JSON.stringify(order, null, 2) は出力をスペース2つでインデントし、Date を ISO 形式の文字列に戻します。

JSON.stringify で失われるもの

JSON.stringify の戻り値の型は string です。変換した値が同じ形で戻ってくるとは限りませんが、型は警告してくれません:

interface Meeting {
  title: string;
  at: Date;
  tags: Set<string>;
}

const meeting: Meeting = {
  title: "Launch",
  at: new Date("2024-03-15T10:30:00Z"),
  tags: new Set(["release"]),
};

const json = JSON.stringify(meeting);
console.log(json); // {"title":"Launch","at":"2024-03-15T10:30:00.000Z","tags":{}}

const back = JSON.parse(json);
console.log(typeof back.at, back.tags); // string {}

const nothing: string = JSON.stringify(undefined); // typed string...
console.log(nothing); // ...but the value is undefined

実行時のルールは普通のJavaScriptと同じで、JavaScriptの JSON で説明しています。

あらゆる JSON の値を表す型

任意の JSON を扱うコードでは、再帰的な型を使うと、JSON が保持できるものを正確に表し、保持できない値を拒否できます:

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

function countLeaves(value: JsonValue): number {
  if (Array.isArray(value)) {
    return value.reduce((n: number, v) => n + countLeaves(v), 0);
  }
  if (typeof value === "object" && value !== null) {
    return Object.values(value).reduce((n: number, v) => n + countLeaves(v), 0);
  }
  return 1;
}

const doc: JsonValue = { name: "Ada", langs: ["en", "fr"], address: { city: "London", zip: null } };
console.log(countLeaves(doc)); // 5

// @ts-expect-error a Date is not a JSON value
const bad: JsonValue = { at: new Date() };

コメントがなければ、Date オブジェクトは JsonValue ではないので、最後の行はコンパイルエラーになります。

.json ファイルを import する

.json ファイルはモジュールのように import でき、TypeScriptはその内容から型を推論します:

{ "name": "app", "port": 8080, "tags": ["a"] }

// CommonJS output, or a bundler
import config from "./config.json";
const port: number = config.port; // typed from the file: number

// An ES module under module: nodenext
import settings from "./config.json" with { type: "json" };

TypeScript 7 では、module が nodenext、node20、commonjs、esnext、preserve のいずれかなら追加の設定なしで動きます。node16 と node18 では、"resolveJsonModule": true を追加するまではエラー TS2732 Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension. で失敗します。これを false にすると、どこでも JSON の import が無効になります。nodenext や node20 の ES モジュールでは、import に with { type: "json" } 属性が必要で（ないとエラー TS1543）、デフォルトの import しか使えません（import { port } はエラー TS1544）。tsc は import された .json ファイルを、コンパイルしたJavaScriptと並べて outDir にコピーします。