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

doc: update internal errors documentation

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/19203
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
This commit is contained in:
Michaël Zasso 2018-03-06 14:23:36 +01:00
parent 49963f4da9
commit 0eec0735d0
No known key found for this signature in database
GPG Key ID: 770F7A9A5AE15600
2 changed files with 29 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CPP_STYLE_GUIDE.md
View File

@ -256,13 +256,13 @@ env->SetMethod(target, "foo", Foo);
exports.foo = function(str) {
// Prefer doing the type-checks in JavaScript
if (typeof str !== 'string') {
throw new errors.TypeError('ERR_INVALID_ARG_TYPE', 'str', 'string');
throw new errors.codes.ERR_INVALID_ARG_TYPE('str', 'string');
}
const ctx = {};
const result = binding.foo(str, ctx);
if (ctx.code !== undefined) {
throw new errors.Error('ERR_ERROR_NAME', ctx.code);
throw new errors.codes.ERR_ERROR_NAME(ctx.code);
}
return result;
};

93
doc/guides/using-internal-errors.md
View File

@ -19,8 +19,8 @@ considered a `semver-major` change.
## Using internal/errors.js
The `internal/errors` module exposes three custom `Error` classes that
are intended to replace existing `Error` objects within the Node.js source.
The `internal/errors` module exposes all custom errors as subclasses of the
builtin errors. After being added, an error can be found in the `codes` object.
For instance, an existing `Error` such as:
@ -32,15 +32,15 @@ Can be replaced by first adding a new error key into the `internal/errors.js`
file:
```js
E('FOO', 'Expected string received %s');
E('FOO', 'Expected string received %s', TypeError);
```
Then replacing the existing `new TypeError` in the code:
```js
const errors = require('internal/errors');
const { FOO } = require('internal/errors').codes;
// ...
const err = new errors.TypeError('FOO', type);
const err = new FOO(type);
```
## Adding new errors
@ -49,8 +49,8 @@ New static error codes are added by modifying the `internal/errors.js` file
and appending the new error codes to the end using the utility `E()` method.
```js
E('EXAMPLE_KEY1', 'This is the error value');
E('EXAMPLE_KEY2', (a, b) => `${a} ${b}`);
E('EXAMPLE_KEY1', 'This is the error value', TypeError);
E('EXAMPLE_KEY2', (a, b) => `${a} ${b}`, RangeError);
```
The first argument passed to `E()` is the static identifier. The second
@ -58,7 +58,24 @@ argument is either a String with optional `util.format()` style replacement
tags (e.g. `%s`, `%d`), or a function returning a String. The optional
additional arguments passed to the `errors.message()` function (which is
used by the `errors.Error`, `errors.TypeError` and `errors.RangeError` classes),
will be used to format the error message.
will be used to format the error message. The third argument is the base class
that the new error will extend.
It is possible to create multiple derived
classes by providing additional arguments. The other ones will be exposed as
properties of the main class:
<!-- eslint-disable no-unreachable -->
```js
E('EXAMPLE_KEY', 'Error message', TypeError, RangeError);
// In another module
const { EXAMPLE_KEY } = require('internal/errors').codes;
// TypeError
throw new EXAMPLE_KEY();
// RangeError
throw new EXAMPLE_KEY.RangeError();
```
## Documenting new errors
@ -115,65 +132,9 @@ likely be required.
## API
### Class: errors.Error(key[, args...])
### Object: errors.codes
* `key` {string} The static error identifier
* `args...` {any} Zero or more optional arguments
```js
const errors = require('internal/errors');
const arg1 = 'foo';
const arg2 = 'bar';
const myError = new errors.Error('KEY', arg1, arg2);
throw myError;
```
The specific error message for the `myError` instance will depend on the
associated value of `KEY` (see "Adding new errors").
The `myError` object will have a `code` property equal to the `key` and a
`name` property equal to `` `Error [${key}]` ``.
### Class: errors.TypeError(key[, args...])
* `key` {string} The static error identifier
* `args...` {any} Zero or more optional arguments
```js
const errors = require('internal/errors');
const arg1 = 'foo';
const arg2 = 'bar';
const myError = new errors.TypeError('KEY', arg1, arg2);
throw myError;
```
The specific error message for the `myError` instance will depend on the
associated value of `KEY` (see "Adding new errors").
The `myError` object will have a `code` property equal to the `key` and a
`name` property equal to `` `TypeError [${key}]` ``.
### Class: errors.RangeError(key[, args...])
* `key` {string} The static error identifier
* `args...` {any} Zero or more optional arguments
```js
const errors = require('internal/errors');
const arg1 = 'foo';
const arg2 = 'bar';
const myError = new errors.RangeError('KEY', arg1, arg2);
throw myError;
```
The specific error message for the `myError` instance will depend on the
associated value of `KEY` (see "Adding new errors").
The `myError` object will have a `code` property equal to the `key` and a
`name` property equal to `` `RangeError [${key}]` ``.
Exposes all internal error classes to be used by Node.js APIs.
### Method: errors.message(key, args)