إنتقل إلى المحتوى الرئيسي

@powerduck/conf-patch

@powerduck/conf-patch مكتبة لتحرير الإعدادات تعتمد بنية من طبقتين. تطبّق دلالات RFC 6902 JSON Patch على سلاسل JSON وJSONC وYAML مع الحفاظ على التعليقات والتنسيق، وتوفّر كتابة ذرّية وأقفال ملفات بين العمليات في Node.js وElectron.

لماذا conf-patch؟​

غالبًا ما يتطلب تحرير ملفات الإعدادات برمجيًا الاختيار بين إعادة تسلسل المستند كاملًا، مما قد يغيّر التعليقات والتنسيق، وبين معالجة نصية يدوية عرضة للأخطاء. توفّر conf-patch ما يلي:

  • تعديلات تدريجية تحافظ على التعليقات في JSON/JSONC باستخدام jsonc-parser، وتعديل شجرة AST في YAML باستخدام yaml. لا يُعاد تسلسل JSON/JSONC كاملًا؛ أما YAML فيُعاد تسلسل شجرته المعدّلة.
  • كتابة ذرّية عبر ملف مؤقت ثم إعادة تسميته، لتجنّب ترك الملف المستهدف مكتوبًا جزئيًا.
  • أقفال بين العمليات مع رموز ملكية، وفترات انتظار متزايدة أُسّيًا بين المحاولات، واستعادة الأقفال القديمة.
  • واجهة تعمل في بيئات متعددة: تعمل الطبقة الأساسية أيضًا في المتصفحات ودوال Edge والتطبيقات التي تستخدم تخزين IndexedDB.

بنية من طبقتين​

┌──────────────────────────────────────────────────────────────┐
│                     Application code                          │
├──────────────────────────────────────────────────────────────┤
│  File layer (Node.js / Electron only)                         │
│  ┌───────────────┐ ┌────────────────┐ ┌──────────────────┐  │
│  │ readConfigFile │ │ writeConfigFile│ │ patchConfigFile   │  │
│  │ setConfigValue │ │ deleteConfig…  │ │ withFileLock     │  │
│  └──────┬────────┘ └───────┬────────┘ └────────┬─────────┘  │
│         │                  │                   │            │
│  ┌──────▼──────────────────▼───────────────────▼───────────┐ │
│  │           Core layer (browser-safe, zero Node deps)      │ │
│  │  patchContent   setContentValue   deleteContentValue     │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

الطبقة الأساسية — @powerduck/conf-patch/core (متوافقة مع المتصفح)​

دوال نقية تتعامل مع السلاسل النصية، دون الاعتماد على node:fs أو node:path أو واجهات خاصة بـ Node.js. يمكن تضمين هذا المسار الفرعي في شيفرة المتصفح أو دوال Edge أو عامل الخدمة.

الدالةالغرض
patchContentتطبيق عمليات RFC 6902 على سلسلة إعدادات
setContentValueتعيين قيمة متداخلة أو إنشاؤها باستخدام add
deleteContentValueحذف مفتاح أو عنصر مصفوفة باستخدام remove

طبقة الملفات — @powerduck/conf-patch (Node.js / Electron)​

دوال غير متزامنة لقراءة الملفات الفعلية وكتابتها، تضيف الكتابة الذرّية والأقفال إلى الطبقة الأساسية.

الدالةالغرض
readConfigFileقراءة نص UTF-8 من مسار ملف أو عنوان file://
writeConfigFileكتابة المحتوى ذرّيًا مع قفل اختياري
patchConfigFileتنفيذ معاملة قراءة وتعديل وكتابة ضمن قفل الملف
setConfigValueتعيين قيمة متداخلة في ملف
deleteConfigValueحذف قيمة متداخلة من ملف
withFileLockتنفيذ مهمة تحت قفل حصري
releaseAllLocalLocksتحرير جميع الأقفال التي تملكها العملية الحالية

التنسيقات المدعومة​

التنسيقالامتدادالسلوك
JSON.jsonJSON قياسي مع تعديلات تدريجية باستخدام jsonc-parser.
JSONC.jsoncJSON مع تعليقات وفواصل ختامية. تُحفَظ التعليقات.
YAML.yaml, .ymlYAML 1.2. يحافظ تعديل AST على التعليقات والمراسي والمسافات البادئة.

تربط detectFormat امتداد الملف بنوع ConfigFormat. تؤدي الامتدادات الأخرى إلى خطأ ما لم تحدد format صراحةً.

عمليات RFC 6902​

تطبّق conf-patch جزءًا محددًا من RFC 6902. العمليات المدعومة هي فقط:

opالسلوك
"add"الإدراج عند فهرس مصفوفة، أو إضافة خاصية كائن أو استبدالها
"replace"استبدال قيمة موجودة؛ يجب أن يكون المسار موجودًا
"remove"حذف مفتاح أو عنصر مصفوفة موجود؛ يجب أن يكون المسار موجودًا
حذر

العمليات "move" و"copy" و"test" غير مدعومة. يقصر النوع JsonPatchOp قيمة op على "add" | "replace" | "remove".

ملاحظات على السلوك:

  • تؤدي add عند فهرس مصفوفة إلى إدراج عنصر وفق RFC 6902. استخدم replace لاستبدال عنصر موجود.
  • تتطلب add وجود المسار الأب مسبقًا. أنشئ الآباء قبل الأبناء.
  • تتطلب replace وremove وجود المسار المستهدف.
  • عند استخدام strict: true، وهو الافتراضي، تؤدي العملية الفاشلة إلى استثناء. وعند استخدام strict: false، تُتخطى العملية ويُسجّل تحذير.

الحفاظ على التعليقات والتنسيق​

  • JSON/JSONC: تُحسب التعديلات كنطاقات نصية استنادًا إلى شجرة البنية، فتُحفَظ التعليقات المحيطة والفواصل الختامية والمسافات البادئة.
  • YAML: تُعدّل شجرة AST الخاصة بـ yaml مباشرةً ثم يُعاد تسلسلها، مع الحفاظ على التعليقات والمراسي والأسماء المستعارة والمسافات البادئة.

التحقق من OpenAPI​

تتحقق conf-patch من مستندات OpenAPI/Swagger عبر واجهة تضيف ضوابط حماية إلى @powerduck/openapi-parser:

  • تتحقق validateOpenAPISpec من محتوى JSON أو YAML الخام.
  • تتحقق validateOpenAPIFile من المستند عبر مسار الملف.
  • تشمل معالجة المدخلات حدود الحجم وتقييد المسارات (allowedRootDirectory) وفحص تعقيد البنية والمهل الزمنية والإلغاء باستخدام AbortSignal.
  • تؤدي حالات الفشل إلى OpenApiValidationError يتضمن code قابلًا للمعالجة برمجيًا.

الخطوات التالية​

  • التثبيت — أضف conf-patch وتعرّف إلى نقطتي الدخول.
  • البدء السريع — عدّل سلسلة في المتصفح وملفًا على القرص.
  • مرجع API — جميع الصادرات والأنواع والخيارات.
  • أمثلة — أمثلة قابلة للتشغيل لـ JSON وYAML وJSONC والتحقق من OpenAPI والأقفال.