انتقل إلى المحتوى

الحزم الشائعة

عرض بتنسيق Markdown التعديل على GitHub التوثيق في 5b53f69

لا يضمن التوافق مع المواصفات أن تعمل المكتبات الفعلية. فكثيرًا ما تتعطل شيفرات الإنتاج في محركات JS التي تجتاز 99 % من test262، لأن المكتبات تعتمد على مجموعة طويلة من «زوايا المواصفات» — مثل اعتراضات Proxy بترتيبات محددة، وأشكال Function.prototype.toString، وسلوك Regex مع مدخلات صعبة، والطريقة الدقيقة التي يتفاعل بها ترتيب Object.keys مع أسماء الخصائص المحسوبة.

يتحقق Phasis من 204 مكتبات واسعة الاستخدام بايتًا ببايت بمقارنتها بـNode.js (V8). توجد في tests/Popular/ داخل المستودع، ويشغّلها CI كلما تغير مصدر المحرك أو مجموعة الاختبارات.

التغطية حسب الفئة

الفئة المكتبات
المحللات / AST acorn 8.16.0, chevrotain 11.0.3, parse5 7.2.1, parsimmon 1.18.1, jsep 1.4.0, postcss-value-parser 4.2.0, acorn-walk 8.3.4, estraverse 5.3.0, escodegen 2.1.0, css-tree 3.0.4, sax 1.4.1, nearley 2.20.1
القوالب / Markdown / HTML mustache 4.2.0, handlebars 4.7.9, marked 18.0.3, markdown-it 14.1.0 (+ markdown-it-emoji), markdown-table 3.0.4, showdown 2.1.0, cheerio 1.1.2, htmlparser2 11.0.0
الأدوات المساعدة / البرمجة الوظيفية lodash 4.18.1, ramda 0.31.3, remeda 2.17.4, es-toolkit 1.27.0, immutable 5.1.3, immer 10.1.1, redux 5.0.1, deepmerge 4.3.1, dot-object 2.1.5, lodash.merge 4.6.2, lodash.clonedeep 4.5.0, extend 3.0.2, extend-shallow 3.0.2, mixin-deep 2.0.1, merge-options 3.0.4
الوصول إلى الكائنات dequal 2.0.3, clsx 2.1.1, classnames 2.5.1, get-value 4.0.1, set-value 4.1.0, object.omit 3.0.0, object.pick 1.3.0, is-plain-obj 4.1.0, kind-of 6.0.3
التحقق / المخططات zod 4.4.3, yup 1.4.0, valibot 1.1.0, superstruct 2.0.2, validator 13.12.0, email-validator 2.0.4, ajv 8.17.1, @sinclair/typebox 0.34.42, runtypes 6.7.0, typanion 3.14.0, ow 2.0.0
التاريخ / الوقت dayjs 1.11.20, date-fns 4.1.0, timeago.js 4.0.2, luxon 3.7.3, moment 2.30.2
الرياضيات / الأعداد bignumber.js 11.1.1, decimal.js 10.6.0, numeral 2.0.6, jsbi 4.3.0, big.js 6.2.2, fraction.js 4.3.7, complex.js 2.4.2, simple-statistics 7.8.8
التجزئة / التشفير blueimp-md5 2.19.0, crypto-js 4.2.0, fnv-plus 1.3.1, murmurhash3js 3.0.1, hash-sum 2.0.0, jwt-decode 4.0.0, @noble/hashes 2.2.0, tweetnacl 1.0.3, aes-js 3.1.2, bcryptjs 3.0.2, xxhashjs 0.2.2, object-hash 3.0.0
البحث / الفروقات fuse.js 7.3.0, minisearch 7.1.1, diff 8.0.2, diff-match-patch 1.0.5, fast-deep-equal 3.1.3, fast-equals 5.2.2, fastest-levenshtein 1.0.16, lunr 2.3.9
JSON / تنسيقات البيانات json5 2.2.3, js-yaml 4.1.0, yaml 2.6.1, toml 3.0.0, smol-toml 1.3.1, fast-json-patch 3.1.1, jmespath 0.16.0, jsonata 2.0.6, jsonpath-plus 10.3.0, mingo 6.7.0, sift 17.1.3, fast-json-stable-stringify 2.1.0, safe-stable-stringify 2.5.0, json-stringify-safe 5.0.1, canonicalize 2.1.0, papaparse 5.5.4
السلاسل / اللغة he 1.2.0, slugify 1.6.9, camelcase 8.0.0, entities 6.0.1, pluralize 8.0.0, inflection 3.0.2, wcwidth 1.0.1, emoji-regex 10.4.0, unraw 3.0.0, jsesc 3.1.0, lower-case 2.0.2, upper-case 2.0.2, dot-case 3.0.4, pascal-case 3.1.2, snake-case 3.0.4, title-case 3.0.3, xregexp 5.1.1, escape-string-regexp 5.0.0, ansi-regex 6.1.0, strip-ansi 7.1.2, string-width 8.1.0
URL / الويب url-parse 1.5.10, qs 6.13.1, query-string 9.1.1, tldts 6.1.69, punycode 2.3.1, linkifyjs 4.3.1, ipaddr.js 2.2.0, uri-js 4.4.1, url-template 3.1.1, bowser 2.11.0
الضغط / الترميز / الأرشفة pako 2.1.0, lz-string 1.5.0, base64-js 1.5.1, JSZip 3.10.1
الألوان color-string 2.1.1, d3-color 3.1.0, chroma-js 3.1.2, color-name 2.0.0, tinycolor2 1.6.0, color 5.0.3
الاستنساخ / التكافؤ rfdc 1.4.1, klona 2.0.6, fast-copy 3.0.2
التنسيق / العرض ms 2.1.3, bytes 3.1.2
المعرّفات / UUIDs uuid 10.0.0, hexoid 2.0.0, ulid 3.0.1, cuid2 2.2.2, short-unique-id 5.4.3
اكتشاف الأنواع / glob type-detect 4.1.0, picomatch 4.0.2, minimatch 10.1.1, wildcard-match 5.1.4, glob-to-regexp 0.4.1, to-regex 4.0.4, array-uniq 3.0.0, array-unique 0.3.2
semver / الإعدادات semver 7.6.3, compare-versions 6.1.1, semver-compare 1.0.0
ذاكرات التخزين المؤقت / الأداء lru-cache 11.0.2, marky 1.3.0, array-flatten 3.0.0, arr-diff 4.0.0
غير المتزامن / الأحداث eventemitter3 5.0.1, eventemitter2 6.4.10, mitt 3.0.1, p-limit 7.1.1, p-queue 9.0.2, p-defer 5.0.0, p-retry 7.1.0, throttle-debounce 5.0.2, async 3.2.6
الحالة التفاعلية mobx 6.13.7, xstate 5.23.0, valtio 2.1.5, nanostores 1.0.1, jotai 2.16.1, redux-saga 1.3.0, redux 5.0.1
CSS / التنسيق postcss 8.5.7, stylis 4.3.6, css-tree 3.0.4
البناء / AST / المترجمات magic-string 0.30.20, escodegen 2.1.0, acorn-walk 8.3.4, estraverse 5.3.0, @babel/parser 7.28.5, terser 5.46.0, prettier 3.3.3, svelte 5.55.7 (compiler), typescript 6.0.3
MQTT / البروتوكول mqtt-packet 9.0.4
GraphQL graphql-js 16.11.0
إبراز البنية النحوية highlight.js 11.11.1
الاختبار / التأكيدات chai 6.2.1

