Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add information about modules cache behavior #26971

Closed
wants to merge 3 commits into from
Closed

doc: add information about modules cache behavior #26971

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4b390c2
docs: add information about modules cache behavior
BridgeAR Mar 28, 2019
3806b7e
fixup!
sagirk Mar 31, 2019
74b06dd
fixup!
sagirk Mar 31, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 25 additions & 31 deletions doc/api/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,28 +199,26 @@ NODE_MODULES_PATHS(START)

<!--type=misc-->

Modules are cached after the first time they are loaded. This means
(among other things) that every call to `require('foo')` will get
exactly the same object returned, if it would resolve to the same file.
Modules are cached after the first time they are loaded. This means (among other
things) that every call to `require('foo')` will get exactly the same object
returned, if it would resolve to the same file.

Provided `require.cache` is not modified, multiple calls to
`require('foo')` will not cause the module code to be executed multiple times.
This is an important feature. With it, "partially done" objects can be returned,
thus allowing transitive dependencies to be loaded even when they would cause
cycles.
Provided `require.cache` is not modified, multiple calls to `require('foo')`
will not cause the module code to be executed multiple times. This is an
important feature. With it, "partially done" objects can be returned, thus
allowing transitive dependencies to be loaded even when they would cause cycles.

To have a module execute code multiple times, export a function, and call
that function.
To have a module execute code multiple times, export a function, and call that
function.

### Module Caching Caveats

<!--type=misc-->

Modules are cached based on their resolved filename. Since modules may
resolve to a different filename based on the location of the calling
module (loading from `node_modules` folders), it is not a *guarantee*
that `require('foo')` will always return the exact same object, if it
would resolve to different files.
Modules are cached based on their resolved filename. Since modules may resolve
to a different filename based on the location of the calling module (loading
from `node_modules` folders), it is not a *guarantee* that `require('foo')` will
always return the exact same object, if it would resolve to different files.

Additionally, on case-insensitive file systems or operating systems, different
resolved filenames can point to the same file, but the cache will still treat
Expand Down Expand Up @@ -415,7 +413,7 @@ are not found elsewhere.
On Windows, `NODE_PATH` is delimited by semicolons (`;`) instead of colons.

`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
ecosystem has settled on a convention for locating dependent modules.
Expand Down Expand Up @@ -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
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
<!-- YAML
added: v0.3.0
Expand All @@ -606,22 +609,13 @@ Process files with the extension `.sjs` as `.js`:
require.extensions['.sjs'] = require.extensions['.js'];
```

**Deprecated.** In the past, this list has been used to load
non-JavaScript modules into Node.js by compiling them on-demand.
However, in practice, there are much better ways to do this, such as
loading modules via some other Node.js program, or compiling them to
JavaScript ahead of time.

Since the module system is locked, this feature will probably never go
away. However, it may have subtle bugs and complexities that are best
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.
**Deprecated.** In the past, this list has been used to load non-JavaScript
modules into Node.js by compiling them on-demand. However, in practice, there
are much better ways to do this, such as loading modules via some other Node.js
program, or compiling them to JavaScript ahead of time.

In other words, adding extensions slows down the module loader and
should be discouraged.
Avoid using `require.extensions`. Use could cause subtle bugs and resolving the
BridgeAR marked this conversation as resolved.
Show resolved Hide resolved
extensions gets slower with each registered extension.

#### require.main
<!-- YAML
Expand Down