Skip to content

Commit c561e42

Browse files
ehmickyehmicky
committed
Improve README
1 parent 3f326bc commit c561e42

File tree

2 files changed

+173
-139
lines changed

2 files changed

+173
-139
lines changed

‎README.md‎

Lines changed: 19 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Without `log-process-errors`:
3232

3333
![Screenshot after](docs/after.png)
3434

35-
# Installation
35+
# Install
3636

3737
Production code (e.g. a web server) can install this either as a production or
3838
development dependency:
@@ -70,161 +70,41 @@ logProcessErrors(options)
7070

7171
`logProcessErrors()` should be called as early as possible in the code.
7272

73-
`options` is an optional object with the following properties:
73+
# Options
7474

75-
- [`log` `{function}`](#custom-logging)
76-
- [`level` `{object}`](#log-level)
77-
- [`message` `{function}`](#log-message)
78-
- [`colors` `{boolean}`](#log-message)
79-
- [`exitOn` `{string[]}`](#process-exit)
75+
`options` is an optional object with the following properties:
8076

81-
# Custom logging
77+
- [`log` `{function}`](#custom-logging): override how events are logged.
78+
Default: use `console.warn()`, `console.error()`, etc.
79+
- [`level` `{object}`](#log-level): which log level to use. Default:
80+
`{ warning: 'warn', multipleResolves: 'info', default: 'error' }`.
81+
- [`message` `{function}`](#log-message): override the default message
82+
generation.
83+
- [`colors` `{boolean}`](#log-message): colorize the default message. Default:
84+
`true`.
85+
- [`exitOn` `{string[]}`](#process-exit): which events should trigger
86+
`process.exit(1)`. Default: `['uncaughtException']`.
8287

83-
By default events will be logged to the console using `console.error()`,
84-
`console.warn()`, etc.
88+
Please see the [options full documentation](options.md).
8589

86-
This behavior can be overridden with the `log` option. For example to log events
87-
with [Winston](https://github.com/winstonjs/winston) instead:
90+
Example:
8891

8992
```js
9093
logProcessErrors({
9194
log(message, level, info) {
9295
winstonLogger[level](message)
9396
},
94-
})
95-
```
96-
97-
The function's arguments are [`message`](#log-message) (string),
98-
[`level`](#log-level) (string) and [`info`](#event-information) (object).
99-
100-
If logging is asynchronous, the function should return a promise (or use
101-
`async`/`await`). This is not necessary if logging is using streams (like
102-
[Winston](https://github.com/winstonjs/winston)).
10397

104-
Duplicate events are only logged once (whether the `log` option is defined or
105-
not).
98+
level: { multiResolves: 'debug' },
10699

107-
# Log level
100+
message(info) {},
108101

109-
The default log level is `warn` for
110-
[`warning`](https://nodejs.org/api/process.html#process_event_warning),
111-
`info` for
112-
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves)
113-
and `error` for the other events.
102+
colors: false,
114103

115-
This can be overridden by using the `level` option. It should be an
116-
object whose:
117-
118-
- keys are the event names among `"default"`,
119-
[`"uncaughtException"`](https://nodejs.org/api/process.html#process_event_uncaughtexception),
120-
[`"warning"`](https://nodejs.org/api/process.html#process_event_warning),
121-
[`"unhandledRejection"`](https://nodejs.org/api/process.html#process_event_unhandledrejection),
122-
[`"rejectionHandled"`](https://nodejs.org/api/process.html#process_event_rejectionhandled)
123-
or
124-
[`"multipleResolves"`](https://nodejs.org/api/process.html#process_event_multipleresolves).
125-
- values are the log level which can be:
126-
- a string among `"debug"`, `"info"`, `"warn"`, `"error"` or `"silent"`.
127-
- `undefined` to use the default value.
128-
- a function using [`info` as argument](#event-information) and
129-
returning a string or `undefined` (as above).
130-
131-
```js
132-
logProcessErrors({
133-
// Use `debug` log level for `multipleResolves` instead of `info`
134-
level: { multipleResolves: 'debug' },
104+
exitOn: ['uncaughtException', 'unhandledRejection'],
135105
})
136106
```
137107

138-
```js
139-
logProcessErrors({
140-
// Skip some logs based on a condition
141-
level: {
142-
default() {
143-
if (shouldSkip()) {
144-
return 'silent'
145-
}
146-
},
147-
},
148-
})
149-
```
150-
151-
# Log message
152-
153-
A nice-looking and descriptive log message is generated by default.
154-
155-
The message will be colorized unless the option `colors` is set to `false`.
156-
157-
The message generation can be overridden by using the `message` option. It
158-
should be a function using [`info` as argument](#event-information) and
159-
returning a string.
160-
161-
# Event information
162-
163-
The [`log`](#custom-logging), [`level`](#log-level) and
164-
[`message`](#log-message) options all receive as argument an `info` object.
165-
166-
## `info.eventName`
167-
168-
Can be
169-
[`"uncaughtException"`](https://nodejs.org/api/process.html#process_event_uncaughtexception),
170-
[`"unhandledRejection"`](https://nodejs.org/api/process.html#process_event_unhandledrejection),
171-
[`"rejectionHandled"`](https://nodejs.org/api/process.html#process_event_rejectionhandled),
172-
[`"multipleResolves"`](https://nodejs.org/api/process.html#process_event_multipleresolves)
173-
or
174-
[`"warning"`](https://nodejs.org/api/process.html#process_event_warning).
175-
176-
## `info.value`
177-
178-
Value:
179-
180-
- thrown by
181-
[`uncaughtException`](https://nodejs.org/api/process.html#process_event_uncaughtexception).
182-
- resolved/rejected by the promise with
183-
[`unhandledRejection`](https://nodejs.org/api/process.html#process_event_unhandledrejection),
184-
[`rejectionHandled`](https://nodejs.org/api/process.html#process_event_rejectionhandled)
185-
and
186-
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves).
187-
- emitted by
188-
[`warning`](https://nodejs.org/api/process.html#process_event_warning).
189-
190-
It is usually an `Error` instance but could be anything.
191-
192-
## `info.rejected`
193-
194-
Boolean indicating whether the promise was initially resolved or rejected. Only
195-
defined with
196-
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves).
197-
198-
## `info.nextValue`, `info.nextRejected`
199-
200-
Like [`value`](#infovalue) and [`rejected`](#inforejected) but for
201-
the second time the promise was resolved/rejected. Only defined with
202-
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves).
203-
204-
## `info.level`
205-
206-
[Log level](#log-level). Only defined with the [`message` option](#log-message).
207-
208-
## `info.colors`
209-
210-
[Chalk instance](https://github.com/chalk/chalk#api) to colorize strings.
211-
Only defined with the [`message` option](#log-message). Disabled if the
212-
[`colors` option](#log-message) is `false`.
213-
214-
# Process exit
215-
216-
The `exitOn` option specifies which event should trigger `process.exit(1)`:
217-
218-
- the default value is `["uncaughtException"]`. This is the
219-
[default behavior](https://nodejs.org/api/process.html#process_warning_using_uncaughtexception_correctly)
220-
of Node.js.
221-
- we recommend using `["uncaughtException", "unhandledRejection"]`
222-
instead since this will be the [future default behavior of Node.js](https://nodejs.org/dist/latest-v8.x/docs/api/deprecations.html#deprecations_dep0018_unhandled_promise_rejections).
223-
- to prevent any `process.exit(1)` use `[]`. Recommended if your process is
224-
long-running and does not automatically restart on exit.
225-
226-
`process.exit(1)` will only be fired after successfully logging the event.
227-
228108
# Restoring default behavior
229109

230110
Node.js default behavior can be restored by firing the function returned by

‎docs/options.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Options
2+
3+
Options are passed as an optional object:
4+
5+
<!-- eslint-disable-next-line import/newline-after-import -->
6+
7+
```js
8+
const logProcessErrors = require('log-process-errors')
9+
logProcessErrors(options)
10+
```
11+
12+
## options.log `{string}`
13+
14+
By default events will be logged to the console using `console.error()`,
15+
`console.warn()`, etc.
16+
17+
This behavior can be overridden with the `log` option. For example to log events
18+
with [Winston](https://github.com/winstonjs/winston) instead:
19+
20+
```js
21+
logProcessErrors({
22+
log(message, level, info) {
23+
winstonLogger[level](message)
24+
},
25+
})
26+
```
27+
28+
The function's arguments are [`message`](#log-message) (string),
29+
[`level`](#log-level) (string) and [`info`](#event-information) (object).
30+
31+
If logging is asynchronous, the function should return a promise (or use
32+
`async`/`await`). This is not necessary if logging is using streams (like
33+
[Winston](https://github.com/winstonjs/winston)).
34+
35+
Duplicate events are only logged once (whether the `log` option is defined or
36+
not).
37+
38+
## options.level `{object}`
39+
40+
Which log level to use. It should be an object whose:
41+
42+
- keys are the event names among `"default"`,
43+
[`"uncaughtException"`](https://nodejs.org/api/process.html#process_event_uncaughtexception),
44+
[`"warning"`](https://nodejs.org/api/process.html#process_event_warning),
45+
[`"unhandledRejection"`](https://nodejs.org/api/process.html#process_event_unhandledrejection),
46+
[`"rejectionHandled"`](https://nodejs.org/api/process.html#process_event_rejectionhandled)
47+
or
48+
[`"multipleResolves"`](https://nodejs.org/api/process.html#process_event_multipleresolves).
49+
- values are the log level which can be:
50+
- a string among `"debug"`, `"info"`, `"warn"`, `"error"` or `"silent"`.
51+
- `undefined` to use the default value.
52+
- a function using [`info` as argument](#event-information) and
53+
returning a string or `undefined` (as above).
54+
55+
Default: `{ warning: 'warn', multipleResolves: 'info', default: 'error' }`.
56+
57+
```js
58+
logProcessErrors({
59+
// Use `debug` log level for `multipleResolves` instead of `info`
60+
level: { multipleResolves: 'debug' },
61+
})
62+
```
63+
64+
```js
65+
logProcessErrors({
66+
// Skip some logs based on a condition
67+
level: {
68+
default() {
69+
if (shouldSkip()) {
70+
return 'silent'
71+
}
72+
},
73+
},
74+
})
75+
```
76+
77+
## options.message `{function}`
78+
79+
Override the default message generation. It should be a function using
80+
[`info` as argument](#event-information) and returning a string.
81+
82+
By default a nice-looking and descriptive log message is generated.
83+
84+
## options.colors `{boolean}`
85+
86+
Colorize the default [`options.message`](#optionsmessagefunction). Default:
87+
`true`.
88+
89+
## options.exitOn `{string[]}`
90+
91+
Which events should trigger `process.exit(1)`:
92+
93+
- the default value is `["uncaughtException"]`. This is the
94+
[default behavior](https://nodejs.org/api/process.html#process_warning_using_uncaughtexception_correctly)
95+
of Node.js.
96+
- we recommend using `["uncaughtException", "unhandledRejection"]`
97+
instead since this will be the [future default behavior of Node.js](https://nodejs.org/dist/latest-v8.x/docs/api/deprecations.html#deprecations_dep0018_unhandled_promise_rejections).
98+
- to prevent any `process.exit(1)` use `[]`. Recommended if your process is
99+
long-running and does not automatically restart on exit.
100+
101+
`process.exit(1)` will only be fired after successfully logging the event.
102+
103+
# Event information
104+
105+
The [`log`](#custom-logging), [`level`](#log-level) and
106+
[`message`](#log-message) options all receive as argument an `info` object.
107+
108+
## `info.eventName`
109+
110+
Can be
111+
[`"uncaughtException"`](https://nodejs.org/api/process.html#process_event_uncaughtexception),
112+
[`"unhandledRejection"`](https://nodejs.org/api/process.html#process_event_unhandledrejection),
113+
[`"rejectionHandled"`](https://nodejs.org/api/process.html#process_event_rejectionhandled),
114+
[`"multipleResolves"`](https://nodejs.org/api/process.html#process_event_multipleresolves)
115+
or
116+
[`"warning"`](https://nodejs.org/api/process.html#process_event_warning).
117+
118+
## `info.value`
119+
120+
Value:
121+
122+
- thrown by
123+
[`uncaughtException`](https://nodejs.org/api/process.html#process_event_uncaughtexception).
124+
- resolved/rejected by the promise with
125+
[`unhandledRejection`](https://nodejs.org/api/process.html#process_event_unhandledrejection),
126+
[`rejectionHandled`](https://nodejs.org/api/process.html#process_event_rejectionhandled)
127+
and
128+
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves).
129+
- emitted by
130+
[`warning`](https://nodejs.org/api/process.html#process_event_warning).
131+
132+
It is usually an `Error` instance but could be anything.
133+
134+
## `info.rejected`
135+
136+
Boolean indicating whether the promise was initially resolved or rejected. Only
137+
defined with
138+
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves).
139+
140+
## `info.nextValue`, `info.nextRejected`
141+
142+
Like [`value`](#infovalue) and [`rejected`](#inforejected) but for
143+
the second time the promise was resolved/rejected. Only defined with
144+
[`multipleResolves`](https://nodejs.org/api/process.html#process_event_multipleresolves).
145+
146+
## `info.level`
147+
148+
[Log level](#log-level). Only defined with the [`message` option](#log-message).
149+
150+
## `info.colors`
151+
152+
[Chalk instance](https://github.com/chalk/chalk#api) to colorize strings.
153+
Only defined with the [`message` option](#log-message). Disabled if the
154+
[`colors` option](#log-message) is `false`.

0 commit comments

Comments
 (0)