doc: add information about modules cache behavior · nodejs/node@0f08a8e (original) (raw)

`@@ -196,28 +196,26 @@ NODE_MODULES_PATHS(START)

196

197

198

199

Modules are cached after the first time they are loaded. This means

200

`` -

(among other things) that every call to require('foo') will get

201

exactly the same object returned, if it would resolve to the same file.

199

Modules are cached after the first time they are loaded. This means (among other

200

`` +

things) that every call to require('foo') will get exactly the same object

201

returned, if it would resolve to the same file.

202

203

`` -

Provided require.cache is not modified, multiple calls to

204

`` -

require('foo') will not cause the module code to be executed multiple times.

205

This is an important feature. With it, "partially done" objects can be returned,

206

thus allowing transitive dependencies to be loaded even when they would cause

207

cycles.

203

`` +

Provided require.cache is not modified, multiple calls to require('foo')

204

will not cause the module code to be executed multiple times. This is an

205

important feature. With it, "partially done" objects can be returned, thus

206

allowing transitive dependencies to be loaded even when they would cause cycles.

208

207

209

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

210

that function.

208

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

209

function.

211

210

212

211

`### Module Caching Caveats

213

212

214

213

215

214

216

Modules are cached based on their resolved filename. Since modules may

217

resolve to a different filename based on the location of the calling

218

`` -

module (loading from node_modules folders), it is not a guarantee

219

`` -

that require('foo') will always return the exact same object, if it

220

would resolve to different files.

215

Modules are cached based on their resolved filename. Since modules may resolve

216

to a different filename based on the location of the calling module (loading

217

`` +

from node_modules folders), it is not a guarantee that require('foo') will

218

always return the exact same object, if it would resolve to different files.

221

219

222

220

`Additionally, on case-insensitive file systems or operating systems, different

223

221

`resolved filenames can point to the same file, but the cache will still treat

`@@ -412,7 +410,7 @@ are not found elsewhere.

412

410

`` On Windows, NODE_PATH is delimited by semicolons (;) instead of colons.

413

411

414

412

`` NODE_PATH was originally created to support loading modules from

415

varying paths before the current [module resolution][] algorithm was frozen.

413

varying paths before the current [module resolution][] algorithm was defined.

416

414

417

415

`` NODE_PATH is still supported, but is less necessary now that the Node.js

418

416

`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

585

583

`this does not apply to [native addons][], for which reloading will result in an

586

584

`error.

587

585

586

Adding or replacing entries is also possible. This cache is checked before

587

native modules and if a name matching a native module is added to the cache,

588

no require call is

589

going to receive the native module anymore. Use with care!

590

+

588

591

`#### require.extensions

589

592

`<!-- YAML

590

593

`added: v0.3.0

`` @@ -603,22 +606,13 @@ Process files with the extension .sjs as .js:

603

606

`require.extensions['.sjs'] = require.extensions['.js'];

604

607

```` ```

````

605

608

606

Deprecated. In the past, this list has been used to load

607

non-JavaScript modules into Node.js by compiling them on-demand.

608

However, in practice, there are much better ways to do this, such as

609

loading modules via some other Node.js program, or compiling them to

610

JavaScript ahead of time.

611

-

612

Since the module system is locked, this feature will probably never go

613

away. However, it may have subtle bugs and complexities that are best

614

left untouched.

615

-

616

Note that the number of file system operations that the module system

617

`` -

has to perform in order to resolve a require(...) statement to a

618

filename scales linearly with the number of registered extensions.

609

Deprecated. In the past, this list has been used to load non-JavaScript

610

modules into Node.js by compiling them on-demand. However, in practice, there

611

are much better ways to do this, such as loading modules via some other Node.js

612

program, or compiling them to JavaScript ahead of time.

619

613

620

In other words, adding extensions slows down the module loader and

621

should be discouraged.

614

`` +

Avoid using require.extensions. Use could cause subtle bugs and resolving the

615

extensions gets slower with each registered extension.

622

616

623

617

`#### require.main

624

618

`<!-- YAML