محوّل JSON إلى TypeScript

ما هو تحويل JSON إلى TypeScript؟

الصق حمولة JSON وستحصل في المقابل على واجهات TypeScript — عقود ذات أنواع محددة تصف بدقة الخصائص التي يمتلكها كائن ما ونوع كل خاصية. بدونها، تصل البيانات القادمة من JSON.parse() بنوع any، مما يحرمك من مساعدة المحرر وفحوصات المُصرِّف عند الوصول إلى الخصائص أو تعيينها. يمنحك تحويل JSON إلى TypeScript تلك السلامة دون الحاجة إلى كتابة الواجهات يدويًا.

يغطي TypeScript جميع أنواع قيم JSON الستة: string وnumber وboolean وnull وobject وarray. كل كائن JSON متداخل يتحول إلى واجهة مسماة مستقلة. تُستنتج أنواع المصفوفات من عنصرها الأول. تطابق النتيجة ما يعيده JSON.parse() فعليًا في وقت التشغيل، لذا تعكس الواجهات بيانات حقيقية لا تخمينات.

كتابة الواجهات يدويًا لـJSON كبير أو متداخل بعمق مهمة مضنية وعرضة للأخطاء. يقرأ مولّد JSON إلى TypeScript البنية تلقائيًا، ويتعامل مع التداخل بشكل تكراري، ويُخرج كود الواجهات النظيف في ثوانٍ. يكون هذا مفيدًا بشكل خاص عند التعامل مع واجهة API غير مألوفة، أو النمذجة ببيانات تجريبية، أو ترحيل قاعدة كود JavaScript إلى TypeScript. كما يعفيك من تتبع أسماء الخصائص المتداخلة وأنواعها يدويًا، حتى تركز على منطق التطبيق بدلًا من نماذج الأنواع المتكررة.

لماذا تستخدم مولّد JSON إلى TypeScript؟

توليد واجهات TypeScript يدويًا أمر عملي للكائنات الصغيرة، لكنه يتعقد سريعًا مع البنى المتداخلة أو استجابات API الكبيرة. تخيّل استجابة API تحتوي على 50 حقلًا بثلاثة مستويات من التداخل — كتابتها يدويًا تعني عشرات الواجهات، كل منها مصدر محتمل لأخطاء إملائية أو حقول قابلة للإلغاء مفقودة. يُنتج المولّد الآلي المجموعة الكاملة في ثوانٍ ويقلل احتمال عدم تطابق الأنواع بين كودك والبيانات التي يستهلكها. وما هو أبعد من الدقة، فهو يُبقي أنواعك متزامنة مع عقد الـAPI الفعلي. عندما تغيّر خدمة ما شكل استجابتها، الصق JSON المحدَّث وأعِد التوليد — أسرع بكثير من البحث عن كل خاصية تغيّرت في ملف واجهة مكتوب يدويًا.

حالات استخدام تحويل JSON إلى TypeScript

مرجع تعيين أنواع JSON إلى TypeScript

كل قيمة JSON تتعيّن على نوع TypeScript. يوضح الجدول أدناه كيف يُترجم كل نوع JSON أساسي وبنيوي. يتبع هذا التعيين معيار JSON وفق ECMA-404 والأنواع المدمجة في TypeScript.

interface مقابل type في TypeScript

يقدم TypeScript طريقتين لوصف أشكال الكائنات: تعريفات interface وأسماء type المستعارة. كلاهما يعمل لتمثيل بنى JSON، لكنهما يختلفان في سلوك التوسيع والدمج. تُخرج معظم مولّدات JSON إلى TypeScript واجهات لأنها الخيار المعتاد لأشكال الكائنات في TypeScript.

أمثلة برمجية

فيما يلي أمثلة على توليد واجهات TypeScript من JSON بلغات وأدوات مختلفة. كل مقتطف يُنتج مخرجات قابلة للتشغيل.

// Manual interface definition from a JSON shape
const json = '{"id": 1, "name": "Alice", "active": true}';
const parsed = JSON.parse(json);

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

const user: User = parsed;
console.log(user.name); // "Alice" — fully typed

import JsonToTS from 'json-to-ts';

const json = {
  id: 1,
  name: "Alice",
  address: { street: "123 Main St", city: "Springfield" },
  tags: ["admin", "user"]
};

const interfaces = JsonToTS(json, { rootName: "User" });
console.log(interfaces.join("\n\n"));
// interface Address {
//   street: string;
//   city: string;
// }
//
// interface User {
//   id: number;
//   name: string;
//   address: Address;
//   tags: string[];
// }

# Install: pip install datamodel-code-generator
# Generate TypeScript-style types from JSON using Pydantic models

# Command line:
# datamodel-codegen --input data.json --output model.py

# Or generate TypeScript directly with quicktype:
# pip install quicktype
# quicktype --lang ts --src data.json --out types.ts

import json

data = {"id": 1, "name": "Alice", "scores": [98, 85, 92]}

# Python equivalent using TypedDict (Python 3.8+)
from typing import TypedDict, List

class User(TypedDict):
    id: int
    name: str
    scores: List[int]

user: User = data  # type-checked by mypy

# Install quicktype globally
npm install -g quicktype

# Generate TypeScript interfaces from a JSON file
quicktype --lang ts --src data.json --out types.ts

# From a JSON string via stdin
echo '{"id": 1, "name": "Alice"}' | quicktype --lang ts

# Output:
# export interface Root {
#   id:   number;
#   name: string;
# }

الأسئلة الشائعة