الوحدات: وحدات ECMAScript

[السجل]

الإصدار	التغييرات
v23.1.0	لم تعد سمات الاستيراد تجريبية.
v22.0.0	إلغاء دعم تأكيدات الاستيراد.
v21.0.0، v20.10.0، v18.20.0	إضافة دعم تجريبي لسمات الاستيراد.
v20.0.0، v18.19.0	يتم تنفيذ خطافات تخصيص الوحدة خارج مؤشر الترابط الرئيسي.
v18.6.0، v16.17.0	إضافة دعم لسلسلة خطافات تخصيص الوحدة.
v17.1.0، v16.14.0	إضافة دعم تجريبي لتأكيدات الاستيراد.
v17.0.0، v16.12.0	توحيد خطافات التخصيص، وإزالة خطافات `getFormat`، `getSource`، `transformSource`، و `getGlobalPreloadCode`، وإضافة خطافات `load` و `globalPreload`، والسماح بإرجاع `format` من خطافات `resolve` أو `load`.
v14.8.0	إلغاء وضع الانتظار في أعلى المستوى.
v15.3.0، v14.17.0، v12.22.0	تثبيت تنفيذ الوحدات.
v14.13.0، v12.20.0	دعم للكشف عن تصدير الأسماء في CommonJS.
v14.0.0، v13.14.0، v12.20.0	إزالة تحذير الوحدات التجريبية.
v13.2.0، v12.17.0	لم يعد تحميل وحدات ECMAScript يتطلب علم سطر الأوامر.
v12.0.0	إضافة دعم لوحدات ES باستخدام امتداد الملف `.js` عبر حقل `"type"` في `package.json`.
v8.5.0	تمت الإضافة في: v8.5.0

[مستقر: 2 - مستقر]

مستقر: 2 الثبات: 2 - مستقر

مقدمة

تُعد وحدات ECMAScript الформат الرسمي القياسي لتغليف رمز JavaScript لإعادة استخدامه. يتم تعريف الوحدات باستخدام مجموعة متنوعة من عبارات import و export.

يوضح المثال التالي لوحدة ES التي تصدر دالة:

// addTwo.mjs
function addTwo(num) {
  return num + 2
}

export { addTwo }

يوضح المثال التالي لوحدة ES التي تستورد الدالة من addTwo.mjs:

// app.mjs
import { addTwo } from './addTwo.mjs'

// يطبع: 6
console.log(addTwo(4))

يدعم Node.js وحدات ECMAScript بالكامل كما هو محدد حاليًا ويوفر التشغيل البيني بينها وبين تنسيق الوحدة الأصلي الخاص به، CommonJS.

تمكين

يحتوي Node.js على نظامين للوحدات: وحدات CommonJS ووحدات ECMAScript.

يمكن للمؤلفين إخبار Node.js بتفسير JavaScript كوحدة ES عبر امتداد الملف .mjs، أو حقل package.json "type" بقيمة "module"، أو علم --input-type بقيمة "module". هذه علامات صريحة تشير إلى أن الرمز مُقصد تشغيله كوحدة ES.

وعكس ذلك، يمكن للمؤلفين أن يخبروا Node.js صراحةً بتفسير JavaScript كوحدة CommonJS عبر امتداد الملف .cjs، أو حقل package.json "type" بقيمة "commonjs"، أو علم --input-type بقيمة "commonjs".

عندما يفتقر الرمز إلى علامات صريحة لأي نظام وحدة، فستقوم Node.js بفحص التعليمات البرمجية المصدر للوحدة للبحث عن بناء جملة وحدة ES. إذا تم العثور على مثل هذا البناء، فستقوم Node.js بتشغيل الرمز كوحدة ES؛ وإلا ستقوم بتشغيل الوحدة كوحدة CommonJS. راجع تحديد نظام الوحدة لمزيد من التفاصيل.

الحزم

تم نقل هذا القسم إلى الوحدات: الحزم.

