JSON في TypeScript: نوع JSON.parse وتحويل JSON إلى interface

يعيد 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 كتبه كودك نفسه قبل لحظة، تحديد النوع لا بأس به. أما للبيانات القادمة من طلب أو ملف أو من التخزين المحلي، فتحقق منها.

التحليل إلى 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 أيضًا. مع البيانات الكبيرة أو المتداخلة تطول الحراسات المكتوبة يدويًا؛ ومكتبات المخططات مثل 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. انظر في عدة استجابات، أو في توثيق الواجهة البرمجية، قبل أن تستقر على ? و| 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 مع nodenext أو node20 يحتاج الاستيراد إلى السمة with { type: "json" } (الخطأ TS1543 دونها)، ولا يُسمح إلا بالاستيراد الافتراضي (الخطأ TS1544 مع import { port }). وينسخ tsc ملف .json المستورد إلى outDir بجوار JavaScript المُترجم.