1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: fix sorting in API references

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/11331
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
This commit is contained in:
Vse Mozhet Byt 2017-02-13 04:49:35 +02:00 committed by Sam Roberts
parent dfa8abe1b5
commit 52b253677a
12 changed files with 480 additions and 480 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
doc/api/buffer.md
View File

@ -313,32 +313,6 @@ Example:
const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
```
### new Buffer(buffer)
<!-- YAML
deprecated: v6.0.0
-->
> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.
* `buffer` {Buffer} An existing `Buffer` to copy data from
Copies the passed `buffer` data onto a new `Buffer` instance.
Example:
```js
const buf1 = new Buffer('buffer');
const buf2 = new Buffer(buf1);
buf1[0] = 0x61;
// Prints: auffer
console.log(buf1.toString());
// Prints: buffer
console.log(buf2.toString());
```
### new Buffer(arrayBuffer[, byteOffset [, length]])
<!-- YAML
deprecated: v6.0.0
@ -383,6 +357,32 @@ arr[1] = 6000;
console.log(buf);
```
### new Buffer(buffer)
<!-- YAML
deprecated: v6.0.0
-->
> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`] instead.
* `buffer` {Buffer} An existing `Buffer` to copy data from
Copies the passed `buffer` data onto a new `Buffer` instance.
Example:
```js
const buf1 = new Buffer('buffer');
const buf2 = new Buffer(buf1);
buf1[0] = 0x61;
// Prints: auffer
console.log(buf1.toString());
// Prints: buffer
console.log(buf2.toString());
```
### new Buffer(size)
<!-- YAML
deprecated: v6.0.0
@ -1113,6 +1113,47 @@ Example: Fill a `Buffer` with a two-byte character
console.log(Buffer.allocUnsafe(3).fill('\u0222'));
```
### buf.includes(value[, byteOffset][, encoding])
<!-- YAML
added: v5.3.0
-->
* `value` {String | Buffer | Integer} What to search for
* `byteOffset` {Integer} Where to begin searching in `buf`. **Default:** `0`
* `encoding` {String} If `value` is a string, this is its encoding.
**Default:** `'utf8'`
* Returns: {Boolean} `true` if `value` was found in `buf`, `false` otherwise
Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].
Examples:
```js
const buf = Buffer.from('this is a buffer');
// Prints: true
console.log(buf.includes('this'));
// Prints: true
console.log(buf.includes('is'));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer')));
// Prints: true
// (97 is the decimal ASCII value for 'a')
console.log(buf.includes(97));
// Prints: false
console.log(buf.includes(Buffer.from('a buffer example')));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));
// Prints: false
console.log(buf.includes('this', 4));
```
### buf.indexOf(value[, byteOffset][, encoding])
<!-- YAML
added: v1.5.0
@ -1192,47 +1233,6 @@ console.log(b.indexOf('b', null));
console.log(b.indexOf('b', []));
```
### buf.includes(value[, byteOffset][, encoding])
<!-- YAML
added: v5.3.0
-->
* `value` {String | Buffer | Integer} What to search for
* `byteOffset` {Integer} Where to begin searching in `buf`. **Default:** `0`
* `encoding` {String} If `value` is a string, this is its encoding.
**Default:** `'utf8'`
* Returns: {Boolean} `true` if `value` was found in `buf`, `false` otherwise
Equivalent to [`buf.indexOf() !== -1`][`buf.indexOf()`].
Examples:
```js
const buf = Buffer.from('this is a buffer');
// Prints: true
console.log(buf.includes('this'));
// Prints: true
console.log(buf.includes('is'));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer')));
// Prints: true
// (97 is the decimal ASCII value for 'a')
console.log(buf.includes(97));
// Prints: false
console.log(buf.includes(Buffer.from('a buffer example')));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));
// Prints: false
console.log(buf.includes('this', 4));
```
### buf.keys()
<!-- YAML
added: v1.1.0
@ -1878,6 +1878,35 @@ buf2.swap64();
Note that JavaScript cannot encode 64-bit integers. This method is intended
for working with 64-bit floats.
### buf.toJSON()
<!-- YAML
added: v0.9.2
-->
* Returns: {Object}
Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls
this function when stringifying a `Buffer` instance.
Example:
```js
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);
// Prints: {"type":"Buffer","data":[1,2,3,4,5]}
console.log(json);
const copy = JSON.parse(json, (key, value) => {
return value && value.type === 'Buffer'
? Buffer.from(value.data)
: value;
});
// Prints: <Buffer 01 02 03 04 05>
console.log(copy);
```
### buf.toString([encoding[, start[, end]]])
<!-- YAML
added: v0.1.90
@ -1921,35 +1950,6 @@ console.log(buf2.toString('utf8', 0, 3));
console.log(buf2.toString(undefined, 0, 3));
```
### buf.toJSON()
<!-- YAML
added: v0.9.2
-->
* Returns: {Object}
Returns a JSON representation of `buf`. [`JSON.stringify()`] implicitly calls
this function when stringifying a `Buffer` instance.
Example:
```js
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);
// Prints: {"type":"Buffer","data":[1,2,3,4,5]}
console.log(json);
const copy = JSON.parse(json, (key, value) => {
return value && value.type === 'Buffer'
? Buffer.from(value.data)
: value;
});
// Prints: <Buffer 01 02 03 04 05>
console.log(copy);
```
### buf.values()
<!-- YAML
added: v1.1.0

