الـ Hooks

بشكل افتراضي، يحصل Volta على Node و npm و Yarn من المصادر والسجلات العامة (https://nodejs.org و https://yarnpkg.com و https://www.npmjs.com). ومع ذلك، اعتمادًا على بيئتك، قد تحتاج إلى إخبار Volta بالتحميل من مصادر مختلفة (مثل npm Enterprise للأدوات الداخلية). لاستيعاب هذه الحالات، يوفر Volta hooks أثناء عملية التحميل.

أين تحدد الـ Hooks

يتم دائمًا تعيين الـ hooks في ملف يسمى hooks.json. يمكن أن يكون هذا الملف في أحد موقعين، اعتمادًا على النطاق الذي تريده لهذه الـ hooks:

• الـ hooks المحددة في دليل Volta (~/.volta/hooks.json على Linux/MacOS، %LOCALAPPDATA%\Volta\hooks.json على Windows) ستطبق على النظام بأكمله.
• الـ hooks المحددة في دليل فرعي .volta للمشروع (<PROJECT ROOT>/.volta/hooks.json) ستطبق فقط داخل ذلك المشروع. هنا، <PROJECT ROOT> معرف كموقع package.json لذلك المشروع.

تنسيق ملف الـ Hooks

يجب أن يكون محتوى hooks.json كائنًا يوفر مفاتيح اختيارية لكل نوع أداة (حاليًا node و npm و yarn). لكل أداة 3 عمليات، ويمكن تطبيق hook على كل عملية:

• index يشير إلى URL المستخدم لتحديد قائمة الإصدارات المتاحة للتحميل لتلك الأداة. يجب أن تتطابق الاستجابة عند الوصول إلى ذلك URL مع تنسيق الفهرس العام للأداة المختارة.
• latest يشير إلى URL المستخدم لتحديد أحدث إصدار لتلك الأداة. بالنسبة إلى node، يجب أن تكون الاستجابة بنفس تنسيق index، مع التأكد من أن أحدث إصدار هو العنصر الأول في القائمة. بالنسبة إلى yarn، يجب أن تكون الاستجابة سلسلة رقم الإصدار الخام، لا أكثر.
• distro يشير إلى URL المستخدم لتحميل الملفات الثنائية للأداة.

أخيرًا، لكل عملية 3 hooks محتملة (كما هو موضح أدناه) يمكن استخدامها (يمكن تحديد واحد فقط لكل عملية في كل مرة). مثال على ملف hooks.json هو:

{
    "node": {
        "index": {
            "bin": "/usr/local/node-lookup"
        },
        "latest": {
            "prefix": "http://example.com/node/"
        },
        "distro": {
            "template": "http://example.com/{{os}}/{{arch}}/node-{{version}}.tar.gz"
        }
    },
    "npm": {
        "index": {
            "prefix": "http://example.com/npm/"
        },
        "latest": {
            "bin": "~/npm-latest"
        },
        "distro": {
            "template": "http://example.com/npm/npm-{{version}}.tgz"
        }
    },
    "yarn": {
        "index": {
            "template": "http://example.com/yarn/{{os}}/{{arch}}/yarn-{{version}}.tgz"
        },
        "latest": {
            "prefix": "http://example.com/yarnpkg/"
        },
        "distro": {
            "bin": "~/yarn-distro"
        }
    }
}

أنواع الـ Hooks

hook prefix

hook prefix هو استبدال URL مباشر. سيتم بناء URL باستخدام البادئة المحددة، ثم اسم الملف العام لتلك العملية. على سبيل المثال، باستخدام hooks.json أعلاه، حددنا hook prefix لتحديد أحدث إصدار yarn. افتراضيًا، سيحصل Volta على أحدث إصدار عن طريق طلب https://yarnpkg.com/latest-version. باستخدام الـ hook، سيحاول Volta الوصول إلى http://example.com/yarnpkg/latest-version، مع إضافة latest-version إلى البادئة المحددة http://example.com/yarnpkg/.

hook template

hook template يسمح لك بتحديد قالب URL يحتوي على أحرف بدل سيتم استبدالها. الأحرف البدل المتاحة هي:

• سيتم استبدالها بـ darwin أو linux أو win اعتمادًا على نظام التشغيل.
• سيتم استبدالها بـ x86 أو x64 اعتمادًا على بنية النظام.
• (متاح فقط لعملية distro) سيتم استبدالها بالإصدار المحدد للأداة التي يحاول Volta تحميلها.
• سيتم استبدالها باسم الملف الذي سيقوم Volta بتحميله من السجل العام.
• (متاح فقط لعملية distro) سيتم استبدالها بامتداد الملف الذي يتوقع Volta تحميله.

TIP

استبدال filename و ext متاح فقط في Volta 0.8.4 أو أحدث

باستخدام hook node.distro من المثال أعلاه، عند الحصول على node@10.15.3 على نظام Linux 64 بت، سيحاول Volta تحميل tarball من: http://example.com/linux/x64/node-10.15.3.tar.gz

hook bin

hook bin هو hook عام سيستدعي سكريبت خارجي لتحديد URL. القيمة هي مسار السكريبت القابل للتنفيذ الذي سيتم استدعاؤه، وسيتم قراءة URL من stdout لذلك السكريبت. سيتم عرض stderr للسكريبت للمستخدم، لذا يمكن استخدامه لعرض شريط التقدم أو مؤشر الانتظار إذا لزم الأمر. إذا كان مسار السكريبت نسبيًا، فسيتم حله بالنسبة لملف hooks.json الذي حدده. في هذه الحالة، المسار النسبي يعني أن المسار يبدأ بـ ./ أو ../ على Linux/MacOS، و .\ أو ..\ على Windows. أخيرًا، بالنسبة إلى hook عملية distro، سيتم تمرير إصدار الأداة المطلوبة كمعامل أول إلى ذلك السكريبت.

باستخدام hook yarn.distro من مثال hooks.json، عند الحصول على yarn@1.13.0، سيستدعي Volta ~/yarn-distro "1.13.0" ويحاول تحميل tarball من URL الذي يعيده ذلك الـ hook.