عرّف مرة واحدة، وثق في كل مكان: غوص عميق في CtroEnv

تستخدم واجهة برمجة التطبيقات (API) الأساسية لـ CtroEnv أربعة مصانع للمدققين (validator factories). يمكنك استخدامها لتأمين متغيرات البيئة الخاصة بك بكل سهولة.

إليك كيفية عملها:

• string() — استخدم هذا للنصوص. يمكنك إضافة قواعد لروابط URL، أو رسائل البريد الإلكتروني، أو المنافذ (ports)، أو أطوال محددة. كما يدعم التعبيرات النمطية (regex) للأنماط المخصصة.

• number() — استخدم هذا للقيم الرقمية. يقوم بتحويل النصوص مثل "3000" إلى أرقام فعلية. يمكنك فرض الأعداد الصحيحة، أو القيم الموجبة، أو نطاقات محددة.

• boolean() — استخدم هذا لقيم true/false. يتعامل تلقائياً مع النصوص مثل "true" أو الأرقام مثل "1". هذا مثالي لأعلام الميزات (feature flags).

• pick() — استخدم هذا لتقييد القيم بقائمة محددة. يقوم بإنشاء أنواع حرفية (literal types) بحيث يعرف الكود الخاص بك بالضبط السلاسل النصية المسموح بها. بل ويقترح تصحيحات في حال ارتكبت خطأً مطبعياً.

طرق مفيدة لكل مدقق:

• .default(value) — يضع قيمة بديلة في حال فقدان المتغير.
• .optional() — يسمح بأن تكون القيمة غير معرفة (undefined).
• .describe(text) — يضيف توثيقاً لرسائل الخطأ والوثائق الخاصة بك.
• .secret() — يقوم بإخفاء القيم الحساسة في مخرجات الطرفية (terminal).
• .validate(fn) — يتيح لك كتابة منطق مخصص لقواعد محددة.

يعمل CtroEnv عبر بيئات مختلفة:

• Node.js: استخدم nodeSource() أو loadEnv() لقراءة ملفات process.env أو .env.
• Vite: استخدم إضافة vite لإيقاف عملية البناء (build) إذا كانت المتغيرات غير صالحة.
• Next.js: استخدم الدعم المدمج لفصل متغيرات الخادم (server) عن متغيرات العميل (client). هذا يمنع تسريب الأسرار إلى المتصفح عن طريق الخطأ.

عند فشل عملية التحقق، لا يتوقف CtroEnv فحسب، بل يجمع كل خطأ على حدة ويعرضها جميعاً في وقت واحد. ستحصل على تقرير واضح يتضمن المفتاح (key)، والرسالة، وحتى اقتراحات حول كيفية إصلاح الخطأ.

المخرج النهائي هو كائن مجمد (frozen object). وهذا يعني أن إعداداتك للقراءة فقط وآمنة من التغييرات العرضية أثناء وقت التشغيل (runtime).

المصدر: https://dev.to/ctrotech/define-once-trust-everywhere-ctroenv-deep-dive-3bjl