مُحددات `import`

المصطلحات

المُحدد لبيان import هو السلسلة الموجودة بعد كلمة from، على سبيل المثال 'node:path' في import { sep } from 'node:path'. تُستخدم المُحددات أيضًا في بيانات export from، وكحجة لتعبير import() .

هناك ثلاثة أنواع من المُحددات:

المُحددات النسبية مثل './startup.js' أو '../config.mjs'. تشير إلى مسار نسبي لموقع الملف المستورد. امتداد الملف ضروري دائمًا لهذه.
المُحددات المجردة مثل 'some-package' أو 'some-package/shuffle'. يمكن أن تشير إلى نقطة الدخول الرئيسية لحزمة حسب اسم الحزمة، أو وحدة مُعينة داخل حزمة مُقدمة باسم الحزمة وفقًا للأمثلة على التوالي. تضمين امتداد الملف ضروري فقط للحزم التي لا تحتوي على حقل "exports".
المُحددات المطلقة مثل 'file:///opt/nodejs/config.js'. تشير مباشرةً وصراحةً إلى مسار كامل.

يتم التعامل مع قرارات المُحددات المجردة بواسطة خوارزمية حل التحميل ووحدة Node.js. يتم حل جميع قرارات المُحددات الأخرى دائمًا فقط باستخدام دلالات حل URL النسبية القياسية.

كما هو الحال في CommonJS، يمكن الوصول إلى ملفات الوحدة داخل الحزم عن طريق إضافة مسار إلى اسم الحزمة ما لم تحتوي package.json للحزمة على حقل "exports"، وفي هذه الحالة لا يمكن الوصول إلى الملفات داخل الحزم إلا عبر المسارات المحددة في "exports".

للحصول على تفاصيل حول قواعد حل الحزم هذه التي تنطبق على المُحددات المجردة في حل وحدة Node.js، راجع وثائق الحزم.

امتدادات الملفات الإلزامية

يجب توفير امتداد الملف عند استخدام كلمة import لحل المُحدِّدات النسبية أو المطلقة. يجب أيضًا تحديد فهرس الدلائل (مثل './startup/index.js') بالكامل.

يتوافق هذا السلوك مع سلوك import في بيئات المتصفح، بافتراض خادم مُهيّأ بشكل نموذجي.

عناوين URL

يتم حل وحدات ES وتخزينها مؤقتًا كعناوين URL. هذا يعني أنه يجب ترميز الأحرف الخاصة بالتشفير النسبي، مثل # مع %23 و ? مع %3F.

يتم دعم مخططات عناوين URL file: و node: و data:. لا يتم دعم مُحدد مثل 'https://example.com/app.js' بشكلٍ أصلي في Node.js إلا عند استخدام محمل HTTPS مخصص.

عناوين URL من نوع `file:`

يتم تحميل الوحدات عدة مرات إذا كان المُحدد import المستخدم لحلها يحتوي على استعلام أو جزء مختلف.

import './foo.mjs?query=1' // يحمل ./foo.mjs باستعلام "?query=1"
import './foo.mjs?query=2' // يحمل ./foo.mjs باستعلام "?query=2"

يمكن الرجوع إلى جذر وحدة التخزين عبر / أو // أو file:///. بالنظر إلى الاختلافات بين URL وحل المسار (مثل تفاصيل الترميز النسبي)، يُوصى باستخدام url.pathToFileURL عند استيراد مسار.

استيرادات `data:`

تمت الإضافة في: v12.10.0

يتم دعم عناوين URL من نوع data: للاستيراد باستخدام أنواع MIME التالية:

text/javascript لوحدات ES
application/json لـ JSON
application/wasm لـ Wasm

import 'data:text/javascript,console.log("hello!");';
import _ from 'data:application/json,"world!"' with { type: 'json' };

