diff --git a/doc/api/addons.md b/doc/api/addons.md index 8c08c5492e8c74..e973ec41113d72 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -1137,5 +1137,5 @@ const addon = require('./build/Release/addon'); [installation instructions]: https://github.com/nodejs/node-gyp#installation [libuv]: https://github.com/libuv/libuv [node-gyp]: https://github.com/nodejs/node-gyp -[require]: globals.html#globals_require +[require]: modules.html#modules_require [v8-docs]: https://v8docs.nodesource.com/ diff --git a/doc/api/globals.md b/doc/api/globals.md index c91acb32447c64..f3a2fc63779b89 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -2,8 +2,15 @@ -These objects are available in all modules. Some of these objects aren't -actually in the global scope but in the module scope - this will be noted. +These objects are available in all modules. The following variables may appear +to be global but are not. They exist only in the scope of modules, see the +[module system documentation][]: + +- [`__dirname`][] +- [`__filename`][] +- [`exports`][] +- [`module`][] +- [`require()`][] The objects listed here are specific to Node.js. There are a number of [built-in objects][] that are part of the JavaScript language itself, which are @@ -21,67 +28,12 @@ added: v0.1.103 Used to handle binary data. See the [buffer section][]. ## \_\_dirname - - - - -* {string} - -The directory name of the current module. This the same as the -[`path.dirname()`][] of the [`__filename`][]. - -`__dirname` is not actually a global but rather local to each module. -Example: running `node example.js` from `/Users/mjr` - -```js -console.log(__dirname); -// Prints: /Users/mjr -console.log(path.dirname(__filename)); -// Prints: /Users/mjr -``` +This variable may appear to be global but is not. See [`__dirname`]. ## \_\_filename - - - - -* {string} - -The file name of the current module. This is the resolved absolute path of the -current module file. - -For a main program this is not necessarily the same as the file name used in the -command line. -See [`__dirname`][] for the directory name of the current module. - -`__filename` is not actually a global but rather local to each module. - -Examples: - -Running `node example.js` from `/Users/mjr` - -```js -console.log(__filename); -// Prints: /Users/mjr/example.js -console.log(__dirname); -// Prints: /Users/mjr -``` - -Given two modules: `a` and `b`, where `b` is a dependency of -`a` and there is a directory structure of: - -* `/Users/mjr/app/a.js` -* `/Users/mjr/app/node_modules/b/b.js` - -References to `__filename` within `b.js` will return -`/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within -`a.js` will return `/Users/mjr/app/a.js`. +This variable may appear to be global but is not. See [`__filename`]. ## clearImmediate(immediateObject) - - - -A reference to the `module.exports` that is shorter to type. -See [module system documentation][] for details on when to use `exports` and -when to use `module.exports`. - -`exports` is not actually a global but rather local to each module. -See the [module system documentation][] for more information. +This variable may appear to be global but is not. See [`exports`]. ## global - - -* {Object} - -A reference to the current module. In particular -`module.exports` is used for defining what a module exports and makes -available through `require()`. - -`module` is not actually a global but rather local to each module. - -See the [module system documentation][] for more information. +This variable may appear to be global but is not. See [`module`]. ## process - - - -* {Function} - -To require modules. See the [Modules][] section. `require` is not actually a -global but rather local to each module. - -### require.cache - - -* {Object} - -Modules are cached in this object when they are required. By deleting a key -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. - -### require.extensions - - -> Stability: 0 - Deprecated - -* {Object} - -Instruct `require` on how to handle certain file extensions. - -Process files with the extension `.sjs` as `.js`: - -```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. - -In other words, adding extensions slows down the module loader and -should be discouraged. - -### require.resolve() - -Use the internal `require()` machinery to look up the location of a module, -but rather than loading the module, just return the resolved filename. +This variable may appear to be global but is not. See [`require()`]. ## setImmediate(callback[, ...args]) + + + +* {string} + +The directory name of the current module. This the same as the +[`path.dirname()`][] of the [`__filename`][]. + +Example: running `node example.js` from `/Users/mjr` + +```js +console.log(__dirname); +// Prints: /Users/mjr +console.log(path.dirname(__filename)); +// Prints: /Users/mjr +``` + +### \_\_filename + + + + +* {string} + +The file name of the current module. This is the resolved absolute path of the +current module file. + +For a main program this is not necessarily the same as the file name used in the +command line. + +See [`__dirname`][] for the directory name of the current module. + +Examples: + +Running `node example.js` from `/Users/mjr` + +```js +console.log(__filename); +// Prints: /Users/mjr/example.js +console.log(__dirname); +// Prints: /Users/mjr +``` + +Given two modules: `a` and `b`, where `b` is a dependency of +`a` and there is a directory structure of: + +* `/Users/mjr/app/a.js` +* `/Users/mjr/app/node_modules/b/b.js` + +References to `__filename` within `b.js` will return +`/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within +`a.js` will return `/Users/mjr/app/a.js`. + +### exports + + + + +A reference to the `module.exports` that is shorter to type. +See the section about the [exports shortcut][] for details on when to use +`exports` and when to use `module.exports`. + +### module + + + + +* {Object} + +A reference to the current module, see the section about the +[`module` object][]. In particular, `module.exports` is used for defining what +a module exports and makes available through `require()`. + +### require() + + + + +* {Function} + +To require modules. + +#### require.cache + + +* {Object} + +Modules are cached in this object when they are required. By deleting a key +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. + +#### require.extensions + + +> Stability: 0 - Deprecated + +* {Object} + +Instruct `require` on how to handle certain file extensions. + +Process files with the extension `.sjs` as `.js`: + +```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. + +In other words, adding extensions slows down the module loader and +should be discouraged. + +#### require.resolve() + + +Use the internal `require()` machinery to look up the location of a module, +but rather than loading the module, just return the resolved filename. + ## The `module` Object