الإجمالي: 204 مكتبة تنتج جميعها مخرجات Node المطابقة تمامًا. ثُبّتت إصداراتها جميعًا على أحدث إصدار من المصدر الأصلي عند آخر تحديث.

طريقة العمل

كل سيناريو هو مجلد tests/Popular/<lib>/ يحتوي على ثلاثة ملفات:

Text
tests/Popular/lodash/
├── lodash.js     ← vendored upstream library (untouched, UMD bundle)
├── runner.js     ← Phasis-side script that exercises the library
└── oracle.txt    ← Node.js output of running runner.js (committed)

tests/Popular/PopularPackagesTest.php اختبار لموفّر بيانات في PHPUnit يقوم بما يلي:

  1. يحمّل lodash.js + runner.js إلى new Phasis\Engine() جديد.
  2. يلتقط مخرجات console.log في مخزن مؤقت.
  3. يتحقق من أن المخزن الملتقط مطابق بايتًا ببايت لـoracle.txt.

أنشئ مرجعًا معياريًا من جديد باستخدام:

سطر الأوامر
node tests/Popular/gen-oracle.js tests/Popular/<lib>

(يُستخدم عند تحديث المكتبة المضمّنة — يعيد تشغيل المشغّل في Node الفعلي ويستبدل oracle.txt.)