تحل عناوين URL من نوع data: المُحددات العارية فقط لوحدات مدمجة والمُحددات المطلقة. لا يعمل حل المُحددات النسبية لأن data: ليس مخططًا خاصًا. على سبيل المثال، تؤدي محاولة تحميل ./foo من data:text/javascript,import "./foo"; إلى الفشل في الحل لأنه لا يوجد مفهوم للحل النسبي لعناوين URL من نوع data:.

`node:` الاستيرادات

[السجل]

الإصدار	التغييرات
v16.0.0، v14.18.0	تمت إضافة دعم استيراد `node:` إلى `require(...)`.
v14.13.1، v12.20.0	تمت الإضافة في: v14.13.1، v12.20.0

يتم دعم عناوين URL من نوع node: كوسيلة بديلة لتحميل الوحدات المضمنة في Node.js. يسمح مخطط عنوان URL هذا بالرجوع إلى الوحدات المضمنة من خلال سلاسل URL المطلقة الصالحة.

import fs from 'node:fs/promises'

سمات الاستيراد

[السجل]

الإصدار	التغييرات
v21.0.0، v20.10.0، v18.20.0	التحويل من تأكيدات الاستيراد إلى سمات الاستيراد.
v17.1.0، v16.14.0	تمت الإضافة في: v17.1.0، v16.14.0

[مستقر: 2 - مستقر]

مستقر: 2 الثبات: 2 - مستقر

سمات الاستيراد هي بناء جملة سطري لتعليمة استيراد الوحدة لنقل مزيد من المعلومات إلى جانب محدد الوحدة.

import fooData from './foo.json' with { type: 'json' };

const { default: barData } =
  await import('./bar.json', { with: { type: 'json' } });

يدعم Node.js سمة type فقط، والتي يدعم لها القيم التالية:

السمة `type`	مطلوب لـ
`'json'`	وحدات JSON

سمة type: 'json' إلزامية عند استيراد وحدات JSON.

الوحدات المضمنة

توفر الوحدات المضمنة تصديرًا مسّماً لواجهة برمجة التطبيقات العامة الخاصة بها. يتم أيضًا توفير تصدير افتراضي وهو قيمة صادرات CommonJS. يمكن استخدام التصدير الافتراضي، من بين أمور أخرى، لتعديل التصدير المسمى. يتم تحديث التصدير المسمى للوحدات المضمنة فقط عن طريق استدعاء module.syncBuiltinESMExports().

import EventEmitter from 'node:events'
const e = new EventEmitter()

import { readFile } from 'node:fs'
readFile('./foo.txt', (err, source) => {
  if (err) {
    console.error(err)
  } else {
    console.log(source)
  }
})

import fs, { readFileSync } from 'node:fs'
import { syncBuiltinESMExports } from 'node:module'
import { Buffer } from 'node:buffer'

fs.readFileSync = () => Buffer.from('Hello, ESM')
syncBuiltinESMExports()

fs.readFileSync === readFileSync

تعبيرات `import()`

يتم دعم import() الديناميكي (Dynamic import()) في كل من وحدات CommonJS ووحدات ES. في وحدات CommonJS، يمكن استخدامه لتحميل وحدات ES.

`import.meta`

(Object>)

خاصية import.meta الميتا هي Object يحتوي على الخصائص التالية. يتم دعمها فقط في وحدات ES.

`import.meta.dirname`

مضاف في: v21.2.0، v20.11.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.2 - مرشح للإصدار

(سلسلة>) اسم الدليل للوحدة الحالية. هذا هو نفس path.dirname() لـ import.meta.filename.

`import.meta.filename`

مضاف في: v21.2.0، v20.11.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.2 - مرشح للإصدار

(سلسلة>) المسار الكامل المطلق واسم الملف للوحدة الحالية، مع حل الرموز الرمزية.
هذا هو نفس url.fileURLToPath() لـ import.meta.url.

`import.meta.url`

(سلسلة>) عنوان URL المطلق file: للوحدة.

