العمل مع YAML في JavaScript (Node.js): التحليل والتوليد والتحقق

العمل مع YAML في JavaScript (Node.js): دليل شامل

\n\n

YAML (YAML Ain't Markup Language) هو تنسيق تسلسل بيانات قابل للقراءة البشرية، يُستخدم على نطاق واسع لملفات التكوين ووصف API وخطوط أنابيب CI/CD وتبادل البيانات. في نظام Node.js البيئي، توجد عدة مكتبات قوية للعمل مع YAML. في هذه المقالة، سنستعرض بالتفصيل الأدوات الرئيسية وإمكانياتها وأمثلة استخدامها.

\n\n

المكتبات الشائعة لـ YAML في Node.js

\n\n

أكثر المكتبات شيوعًا للعمل مع YAML في بيئة Node.js:

\n\n

\n
• js-yaml — المكتبة الأكثر شهرة والتي تحظى بدعم نشط. تدعم مجموعة كاملة من العمليات: التحليل والتسلسل والأنماط والأنواع المخصصة.
\n
• yaml (حزمة yaml) — بديل حديث يدعم التحليل الصارم والتعليقات وAST (شجرة التركيب المجردة).
\n
• yamljs — مكتبة خفيفة الوزن بواجهة برمجة تطبيقات بسيطة، مناسبة للمهام الأساسية.
\n

\n\n

تثبيت مكتبة js-yaml

\n\n

للبدء في العمل مع YAML في Node.js، قم بتثبيت المكتبة عبر npm:

\n\n

npm install js-yaml

\n\n

بعد التثبيت، قم باستيراد المكتبة إلى مشروعك:

\n\n

const yaml = require('js-yaml');\nconst fs = require('fs');

\n\n

تحليل YAML إلى كائن JavaScript

\n\n

العملية الأساسية هي تحويل سلسلة YAML إلى كائن JavaScript:

\n\n

const yamlString = `\nserver:\n  host: localhost\n  port: 8080\n  ssl: true\ndatabases:\n  - name: users\n    type: postgres\n  - name: logs\n    type: mongodb\n`;\n\ntry {\n  const data = yaml.load(yamlString);\n  console.log(data.server.host); // "localhost"\n  console.log(data.databases[0].name); // "users"\n} catch (e) {\n  console.error('خطأ في تحليل YAML:', e.message);\n}

\n\n

تقوم طريقة yaml.load() بتحويل سلسلة YAML إلى كائن بأمان. للتحميل من ملف، استخدم:

\n\n

try {\n  const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));\n  console.log(config);\n} catch (e) {\n  console.error('خطأ في قراءة التكوين:', e);\n}

\n\n

تسلسل كائن JavaScript إلى YAML

\n\n

العملية العكسية — تحويل كائن إلى سلسلة YAML:

\n\n

const configObject = {\n  app: {\n    name: "MyApp",\n    version: "1.0.0"\n  },\n  features: ["auth", "logging", "analytics"],\n  database: {\n    host: "db.example.com",\n    port: 5432\n  }\n};\n\nconst yamlString = yaml.dump(configObject, {\n  indent: 2,\n  lineWidth: 120,\n  noRefs: true\n});\n\nconsole.log(yamlString);\n// الإخراج:\n// app:\n//   name: MyApp\n//   version: 1.0.0\n// features:\n//   - auth\n//   - logging\n//   - analytics\n// database:\n//   host: db.example.com\n//   port: 5432

\n\n

معاملات طريقة yaml.dump():

\n

\n
• indent — عدد المسافات للمسافات البادئة (الافتراضي 2)
\n
• lineWidth — أقصى طول للسطر (الافتراضي 80)
\n
• noRefs — تعطيل استخدام المراسي والمراجع
\n
• skipInvalid — تخطي القيم غير الصالحة بدلاً من إلقاء خطأ
\n

\n\n

العمل مع الأنواع المخصصة لـ YAML

\n\n

تدعم js-yaml الأنماط والأنواع المخصصة للبيانات. على سبيل المثال، يمكن إضافة دعم التواريخ:

\n\n

const yaml = require('js-yaml');\n\n// إنشاء نمط مخصص مع دعم التواريخ\nconst schema = yaml.DEFAULT_SCHEMA.extend([\n  new yaml.Type('tag:yaml.org,2002:timestamp', {\n    kind: 'scalar',\n    resolve: (data) => {\n      return !isNaN(Date.parse(data));\n    },\n    construct: (data) => {\n      return new Date(data);\n    },\n    instanceOf: Date,\n    represent: (date) => {\n      return date.toISOString();\n    }\n  })\n]);\n\nconst yamlString = 'event_date: 2024-03-15T14:30:00Z';\nconst parsed = yaml.load(yamlString, { schema });\nconsole.log(parsed.event_date inst