diff --git a/doc/api/addons.md b/doc/api/addons.md index 17811245f1c23e..4a9b72e1661612 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -101,7 +101,7 @@ Addon module name is `addon`. Once the source code has been written, it must be compiled into the binary `addon.node` file. To do so, create a file called `binding.gyp` in the top-level of the project describing the build configuration of your module -using a JSON-like format. This file is used by [node-gyp][] -- a tool written +using a JSON-like format. This file is used by [node-gyp][] — a tool written specifically to compile Node.js Addons. ```json diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 9583fa15949fd2..2668d43e8754f4 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -395,7 +395,7 @@ deprecated: v6.0.0 * `size` {integer} The desired length of the new `Buffer`. -Allocates a new `Buffer` of `size` bytes. The `size` must be less than or equal +Allocates a new `Buffer` of `size` bytes. The `size` must be less than or equal to the value of [`buffer.kMaxLength`]. Otherwise, a [`RangeError`] is thrown. A zero-length `Buffer` will be created if `size <= 0`. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index b55bd0fea1d874..4759d9bd4a9337 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -38,7 +38,7 @@ the event loop until the spawned process either exits or is terminated. For convenience, the `child_process` module provides a handful of synchronous and asynchronous alternatives to [`child_process.spawn()`][] and -[`child_process.spawnSync()`][]. *Note that each of these alternatives are +[`child_process.spawnSync()`][]. *Note that each of these alternatives are implemented on top of [`child_process.spawn()`][] or [`child_process.spawnSync()`][].* * [`child_process.exec()`][]: spawns a shell and runs a command within that shell, @@ -140,7 +140,8 @@ added: v0.1.90 command line parsing should be compatible with `cmd.exe`. * `timeout` {number} **Default:** `0` * [`maxBuffer`][] {number} Largest amount of data (in bytes) allowed on - stdout or stderr - if exceeded child process is killed. **Default:** `200*1024` + stdout or stderr - if exceeded child process is killed. + **Default:** `200 * 1024`. * `killSignal` {string|integer} **Default:** `'SIGTERM'` * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). @@ -170,7 +171,7 @@ exec('cat *.js bad_file | wc -l', (error, stdout, stderr) => { ``` If a `callback` function is provided, it is called with the arguments -`(error, stdout, stderr)`. On success, `error` will be `null`. On error, +`(error, stdout, stderr)`. On success, `error` will be `null`. On error, `error` will be an instance of [`Error`][]. The `error.code` property will be the exit code of the child process while `error.signal` will be set to the signal that terminated the process. Any exit code other than `0` is considered @@ -218,7 +219,7 @@ added: v0.1.91 * `timeout` {number} **Default:** `0` * [`maxBuffer`][] {number} Largest amount of data (in bytes) allowed on stdout or stderr - if exceeded child process is killed. - **Default:**: `200*1024` + **Default:** `200 * 1024`. * `killSignal` {string|integer} **Default:** `'SIGTERM'` * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). @@ -446,7 +447,7 @@ disabled*. On non-Windows platforms, if `options.detached` is set to `true`, the child process will be made the leader of a new process group and session. Note that child processes may continue running after the parent exits regardless of -whether they are detached or not. See setsid(2) for more information. +whether they are detached or not. See setsid(2) for more information. By default, the parent will wait for the detached child to exit. To prevent the parent from waiting for a given `subprocess`, use the `subprocess.unref()` @@ -656,12 +657,12 @@ The `child_process.execSync()` method is generally identical to [`child_process.exec()`][] with the exception that the method will not return until the child process has fully closed. When a timeout has been encountered and `killSignal` is sent, the method won't return until the process has completely -exited. *Note that if the child process intercepts and handles the `SIGTERM` +exited. *Note that if the child process intercepts and handles the `SIGTERM` signal and doesn't exit, the parent process will wait until the child process has exited.* If the process times out, or has a non-zero exit code, this method ***will*** -throw. The [`Error`][] object will contain the entire result from +throw. The [`Error`][] object will contain the entire result from [`child_process.spawnSync()`][] **Note: Never pass unsanitised user input to this function. Any input @@ -997,7 +998,7 @@ properties: Defaults to `false`. The optional `callback` is a function that is invoked after the message is -sent but before the child may have received it. The function is called with a +sent but before the child may have received it. The function is called with a single argument: `null` on success, or an [`Error`][] object on failure. If no `callback` function is provided and the message cannot be sent, an diff --git a/doc/api/cli.md b/doc/api/cli.md index f1b33e883ae883..a8aee18e3efd3e 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -342,7 +342,7 @@ added: v6.12.0 --> `options...` are interpreted as if they had been specified on the command line -before the actual command line (so they can be overriden). Node will exit with +before the actual command line (so they can be overriden). Node will exit with an error if an option that is not allowed in the environment is used, such as `-p` or a script file. @@ -382,7 +382,7 @@ added: v3.0.0 Path to the file used to store the persistent REPL history. The default path is `~/.node_repl_history`, which is overridden by this variable. Setting the value -to an empty string (`""` or `" "`) disables persistent REPL history. +to an empty string (`''` or `' '`) disables persistent REPL history. ### `NODE_TTY_UNSAFE_ASYNC=1` diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 0bc768030728ab..fd5b8398bceb69 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -90,26 +90,26 @@ Node.js process and a cluster worker differs: idea of what the number 7 file descriptor references. 2. `server.listen(handle)` Listening on handles explicitly will cause the worker to use the supplied handle, rather than talk to the master - process. If the worker already has the handle, then it's presumed + process. If the worker already has the handle, then it's presumed that you know what you are doing. 3. `server.listen(0)` Normally, this will cause servers to listen on a - random port. However, in a cluster, each worker will receive the - same "random" port each time they do `listen(0)`. In essence, the - port is random the first time, but predictable thereafter. If you + random port. However, in a cluster, each worker will receive the + same "random" port each time they do `listen(0)`. In essence, the + port is random the first time, but predictable thereafter. If you want to listen on a unique port, generate a port number based on the cluster worker ID. There is no routing logic in Node.js, or in your program, and no shared -state between the workers. Therefore, it is important to design your +state between the workers. Therefore, it is important to design your program such that it does not rely too heavily on in-memory data objects for things like sessions and login. Because workers are all separate processes, they can be killed or re-spawned depending on your program's needs, without affecting other -workers. As long as there are some workers still alive, the server will -continue to accept connections. If no workers are alive, existing connections -will be dropped and new connections will be refused. Node.js does not -automatically manage the number of workers for you, however. It is your +workers. As long as there are some workers still alive, the server will +continue to accept connections. If no workers are alive, existing connections +will be dropped and new connections will be refused. Node.js does not +automatically manage the number of workers for you, however. It is your responsibility to manage the worker pool for your application's needs. Although a primary use case for the `cluster` module is networking, it can @@ -489,7 +489,7 @@ Emitted after the worker IPC channel has disconnected. This can occur when a worker exits gracefully, is killed, or is disconnected manually (such as with worker.disconnect()). -There may be a delay between the `'disconnect'` and `'exit'` events. These events +There may be a delay between the `'disconnect'` and `'exit'` events. These events can be used to detect if the process is stuck in a cleanup or if there are long-living connections. @@ -582,7 +582,7 @@ The `addressType` is one of: * `4` (TCPv4) * `6` (TCPv6) * `-1` (unix domain socket) -* `"udp4"` or `"udp6"` (UDP v4 or v6) +* `'udp4'` or `'udp6'` (UDP v4 or v6) ## Event: 'message' @@ -709,7 +709,7 @@ distribute IOCP handles without incurring a large performance hit. `cluster.schedulingPolicy` can also be set through the `NODE_CLUSTER_SCHED_POLICY` environment variable. Valid -values are `"rr"` and `"none"`. +values are `'rr'` and `'none'`. ## cluster.settings Returns the Diffie-Hellman generator in the specified `encoding`, which can -be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is +be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrime([encoding]) diff --git a/doc/api/debugger.md b/doc/api/debugger.md index a24437021b7bea..92b49fc9ed77eb 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -68,7 +68,7 @@ debug> repl Press Ctrl + C to leave debug repl > x 5 -> 2+2 +> 2 + 2 4 debug> next break in /home/indutny/Code/git/indutny/myscript.js:5 diff --git a/doc/api/dns.md b/doc/api/dns.md index 7fce91970aa10e..e4321b487340cf 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -212,7 +212,7 @@ will contain an array of IPv4 addresses (e.g. * `options` {Object} * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. The callback receives an array of `{ address: '1.2.3.4', ttl: 60 }` objects - rather than an array of strings. The TTL is expressed in seconds. + rather than an array of strings. The TTL is expressed in seconds. * `callback` {Function} An `(err, result)` callback function. ## dns.resolve6(hostname[, options], callback) @@ -228,7 +228,7 @@ will contain an array of IPv6 addresses. * `options` {Object} * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. The callback receives an array of `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` - objects rather than an array of strings. The TTL is expressed in seconds. + objects rather than an array of strings. The TTL is expressed in seconds. * `callback` {Function} An `(err, result)` callback function. ## dns.resolveCname(hostname, callback) @@ -258,7 +258,7 @@ added: v0.9.12 Uses the DNS protocol to resolve regular expression based records (`NAPTR` records) for the `hostname`. The `callback` function has arguments -`(err, addresses)`. The `addresses` argument passed to the `callback` function +`(err, addresses)`. The `addresses` argument passed to the `callback` function will contain an array of objects with the following properties: * `flags` diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 917e3e8134a37c..8a768949f0530b 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -26,10 +26,10 @@ using the `tools/doc/generate.js` program. An HTML template is located at Throughout the documentation, you will see indications of a section's -stability. The Node.js API is still somewhat changing, and as it -matures, certain parts are more reliable than others. Some are so +stability. The Node.js API is still somewhat changing, and as it +matures, certain parts are more reliable than others. Some are so proven, and so relied upon, that they are unlikely to ever change at -all. Others are brand new and experimental, or known to be hazardous +all. Others are brand new and experimental, or known to be hazardous and in the process of being redesigned. The stability indices are as follows: diff --git a/doc/api/domain.md b/doc/api/domain.md index 08d6edc7d8cb24..99a44925034827 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -12,7 +12,7 @@ but should expect to have to migrate to a different solution in the future. Domains provide a way to handle multiple different IO operations as a -single group. If any of the event emitters or callbacks registered to a +single group. If any of the event emitters or callbacks registered to a domain emit an `'error'` event, or throw an error, then the domain object will be notified, rather than losing the context of the error in the `process.on('uncaughtException')` handler, or causing the program to @@ -30,7 +30,7 @@ never any way to safely "pick up where you left off", without leaking references, or creating some other sort of undefined brittle state. The safest way to respond to a thrown error is to shut down the -process. Of course, in a normal web server, you might have many +process. Of course, in a normal web server, you might have many connections open, and it is not reasonable to abruptly shut those down because an error was triggered by someone else. @@ -40,7 +40,7 @@ time, and stop listening for new requests in that worker. In this way, `domain` usage goes hand-in-hand with the cluster module, since the master process can fork a new worker when a worker -encounters an error. For Node.js programs that scale to multiple +encounters an error. For Node.js programs that scale to multiple machines, the terminating proxy or service registry can take note of the failure, and react accordingly. @@ -103,7 +103,7 @@ if (cluster.isMaster) { const domain = require('domain'); // See the cluster documentation for more details about using - // worker processes to serve requests. How it works, caveats, etc. + // worker processes to serve requests. How it works, caveats, etc. const server = require('http').createServer((req, res) => { const d = domain.create(); @@ -126,7 +126,7 @@ if (cluster.isMaster) { // stop taking new requests. server.close(); - // Let the master know we're dead. This will trigger a + // Let the master know we're dead. This will trigger a // 'disconnect' in the cluster master, and then it will fork // a new worker. cluster.worker.disconnect(); @@ -155,7 +155,7 @@ if (cluster.isMaster) { server.listen(PORT); } -// This part is not important. Just an example routing thing. +// This part is not important. Just an example routing thing. // You'd put your fancy application logic here. function handleRequest(req, res) { switch (req.url) { @@ -197,11 +197,11 @@ the active domain at the time of their creation. Additionally, callbacks passed to lowlevel event loop requests (such as to fs.open, or other callback-taking methods) will automatically be -bound to the active domain. If they throw, then the domain will catch +bound to the active domain. If they throw, then the domain will catch the error. In order to prevent excessive memory usage, Domain objects themselves -are not implicitly added as children of the active domain. If they +are not implicitly added as children of the active domain. If they were, then it would be too easy to prevent request and response objects from being properly garbage collected. @@ -218,7 +218,7 @@ Implicit binding only takes care of thrown errors and `'error'` events. Sometimes, the domain in use is not the one that ought to be used for a -specific event emitter. Or, the event emitter could have been created +specific event emitter. Or, the event emitter could have been created in the context of one domain, but ought to instead be bound to some other domain. @@ -268,7 +268,7 @@ Returns a new Domain object. The Domain class encapsulates the functionality of routing errors and uncaught exceptions to the active Domain object. -Domain is a child class of [`EventEmitter`][]. To handle the errors that it +Domain is a child class of [`EventEmitter`][]. To handle the errors that it catches, listen to its `'error'` event. ### domain.run(fn[, ...args]) @@ -318,13 +318,13 @@ to the domain. * `emitter` {EventEmitter|Timer} emitter or timer to be added to the domain -Explicitly adds an emitter to the domain. If any event handlers called by +Explicitly adds an emitter to the domain. If any event handlers called by the emitter throw an error, or if the emitter emits an `'error'` event, it will be routed to the domain's `'error'` event, just like with implicit binding. This also works with timers that are returned from [`setInterval()`][] and -[`setTimeout()`][]. If their callback function throws, it will be caught by +[`setTimeout()`][]. If their callback function throws, it will be caught by the domain 'error' handler. If the Timer or EventEmitter was already bound to a domain, it is removed @@ -334,7 +334,7 @@ from that one, and bound to this one instead. * `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain -The opposite of [`domain.add(emitter)`][]. Removes domain handling from the +The opposite of [`domain.add(emitter)`][]. Removes domain handling from the specified emitter. ### domain.bind(callback) @@ -343,7 +343,7 @@ specified emitter. * Returns: {Function} The bound function The returned function will be a wrapper around the supplied callback -function. When the returned function is called, any errors that are +function. When the returned function is called, any errors that are thrown will be routed to the domain's `'error'` event. #### Example @@ -370,7 +370,7 @@ d.on('error', (er) => { * `callback` {Function} The callback function * Returns: {Function} The intercepted function -This method is almost identical to [`domain.bind(callback)`][]. However, in +This method is almost identical to [`domain.bind(callback)`][]. However, in addition to catching thrown errors, it will also intercept [`Error`][] objects sent as the first argument to the function. @@ -439,7 +439,7 @@ without exiting the domain. ### domain.dispose() -> Stability: 0 - Deprecated. Please recover from failed IO actions +> Stability: 0 - Deprecated. Please recover from failed IO actions > explicitly via error event handlers set on the domain. Once `dispose` has been called, the domain will no longer be used by callbacks diff --git a/doc/api/errors.md b/doc/api/errors.md index 49b4bac595a6dc..306b58a908ee5d 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -107,7 +107,7 @@ pass or fail). For *all* `EventEmitter` objects, if an `'error'` event handler is not provided, the error will be thrown, causing the Node.js process to report an -unhandled exception and crash unless either: The [`domain`][domains] module is used +unhandled exception and crash unless either: The [`domain`][domains] module is used appropriately or a handler has been registered for the [`process.on('uncaughtException')`][] event. @@ -133,7 +133,7 @@ exactly how errors raised by those methods are propagated. Most asynchronous methods exposed by the Node.js core API follow an idiomatic -pattern referred to as a "Node.js style callback". With this pattern, a +pattern referred to as a "Node.js style callback". With this pattern, a callback function is passed to the method as an argument. When the operation either completes or an error is raised, the callback function is called with the Error object (if any) passed as the first argument. If no error was raised, @@ -155,7 +155,7 @@ fs.readFile('/some/file/that/does-exist', nodeStyleCallback); ``` The JavaScript `try / catch` mechanism **cannot** be used to intercept errors -generated by asynchronous APIs. A common mistake for beginners is to try to +generated by asynchronous APIs. A common mistake for beginners is to try to use `throw` inside a Node.js style callback: ```js @@ -204,7 +204,7 @@ provided text message. If an object is passed as `message`, the text message is generated by calling `message.toString()`. The `error.stack` property will represent the point in the code at which `new Error()` was called. Stack traces are dependent on [V8's stack trace API][]. Stack traces extend only to either -(a) the beginning of *synchronous code execution*, or (b) the number of frames +(a) the beginning of *synchronous code execution*, or (b) the number of frames given by the property `Error.stackTraceLimit`, whichever is smaller. ### Error.captureStackTrace(targetObject[, constructorOpt]) @@ -502,7 +502,7 @@ found [here][online]. - `EACCES` (Permission denied): An attempt was made to access a file in a way forbidden by its file access permissions. -- `EADDRINUSE` (Address already in use): An attempt to bind a server +- `EADDRINUSE` (Address already in use): An attempt to bind a server ([`net`][], [`http`][], or [`https`][]) to a local address failed due to another server on the local system already occupying that address. @@ -530,14 +530,14 @@ found [here][online]. `ulimit -n 2048` in the same shell that will run the Node.js process. - `ENOENT` (No such file or directory): Commonly raised by [`fs`][] operations - to indicate that a component of the specified pathname does not exist -- no + to indicate that a component of the specified pathname does not exist — no entity (file or directory) could be found by the given path. - `ENOTDIR` (Not a directory): A component of the given pathname existed, but was not a directory as expected. Commonly raised by [`fs.readdir`][]. - `ENOTEMPTY` (Directory not empty): A directory with entries was the target - of an operation that requires an empty directory -- usually [`fs.unlink`][]. + of an operation that requires an empty directory — usually [`fs.unlink`][]. - `EPERM` (Operation not permitted): An attempt was made to perform an operation that requires elevated privileges. @@ -549,7 +549,7 @@ found [here][online]. - `ETIMEDOUT` (Operation timed out): A connect or send request failed because the connected party did not properly respond after a period of time. Usually - encountered by [`http`][] or [`net`][] -- often a sign that a `socket.end()` + encountered by [`http`][] or [`net`][] — often a sign that a `socket.end()` was not properly called. [`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback diff --git a/doc/api/fs.md b/doc/api/fs.md index b47e639e3ca98f..74e3cc3c460c29 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -6,7 +6,7 @@ -File I/O is provided by simple wrappers around standard POSIX functions. To +File I/O is provided by simple wrappers around standard POSIX functions. To use this module do `require('fs')`. All the methods have asynchronous and synchronous forms. @@ -67,7 +67,7 @@ fs.rename('/tmp/hello', '/tmp/world', (err) => { In busy processes, the programmer is _strongly encouraged_ to use the asynchronous versions of these calls. The synchronous versions will block -the entire process until they complete--halting all connections. +the entire process until they complete — halting all connections. The relative path to a filename can be used. Remember, however, that this path will be relative to `process.cwd()`. @@ -252,16 +252,16 @@ page. The times in the stat object have the following semantics: -* `atime` "Access Time" - Time when file data last accessed. Changed +* `atime` "Access Time" - Time when file data last accessed. Changed by the mknod(2), utimes(2), and read(2) system calls. * `mtime` "Modified Time" - Time when file data last modified. Changed by the mknod(2), utimes(2), and write(2) system calls. * `ctime` "Change Time" - Time when file status was last changed - (inode data modification). Changed by the chmod(2), chown(2), + (inode data modification). Changed by the chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), and write(2) system calls. -* `birthtime` "Birth Time" - Time of file creation. Set once when the - file is created. On filesystems where birthtime is not available, +* `birthtime` "Birth Time" - Time of file creation. Set once when the + file is created. On filesystems where birthtime is not available, this field may instead hold either the `ctime` or `1970-01-01T00:00Z` (ie, unix epoch timestamp `0`). Note that this value may be greater than `atime` or `mtime` in this case. On Darwin @@ -270,7 +270,7 @@ The times in the stat object have the following semantics: utimes(2) system call. Prior to Node v0.12, the `ctime` held the `birthtime` on Windows -systems. Note that as of v0.12, `ctime` is not "creation time", and +systems. Note that as of v0.12, `ctime` is not "creation time", and on Unix systems, it never was. ## Class: fs.WriteStream @@ -567,7 +567,7 @@ added: v0.0.2 * `callback` {Function} * `err` {Error} -Asynchronous close(2). No arguments other than a possible exception are given +Asynchronous close(2). No arguments other than a possible exception are given to the completion callback. ## fs.closeSync(fd) @@ -621,7 +621,7 @@ const defaults = { ``` `options` can include `start` and `end` values to read a range of bytes from -the file instead of the entire file. Both `start` and `end` are inclusive and +the file instead of the entire file. Both `start` and `end` are inclusive and start counting at 0. If `fd` is specified and `start` is omitted or `undefined`, `fs.createReadStream()` reads sequentially from the current file position. The `encoding` can be any one of those accepted by [`Buffer`][]. @@ -632,8 +632,8 @@ emitted. Note that `fd` should be blocking; non-blocking `fd`s should be passed to [`net.Socket`][]. If `autoClose` is false, then the file descriptor won't be closed, even if -there's an error. It is your responsibility to close it and make sure -there's no file descriptor leak. If `autoClose` is set to true (default +there's an error. It is your responsibility to close it and make sure +there's no file descriptor leak. If `autoClose` is set to true (default behavior), on `error` or `end` the file descriptor will be closed automatically. @@ -677,7 +677,7 @@ const defaults = { ``` `options` may also include a `start` option to allow writing data at -some position past the beginning of the file. Modifying a file rather +some position past the beginning of the file. Modifying a file rather than replacing it may require a `flags` mode of `r+` rather than the default mode `w`. The `defaultEncoding` can be any one of those accepted by [`Buffer`][]. @@ -708,7 +708,7 @@ deprecated: v1.0.0 * `exists` {Boolean} Test whether or not the given path exists by checking with the file system. -Then call the `callback` argument with either true or false. Example: +Then call the `callback` argument with either true or false. Example: ```js fs.exists('/etc/passwd', (exists) => { @@ -1286,7 +1286,7 @@ to a non-existent file. The exclusive flag may or may not work with network file systems. `flags` can also be a number as documented by open(2); commonly used constants -are available from `fs.constants`. On Windows, flags are translated to +are available from `fs.constants`. On Windows, flags are translated to their equivalent ones where applicable, e.g. `O_WRONLY` to `FILE_GENERIC_WRITE`, or `O_EXCL|O_CREAT` to `CREATE_NEW`, as accepted by CreateFileW. @@ -1373,7 +1373,7 @@ added: v0.1.8 * `err` {Error} * `files` {string[]|Buffer[]} -Asynchronous readdir(3). Reads the contents of a directory. +Asynchronous readdir(3). Reads the contents of a directory. The callback gets two arguments `(err, files)` where `files` is an array of the names of the files in the directory excluding `'.'` and `'..'`. @@ -1809,12 +1809,12 @@ added: v0.5.10 * `filename` {string|Buffer} Watch for changes on `filename`, where `filename` is either a file or a -directory. The returned object is a [`fs.FSWatcher`][]. +directory. The returned object is a [`fs.FSWatcher`][]. The second argument is optional. If `options` is provided as a string, it specifies the `encoding`. Otherwise `options` should be passed as an object. -The listener callback gets two arguments `(eventType, filename)`. `eventType` is either +The listener callback gets two arguments `(eventType, filename)`. `eventType` is either `'rename'` or `'change'`, and `filename` is the name of the file which triggered the event. @@ -1879,7 +1879,7 @@ this improves the usability of file watching. This is expected behavior. Providing `filename` argument in the callback is only supported on Linux and -Windows. Even on supported platforms, `filename` is not always guaranteed to +Windows. Even on supported platforms, `filename` is not always guaranteed to be provided. Therefore, don't assume that `filename` argument is always provided in the callback, and have some fallback logic if it is null. @@ -2000,7 +2000,7 @@ added: v0.11.5 * `written` {integer} * `string` {string} -Write `string` to the file specified by `fd`. If `string` is not a string, then +Write `string` to the file specified by `fd`. If `string` is not a string, then the value will be coerced to one. `position` refers to the offset from the beginning of the file where this data diff --git a/doc/api/globals.md b/doc/api/globals.md index 054bc2300bd411..79b11d0bde6c0e 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -188,7 +188,7 @@ added: v0.1.13 * {Function} -To require modules. See the [Modules][] section. `require` is not actually a +To require modules. See the [Modules][] section. `require` is not actually a global but rather local to each module. ### require.cache @@ -221,14 +221,14 @@ 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 +**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 +away. However, it may have subtle bugs and complexities that are best left untouched. ### require.resolve() diff --git a/doc/api/http.md b/doc/api/http.md index 597aa3fda179ed..00b0bb5b3b8c88 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -9,7 +9,7 @@ To use the HTTP server and client one must `require('http')`. The HTTP interfaces in Node.js are designed to support many features of the protocol which have been traditionally difficult to use. In particular, large, possibly chunk-encoded, messages. The interface is -careful to never buffer entire requests or responses--the +careful to never buffer entire requests or responses — the user is able to stream data. HTTP message headers are represented by an object like this: @@ -33,7 +33,7 @@ parse the actual headers or the body. See [`message.headers`][] for details on how duplicate headers are handled. The raw headers as they were received are retained in the `rawHeaders` -property, which is an array of `[key, value, key2, value2, ...]`. For +property, which is an array of `[key, value, key2, value2, ...]`. For example, the previous message header object might have a `rawHeaders` list like the following: @@ -122,9 +122,9 @@ added: v0.3.4 for TCP Keep-Alive packets. Ignored when the `keepAlive` option is `false` or `undefined`. Default = `1000`. * `maxSockets` {number} Maximum number of sockets to allow per - host. Default = `Infinity`. + host. Default = `Infinity`. * `maxFreeSockets` {number} Maximum number of sockets to leave open - in a free state. Only relevant if `keepAlive` is set to `true`. + in a free state. Only relevant if `keepAlive` is set to `true`. Default = `256`. The default [`http.globalAgent`][] that is used by [`http.request()`][] has all @@ -202,9 +202,9 @@ added: v0.11.4 Destroy any sockets that are currently in use by the agent. -It is usually not necessary to do this. However, if you are using an +It is usually not necessary to do this. However, if you are using an agent with `keepAlive` enabled, then it is best to explicitly shut down -the agent when you know that it will no longer be used. Otherwise, +the agent when you know that it will no longer be used. Otherwise, sockets may hang open for quite a long time before the server terminates them. @@ -216,7 +216,7 @@ added: v0.11.4 * {Object} An object which contains arrays of sockets currently awaiting use by -the agent when `keepAlive` is enabled. Do not modify. +the agent when `keepAlive` is enabled. Do not modify. ### agent.getName(options) -This object is created internally and returned from [`http.request()`][]. It -represents an _in-progress_ request whose header has already been queued. The +This object is created internally and returned from [`http.request()`][]. It +represents an _in-progress_ request whose header has already been queued. The header is still mutable using the `setHeader(name, value)`, `getHeader(name)`, -`removeHeader(name)` API. The actual header will be sent along with the first +`removeHeader(name)` API. The actual header will be sent along with the first data chunk or when closing the connection. To get the response, add a listener for [`'response'`][] to the request object. [`'response'`][] will be emitted from the request object when the response -headers have been received. The [`'response'`][] event is executed with one +headers have been received. The [`'response'`][] event is executed with one argument which is an instance of [`http.IncomingMessage`][]. During the [`'response'`][] event, one can add listeners to the response object; particularly to listen for the `'data'` event. If no [`'response'`][] handler is added, then the response will be -entirely discarded. However, if you add a [`'response'`][] event handler, +entirely discarded. However, if you add a [`'response'`][] event handler, then you **must** consume the data from the response object, either by calling `response.read()` whenever there is a `'readable'` event, or by adding a `'data'` handler, or by calling the `.resume()` method. -Until the data is consumed, the `'end'` event will not fire. Also, until +Until the data is consumed, the `'end'` event will not fire. Also, until the data is read it will consume memory that can eventually lead to a 'process out of memory' error. @@ -517,11 +517,11 @@ added: v1.6.0 Flush the request headers. For efficiency reasons, Node.js normally buffers the request headers until you -call `request.end()` or write the first chunk of request data. It then tries +call `request.end()` or write the first chunk of request data. It then tries hard to pack the request headers and data into a single TCP packet. That's usually what you want (it saves a TCP round-trip) but not when the first -data is not sent until possibly much later. `request.flushHeaders()` lets you bypass +data is not sent until possibly much later. `request.flushHeaders()` lets you bypass the optimization and kickstart the request. ### request.setNoDelay([noDelay]) @@ -567,9 +567,9 @@ added: v0.1.29 * `encoding` {string} * `callback` {Function} -Sends a chunk of the body. By calling this method +Sends a chunk of the body. By calling this method many times, the user can stream a request body to a -server--in that case it is suggested to use the +server — in that case it is suggested to use the `['Transfer-Encoding', 'chunked']` header line when creating the request. @@ -733,7 +733,7 @@ added: v0.1.90 * `callback` {Function} -Stops the server from accepting new connections. See [`net.Server.close()`][]. +Stops the server from accepting new connections. See [`net.Server.close()`][]. ### server.listen(handle[, callback]) -This object is created internally by an HTTP server--not by the user. It is +This object is created internally by an HTTP server — not by the user. It is passed as the second parameter to the [`'request'`][] event. The response implements, but does not inherit from, the [Writable Stream][] @@ -1015,8 +1015,8 @@ added: v0.4.0 * `name` {string} * `value` {string} -Sets a single header value for implicit headers. If this header already exists -in the to-be-sent headers, its value will be replaced. Use an array of strings +Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings here if you need to send multiple headers with the same name. Example: @@ -1056,12 +1056,12 @@ added: v0.9.12 * `msecs` {number} * `callback` {Function} -Sets the Socket's timeout value to `msecs`. If a callback is +Sets the Socket's timeout value to `msecs`. If a callback is provided, then it is added as a listener on the `'timeout'` event on the response object. If no `'timeout'` listener is added to the request, the response, or -the server, then sockets are destroyed when they time out. If you +the server, then sockets are destroyed when they time out. If you assign a handler on the request, the response, or the server's `'timeout'` events, then it is your responsibility to handle timed out sockets. @@ -1313,8 +1313,8 @@ added: v0.11.6 The raw request/response headers list exactly as they were received. -Note that the keys and values are in the same list. It is *not* a -list of tuples. So, the even-numbered offsets are key values, and the +Note that the keys and values are in the same list. It is *not* a +list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. Header names are not lowercased, and duplicates are not merged. @@ -1341,7 +1341,7 @@ added: v0.11.6 * {Array} The raw request/response trailer keys and values exactly as they were -received. Only populated at the `'end'` event. +received. Only populated at the `'end'` event. ### message.setTimeout(msecs, callback) -An Agent object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] +An Agent object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] for more information. ## Class: https.Server diff --git a/doc/api/modules.md b/doc/api/modules.md index e87b209395fb1a..59c675f17c813e 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -28,7 +28,7 @@ exports.circumference = (r) => 2 * PI * r; ``` The module `circle.js` has exported the functions `area()` and -`circumference()`. To add functions and objects to the root of your module, +`circumference()`. To add functions and objects to the root of your module, you can add them to the special `exports` object. Variables local to the module will be private, because the module is wrapped @@ -92,7 +92,7 @@ Let's say that we wanted to have the folder at specific version of a package. Packages can depend on one another. In order to install package `foo`, you -may have to install a specific version of package `bar`. The `bar` package +may have to install a specific version of package `bar`. The `bar` package may itself have dependencies, and in some cases, these dependencies may even collide or form cycles. @@ -121,12 +121,12 @@ the version that is symlinked into Furthermore, to make the module lookup process even more optimal, rather than putting packages directly in `/usr/lib/node`, we could put them in -`/usr/lib/node_modules//`. Then Node.js will not bother +`/usr/lib/node_modules//`. Then Node.js will not bother looking for missing dependencies in `/usr/node_modules` or `/node_modules`. In order to make modules available to the Node.js REPL, it might be useful to also add the `/usr/lib/node_modules` folder to the `$NODE_PATH` environment -variable. Since the module lookups using `node_modules` folders are all +variable. Since the module lookups using `node_modules` folders are all relative, and based on the real path of the files making the calls to `require()`, the packages themselves can be anywhere. @@ -194,12 +194,12 @@ NODE_MODULES_PATHS(START) -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 things) that every call to `require('foo')` will get exactly the same object returned, if it would resolve to the same file. Multiple calls to `require('foo')` may not cause the module code to be -executed multiple times. This is an important feature. With it, +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. @@ -210,7 +210,7 @@ function, and call that function. -Modules are cached based on their resolved filename. Since modules may +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 @@ -226,14 +226,14 @@ irrespective of whether or not `./foo` and `./FOO` are the same file. -Node.js has several modules compiled into the binary. These modules are +Node.js has several modules compiled into the binary. These modules are described in greater detail elsewhere in this documentation. The core modules are defined within Node.js's source and are located in the `lib/` folder. Core modules are always preferentially loaded if their identifier is -passed to `require()`. For instance, `require('http')` will always +passed to `require()`. For instance, `require('http')` will always return the built in HTTP module, even if there is a file by that name. ## Cycles @@ -273,13 +273,13 @@ console.log('b done'); console.log('main starting'); const a = require('./a.js'); const b = require('./b.js'); -console.log('in main, a.done=%j, b.done=%j', a.done, b.done); +console.log('in main, a.done = %j, b.done = %j', a.done, b.done); ``` -When `main.js` loads `a.js`, then `a.js` in turn loads `b.js`. At that -point, `b.js` tries to load `a.js`. In order to prevent an infinite +When `main.js` loads `a.js`, then `a.js` in turn loads `b.js`. At that +point, `b.js` tries to load `a.js`. In order to prevent an infinite loop, an **unfinished copy** of the `a.js` exports object is returned to the -`b.js` module. `b.js` then finishes loading, and its `exports` object is +`b.js` module. `b.js` then finishes loading, and its `exports` object is provided to the `a.js` module. By the time `main.js` has loaded both modules, they're both finished. @@ -294,7 +294,7 @@ in b, a.done = false b done in a, b.done = true a done -in main, a.done=true, b.done=true +in main, a.done = true, b.done = true ``` If you have cyclic module dependencies in your program, make sure to @@ -312,7 +312,7 @@ required filename with the added extensions: `.js`, `.json`, and finally parsed as JSON text files. `.node` files are interpreted as compiled addon modules loaded with `dlopen`. -A required module prefixed with `'/'` is an absolute path to the file. For +A required module prefixed with `'/'` is an absolute path to the file. For example, `require('/home/marco/foo.js')` will load the file at `/home/marco/foo.js`. @@ -336,7 +336,7 @@ There are three ways in which a folder may be passed to `require()` as an argument. The first is to create a `package.json` file in the root of the folder, -which specifies a `main` module. An example package.json file might +which specifies a `main` module. An example package.json file might look like this: ```json @@ -350,7 +350,7 @@ If this was in a folder at `./some-library`, then This is the extent of Node.js's awareness of package.json files. -Note: If the file specified by the `"main"` entry of `package.json` is missing +Note: If the file specified by the `'main'` entry of `package.json` is missing and can not be resolved, Node.js will report the entire module as missing with the default error: @@ -360,7 +360,7 @@ Error: Cannot find module 'some-library' If there is no package.json file present in the directory, then Node.js will attempt to load an `index.js` or `index.node` file out of that -directory. For example, if there was no package.json file in the above +directory. For example, if there was no package.json file in the above example, then `require('./some-library')` would attempt to load: * `./some-library/index.js` @@ -403,7 +403,7 @@ same module resolution semantics. If the `NODE_PATH` environment variable is set to a colon-delimited list of absolute paths, then Node.js will search those paths for modules if they -are not found elsewhere. (Note: On Windows, `NODE_PATH` is delimited by +are not found elsewhere. (Note: On Windows, `NODE_PATH` is delimited by semicolons instead of colons.) `NODE_PATH` was originally created to support loading modules from @@ -412,7 +412,7 @@ varying paths before the current [module resolution][] algorithm was frozen. `NODE_PATH` is still supported, but is less necessary now that the Node.js ecosystem has settled on a convention for locating dependent modules. Sometimes deployments that rely on `NODE_PATH` show surprising behavior -when people are unaware that `NODE_PATH` must be set. Sometimes a +when people are unaware that `NODE_PATH` must be set. Sometimes a module's dependencies change, causing a different version (or even a different module) to be loaded as the `NODE_PATH` is searched. @@ -425,8 +425,8 @@ Additionally, Node.js will search in the following locations: Where `$HOME` is the user's home directory, and `$PREFIX` is Node.js's configured `node_prefix`. -These are mostly for historic reasons. **You are highly encouraged -to place your dependencies locally in `node_modules` folders.** They +These are mostly for historic reasons. **You are highly encouraged +to place your dependencies locally in `node_modules` folders.** They will be loaded faster, and more reliably. ## The module wrapper @@ -464,7 +464,7 @@ added: v0.1.16 * {Object} In each module, the `module` free variable is a reference to the object -representing the current module. For convenience, `module.exports` is +representing the current module. For convenience, `module.exports` is also accessible via the `exports` module-global. `module` is not actually a global but rather local to each module. @@ -515,7 +515,7 @@ a.on('ready', () => { Note that assignment to `module.exports` must be done immediately. It cannot be -done in any callbacks. This does not work: +done in any callbacks. This does not work: x.js: @@ -595,7 +595,7 @@ added: v0.1.16 * {string} -The identifier for the module. Typically this is the fully resolved +The identifier for the module. Typically this is the fully resolved filename. ### module.loaded @@ -629,7 +629,7 @@ The `module.require` method provides a way to load a module as if `require()` was called from the original module. Note that in order to do this, you must get a reference to the `module` -object. Since `require()` returns the `module.exports`, and the `module` is +object. Since `require()` returns the `module.exports`, and the `module` is typically *only* available within a specific module's code, it must be explicitly exported in order to be used. @@ -642,7 +642,7 @@ added: v0.3.7 * {Object} Provides general utility methods when interacting with instances of -`Module` -- the `module` variable often seen in file modules. Accessed +`Module` — the `module` variable often seen in file modules. Accessed via `require('module')`. ### module.builtinModules @@ -652,7 +652,7 @@ added: v6.13.0 * {string[]} -A list of the names of all modules provided by Node.js. Can be used to verify +A list of the names of all modules provided by Node.js. Can be used to verify if a module is maintained by a third-party module or not. [`__dirname`]: #modules_dirname diff --git a/doc/api/net.md b/doc/api/net.md index 8e40c2297df77a..0c9adf4bd1ab9d 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -121,7 +121,7 @@ connections use asynchronous `server.getConnections` instead. added: v0.9.7 --> -* Returns {net.Server} +* Returns: {net.Server} Asynchronously get the number of concurrent connections on the server. Works when sockets were sent to forks. @@ -147,7 +147,7 @@ already been bound to a port or domain socket. Listening on a file descriptor is not supported on Windows. -This function is asynchronous. When the server has been bound, +This function is asynchronous. When the server has been bound, [`'listening'`][] event will be emitted. The last parameter `callback` will be added as a listener for the [`'listening'`][] event. @@ -203,8 +203,8 @@ added: v0.1.90 Start a local socket server listening for connections on the given `path`. -This function is asynchronous. When the server has been bound, -[`'listening'`][] event will be emitted. The last parameter `callback` +This function is asynchronous. When the server has been bound, +[`'listening'`][] event will be emitted. The last parameter `callback` will be added as a listener for the [`'listening'`][] event. On UNIX, the local domain is usually known as the UNIX domain. The path is a @@ -218,7 +218,7 @@ unlinked*. On Windows, the local domain is implemented using a named pipe. The path *must* refer to an entry in `\\?\pipe\` or `\\.\pipe\`. Any characters are permitted, but the latter may do some processing of pipe names, such as resolving `..` -sequences. Despite appearances, the pipe name space is flat. Pipes will *not +sequences. Despite appearances, the pipe name space is flat. Pipes will *not persist*, they are removed when the last reference to them is closed. Do not forget JavaScript string escaping requires paths to be specified with double-backslashes, such as: @@ -252,8 +252,8 @@ The actual length will be determined by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. The default value of this parameter is 511 (not 512). -This function is asynchronous. When the server has been bound, -[`'listening'`][] event will be emitted. The last parameter `callback` +This function is asynchronous. When the server has been bound, +[`'listening'`][] event will be emitted. The last parameter `callback` will be added as a listener for the [`'listening'`][] event. One issue some users run into is getting `EADDRINUSE` errors. This means that @@ -323,8 +323,8 @@ active server in the event system. If the server is already `unref`d calling added: v0.3.4 --> -This object is an abstraction of a TCP or local socket. `net.Socket` -instances implement a duplex Stream interface. They can be created by the +This object is an abstraction of a TCP or local socket. `net.Socket` +instances implement a duplex Stream interface. They can be created by the user and used as a client (with [`connect()`][]) or they can be created by Node.js and passed to the user through the `'connection'` event of a server. @@ -379,8 +379,8 @@ added: v0.1.90 * {Buffer} -Emitted when data is received. The argument `data` will be a `Buffer` or -`String`. Encoding of data is set by `socket.setEncoding()`. +Emitted when data is received. The argument `data` will be a `Buffer` or +`String`. Encoding of data is set by `socket.setEncoding()`. (See the [Readable Stream][] section for more information.) Note that the **data will be lost** if there is no listener when a `Socket` @@ -403,7 +403,7 @@ added: v0.1.90 Emitted when the other end of the socket sends a FIN packet. By default (`allowHalfOpen == false`) the socket will destroy its file -descriptor once it has written out its pending write queue. However, by +descriptor once it has written out its pending write queue. However, by setting `allowHalfOpen == true` the socket will not automatically `end()` its side allowing the user to write arbitrary amounts of data, with the caveat that the user is required to `end()` their side now. @@ -415,7 +415,7 @@ added: v0.1.90 * {Error} -Emitted when an error occurs. The `'close'` event will be called directly +Emitted when an error occurs. The `'close'` event will be called directly following this event. ### Event: 'lookup' @@ -426,9 +426,9 @@ added: v0.11.3 Emitted after resolving the hostname but before connecting. Not applicable to UNIX sockets. -* `err` {Error|null} The error object. See [`dns.lookup()`][]. +* `err` {Error|null} The error object. See [`dns.lookup()`][]. * `address` {string} The IP address. -* `family` {string|null} The address type. See [`dns.lookup()`][]. +* `family` {string|null} The address type. See [`dns.lookup()`][]. * `host` {string} The hostname. ### Event: 'timeout' @@ -718,7 +718,7 @@ added: v0.1.90 --> Sends data on the socket. The second parameter specifies the encoding in the -case of a string--it defaults to UTF8 encoding. +case of a string — it defaults to UTF8 encoding. Returns `true` if the entire data was flushed successfully to the kernel buffer. Returns `false` if all or part of the data was queued in user memory. diff --git a/doc/api/os.md b/doc/api/os.md index 011ce5e2bf1742..b8f5c76ce00793 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -225,7 +225,7 @@ The `os.loadavg()` method returns an array containing the 1, 5, and 15 minute load averages. The load average is a measure of system activity, calculated by the operating -system and expressed as a fractional number. As a rule of thumb, the load +system and expressed as a fractional number. As a rule of thumb, the load average should ideally be less than the number of logical CPUs in the system. The load average is a UNIX-specific concept with no real equivalent on @@ -392,7 +392,7 @@ added: v6.0.0 * Returns: {Object} The `os.userInfo()` method returns information about the currently effective -user -- on POSIX platforms, this is typically a subset of the password file. The +user — on POSIX platforms, this is typically a subset of the password file. The returned object includes the `username`, `uid`, `gid`, `shell`, and `homedir`. On Windows, the `uid` and `gid` fields are `-1`, and `shell` is `null`. diff --git a/doc/api/path.md b/doc/api/path.md index 807cf9b88c9869..7ab4dabb79e04f 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -145,7 +145,7 @@ added: v0.1.25 The `path.extname()` method returns the extension of the `path`, from the last occurrence of the `.` (period) character to end of string in the last portion of -the `path`. If there is no `.` in the last portion of the `path`, or if the +the `path`. If there is no `.` in the last portion of the `path`, or if the first character of the basename of `path` (see `path.basename()`) is `.`, then an empty string is returned. @@ -380,7 +380,7 @@ path.parse('/home/user/dir/file.txt'); │ root │ │ name │ ext │ " / home/user/dir / file .txt " └──────┴──────────────┴──────┴─────┘ -(all spaces in the "" line should be ignored -- they are purely for formatting) +(all spaces in the "" line should be ignored — they are purely for formatting) ``` On Windows: @@ -404,7 +404,7 @@ path.parse('C:\\path\\dir\\file.txt'); │ root │ │ name │ ext │ " C:\ path\dir \ file .txt " └──────┴──────────────┴──────┴─────┘ -(all spaces in the "" line should be ignored -- they are purely for formatting) +(all spaces in the "" line should be ignored — they are purely for formatting) ``` A [`TypeError`][] is thrown if `path` is not a string. diff --git a/doc/api/process.md b/doc/api/process.md index c9aebfa8d2cce4..af20ddb1f751b1 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -189,7 +189,7 @@ process will exit with a non-zero exit code and the stack trace will be printed. This is to avoid infinite recursion. Attempting to resume normally after an uncaught exception can be similar to -pulling out of the power cord when upgrading a computer -- nine out of ten +pulling out of the power cord when upgrading a computer — nine out of ten times nothing happens - but the 10th time, the system becomes corrupted. The correct use of `'uncaughtException'` is to perform synchronous cleanup @@ -388,7 +388,7 @@ For example: process.stdin.resume(); process.on('SIGINT', () => { - console.log('Received SIGINT. Press Control-D to exit.'); + console.log('Received SIGINT. Press Control-D to exit.'); }); ``` @@ -397,7 +397,7 @@ terminal programs. It is important to take note of the following: -* `SIGUSR1` is reserved by Node.js to start the debugger. It's possible to +* `SIGUSR1` is reserved by Node.js to start the debugger. It's possible to install a listener but doing so will _not_ stop the debugger from starting. * `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that resets the terminal mode before exiting with code `128 + signal number`. If @@ -470,7 +470,7 @@ added: v0.1.27 The `process.argv` property returns an array containing the command line arguments passed when the Node.js process was launched. The first element will be [`process.execPath`]. See `process.argv0` if access to the original value of -`argv[0]` is needed. The second element will be the path to the JavaScript +`argv[0]` is needed. The second element will be the path to the JavaScript file being executed. The remaining elements will be any additional command line arguments. @@ -890,7 +890,7 @@ added: v0.1.13 The `process.exit()` method instructs Node.js to terminate the process synchronously with an exit status of `code`. If `code` is omitted, exit uses either the 'success' code `0` or the value of `process.exitCode` if it has been -set. Node.js will not terminate until all the [`'exit'`] event listeners are +set. Node.js will not terminate until all the [`'exit'`] event listeners are called. To exit with a 'failure' code: @@ -1129,7 +1129,7 @@ Windows platforms will throw an error if the `pid` is used to kill a process group. *Note*:Even though the name of this function is `process.kill()`, it is really -just a signal sender, like the `kill` system call. The signal sent may do +just a signal sender, like the `kill` system call. The signal sent may do something other than kill the target process. For example: @@ -1219,7 +1219,7 @@ Once the current turn of the event loop turn runs to completion, all callbacks currently in the next tick queue will be called. This is *not* a simple alias to [`setTimeout(fn, 0)`][]. It is much more -efficient. It runs before any additional I/O events (including +efficient. It runs before any additional I/O events (including timers) fire in subsequent ticks of the event loop. ```js @@ -1254,7 +1254,7 @@ thing.getReadyForStuff(); ``` It is very important for APIs to be either 100% synchronous or 100% -asynchronous. Consider this example: +asynchronous. Consider this example: ```js // WARNING! DO NOT USE! BAD UNSAFE HAZARD! @@ -1296,7 +1296,7 @@ function definitelyAsync(arg, cb) { ``` *Note*: the next tick queue is completely drained on each pass of the -event loop **before** additional I/O is processed. As a result, +event loop **before** additional I/O is processed. As a result, recursively setting nextTick callbacks will block any I/O from happening, just like a `while(true);` loop. @@ -1371,8 +1371,8 @@ tarball. Support) line the current release is part of. This property only exists for LTS releases and is `undefined` for all other release types, including stable releases. Current valid values are: - - `"Argon"` for the v4.x LTS line beginning with v4.2.0. - - `"Boron"` for the v6.x LTS line beginning with v6.9.0. + - `'Argon'` for the v4.x LTS line beginning with v4.2.0. + - `'Boron'` for the v6.x LTS line beginning with v6.9.0. * `sourceUrl` {string} an absolute URL pointing to a _`.tar.gz`_ file containing the source code of the current release. * `headersUrl`{string} an absolute URL pointing to a _`.tar.gz`_ file containing @@ -1461,7 +1461,7 @@ added: v2.0.0 The `process.seteuid()` method sets the effective user identity of the process. (See seteuid(2).) The `id` can be passed as either a numeric ID or a username -string. If a username is specified, the method blocks while resolving the +string. If a username is specified, the method blocks while resolving the associated numeric ID. ```js @@ -1487,7 +1487,7 @@ added: v0.1.31 * `id` {string|number} The group name or ID The `process.setgid()` method sets the group identity of the process. (See -setgid(2).) The `id` can be passed as either a numeric ID or a group name +setgid(2).) The `id` can be passed as either a numeric ID or a group name string. If a group name is specified, this method blocks while resolving the associated numeric ID. @@ -1528,7 +1528,7 @@ added: v0.1.28 --> The `process.setuid(id)` method sets the user identity of the process. (See -setuid(2).) The `id` can be passed as either a numeric ID or a username string. +setuid(2).) The `id` can be passed as either a numeric ID or a username string. If a username is specified, the method blocks while resolving the associated numeric ID. @@ -1790,7 +1790,7 @@ Will generate an object similar to: ## Exit Codes Node.js will normally exit with a `0` status code when no more async -operations are pending. The following status codes are used in other +operations are pending. The following status codes are used in other cases: * `1` **Uncaught Fatal Exception** - There was an uncaught exception, @@ -1798,12 +1798,12 @@ cases: handler. * `2` - Unused (reserved by Bash for builtin misuse) * `3` **Internal JavaScript Parse Error** - The JavaScript source code - internal in Node.js's bootstrapping process caused a parse error. This + internal in Node.js's bootstrapping process caused a parse error. This is extremely rare, and generally can only happen during development of Node.js itself. * `4` **Internal JavaScript Evaluation Failure** - The JavaScript source code internal in Node.js's bootstrapping process failed to - return a function value when evaluated. This is extremely rare, and + return a function value when evaluated. This is extremely rare, and generally can only happen during development of Node.js itself. * `5` **Fatal Error** - There was a fatal unrecoverable error in V8. Typically a message will be printed to stderr with the prefix `FATAL @@ -1813,23 +1813,23 @@ cases: function was somehow set to a non-function, and could not be called. * `7` **Internal Exception Handler Run-Time Failure** - There was an uncaught exception, and the internal fatal exception handler - function itself threw an error while attempting to handle it. This + function itself threw an error while attempting to handle it. This can happen, for example, if a [`'uncaughtException'`][] or `domain.on('error')` handler throws an error. -* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes +* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes indicated an uncaught exception. * `9` - **Invalid Argument** - Either an unknown option was specified, or an option requiring a value was provided without a value. * `10` **Internal JavaScript Run-Time Failure** - The JavaScript source code internal in Node.js's bootstrapping process threw an error - when the bootstrapping function was called. This is extremely rare, + when the bootstrapping function was called. This is extremely rare, and generally can only happen during development of Node.js itself. * `12` **Invalid Debug Argument** - The `--debug`, `--inspect` and/or `--debug-brk` options were set, but the port number chosen was invalid or unavailable. * `>128` **Signal Exits** - If Node.js receives a fatal signal such as `SIGKILL` or `SIGHUP`, then its exit code will be `128` plus the - value of the signal code. This is a standard POSIX practice, since + value of the signal code. This is a standard POSIX practice, since exit codes are defined to be 7-bit integers, and signal exits set the high-order bit, and then contain the value of the signal code. diff --git a/doc/api/readline.md b/doc/api/readline.md index 04c838a0024ed4..d31af7ff3f6b02 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -295,7 +295,7 @@ added: v0.1.98 * `shift` {boolean} `true` to indicate the `` key. * `name` {string} The name of the a key. -The `rl.write()` method will write either `data` or a key sequence identified +The `rl.write()` method will write either `data` or a key sequence identified by `key` to the `output`. The `key` argument is supported only if `output` is a [TTY][] text terminal. diff --git a/doc/api/repl.md b/doc/api/repl.md index 17c44fbe36c7ba..e8c87240b1a579 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -96,7 +96,7 @@ declared either implicitly or using the `var` keyword are declared at the The default evaluator provides access to any variables that exist in the global scope. It is possible to expose a variable to the REPL explicitly by assigning -it to the `context` object associated with each `REPLServer`. For example: +it to the `context` object associated with each `REPLServer`. For example: ```js const repl = require('repl'); @@ -391,7 +391,7 @@ added: v0.1.91 stream upon instantiation. * `eval` {Function} The function to be used when evaluating each given line of input. Defaults to an async wrapper for the JavaScript `eval()` - function. An `eval` function can error with `repl.Recoverable` to indicate + function. An `eval` function can error with `repl.Recoverable` to indicate the input was incomplete and prompt for additional lines. * `useColors` {boolean} If `true`, specifies that the default `writer` function should include ANSI color styling to REPL output. If a custom @@ -414,7 +414,7 @@ added: v0.1.91 * `repl.REPL_MODE_STRICT` - evaluates expressions in strict mode. This is equivalent to prefacing every repl statement with `'use strict'`. * `repl.REPL_MODE_MAGIC` - attempt to evaluates expressions in default - mode. If expressions fail to parse, re-try in strict mode. + mode. If expressions fail to parse, re-try in strict mode. * `breakEvalOnSigint` - Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is pressed. This cannot be used together with a custom `eval` function. Defaults to `false`. @@ -456,7 +456,7 @@ environment variables: - `NODE_REPL_HISTORY` - When a valid path is given, persistent REPL history will be saved to the specified file rather than `.node_repl_history` in the - user's home directory. Setting this value to `""` will disable persistent + user's home directory. Setting this value to `''` will disable persistent REPL history. Whitespace will be trimmed from the value. - `NODE_REPL_HISTORY_SIZE` - Defaults to `1000`. Controls how many lines of history will be persisted if history is available. Must be a positive number. @@ -469,7 +469,7 @@ environment variables: By default, the Node.js REPL will persist history between `node` REPL sessions by saving inputs to a `.node_repl_history` file located in the user's home directory. This can be disabled by setting the environment variable -`NODE_REPL_HISTORY=""`. +`NODE_REPL_HISTORY=''`. #### NODE_REPL_HISTORY_FILE * `size` {number} Optional argument to specify how much data to read. -* Return {string|Buffer|null} +* Returns: {string|Buffer|null} The `readable.read()` method pulls some data out of the internal buffer and returns it. If no data available to be read, `null` is returned. By default, @@ -1364,7 +1364,7 @@ It is recommended that errors occurring during the processing of the the callback and passing the error as the first argument. This will cause an `'error'` event to be emitted by the Writable. Throwing an Error from within `writable._write()` can result in unexpected and inconsistent behavior depending -on how the stream is being used. Using the callback ensures consistent and +on how the stream is being used. Using the callback ensures consistent and predictable handling of errors. ```js @@ -1543,7 +1543,7 @@ user programs. #### readable.push(chunk[, encoding]) * `chunk` {Buffer|null|string} Chunk of data to push into the read queue -* `encoding` {string} Encoding of String chunks. Must be a valid +* `encoding` {string} Encoding of String chunks. Must be a valid Buffer encoding, such as `'utf8'` or `'ascii'` * Returns: {boolean} `true` if additional chunks of data may continued to be pushed; `false` otherwise. @@ -1963,7 +1963,7 @@ The `transform._transform()` method is prefixed with an underscore because it is internal to the class that defines it, and should never be called directly by user programs. -`transform._transform()` is never called in parallel; streams implement a +`transform._transform()` is never called in parallel; streams implement a queue mechanism, and to receive the next chunk, `callback` must be called, either synchronously or asynchronously. diff --git a/doc/api/tls.md b/doc/api/tls.md index d307b376ef58e2..9b6027ab11f278 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -374,7 +374,7 @@ added: v0.6.0 --> Returns the bound address, the address family name, and port of the -server as reported by the operating system. See [`net.Server.address()`][] for +server as reported by the operating system. See [`net.Server.address()`][] for more information. ### server.close([callback]) @@ -472,7 +472,7 @@ added: v0.11.4 * `options` {Object} * `isServer`: The SSL/TLS protocol is asymmetrical, TLSSockets must know if they are to behave as a server or a client. If `true` the TLS socket will be - instantiated as a server. Defaults to `false`. + instantiated as a server. Defaults to `false`. * `server` {net.Server} An optional [`net.Server`][] instance. * `requestCert`: Whether to authenticate the remote peer by requesting a certificate. Clients always request a server certificate. Servers @@ -624,7 +624,7 @@ For example: { ... another certificate, possibly with a .issuerCertificate ... }, raw: < RAW DER buffer >, valid_from: 'Nov 11 09:52:22 2009 GMT', - valid_to: 'Nov 6 09:52:22 2029 GMT', + valid_to: 'Nov 6 09:52:22 2029 GMT', fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF', serialNumber: 'B9B0D332A1AA5635' } ``` @@ -795,7 +795,7 @@ changes: rather than creating a new socket. Typically, this is an instance of [`net.Socket`][], but any `Duplex` stream is allowed. If this option is specified, `path`, `host` and `port` are ignored, - except for certificate validation. Usually, a socket is already connected + except for certificate validation. Usually, a socket is already connected when passed to `tls.connect()`, but it can be connected later. Note that connection/disconnection/destruction of `socket` is the user's responsibility, calling `tls.connect()` will not cause `net.connect()` to be @@ -910,7 +910,7 @@ added: v0.11.13 to decrypt it. * `key` {string|string[]|Buffer|Buffer[]|Object[]} Optional private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted - keys will be decrypted with `options.passphrase`. Multiple keys using + keys will be decrypted with `options.passphrase`. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form `{pem: [, passphrase: ]}`. The object form can only occur in @@ -923,7 +923,7 @@ added: v0.11.13 consist of the PEM formatted certificate for a provided private `key`, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, - see `ca`). When providing multiple cert chains, they do not have to be in + see `ca`). When providing multiple cert chains, they do not have to be in the same order as their private keys in `key`. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail. @@ -933,7 +933,7 @@ added: v0.11.13 using this option. The value can be a string or Buffer, or an Array of strings and/or Buffers. Any string or Buffer can contain multiple PEM CAs concatenated together. The peer's certificate must be chainable to a CA - trusted by the server for the connection to be authenticated. When using + trusted by the server for the connection to be authenticated. When using certificates that are not chainable to a well-known CA, the certificate's CA must be explicitly specified as a trusted or the connection will fail to authenticate. @@ -945,7 +945,7 @@ added: v0.11.13 * `crl` {string|string[]|Buffer|Buffer[]} Optional PEM formatted CRLs (Certificate Revocation Lists). * `ciphers` {string} Optional cipher suite specification, replacing the - default. For more information, see [modifying the default cipher suite][]. + default. For more information, see [modifying the default cipher suite][]. * `honorCipherOrder` {boolean} Attempt to use the server's cipher suite preferences instead of the client's. When `true`, causes `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see @@ -954,7 +954,7 @@ added: v0.11.13 APIs that create secure contexts leave it unset. * `ecdhCurve` {string} A string describing a named curve to use for ECDH key agreement or `false` to disable ECDH. Defaults to - [`tls.DEFAULT_ECDH_CURVE`]. Use [`crypto.getCurves()`][] to obtain a list + [`tls.DEFAULT_ECDH_CURVE`]. Use [`crypto.getCurves()`][] to obtain a list of available curve names. On recent releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. * `dhparam` {string|Buffer} Diffie Hellman parameters, required for @@ -964,8 +964,8 @@ added: v0.11.13 for stronger security. If omitted or invalid, the parameters are silently discarded and DHE ciphers will not be available. * `secureProtocol` {string} Optional SSL method to use, default is - `"SSLv23_method"`. The possible values are listed as [SSL_METHODS][], use - the function names as strings. For example, `"SSLv3_method"` to force SSL + `'SSLv23_method'`. The possible values are listed as [SSL_METHODS][], use + the function names as strings. For example, `'SSLv3_method'` to force SSL version 3. * `secureOptions` {number} Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all! @@ -1027,7 +1027,7 @@ added: v0.3.2 servers, the identity options (`pfx` or `key`/`cert`) are usually required. * `secureConnectionListener` {Function} -Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is +Creates a new [tls.Server][]. The `secureConnectionListener`, if provided, is automatically set as a listener for the [`'secureConnection'`][] event. The following illustrates a simple echo server: diff --git a/doc/api/url.md b/doc/api/url.md index 61899d3c0ccf7b..5b9c3c23f43426 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -51,7 +51,7 @@ properties of a WHATWG `URL` object. ├─────────────┴─────────────────────┴─────────────────────┴──────────┴────────────────┴───────┤ │ href │ └─────────────────────────────────────────────────────────────────────────────────────────────┘ -(all spaces in the "" line should be ignored -- they are purely for formatting) +(all spaces in the "" line should be ignored — they are purely for formatting) ``` Parsing the URL string using the WHATWG API: @@ -555,7 +555,7 @@ Instantiate a new `URLSearchParams` object with an iterable map in a way that is similar to [`Map`][]'s constructor. `iterable` can be an Array or any iterable object. That means `iterable` can be another `URLSearchParams`, in which case the constructor will simply create a clone of the provided -`URLSearchParams`. Elements of `iterable` are key-value pairs, and can +`URLSearchParams`. Elements of `iterable` are key-value pairs, and can themselves be any iterable object. Duplicate keys are allowed. diff --git a/doc/api/util.md b/doc/api/util.md index 9e29cfc073ccc5..e1ad92095539bb 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -23,9 +23,9 @@ added: v0.11.3 The `util.debuglog()` method is used to create a function that conditionally writes debug messages to `stderr` based on the existence of the `NODE_DEBUG` -environment variable. If the `section` name appears within the value of that +environment variable. If the `section` name appears within the value of that environment variable, then the returned function operates similar to -[`console.error()`][]. If not, then the returned function is a no-op. +[`console.error()`][]. If not, then the returned function is a no-op. For example: @@ -43,7 +43,7 @@ it will output something like: FOO 3245: hello from foo [123] ``` -where `3245` is the process id. If it is not run with that +where `3245` is the process id. If it is not run with that environment variable set, then it will not print anything. Multiple comma-separated `section` names may be specified in the `NODE_DEBUG` @@ -108,7 +108,7 @@ corresponding argument. Supported placeholders are: * `%d` - Number (integer or floating point value). * `%i` - Integer. * `%f` - Floating point value. -* `%j` - JSON. Replaced with the string `'[Circular]'` if the argument +* `%j` - JSON. Replaced with the string `'[Circular]'` if the argument contains circular references. * `%%` - single percent sign (`'%'`). This does not consume an argument. @@ -157,7 +157,7 @@ the two styles are [semantically incompatible][]._ * `constructor` {Function} * `superConstructor` {Function} -Inherit the prototype methods from one [constructor][] into another. The +Inherit the prototype methods from one [constructor][] into another. The prototype of `constructor` will be set to a new object created from `superConstructor`. diff --git a/doc/api/v8.md b/doc/api/v8.md index 234835376bd3e0..a74bf64e535108 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -110,7 +110,7 @@ after the VM has started may result in unpredictable behavior, including crashes and data loss; or it may simply do nothing. The V8 options available for a version of Node.js may be determined by running -`node --v8-options`. An unofficial, community-maintained list of options +`node --v8-options`. An unofficial, community-maintained list of options and their effects is available [here][]. Usage: diff --git a/doc/api/vm.md b/doc/api/vm.md index 8c196f1d1a682f..9aab34f20b86c2 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -108,7 +108,7 @@ added: v0.3.1 will be thrown. * `breakOnSigint`: if `true`, the execution will be terminated when `SIGINT` (Ctrl+C) is received. Existing handlers for the - event that have been attached via `process.on("SIGINT")` will be disabled + event that have been attached via `process.on('SIGINT')` will be disabled during script execution, but will continue to work after that. If execution is terminated, an [`Error`][] will be thrown. diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 6cef23824977c9..19ab15231913c3 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -57,8 +57,8 @@ header is used to identify the compression encodings actually applied to a message. **Note: the examples given below are drastically simplified to show -the basic concept.** Using `zlib` encoding can be expensive, and the results -ought to be cached. See [Memory Usage Tuning][] for more information +the basic concept.** Using `zlib` encoding can be expensive, and the results +ought to be cached. See [Memory Usage Tuning][] for more information on the speed/memory/compression tradeoffs involved in `zlib` usage. ```js @@ -157,7 +157,7 @@ The memory requirements for deflate are (in bytes): (1 << (windowBits + 2)) + (1 << (memLevel + 9)); ``` -That is: 128K for windowBits=15 + 128K for memLevel = 8 +That is: 128K for windowBits = 15 + 128K for memLevel = 8 (default values) plus a few kilobytes for small objects. For example, to reduce the default memory requirements from 256K to 128K, the @@ -175,20 +175,20 @@ The memory requirements for inflate are (in bytes) 1 << windowBits; ``` -That is, 32K for windowBits=15 (default value) plus a few kilobytes +That is, 32K for windowBits = 15 (default value) plus a few kilobytes for small objects. This is in addition to a single internal output slab buffer of size `chunkSize`, which defaults to 16K. The speed of `zlib` compression is affected most dramatically by the -`level` setting. A higher level will result in better compression, but -will take longer to complete. A lower level will result in less +`level` setting. A higher level will result in better compression, but +will take longer to complete. A lower level will result in less compression, but will be much faster. In general, greater memory usage options will mean that Node.js has to make fewer calls to `zlib` because it will be able to process more data on -each `write` operation. So, this is another factor that affects the +each `write` operation. So, this is another factor that affects the speed, at the cost of memory usage. ## Flushing @@ -231,7 +231,7 @@ added: v0.5.8 All of the constants defined in `zlib.h` are also defined on `require('zlib')`. In the normal course of operations, it will not be necessary to use these constants. They are documented so that their presence is not surprising. This -section is taken almost directly from the [zlib documentation][]. See +section is taken almost directly from the [zlib documentation][]. See for more details. Allowed flush values. @@ -288,14 +288,14 @@ added: v0.11.1 -Each class takes an `options` object. All options are optional. +Each class takes an `options` object. All options are optional. Note that some options are only relevant when compressing, and are ignored by the decompression classes. * `flush` (default: `zlib.Z_NO_FLUSH`) * `finishFlush` (default: `zlib.Z_FINISH`) -* `chunkSize` (default: 16*1024) +* `chunkSize` (default: `16 * 1024`) * `windowBits` * `level` (compression only) * `memLevel` (compression only)