هذا مُعرّف بنفس الطريقة تمامًا كما هو الحال في المتصفحات التي توفر عنوان URL لملف الوحدة الحالي.

هذا يُمكّن أنماطًا مفيدة مثل تحميل الملفات النسبية:

import { readFileSync } from 'node:fs'
const buffer = readFileSync(new URL('./data.proto', import.meta.url))

`import.meta.resolve(specifier)`

[السجل]

الإصدار	التغييرات
v20.6.0، v18.19.0	لم يعد خلف علم `--experimental-import-meta-resolve` CLI، إلا بالنسبة لمعامل `parentURL` غير القياسي.
v20.6.0، v18.19.0	لم يعد هذا API يُلقي استثناءً عند استهداف عناوين URL `file:` التي لا تُطابق ملفًا موجودًا على نظام الملفات المحلي.
v20.0.0، v18.19.0	يُعيد هذا API الآن سلسلة مُزامنة بدلاً من Promise.
v16.2.0، v14.18.0	إضافة دعم لكائن WHATWG `URL` لمعامل `parentURL`.
v13.9.0، v12.16.2	مضاف في: v13.9.0، v12.16.2

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.2 - مرشح للإصدار

specifier (سلسلة>) مُحدد وحدة يجب حله بالنسبة للوحدة الحالية.
المُرجّع: (سلسلة>) سلسلة عنوان URL المطلق التي سيتم حل المُحدد إليها.

import.meta.resolve هي دالة حلّ نسبية للوحدة محدودة النطاق لكل وحدة، تُعيد سلسلة عنوان URL.

const dependencyAsset = import.meta.resolve('component-lib/asset.css')
// file:///app/node_modules/component-lib/asset.css
import.meta.resolve('./dep.js')
// file:///app/dep.js

يتم دعم جميع ميزات حلّ وحدة Node.js. تخضع قرارات التبعيات لقرارات التصدير المُسموح بها داخل الحزمة.

تحذيرات:

قد يؤدي هذا إلى عمليات نظام ملفات مُزامنة، مما قد يؤثر على الأداء بشكل مشابه لـ require.resolve.
هذه الميزة غير متوفرة داخل أجهزة التحميل المخصصة (ستؤدي إلى طريق مسدود).

واجهة برمجة التطبيقات غير القياسية:

عند استخدام علم --experimental-import-meta-resolve، تقبل هذه الدالة وسيطة ثانية:

parent (سلسلة>) | (URL>) عنوان URL وحدة أب مطلق اختياري للحلّ منه. الافتراضي: import.meta.url

التشغيل البيني مع CommonJS

عبارات `import`

يمكن لعبارة import الرجوع إلى وحدة ES أو وحدة CommonJS. تُسمح عبارات import فقط في وحدات ES، ولكن يتم دعم تعبيرات import() الديناميكية في CommonJS لتحميل وحدات ES.

عند استيراد وحدات CommonJS، يتم توفير كائن module.exports كتصدير افتراضي. قد تكون التصدير المسماة متاحة، مقدمة من خلال التحليل الثابت كوسيلة مساعدة لتحسين توافق النظام الإيكولوجي.

`require`

لا تدعم وحدة CommonJS require حاليًا إلا تحميل وحدات ES المتزامنة (أي وحدات ES التي لا تستخدم await على مستوى أعلى).

راجع تحميل وحدات ECMAScript باستخدام require() للحصول على التفاصيل.

مسافات أسماء CommonJS

[التاريخ]

الإصدار	التغييرات
v23.0.0	تمت إضافة علامة تصدير `'module.exports'` إلى مسافات أسماء CJS.
v14.13.0	تمت الإضافة في: v14.13.0

تتكون وحدات CommonJS من كائن module.exports والذي يمكن أن يكون من أي نوع.

لدعم هذا، عند استيراد CommonJS من وحدة ECMAScript، يتم إنشاء غلاف مساحة اسم لوحدة CommonJS، والذي يوفر دائمًا مفتاح تصدير افتراضي يشير إلى قيمة CommonJS module.exports.

