1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add information about modules cache behavior

Browse Source 
This publicly documents that adding native module names will resolve
the added entry instead of the native module.

It also updates the description why extensions are deprecated.

PR-URL: https://github.com/nodejs/node/pull/26971
Refs: https://github.com/nodejs/node/pull/25362
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
This commit is contained in:
Ruben Bridgewater 2019-03-29 00:07:09 +01:00
parent fcdee7430d
commit 6eae41480b
No known key found for this signature in database
GPG Key ID: F07496B3EB3C1762
1 changed files with 25 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/api/modules.md
View File

@ -199,28 +199,26 @@ NODE_MODULES_PATHS(START)
<!--type=misc--> <!--type=misc-->
Modules are cached after the first time they are loaded. This means Modules are cached after the first time they are loaded. This means (among other
(among other things) that every call to `require('foo')` will get things) that every call to `require('foo')` will get exactly the same object
exactly the same object returned, if it would resolve to the same file. returned, if it would resolve to the same file.
Provided `require.cache` is not modified, multiple calls to Provided `require.cache` is not modified, multiple calls to `require('foo')`
`require('foo')` will not cause the module code to be executed multiple times. will not cause the module code to be executed multiple times. This is an
This is an important feature. With it, "partially done" objects can be returned, important feature. With it, "partially done" objects can be returned, thus
thus allowing transitive dependencies to be loaded even when they would cause allowing transitive dependencies to be loaded even when they would cause cycles.
cycles.
To have a module execute code multiple times, export a function, and call To have a module execute code multiple times, export a function, and call that
that function. function.
### Module Caching Caveats ### Module Caching Caveats
<!--type=misc--> <!--type=misc-->
Modules are cached based on their resolved filename. Since modules may Modules are cached based on their resolved filename. Since modules may resolve
resolve to a different filename based on the location of the calling to a different filename based on the location of the calling module (loading
module (loading from `node_modules` folders), it is not a *guarantee* from `node_modules` folders), it is not a *guarantee* that `require('foo')` will
that `require('foo')` will always return the exact same object, if it always return the exact same object, if it would resolve to different files.
would resolve to different files.
Additionally, on case-insensitive file systems or operating systems, different Additionally, on case-insensitive file systems or operating systems, different
resolved filenames can point to the same file, but the cache will still treat resolved filenames can point to the same file, but the cache will still treat
@ -415,7 +413,7 @@ are not found elsewhere.
On Windows, `NODE_PATH` is delimited by semicolons (`;`) instead of colons. On Windows, `NODE_PATH` is delimited by semicolons (`;`) instead of colons.
`NODE_PATH` was originally created to support loading modules from `NODE_PATH` was originally created to support loading modules from
varying paths before the current [module resolution][] algorithm was frozen. varying paths before the current [module resolution][] algorithm was defined.
`NODE_PATH` is still supported, but is less necessary now that the Node.js `NODE_PATH` is still supported, but is less necessary now that the Node.js
ecosystem has settled on a convention for locating dependent modules. ecosystem has settled on a convention for locating dependent modules.
@ -588,6 +586,11 @@ value from this object, the next `require` will reload the module. Note that
this does not apply to [native addons][], for which reloading will result in an this does not apply to [native addons][], for which reloading will result in an
error. error.
Adding or replacing entries is also possible. This cache is checked before
native modules and if a name matching a native module is added to the cache,
no require call is
going to receive the native module anymore. Use with care!
#### require.extensions #### require.extensions
<!-- YAML <!-- YAML
added: v0.3.0 added: v0.3.0
@ -606,22 +609,13 @@ Process files with the extension `.sjs` as `.js`:
require.extensions['.sjs'] = require.extensions['.js']; require.extensions['.sjs'] = require.extensions['.js'];
``` ```
**Deprecated.** In the past, this list has been used to load **Deprecated.** In the past, this list has been used to load non-JavaScript
non-JavaScript modules into Node.js by compiling them on-demand. modules into Node.js by compiling them on-demand. However, in practice, there
However, in practice, there are much better ways to do this, such as are much better ways to do this, such as loading modules via some other Node.js
loading modules via some other Node.js program, or compiling them to program, or compiling them to JavaScript ahead of time.
JavaScript ahead of time.
Since the module system is locked, this feature will probably never go Avoid using `require.extensions`. Use could cause subtle bugs and resolving the
away. However, it may have subtle bugs and complexities that are best extensions gets slower with each registered extension.
left untouched.
Note that the number of file system operations that the module system
has to perform in order to resolve a `require(...)` statement to a
filename scales linearly with the number of registered extensions.
In other words, adding extensions slows down the module loader and
should be discouraged.
#### require.main #### require.main
<!-- YAML <!-- YAML