From 4b75b64cae76489eb1dff70f6acfc4f4f5db1bb7 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Wed, 13 Nov 2019 20:40:16 -0800 Subject: [PATCH] doc: rename for clarity --- doc/api/esm.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index f3cdd124985762..6812447fe17f30 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -455,7 +455,7 @@ ignores) the top-level `"module"` field. Node.js can now run ES module entry points, and a package can contain both CommonJS and ES module entry points (either via separate specifiers such as -`'pkg'` and `'pkg/module'`, or both at the same specifier via [Conditional +`'pkg'` and `'pkg/es-module'`, or both at the same specifier via [Conditional Exports][] with the `--experimental-conditional-exports` flag). Unlike in the scenario where `"module"` is only used by bundlers, or ES module files are transpiled into CommonJS on the fly before evaluation by Node.js, the files @@ -465,20 +465,21 @@ referenced by the ES module entry point are evaluated as ES modules. When an application is using a package that provides both CommonJS and ES module sources, there is a risk of certain bugs if both versions of the package get -loaded. This potential comes from the fact that the `pkg` created by `const pkg -= require('pkg')` is not the same as the `pkg` created by `import pkg from -'pkg'` (or an alternative main path like `'pkg/module'`). This is the “dual -package hazard,” where two versions of the same package can be loaded within the -same runtime environment. While it is unlikely that an application or package -would intentionally load both versions directly, it is common for an application -to load one version while a dependency of the application loads the other -version. This hazard can happen because Node.js supports intermixing CommonJS -and ES modules, and can lead to unexpected behavior. +loaded. This potential comes from the fact that the `pkgInstance` created by +`const pkgInstance = require('pkg')` is not the same as the `pkgInstance` +created by `import pkgInstance from 'pkg'` (or an alternative main path like +`'pkg/module'`). This is the “dual package hazard,” where two versions of the +same package can be loaded within the same runtime environment. While it is +unlikely that an application or package would intentionally load both versions +directly, it is common for an application to load one version while a dependency +of the application loads the other version. This hazard can happen because +Node.js supports intermixing CommonJS and ES modules, and can lead to unexpected +behavior. If the package main export is a constructor, an `instanceof` comparison of instances created by the two versions returns `false`, and if the export is an -object, properties added to one (like `pkg.foo = 3`) are not present on the -other. This differs from how `import` and `require` statements work in +object, properties added to one (like `pkgInstance.foo = 3`) are not present on +the other. This differs from how `import` and `require` statements work in all-CommonJS or all-ES module environments, respectively, and therefore is surprising to users. It also differs from the behavior users are familiar with when using transpilation via tools like [Babel][] or [`esm`][].