JSON ב-TypeScript: טיפוס ל-JSON.parse, JSON ל-interface ו-imports

JSON.parse מחזיר any, ולכן TypeScript מקבל כל טיפוס שתשימו בו את התוצאה. בזכות זה, מתן טיפוס ל-JSON מפוענח לוקח שורה אחת, אבל זה גם אומר שהטיפוס הוא הבטחה שלכם, ולא משהו שהקומפיילר בודק:

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

באובייקט השני age הוא המחרוזת "41". TypeScript עדיין מתייחס אליו כ-number, כי אפשר להשים any לכל דבר, והתוכנית מדפיסה 411. ל-JSON שהקוד שלכם כתב לפני רגע, ה-annotation מספיק. לנתונים מבקשת רשת, מקובץ או מ-local storage, אמתו אותם.

פענוח לתוך 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 עוד קצת.

אימות עם Type Guard

type guard הוא פונקציה שמחזירה 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. ב-payloads גדולים או מקוננים, guards שנכתבים ביד מתארכים; ספריות סכמה כמו Zod או Valibot מאפשרות להצהיר על המבנה פעם אחת ולגזור ממנו גם את פונקציית האימות וגם את הטיפוס של TypeScript.

המרת JSON ל-interface של 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 משלהם, וסמנו את מה שיכול להשתנות:

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. בדקו כמה תשובות, או את התיעוד של ה-API, לפני שאתם מחליטים על ? ועל | null.

תאריכים וה-Reviver

ל-JSON אין טיפוס תאריך, ולכן תאריכים מגיעים כמחרוזות. הארגומנט השני של JSON.parse, ה-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));

הפרמטר value של ה-reviver הוא any, וכך גם התוצאה, ולכן עדיין סומכים על הטיפוס Order ולא בודקים אותו. JSON.stringify(order, null, 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 רגיל, ומוסברים ב-JSON ב-JavaScript.

טיפוס לכל ערך 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

אפשר לייבא קובץ .json כמו מודול, ו-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 זה נכשל עם השגיאה TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., עד שמוסיפים "resolveJsonModule": true; הגדרה שלו ל-false מכבה ייבוא JSON בכל מקום. ב-ES module תחת nodenext או node20, הייבוא צריך את ה-attribute with { type: "json" } (שגיאה TS1543 בלעדיו), ורק default import מותר (שגיאה TS1544 עבור import { port }). tsc מעתיק את קובץ ה-.json המיובא ל-outDir, ליד ה-JavaScript המקומפל.