بوابة CI

سير العمل: .github/workflows/popular.yml.

يعمل عند دفع التغييرات وفتح طلبات السحب إلى main التي تغيّر src/ أو tests/Popular/ أو phpunit.xml.dist أو ملفات Composer أو سير العمل نفسه، وكذلك عند تشغيله يدويًا. يتضمن خطوتين:

  1. جانب Phasis — يشغّل مجموعة اختبارات PHPUnit popular، التي تنفّذ كل مكتبة عبر Phasis وتقارن النتائج بالمرجع المعياري المودع. يفشل الاختبار إذا اختلف بايت واحد.
  2. إعادة التحقق باستخدام Node — يشغّل node tests/Popular/gen-oracle.js … على كل مكتبة ويتحقق من تطابق المرجع المعياري المعاد توليده مع النسخة المودعة. يكشف أي اختلاف ناتج عن «تحديث مكتبة مضمّنة من دون تحديث المرجع المعياري».

يجب أن ينجح الاختباران قبل دمج طلب السحب. لا يُقبل اجتياز test262 إذا أدى إلى تعطيل lodash، كما لا يُقبل نجاح lodash إذا أدى إلى تعطيل test262.

لماذا هذه المكتبات

  • acorn — يُعد التحليل أكثر الجوانب هشاشة في أي محرك JS. فهو يختبر كل الحالات النحوية الخاصة التي أضافتها JS الحديثة. إذا كان Phasis قادرًا على تحليل أي شيفرة حديثة باستخدام acorn، فبيئة التشغيل سليمة.
  • mustache.js — تُعد القوالب إحدى حالات الاستخدام المضمنة التي يستهدفها Phasis صراحةً (أول مثال عملي في README هو «محركات القوالب»). يختبر Mustache التكرار وحل النطاق وتحويل السلاسل بالترتيب الذي تستخدمه القوالب الحقيقية.
  • lodash — مكتبة الأدوات المساعدة لـ JS الأكثر استخدامًا في العالم. تلامس وظائفها التي يزيد عددها على 300 كل أساليب المكتبة القياسية بصورة غير مباشرة. إذا عملت lodash، فستعمل شيفرة JS العامة لتحويل البيانات.
  • marked — عرض Markdown. اختبار عملي يختبر التعبيرات النمطية (بكثرة) إضافةً إلى معالجة السلاسل مع حالة تمتد عبر الأسطر. يكشف اختلافات محرك التعبيرات النمطية بين PCRE2 (البديل الاحتياطي لـ Phasis) وIrregexp في V8.
  • dayjs — تُعد العمليات الحسابية على التاريخ والوقت مصدرًا كلاسيكيًا للأخطاء بفارق يوم واحد، ولا تلتقطها أي حالة في test262. يختبر dayjs صيغ المُنشئ، والحساب عبر حدود الأشهر المكافئة للتوقيت الصيفي، وتوسيع رموز التنسيق، في مسارات الشيفرة نفسها تقريبًا التي تستخدمها كل مكتبات Date في JS.
  • bignumber.js — تختبر العمليات الحسابية بدقة اعتباطية دون TypedArrays تحليل الأعداد المعتمد على السلاسل، وحلقات الضرب والقسمة للأعداد الكبيرة، واختيار أوضاع التقريب، وكلها بـ JS خالصة، لذا يتحمل المحرك التكلفة كاملة. ويكشف أي خلل دقيق في التحويل بين Number وString.
  • json5 — يعتمد تحليل JSON المرن بشدة على تعبيرات نمطية لفئات المحارف وعلى تقسيم الرموز ذي الحالة. وهو اختبار إنذار جيد لصحة التعبيرات النمطية وحالات تكرار السلاسل.
  • fuse.js — مكتبة UMD محوّلة باستخدام Babel تختبر _classCallCheck (النمط this instanceof Ctor الذي تستخدمه كل الفئات المحوّلة قبل ES6) إضافةً إلى خوارزمية المطابقة التقريبية bitap كاملة. هذا شكل شائع في كل مكتبة محوّلة باستخدام Babel، لذا فإن أي عطل يصيب Fuse يؤثر في نصف منظومة npm.
  • handlebars — قوالب متكاملة الميزات تُترجم ثم تُعرض. تختبر مسار التشغيل الخالي من eval عبر مدخل compile() واحد ضخم، واجتياز AST، واستدعاء المساعدات عبر جدول بحث ديناميكي، والتحقق من نوع SafeString باستخدام instanceof عبر البيئات. وهي نقطة مقابلة لمتجول القوالب الأبسط في mustache.js.
  • zod — التحقق من المخططات وقت التشغيل. يتضمن تسلسلات هرمية كثيفة من الفئات (ZodString، ZodObject، ZodArray، ZodUnion، …) مع تسلسل استدعاءات الأساليب الذي يعيد فئات فرعية منقحة، وتنسيقًا منظمًا للأخطاء حيث يجب أن يطابق شكل مصفوفة .issues في جانب JS بايتًا ببايت، وأنماط الوسوم الحرفية والمميزة. تختبر شيفرة التحقق كثيفة البرمجة كائنية التوجه التي تغلف نصف تطبيقات TypeScript الحديثة.
  • typescript — مُصرّف TypeScript الفعلي يعمل على المحرك المضمن. مُصرّف مصغّر حجمه 9 MB يعيد تحليل أي TS، ويتجول في AST، ويصدر JS؛ وهو أثقل حمولة خالصة من JS يمكن تخيلها. إذا استطاع Phasis تحويل الأنواع العامة وasync/await والتعدادات وتسلسلات الفئات الهرمية إلى نتيجة مطابقة بايتًا ببايت لـ tsc، فدلالات اللغة سليمة.
  • prettier — منسق JS ذو آراء محددة. إن تنسيق JS باستخدام JS يلامس كل زاوية من المواصفات في المحرك عبر مسار التحكم نفسه الذي ينسق شيفرتك، ما يجعله عبئًا فريدًا يتطلب الكثير.
  • svelte/compiler — المُصرّف المستقل لـ Svelte. يحلل مصدر .svelte، ويتجول في AST، ويصدر JS لكل من أهداف العميل وSSR.
  • terser / @babel/parser / postcss — مصغّر JS، ومحلل JS، ومعالج CSS لاحق. عشرات الآلاف من أسطر الشيفرة المصغرة التي تعيد تحليل أي مدخل، وهو المجال الذي تظهر فيه أشكال AST النادرة.
  • ajv — مدقق مخططات JSON يترجم كل مخطط آنيًا إلى دالة تحقق مخصصة عبر new Function(...). يختبر مسار مُنشئ Function الذي تعتمد عليه معظم مكتبات المخططات والقوالب.
  • mobx — حالة تفاعلية قائمة على Proxy. تمر كل قراءة لقيمة قابلة للرصد عبر مصيدة Proxy get تسجل اعتمادًا؛ وكل كتابة تطلق التفاعلات. اختبار ضغط لبنية Proxy التحتية، والخرائط والمصفوفات والكائنات المتداخلة القابلة للرصد، ومجدول autorun.
  • cheerio / htmlparser2 — jQuery من جانب الخادم مبني على محلل HTML سريع. تحليل محرك المحددات، والتنقل بأسلوب DOM، ومعالجة السمات، وتسلسل HTML في حزمة واحدة.
  • graphql-js / jsonata — التنفيذ المرجعي لـ GraphQL ولغة استعلام JSON. كلاهما يعتمد بكثافة على المخططات والتحقق والمقيّمات التكرارية، وهي شيفرة نموذجية لـ«طبقة البيانات في المتصفح».
  • JSZip — منشئ أرشيف ZIP غير متزامن. يوجه العمل عبر جدولة قائمة على setImmediate وينتج مخرجات ثنائية فعلية، مختبرًا سطح المؤقتات والمسارات كثيفة Uint8Array.
  • moment / luxon — العمليات الحسابية على التاريخ والوقت. moment مكتبة UMD قابلة للتغيير ومضبوطة يدويًا؛ أما luxon فهي إعادة كتابة حديثة غير قابلة للتغيير. وتغطيان معًا كامل نطاق التنسيق والتحليل والحساب على الأشهر والسنوات المكافئة بحسب المنطقة الزمنية.
  • mqtt-packet — برنامج ترميز MQTT 3.1.1 / 5.0 خالص بـ JS. تجميع وفك ترميز على مستوى البايت، إلى جانب فئات المحارف في التعبيرات النمطية التي تتعامل مع محارف خارج أبجدية Base64، ما يختبر حواف قواعد Annex-B.
  • xstate / valtio / nanostores / jotai / redux-saga — مجموعة مكتبات إدارة الحالة الحديثة. آلات الحالات، وحالة الوكيل، ومخازن الذرات، والذرات المشتقة، ومشغلات التأثيرات القائمة على المولدات؛ تختبر كل مكتبة شكلًا مختلفًا من التفاعلية.
  • escodegen / acorn-walk / estraverse / magic-string — أدوات AST. توليد الشيفرة، والاجتياز، وتحرير المصدر دون إتلافه؛ وهي اللبنات الأساسية لأي محول JS إلى JS (أدوات البناء، وتعديلات الشيفرة، وأدوات فحص الشيفرة).
  • papaparse / lunr / yaml / sax / css-tree — محللات ومجزئات رموز خالصة. CSV، وفهرس بحث بالنص الكامل، وYAML 1.2، وتحليل بأسلوب SAX للبث XML، وAST لـ CSS. قواعد نحوية مختلفة، وكلها اختبارات إنذار جيدة للمسح على مستوى المحارف وسلوك التعبيرات النمطية.

إضافة المزيد

أضف مجلدًا جديدًا داخل tests/Popular/<name>/ ببنية الملفات الثلاثة، ثم:

سطر الأوامر
node tests/Popular/gen-oracle.js tests/Popular/<name>   # one-time, generates oracle.txt
git add tests/Popular/<name>

ستكتشفه مجموعة PHPUnit تلقائيًا في التشغيل التالي، وسيلتقطه CI لأن التغيير يمس tests/Popular/.

من الخيارات الواعدة التي تستحق الإضافة: chevrotain (مركّب للمحللات يختبر الإغلاقات والتعبيرات النمطية)، وnanoid (حدود التشفير والعشوائية)، وdate-fns (نطاق المناطق الزمنية بما يتجاوز dayjs).