بالإضافة إلى ذلك، يتم إجراء تحليل ثابت استدلالي ضد نص مصدر وحدة CommonJS للحصول على قائمة ثابتة بأفضل جهد للتصدير لتوفيرها على مساحة الاسم من القيم الموجودة على module.exports. هذا ضروري لأن هذه المسافات الاسمية يجب إنشاؤها قبل تقييم وحدة CJS.

توفر كائنات مساحة اسم CommonJS هذه أيضًا التصدير الافتراضي كتصدير مسماة 'module.exports'، من أجل الإشارة بشكل لا لبس فيه إلى أن تمثيلها في CommonJS يستخدم هذه القيمة، وليس قيمة مساحة الاسم. هذا يعكس دلالات معالجة اسم التصدير 'module.exports' في دعم التشغيل البيني require(esm).

عند استيراد وحدة CommonJS، يمكن استيرادها بشكل موثوق باستخدام استيراد ES الافتراضي أو بناء جملة السكر المقابل:

import { default as cjs } from 'cjs'
// مطابق لما سبق
import cjsSugar from 'cjs'

console.log(cjs)
console.log(cjs === cjsSugar)
// يطبع:
//   <module.exports>
//   true

يمكن ملاحظة كائن مساحة اسم الوحدة الغريب هذا مباشرةً إما عند استخدام import * as m from 'cjs' أو استيراد ديناميكي:

import * as m from 'cjs'
console.log(m)
console.log(m === (await import('cjs')))
// يطبع:
//   [Module] { default: <module.exports>, 'module.exports': <module.exports> }
//   true

لتحسين التوافق مع الاستخدامات الحالية في نظام JS البيئي، تحاول Node.js بالإضافة إلى ذلك تحديد التصدير المسماة CommonJS لكل وحدة CommonJS مستوردة لتوفيرها كتصدير لوحدة ES منفصلة باستخدام عملية تحليل ثابتة.

على سبيل المثال، ضع في اعتبارك وحدة CommonJS المكتوبة:

// cjs.cjs
exports.name = 'exported'

تدعم الوحدة السابقة الاستيرادات المسماة في وحدات ES:

import { name } from './cjs.cjs'
console.log(name)
// يطبع: 'exported'

import cjs from './cjs.cjs'
console.log(cjs)
// يطبع: { name: 'exported' }

import * as m from './cjs.cjs'
console.log(m)
// يطبع:
//   [Module] {
//     default: { name: 'exported' },
//     'module.exports': { name: 'exported' },
//     name: 'exported'
//   }

كما هو موضح في المثال الأخير لكائن مساحة اسم الوحدة الغريب الذي تم تسجيله، يتم نسخ تصدير name من كائن module.exports ووضعه مباشرةً على مساحة اسم وحدة ES عند استيراد الوحدة.

لا يتم الكشف عن تحديثات الربط المباشر أو التصدير الجديد المضاف إلى module.exports لهذه التصدير المسماة.

يعتمد الكشف عن التصدير المسماة على أنماط بناء جملة شائعة ولكنه لا يكتشف دائمًا التصدير المسماة بشكل صحيح. في هذه الحالات، يمكن أن يكون استخدام نموذج الاستيراد الافتراضي الموضح أعلاه خيارًا أفضل.

يغطي الكشف عن التصدير المسماة العديد من أنماط التصدير الشائعة، وأنماط إعادة التصدير، ومخرجات أداة البناء والمترجم. راجع cjs-module-lexer للحصول على الدلالات الدقيقة المُنفذة.

الفروقات بين وحدات ES و CommonJS

عدم وجود `require` أو `exports` أو `module.exports`

في معظم الحالات، يمكن استخدام وحدة ES import لتحميل وحدات CommonJS.

إذا لزم الأمر، يمكن إنشاء دالة require داخل وحدة ES باستخدام module.createRequire().

