عن المشروع

GraphQL.js هو التنفيذ المرجعي لـ GraphQL بلغة JavaScript، وهي لغة استعلام لواجهات برمجة التطبيقات (APIs) تم إنشاؤها في الأصل في Facebook. يشير ملف README إلى مستودع مواصفات GraphQL للحصول على نظرة عامة عامة عن اللغة، ويوضح أن الأمثلة الموصوفة هناك تظهر كاختبارات داخل هذا المستودع — والمسار المقترح للقادمين الجدد هو قراءة تلك النظرة العامة جنبًا إلى جنب مع الاختبارات المقابلة. القدرات الرئيسية توفر المكتبة قدرتين مركزيتين: بناء مخطط أنواع (type schema) وتقديم الاستعلامات بناءً على ذلك المخطط. يتم تعريف المخطط باستخدام GraphQLSchema و GraphQLObjectType، مع حقول يكون نوعها أحد السكالرز المدمجة مثل GraphQLString؛ ويمكن لكل حقل توفير دالة resolve. يذكر ملف README أن الـ resolver قد يعيد قيمة، أو promise، أو مصفوفة من الـ promises. يتم تشغيل الاستعلامات من خلال دالة graphql، التي تقبل مخططًا وسلسلة مصدرية وتعيد promise بالنتيجة. قبل التنفيذ، تتحقق الدالة من أن الاستعلام صالح نحويًا ودلاليًا وإلا فإنها تبلغ عن الأخطاء، وهو ما يوضحه مثال يعيد خطأ "Cannot query field" مع معلومات الموقع. التثبيت يتم تثبيت GraphQL.js من npm كحزمة `graphql` باستخدام npm أو yarn أو bun. يذكر ملف README أيضًا وجود فرع `npm` يتم صيانته تلقائيًا في المستودع يتتبع آخر التزام في خط 17.x.x الذي يجتاز جميع الاختبارات؛ ويُطرح الاعتماد المباشر على هذا الفرع كوسيلة لاستخدام كود لم يتم إصداره بعد، بينما يوصي ملف README باستخدام إصدارات npm المنشورة. الاستخدام في المتصفح وأدوات التجميع (bundlers) يشير ملف README إلى أن المكتبة عامة الغرض ويمكن استخدامها في خادم Node وفي المتصفح على حد سواء، مستشهدًا بمشروع GraphiQL كمثال على المشاريع المبنية بها. يجب أن تعمل المشاريع التي تستخدم webpack أو rollup دون تكوين خاص وأن تتضمن فقط الأجزاء التي تستخدمها من المكتبة، لأن GraphQL.js يتم توزيعه بملفات CommonJS (`require()`) و ESModule (`import`). وتوجه خريطة `exports` في `package.json` بيئات التشغيل وأدوات التجميع إلى الملفات المناسبة؛ أما الأدوات التي لا تدعم `exports` فتجد إصدارات CommonJS في ملفات `.js` وإصدار ESModule في ملفات `.mjs`. حوكمة المشروع والدعم المساهمات مرحب بها عبر طلبات السحب (pull requests)، ويتم إدارة المستودع بواسطة EasyCLA: يجب على المشاركين التوقيع على اتفاقية عضوية مواصفات GraphQL، إما بشكل فردي أو من خلال صاحب العمل، قبل المساهمة. يذكر ملف README أيضًا عضوية GraphQL Foundation كوسيلة لدعم المجتمع ماليًا. يتم تتبع التغييرات كإصدارات GitHub. المشروع مرخص بموجب MIT. وهو يتبع الإصدار الدلالي (Semantic Versioning)، مع دعم كامل (إصلاحات الأخطاء وتحديثات الأمان) لأحدث إصدار رئيسي، ودعم الميزات للإصدار الرئيسي السابق لمدة 12 شهرًا بعد إصدار رئيسي جديد (مع نقل تغييرات المواصفات فقط عندما لا تكون مكسرة)، ولا توجد صيانة نشطة للإصدارات الأقدم — باستثناء أن الإصدار الذي تم إطلاقه قبل أقل من عام يتم التعامل معه كإصدار رئيسي سابق. لا يوجد حاليًا إصدار دعم طويل الأمد (LTS)؛ ويُشجع المستخدمون على الترقية إلى أحدث إصدار مستقر. يتم الإعلان عن تواريخ نهاية العمر (End-of-life) للإصدار الرئيسي قبل ستة أشهر على الأقل، وبعد ذلك لا يتلقى ذلك الإصدار أي تحديثات حتى بالنسبة للمشكلات الأمنية الحرجة. تنطبق التحديثات الأمنية الحرجة على كل من الإصدار الرئيسي الحالي والسابق. يتم تقديم المساعدة في الترقية من خلال ملاحظات الإصدار لكل نسخة، وأدلة الهجرة في موقع التوثيق، وقناة Discord المجتمعية.