From 0f08a8e081558eb26f5a1b46ea6ce5a1a1253fd1 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Fri, 29 Mar 2019 00:07:09 +0100 Subject: [PATCH] doc: add information about modules cache behavior 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 Reviewed-By: Vse Mozhet Byt Signed-off-by: Beth Griggs --- doc/api/modules.md | 56 +++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 31 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index 5ef61141a6353c..40d3b525355250 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -196,28 +196,26 @@ NODE_MODULES_PATHS(START) -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 -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 @@ -412,7 +410,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. @@ -585,6 +583,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