JSON trong TypeScript: kiểu JSON.parse, JSON sang interface

JSON.parse trả về any, nên TypeScript chấp nhận mọi kiểu bạn gán cho kết quả. Nhờ vậy, khai báo kiểu cho JSON sau khi parse chỉ mất một dòng, nhưng cũng có nghĩa kiểu đó là lời hứa của bạn, không phải thứ trình biên dịch kiểm tra:

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

Đối tượng thứ hai có age là chuỗi "41". TypeScript vẫn coi nó là number, vì any gán được cho mọi kiểu, và chương trình in ra 411. Với JSON do chính code của bạn vừa tạo ra, chú thích kiểu như vậy là đủ. Với dữ liệu từ request, từ tệp hay từ local storage, hãy kiểm tra nó.

Parse vào unknown

Khai báo kết quả là unknown buộc trình biên dịch đòi một bước kiểm tra trước khi bạn dùng bất kỳ thuộc tính nào:

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

console.log(data.name);

Lỗi in ra là index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Mỗi bước kiểm tra bạn viết sau đó lại thu hẹp data thêm một chút.

Kiểm tra bằng type guard

Type guard là một hàm trả về value is User. Khi hàm trả về true, TypeScript coi giá trị là User từ đó trở đi, và các bước kiểm tra bên trong hàm là kiểm tra thật lúc chạy:

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"}
}

Bản thân JSON.parse ném SyntaxError khi văn bản sai định dạng, nên code thực tế còn bọc nó trong try/catch. Với dữ liệu lớn hoặc lồng nhiều tầng, type guard viết tay sẽ rất dài; các thư viện schema như Zod hay Valibot cho phép bạn khai báo cấu trúc một lần rồi suy ra cả hàm kiểm tra lẫn kiểu TypeScript từ đó.

Chuyển JSON sang interface TypeScript

Chuyển một mẫu JSON thành kiểu là việc làm theo quy tắc. Với response này:

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

Ánh xạ mỗi giá trị sang kiểu của nó, cho mỗi đối tượng lồng nhau một interface riêng, và đánh dấu những gì có thể thay đổi:

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

Một mẫu duy nhất không cho bạn biết trường nào là tùy chọn hay có thể null. Hãy xem vài response khác, hoặc tài liệu của API, trước khi quyết định dùng ? và | null.

Ngày tháng và hàm reviver

JSON không có kiểu ngày tháng, nên ngày tháng đến dưới dạng chuỗi. Tham số thứ hai của JSON.parse, gọi là reviver, được gọi cho từng khóa và có thể dựng lại chúng:

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));

Tham số value của reviver có kiểu any, kết quả cũng vậy, nên kiểu Order vẫn chỉ được tin chứ không được kiểm tra. JSON.stringify(order, null, 2) thụt lề đầu ra hai dấu cách và chuyển Date trở lại chuỗi ISO.

JSON.stringify và những gì bị mất

JSON.stringify được khai báo trả về string. Các giá trị nó chuyển đổi không phải lúc nào cũng quay về như cũ, và kiểu không cảnh báo bạn điều đó:

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

Các quy tắc lúc chạy giống hệt JavaScript thuần, được trình bày trong JSON trong JavaScript.

Một kiểu cho mọi giá trị JSON

Khi code xử lý JSON bất kỳ, một kiểu đệ quy mô tả chính xác những gì JSON có thể chứa và từ chối những giá trị nó không chứa được:

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() };

Nếu bỏ chú thích, dòng cuối là lỗi biên dịch vì một đối tượng Date không phải là JsonValue.

Import tệp .json

Tệp .json có thể được import như một module, và TypeScript suy ra kiểu của nó từ nội dung:

{ "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" };

Trong TypeScript 7, cách này chạy mà không cần thiết lập thêm khi module là nodenext, node20, commonjs, esnext hoặc preserve. Với node16 và node18, nó báo lỗi TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., cho đến khi bạn thêm "resolveJsonModule": true; đặt giá trị này thành false sẽ tắt việc import JSON ở mọi nơi. Trong một ES module dùng nodenext hoặc node20, câu lệnh import cần thuộc tính with { type: "json" } (thiếu nó sẽ gặp lỗi TS1543) và chỉ cho phép default import (lỗi TS1544 với import { port }). tsc sao chép tệp .json được import vào outDir, cạnh JavaScript đã biên dịch.