32
doc/api/crypto.md
View File

@ -1427,22 +1427,6 @@ keys:
All paddings are defined in `crypto.constants`.
### crypto.timingSafeEqual(a, b)
<!-- YAML
added: v6.6.0
-->
Returns true if `a` is equal to `b`, without leaking timing information that
would allow an attacker to guess one of the values. This is suitable for
comparing HMAC digests or secret values like authentication cookies or
[capability urls](https://www.w3.org/TR/capability-urls/).
`a` and `b` must both be `Buffer`s, and they must have the same length.
**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the
*surrounding* code is timing-safe. Care should be taken to ensure that the
surrounding code does not introduce timing vulnerabilities.
### crypto.privateEncrypt(private_key, buffer)
<!-- YAML
added: v1.1.0
@ -1576,6 +1560,22 @@ is a bit field taking one of or a mix of the following flags (defined in
* `crypto.constants.ENGINE_METHOD_ALL`
* `crypto.constants.ENGINE_METHOD_NONE`
### crypto.timingSafeEqual(a, b)
<!-- YAML
added: v6.6.0
-->
Returns true if `a` is equal to `b`, without leaking timing information that
would allow an attacker to guess one of the values. This is suitable for
comparing HMAC digests or secret values like authentication cookies or
[capability urls](https://www.w3.org/TR/capability-urls/).
`a` and `b` must both be `Buffer`s, and they must have the same length.
**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the
*surrounding* code is timing-safe. Care should be taken to ensure that the
surrounding code does not introduce timing vulnerabilities.
## Notes
### Legacy Streams API (pre Node.js v0.10)

32
doc/api/dgram.md
View File

@ -225,6 +225,22 @@ never have reason to call this.
If `multicastInterface` is not specified, the operating system will attempt to
drop membership on all valid interfaces.
### socket.ref()
<!-- YAML
added: v0.9.1
-->
By default, binding a socket will cause it to block the Node.js process from
exiting as long as the socket is open. The `socket.unref()` method can be used
to exclude the socket from the reference counting that keeps the Node.js
process active. The `socket.ref()` method adds the socket back to the reference
counting and restores the default behavior.
Calling `socket.ref()` multiples times will have no additional effect.
The `socket.ref()` method returns a reference to the socket so calls can be
chained.
### socket.send(msg, [offset, length,] port [, address] [, callback])
<!-- YAML
added: v0.1.99
@ -379,22 +395,6 @@ Changing TTL values is typically done for network probes or when multicasting.
The argument to `socket.setTTL()` is a number of hops between 1 and 255.
The default on most systems is 64 but can vary.
### socket.ref()
<!-- YAML
added: v0.9.1
-->
By default, binding a socket will cause it to block the Node.js process from
exiting as long as the socket is open. The `socket.unref()` method can be used
to exclude the socket from the reference counting that keeps the Node.js
process active. The `socket.ref()` method adds the socket back to the reference
counting and restores the default behavior.
Calling `socket.ref()` multiples times will have no additional effect.
The `socket.ref()` method returns a reference to the socket so calls can be
chained.
### socket.unref()
<!-- YAML
added: v0.9.1

18
doc/api/dns.md
View File

@ -288,6 +288,15 @@ Uses the DNS protocol to resolve name server records (`NS` records) for the
contain an array of name server records available for `hostname`
(e.g. `['ns1.example.com', 'ns2.example.com']`).
## dns.resolvePtr(hostname, callback)
<!-- YAML
added: v6.0.0
-->
Uses the DNS protocol to resolve pointer records (`PTR` records) for the
`hostname`. The `addresses` argument passed to the `callback` function will
be an array of strings containing the reply records.
## dns.resolveSoa(hostname, callback)
<!-- YAML
added: v0.11.10
@ -340,15 +349,6 @@ be an array of objects with the following properties:
}
```
## dns.resolvePtr(hostname, callback)
<!-- YAML
added: v6.0.0
-->
Uses the DNS protocol to resolve pointer records (`PTR` records) for the
`hostname`. The `addresses` argument passed to the `callback` function will
be an array of strings containing the reply records.
## dns.resolveTxt(hostname, callback)
<!-- YAML
added: v0.1.27

152
doc/api/domain.md
View File

@ -269,42 +269,6 @@ uncaught exceptions to the active Domain object.
Domain is a child class of [`EventEmitter`][]. To handle the errors that it
catches, listen to its `'error'` event.
### domain.run(fn[, ...args])
* `fn` {Function}
* `...args` {any}
Run the supplied function in the context of the domain, implicitly
binding all event emitters, timers, and lowlevel requests that are
created in that context. Optionally, arguments can be passed to
the function.
This is the most basic way to use a domain.
Example:
```js
const domain = require('domain');
const fs = require('fs');
const d = domain.create();
d.on('error', (er) => {
console.error('Caught error!', er);
});
d.run(() => {
process.nextTick(() => {
setTimeout(() => { // simulating some various async stuff
fs.open('non-existent file', 'r', (er, fd) => {
if (er) throw er;
// proceed...
});
}, 100);
});
});
```
In this example, the `d.on('error')` handler will be triggered, rather
than crashing the program.
### domain.members
* {Array}
@ -328,13 +292,6 @@ the domain 'error' handler.
If the Timer or EventEmitter was already bound to a domain, it is removed
from that one, and bound to this one instead.
### domain.remove(emitter)
* `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain
The opposite of [`domain.add(emitter)`][]. Removes domain handling from the
specified emitter.
### domain.bind(callback)
* `callback` {Function} The callback function
@ -363,6 +320,49 @@ d.on('error', (er) => {
});
```
### domain.dispose()
> 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
bound into the domain via `run`, `bind`, or `intercept`, and a `'dispose'` event
is emitted.
### domain.enter()
The `enter` method is plumbing used by the `run`, `bind`, and `intercept`
methods to set the active domain. It sets `domain.active` and `process.domain`
to the domain, and implicitly pushes the domain onto the domain stack managed
by the domain module (see [`domain.exit()`][] for details on the domain stack). The
call to `enter` delimits the beginning of a chain of asynchronous calls and I/O
operations bound to a domain.
Calling `enter` changes only the active domain, and does not alter the domain
itself. `enter` and `exit` can be called an arbitrary number of times on a
single domain.
If the domain on which `enter` is called has been disposed, `enter` will return
without setting the domain.
### domain.exit()
The `exit` method exits the current domain, popping it off the domain stack.
Any time execution is going to switch to the context of a different chain of
asynchronous calls, it's important to ensure that the current domain is exited.
The call to `exit` delimits either the end of or an interruption to the chain
of asynchronous calls and I/O operations bound to a domain.
If there are multiple, nested domains bound to the current execution context,
`exit` will exit any domains nested within this domain.
Calling `exit` changes only the active domain, and does not alter the domain
itself. `enter` and `exit` can be called an arbitrary number of times on a
single domain.
If the domain on which `exit` is called has been disposed, `exit` will return
without exiting the domain.
### domain.intercept(callback)
* `callback` {Function} The callback function
@ -401,48 +401,48 @@ d.on('error', (er) => {
});
```
### domain.enter()
### domain.remove(emitter)
The `enter` method is plumbing used by the `run`, `bind`, and `intercept`
methods to set the active domain. It sets `domain.active` and `process.domain`
to the domain, and implicitly pushes the domain onto the domain stack managed
by the domain module (see [`domain.exit()`][] for details on the domain stack). The
call to `enter` delimits the beginning of a chain of asynchronous calls and I/O
operations bound to a domain.
* `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain
Calling `enter` changes only the active domain, and does not alter the domain
itself. `enter` and `exit` can be called an arbitrary number of times on a
single domain.
The opposite of [`domain.add(emitter)`][]. Removes domain handling from the
specified emitter.
If the domain on which `enter` is called has been disposed, `enter` will return
without setting the domain.
### domain.run(fn[, ...args])
### domain.exit()
* `fn` {Function}
* `...args` {any}
The `exit` method exits the current domain, popping it off the domain stack.
Any time execution is going to switch to the context of a different chain of
asynchronous calls, it's important to ensure that the current domain is exited.
The call to `exit` delimits either the end of or an interruption to the chain
of asynchronous calls and I/O operations bound to a domain.
Run the supplied function in the context of the domain, implicitly
binding all event emitters, timers, and lowlevel requests that are
created in that context. Optionally, arguments can be passed to
the function.
If there are multiple, nested domains bound to the current execution context,
`exit` will exit any domains nested within this domain.
This is the most basic way to use a domain.
Calling `exit` changes only the active domain, and does not alter the domain
itself. `enter` and `exit` can be called an arbitrary number of times on a
single domain.
Example:
If the domain on which `exit` is called has been disposed, `exit` will return
without exiting the domain.
```js
const domain = require('domain');
const fs = require('fs');
const d = domain.create();
d.on('error', (er) => {
console.error('Caught error!', er);
});
d.run(() => {
process.nextTick(() => {
setTimeout(() => { // simulating some various async stuff
fs.open('non-existent file', 'r', (er, fd) => {
if (er) throw er;
// proceed...
});
}, 100);
});
});
```
### domain.dispose()
> 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
bound into the domain via `run`, `bind`, or `intercept`, and a `'dispose'` event
is emitted.
In this example, the `d.on('error')` handler will be triggered, rather
than crashing the program.
[`domain.add(emitter)`]: #domain_domain_add_emitter
[`domain.bind(callback)`]: #domain_domain_bind_callback

40
doc/api/fs.md
View File

@ -164,6 +164,14 @@ added: v0.1.93
`ReadStream` is a [Readable Stream][].
### Event: 'close'
<!-- YAML
added: v0.1.93
-->
Emitted when the `ReadStream`'s underlying file descriptor has been closed
using the `fs.close()` method.
### Event: 'open'
<!-- YAML
added: v0.1.93
@ -173,14 +181,6 @@ added: v0.1.93
Emitted when the ReadStream's file is opened.
### Event: 'close'
<!-- YAML
added: v0.1.93
-->
Emitted when the `ReadStream`'s underlying file descriptor has been closed
using the `fs.close()` method.
### readStream.bytesRead
<!-- YAML
added: 6.4.0
@ -278,6 +278,14 @@ added: v0.1.93
`WriteStream` is a [Writable Stream][].
### Event: 'close'
<!-- YAML
added: v0.1.93
-->
Emitted when the `WriteStream`'s underlying file descriptor has been closed
using the `fs.close()` method.
### Event: 'open'
<!-- YAML
added: v0.1.93
@ -287,14 +295,6 @@ added: v0.1.93
Emitted when the WriteStream's file is opened.
### Event: 'close'
<!-- YAML
added: v0.1.93
-->
Emitted when the `WriteStream`'s underlying file descriptor has been closed
using the `fs.close()` method.
### writeStream.bytesWritten
<!-- YAML
added: v0.4.7
@ -1753,10 +1753,10 @@ watching the *original* inode. Events for the new inode will not be emitted.
This is expected behavior.
In AIX, save and close of a file being watched causes two notifications -
one for adding new content, and one for truncation. Moreover, save and
close operations on some platforms cause inode changes that force watch
operations to become invalid and ineffective. AIX retains inode for the
lifetime of a file, that way though this is different from Linux / OS X,
one for adding new content, and one for truncation. Moreover, save and
close operations on some platforms cause inode changes that force watch
operations to become invalid and ineffective. AIX retains inode for the
lifetime of a file, that way though this is different from Linux / OS X,
this improves the usability of file watching. This is expected behavior.
#### Filename Argument

24
doc/api/http.md
View File

@ -1316,6 +1316,18 @@ Calls `message.connection.setTimeout(msecs, callback)`.
Returns `message`.
### message.socket
<!-- YAML
added: v0.3.0
-->
* {net.Socket}
The [`net.Socket`][] object associated with the connection.
With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the
client's authentication details.
### message.statusCode
<!-- YAML
added: v0.1.1
@ -1338,18 +1350,6 @@ added: v0.11.10
The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`.
### message.socket
<!-- YAML
added: v0.3.0
-->
* {net.Socket}
The [`net.Socket`][] object associated with the connection.
With HTTPS support, use [`request.socket.getPeerCertificate()`][] to obtain the
client's authentication details.
### message.trailers
<!-- YAML
added: v0.3.0

154
doc/api/process.md
View File

@ -629,83 +629,6 @@ process's [`ChildProcess.disconnect()`][].
If the Node.js process was not spawned with an IPC channel,
`process.disconnect()` will be `undefined`.
## process.env
<!-- YAML
added: v0.1.27
-->
* {Object}
The `process.env` property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
```js
{
TERM: 'xterm-256color',
SHELL: '/usr/local/bin/bash',
USER: 'maciej',
PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
PWD: '/Users/maciej',
EDITOR: 'vim',
SHLVL: '1',
HOME: '/Users/maciej',
LOGNAME: 'maciej',
_: '/usr/local/bin/node'
}
```
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process. In other words, the following example
would not work:
```console
$ node -e 'process.env.foo = "bar"' && echo $foo
```
While the following will:
```js
process.env.foo = 'bar';
console.log(process.env.foo);
```
Assigning a property on `process.env` will implicitly convert the value
to a string.
Example:
```js
process.env.test = null;
console.log(process.env.test);
// => 'null'
process.env.test = undefined;
console.log(process.env.test);
// => 'undefined'
```
Use `delete` to delete a property from `process.env`.
Example:
```js
process.env.TEST = 1;
delete process.env.TEST;
console.log(process.env.TEST);
// => undefined
```
On Windows operating systems, environment variables are case-insensitive.
Example:
```js
process.env.TEST = 1;
console.log(process.env.test);
// => 1
```
## process.emitWarning(warning[, type[, code]][, ctor])
<!-- YAML
added: v6.0.0
@ -803,6 +726,83 @@ emitMyWarning();
// Emits nothing
```
## process.env
<!-- YAML
added: v0.1.27
-->
* {Object}
The `process.env` property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
```js
{
TERM: 'xterm-256color',
SHELL: '/usr/local/bin/bash',
USER: 'maciej',
PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
PWD: '/Users/maciej',
EDITOR: 'vim',
SHLVL: '1',
HOME: '/Users/maciej',
LOGNAME: 'maciej',
_: '/usr/local/bin/node'
}
```
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process. In other words, the following example
would not work:
```console
$ node -e 'process.env.foo = "bar"' && echo $foo
```
While the following will:
```js
process.env.foo = 'bar';
console.log(process.env.foo);
```
Assigning a property on `process.env` will implicitly convert the value
to a string.
Example:
```js
process.env.test = null;
console.log(process.env.test);
// => 'null'
process.env.test = undefined;
console.log(process.env.test);
// => 'undefined'
```
Use `delete` to delete a property from `process.env`.
Example:
```js
process.env.TEST = 1;
delete process.env.TEST;
console.log(process.env.TEST);
// => undefined
```
On Windows operating systems, environment variables are case-insensitive.
Example:
```js
process.env.TEST = 1;
console.log(process.env.test);
// => 1
```
## process.execArgv
<!-- YAML
added: v0.7.7

104
doc/api/tls.md
View File

@ -214,19 +214,6 @@ added: v0.3.2
The `tls.Server` class is a subclass of `net.Server` that accepts encrypted
connections using TLS or SSL.
### Event: 'tlsClientError'
<!-- YAML
added: v6.0.0
-->
The `'tlsClientError'` event is emitted when an error occurs before a secure
connection is established. The listener callback is passed two arguments when
called:
* `exception` {Error} The `Error` object describing the error
* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the
error originated.
### Event: 'newSession'
<!-- YAML
added: v0.9.2
@ -353,6 +340,19 @@ When ALPN has no selected protocol, `tlsSocket.alpnProtocol` returns `false`.
The `tlsSocket.servername` property is a string containing the server name
requested via SNI.
### Event: 'tlsClientError'
<!-- YAML
added: v6.0.0
-->
The `'tlsClientError'` event is emitted when an error occurs before a secure
connection is established. The listener callback is passed two arguments when
called:
* `exception` {Error} The `Error` object describing the error
* `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the
error originated.
### server.addContext(hostname, context)
<!-- YAML
added: v0.5.3
@ -531,14 +531,6 @@ underlying socket as reported by the operating system. Returns an
object with three properties, e.g.,
`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
### tlsSocket.authorized
<!-- YAML
added: v0.11.4
-->
Returns `true` if the peer certificate was signed by one of the CAs specified
when creating the `tls.TLSSocket` instance, otherwise `false`.
### tlsSocket.authorizationError
<!-- YAML
added: v0.11.4
@ -547,6 +539,14 @@ added: v0.11.4
Returns the reason why the peer's certificate was not been verified. This
property is set only when `tlsSocket.authorized === false`.
### tlsSocket.authorized
<!-- YAML
added: v0.11.4
-->
Returns `true` if the peer certificate was signed by one of the CAs specified
when creating the `tls.TLSSocket` instance, otherwise `false`.
### tlsSocket.encrypted
<!-- YAML
added: v0.11.4
@ -741,37 +741,6 @@ and their processing can be delayed due to packet loss or reordering. However,
smaller fragments add extra TLS framing bytes and CPU overhead, which may
decrease overall server throughput.
## tls.connect(port[, host][, options][, callback])
<!-- YAML
added: v0.11.3
-->
* `port` {number} Default value for `options.port`.
* `host` {string} Optional default value for `options.host`.
* `options` {Object} See [`tls.connect()`][].
* `callback` {Function} See [`tls.connect()`][].
Same as [`tls.connect()`][] except that `port` and `host` can be provided
as arguments instead of options.
*Note*: A port or host option, if specified, will take precedence over any port
or host argument.
## tls.connect(path[, options][, callback])
<!-- YAML
added: v0.11.3
-->
* `path` {string} Default value for `options.path`.
* `options` {Object} See [`tls.connect()`][].
* `callback` {Function} See [`tls.connect()`][].
Same as [`tls.connect()`][] except that `path` can be provided
as an argument instead of an option.
*Note*: A path option, if specified, will take precedence over the path
argument.
## tls.connect(options[, callback])
<!-- YAML
added: v0.11.3
@ -884,6 +853,37 @@ socket.on('end', () => {
});
```
## tls.connect(path[, options][, callback])
<!-- YAML
added: v0.11.3
-->
* `path` {string} Default value for `options.path`.
* `options` {Object} See [`tls.connect()`][].
* `callback` {Function} See [`tls.connect()`][].
Same as [`tls.connect()`][] except that `path` can be provided
as an argument instead of an option.
*Note*: A path option, if specified, will take precedence over the path
argument.
## tls.connect(port[, host][, options][, callback])
<!-- YAML
added: v0.11.3
-->
* `port` {number} Default value for `options.port`.
* `host` {string} Optional default value for `options.host`.
* `options` {Object} See [`tls.connect()`][].
* `callback` {Function} See [`tls.connect()`][].
Same as [`tls.connect()`][] except that `port` and `host` can be provided
as arguments instead of options.
*Note*: A port or host option, if specified, will take precedence over any port
or host argument.
## tls.createSecureContext(options)
<!-- YAML

90
doc/api/url.md
View File

@ -34,32 +34,6 @@ illustrate each.
(all spaces in the "" line should be ignored -- they are purely for formatting)
```
### urlObject.href
The `href` property is the full URL string that was parsed with both the
`protocol` and `host` components converted to lower-case.
For example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
### urlObject.protocol
The `protocol` property identifies the URL's lower-cased protocol scheme.
For example: `'http:'`
### urlObject.slashes
The `slashes` property is a `boolean` with a value of `true` if two ASCII
forward-slash characters (`/`) are required following the colon in the
`protocol`.
### urlObject.host
The `host` property is the full lower-cased host portion of the URL, including
the `port` if specified.
For example: `'host.com:8080'`
### urlObject.auth
The `auth` property is the username and password portion of the URL, also
@ -70,6 +44,20 @@ with the `[:{password}]` portion being optional.
For example: `'user:pass'`
### urlObject.hash
The `hash` property consists of the "fragment" portion of the URL including
the leading ASCII hash (`#`) character.
For example: `'#hash'`
### urlObject.host
The `host` property is the full lower-cased host portion of the URL, including
the `port` if specified.
For example: `'host.com:8080'`
### urlObject.hostname
The `hostname` property is the lower-cased host name portion of the `host`
@ -77,11 +65,21 @@ component *without* the `port` included.
For example: `'host.com'`
### urlObject.port
### urlObject.href
The `port` property is the numeric port portion of the `host` component.
The `href` property is the full URL string that was parsed with both the
`protocol` and `host` components converted to lower-case.
For example: `'8080'`
For example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
### urlObject.path
The `path` property is a concatenation of the `pathname` and `search`
components.
For example: `'/p/a/t/h?query=string'`
No decoding of the `path` is performed.
### urlObject.pathname
@ -94,23 +92,17 @@ For example `'/p/a/t/h'`
No decoding of the path string is performed.
### urlObject.search
### urlObject.port
The `search` property consists of the entire "query string" portion of the
URL, including the leading ASCII question mark (`?`) character.
The `port` property is the numeric port portion of the `host` component.
For example: `'?query=string'`
For example: `'8080'`
No decoding of the query string is performed.
### urlObject.protocol
### urlObject.path
The `protocol` property identifies the URL's lower-cased protocol scheme.
The `path` property is a concatenation of the `pathname` and `search`
components.
For example: `'/p/a/t/h?query=string'`
No decoding of the `path` is performed.
For example: `'http:'`
### urlObject.query
@ -124,12 +116,20 @@ For example: `'query=string'` or `{'query': 'string'}`
If returned as a string, no decoding of the query string is performed. If
returned as an object, both keys and values are decoded.
### urlObject.hash
### urlObject.search
The `hash` property consists of the "fragment" portion of the URL including
the leading ASCII hash (`#`) character.
The `search` property consists of the entire "query string" portion of the
URL, including the leading ASCII question mark (`?`) character.
For example: `'#hash'`
For example: `'?query=string'`
No decoding of the query string is performed.
### urlObject.slashes
The `slashes` property is a `boolean` with a value of `true` if two ASCII
forward-slash characters (`/`) are required following the colon in the
`protocol`.
## url.format(urlObject)
<!-- YAML

44
doc/api/util.md
View File

@ -343,6 +343,14 @@ util.inspect(obj);
// Returns: "{ bar: 'baz' }"
```
### util.inspect.custom
<!-- YAML
added: v6.6.0
-->
A Symbol that can be used to declare custom inspect functions, see
[Custom inspection functions on Objects][].
### util.inspect.defaultOptions
<!-- YAML
added: v6.4.0
@ -363,19 +371,25 @@ util.inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array
```
### util.inspect.custom
<!-- YAML
added: v6.6.0
-->
A Symbol that can be used to declare custom inspect functions, see
[Custom inspection functions on Objects][].
## Deprecated APIs
The following APIs have been deprecated and should no longer be used. Existing
applications and modules should be updated to find alternative approaches.
### util.\_extend(target, source)
<!-- YAML
added: v0.7.5
deprecated: v6.0.0
-->
> Stability: 0 - Deprecated: Use [`Object.assign()`] instead.
The `util._extend()` method was never intended to be used outside of internal
Node.js modules. The community found and used it anyway.
It is deprecated and should not be used in new code. JavaScript comes with very
similar built-in functionality through [`Object.assign()`].
### util.debug(string)
<!-- YAML
added: v0.3.0
@ -829,20 +843,6 @@ deprecated: v0.11.3
Deprecated predecessor of `console.log`.
### util.\_extend(target, source)
<!-- YAML
added: v0.7.5
deprecated: v6.0.0
-->
> Stability: 0 - Deprecated: Use [`Object.assign()`] instead.
The `util._extend()` method was never intended to be used outside of internal
Node.js modules. The community found and used it anyway.
It is deprecated and should not be used in new code. JavaScript comes with very
similar built-in functionality through [`Object.assign()`].
[`Array.isArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray
[constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor
[semantically incompatible]: https://github.com/nodejs/node/issues/4179

78
doc/api/v8.md
View File

@ -9,45 +9,6 @@ const v8 = require('v8');
*Note*: The APIs and implementation are subject to change at any time.
## v8.getHeapStatistics()
<!-- YAML
added: v1.0.0
-->
Returns an object with the following properties:
* `total_heap_size` {number}
* `total_heap_size_executable` {number}
* `total_physical_size` {number}
* `total_available_size` {number}
* `used_heap_size` {number}
* `heap_size_limit` {number}
* `malloced_memory` {number}
* `peak_malloced_memory` {number}
* `does_zap_garbage` {number}
`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space`
option is enabled or not. This makes V8 overwrite heap garbage with a bit
pattern. The RSS footprint (resident memory set) gets bigger because it
continuously touches all heap pages and that makes them less likely to get
swapped out by the operating system.
For example:
```js
{
total_heap_size: 7326976,
total_heap_size_executable: 4194304,
total_physical_size: 7326976,
total_available_size: 1152656,
used_heap_size: 3476208,
heap_size_limit: 1535115264,
malloced_memory: 16384,
peak_malloced_memory: 1127496,
does_zap_garbage: 0
}
```
## v8.getHeapSpaceStatistics()
<!-- YAML
added: v6.0.0
@ -108,6 +69,45 @@ For example:
]
```
## v8.getHeapStatistics()
<!-- YAML
added: v1.0.0
-->
Returns an object with the following properties:
* `total_heap_size` {number}
* `total_heap_size_executable` {number}
* `total_physical_size` {number}
* `total_available_size` {number}
* `used_heap_size` {number}
* `heap_size_limit` {number}
* `malloced_memory` {number}
* `peak_malloced_memory` {number}
* `does_zap_garbage` {number}
`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space`
option is enabled or not. This makes V8 overwrite heap garbage with a bit
pattern. The RSS footprint (resident memory set) gets bigger because it
continuously touches all heap pages and that makes them less likely to get
swapped out by the operating system.
For example:
```js
{
total_heap_size: 7326976,
total_heap_size_executable: 4194304,
total_physical_size: 7326976,
total_available_size: 1152656,
used_heap_size: 3476208,
heap_size_limit: 1535115264,
malloced_memory: 16384,
peak_malloced_memory: 1127496,
does_zap_garbage: 0
}
```
## v8.setFlagsFromString(string)
<!-- YAML
added: v1.0.0