عدم وجود `filename` أو `dirname`

لا تتوفر متغيرات CommonJS هذه في وحدات ES.

يمكن استنساخ حالات استخدام __filename و __dirname عبر import.meta.filename و import.meta.dirname.

عدم وجود تحميل الوظائف الإضافية

لا يتم دعم الوظائف الإضافية حاليًا مع استيراد وحدات ES.

يمكن تحميلها بدلاً من ذلك باستخدام module.createRequire() أو process.dlopen.

عدم وجود `require.resolve`

يمكن التعامل مع الحل النسبي عبر new URL('./local', import.meta.url).

للحصول على بديل كامل لـ require.resolve، يوجد واجهة برمجة التطبيقات import.meta.resolve.

بدلاً من ذلك، يمكن استخدام module.createRequire().

عدم وجود `NODE_PATH`

NODE_PATH ليس جزءًا من حل مُحددات import. يرجى استخدام الارتباطات الرمزية إذا رغبت في هذا السلوك.

عدم وجود `require.extensions`

لا يستخدم import require.extensions. يمكن لخطافات تخصيص الوحدة توفير بديل.

عدم وجود `require.cache`

لا يستخدم import require.cache حيث أن مُحمّل وحدة ES لديه ذاكرة تخزين مؤقت منفصلة خاصة به.

وحدات JSON

[السجل]

الإصدار	التغييرات
v23.1.0	لم تعد وحدات JSON تجريبية.

[مستقر: 2 - مستقر]

مستقر: 2 الثبات: 2 - مستقر

يمكن الرجوع إلى ملفات JSON بواسطة import:

import packageConfig from './package.json' with { type: 'json' };

إن بناء جملة with { type: 'json' } إلزامي؛ انظر سمات الاستيراد.

لا يُصدر JSON المستورد سوى تصدير افتراضي. لا يوجد دعم للتصدير المسمى. يتم إنشاء إدخال ذاكرة تخزين مؤقت في ذاكرة تخزين CommonJS المؤقتة لتجنب التكرار. يتم إرجاع نفس الكائن في CommonJS إذا تم استيراد وحدة JSON بالفعل من نفس المسار.

وحدات Wasm

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

يتم دعم استيراد وحدات WebAssembly ضمن علم --experimental-wasm-modules، مما يسمح باستيراد أي ملفات .wasm كوحدات عادية مع دعم استيراد وحداتها أيضًا.

تتماشى هذه التكامل مع اقتراح تكامل وحدة ES لـ WebAssembly.

على سبيل المثال، ملف index.mjs الذي يحتوي على:

import * as M from './module.wasm'
console.log(M)

يتم تنفيذه تحت:

bash

node --experimental-wasm-modules index.mjs

سوف يوفر واجهة التصدير لإنشاء module.wasm.

`await` على مستوى الأعلى

مضاف في: v14.8.0

يمكن استخدام كلمة await الرئيسية في جسم ECMAScript module على مستوى الأعلى.

بافتراض ملف a.mjs يحتوي على:

export const five = await Promise.resolve(5)

وملف b.mjs يحتوي على:

import { five } from './a.mjs'

console.log(five) // يسجل `5`

bash

node b.mjs # يعمل

إذا لم يتم حل تعبير await على مستوى الأعلى أبدًا، فسيتم إيقاف عملية node برمز حالة 13 رمز الحالة.

import { spawn } from 'node:child_process'
import { execPath } from 'node:process'

spawn(execPath, [
  '--input-type=module',
  '--eval',
  // وعد غير قابل للحل أبدًا:
  'await new Promise(() => {})',
]).once('exit', code => {
  console.log(code) // يسجل `13`
})

برامج التحميل

وثائق برامج التحميل السابقة موجودة الآن في الوحدات: خطافات التخصيص.

خوارزمية الحل والتحميل

الميزات

يحتوي مُحلل الحل الافتراضي على الخصائص التالية:

حل قائم على عنوان URL للملف كما هو مستخدم بواسطة وحدات ES
حل عنوان URL النسبي والمطلق
لا امتدادات افتراضية
لا عناصر رئيسية للمجلدات
البحث عن حل حزمة محدد أساسي من خلال node_modules
لا يفشل في الامتدادات أو البروتوكولات غير المعروفة
يمكن أن يوفر اختياريًا تلميحًا للصيغة إلى مرحلة التحميل

يحتوي برنامج التحميل الافتراضي على الخصائص التالية:

دعم تحميل الوحدة المضمنة عبر عناوين URL node:
دعم تحميل الوحدة "ضمني" عبر عناوين URL data:
دعم تحميل الوحدة file:
يفشل في أي بروتوكول عنوان URL آخر
يفشل في الامتدادات غير المعروفة لتحميل file: (يدعم فقط .cjs و.js و.mjs)

خوارزمية الحل

تُعطى خوارزمية تحميل محدد وحدة ES من خلال طريقة ESM_RESOLVE أدناه. إنها تُرجع عنوان URL المُحلل لوحدة مُحددة نسبةً إلى parentURL.

تحدد خوارزمية الحل عنوان URL الكامل المُحلل لتحميل وحدة، بالإضافة إلى تنسيق الوحدة المقترح. لا تحدد خوارزمية الحل ما إذا كان بإمكان تحميل بروتوكول عنوان URL المُحلل، أو ما إذا كانت امتدادات الملفات مسموح بها، وبدلاً من ذلك، يتم تطبيق هذه التحقق بواسطة Node.js أثناء مرحلة التحميل (على سبيل المثال، إذا طُلب منها تحميل عنوان URL به بروتوكول ليس file: أو data: أو node:).

تحاول الخوارزمية أيضًا تحديد تنسيق الملف بناءً على الامتداد (انظر خوارزمية ESM_FILE_FORMAT أدناه). إذا لم تتعرف على امتداد الملف (مثلًا إذا لم يكن .mjs أو .cjs أو .json)، فسيتم إرجاع تنسيق undefined، والذي سيُلقي خطأً أثناء مرحلة التحميل.

يتم توفير خوارزمية تحديد تنسيق وحدة عنوان URL المُحلل بواسطة ESM_FILE_FORMAT، والتي تُرجع تنسيق الوحدة الفريد لأي ملف. يتم إرجاع تنسيق "module" لوحدة ECMAScript، بينما يتم استخدام تنسيق "commonjs" للإشارة إلى التحميل من خلال مُحمِّل CommonJS القديم. يمكن توسيع تنسيقات إضافية مثل "addon" في التحديثات المستقبلية.

في الخوارزميات التالية، يتم نشر جميع أخطاء الوظيفة الفرعية كأخطاء لهذه الروتينات الرئيسية ما لم يُذكر خلاف ذلك.

defaultConditions هي مصفوفة اسم بيئة مشروطة، ["node", "import"].

يمكن أن يُلقي المُحلل الأخطاء التالية:

محدد وحدة غير صالح: محدد الوحدة هو عنوان URL غير صالح، أو اسم حزمة، أو محدد مسار فرعي للحزمة.
تهيئة حزمة غير صالحة: تهيئة package.json غير صالحة أو تحتوي على تهيئة غير صالحة.
هدف حزمة غير صالح: تصدير الحزمة أو استيراداتها يُعرّف وحدة هدف للحزمة وهي من نوع أو سلسلة هدف غير صالحة.
مسار الحزمة غير مُصدّر: لا تُعرّف تصدير الحزمة أو تسمح بمسار فرعي هدف في الحزمة لوحدة معينة.
استيراد الحزمة غير مُعرّف: لا تُعرّف استيرادات الحزمة المُحدد.
وحدة غير موجودة: الحزمة أو الوحدة المطلوبة غير موجودة.
استيراد دليل غير مدعوم: يتوافق المسار المُحلل مع دليل، وهو ليس هدفًا مدعومًا لاستيراد الوحدات.

مواصفات خوارزمية الحل

ESM_RESOLVE(specifier, parentURL)

PACKAGE_RESOLVE(packageSpecifier, parentURL)

PACKAGE_SELF_RESOLVE(packageName, packageSubpath, parentURL)

PACKAGE_EXPORTS_RESOLVE(packageURL, subpath, exports, conditions)

PACKAGE_IMPORTS_RESOLVE(specifier, parentURL, conditions)

PACKAGE_IMPORTS_EXPORTS_RESOLVE(matchKey, matchObj, packageURL, isImports, conditions)

PATTERN_KEY_COMPARE(keyA, keyB)

PACKAGE_TARGET_RESOLVE(packageURL, target, patternMatch, isImports, conditions)

ESM_FILE_FORMAT(url)

LOOKUP_PACKAGE_SCOPE(url)

READ_PACKAGE_JSON(packageURL)

DETECT_MODULE_SYNTAX(source)

تخصيص خوارزمية حل مُحدد ESM

توفر خطافات تخصيص الوحدة النمطية آلية لتخصيص خوارزمية حل مُحدد ESM. مثال يوفر حلًا على طراز CommonJS لمُحددات ESM هو commonjs-extension-resolution-loader.

الوحدات: وحدات ECMAScript ​

مقدمة ​

تمكين ​

الحزم ​

مُحددات import ​

المصطلحات ​

امتدادات الملفات الإلزامية ​

عناوين URL ​

عناوين URL من نوع file: ​

استيرادات data: ​

node: الاستيرادات ​

سمات الاستيراد ​

الوحدات المضمنة ​

تعبيرات import() ​

import.meta ​

import.meta.dirname ​

import.meta.filename ​

import.meta.url ​

import.meta.resolve(specifier) ​

التشغيل البيني مع CommonJS ​

عبارات import ​

require ​

مسافات أسماء CommonJS ​

الفروقات بين وحدات ES و CommonJS ​

عدم وجود require أو exports أو module.exports ​

عدم وجود __filename أو __dirname ​

عدم وجود تحميل الوظائف الإضافية ​

عدم وجود require.resolve ​

عدم وجود NODE_PATH ​

عدم وجود require.extensions ​

عدم وجود require.cache ​

وحدات JSON ​

وحدات Wasm ​

await على مستوى الأعلى ​

برامج التحميل ​

خوارزمية الحل والتحميل ​

الميزات ​

خوارزمية الحل ​

مواصفات خوارزمية الحل ​

تخصيص خوارزمية حل مُحدد ESM ​

الوحدات: وحدات ECMAScript

مقدمة

تمكين

الحزم

مُحددات `import`

المصطلحات

امتدادات الملفات الإلزامية

عناوين URL

عناوين URL من نوع `file:`

استيرادات `data:`

`node:` الاستيرادات

سمات الاستيراد

الوحدات المضمنة

تعبيرات `import()`

`import.meta`

`import.meta.dirname`

`import.meta.filename`

`import.meta.url`

`import.meta.resolve(specifier)`

التشغيل البيني مع CommonJS

عبارات `import`

`require`

مسافات أسماء CommonJS

الفروقات بين وحدات ES و CommonJS

عدم وجود `require` أو `exports` أو `module.exports`

عدم وجود `filename` أو `dirname`

عدم وجود تحميل الوظائف الإضافية

عدم وجود `require.resolve`

عدم وجود `NODE_PATH`

عدم وجود `require.extensions`

عدم وجود `require.cache`

وحدات JSON

وحدات Wasm

`await` على مستوى الأعلى

برامج التحميل

خوارزمية الحل والتحميل

الميزات

خوارزمية الحل

مواصفات خوارزمية الحل

تخصيص خوارزمية حل مُحدد ESM