feat(defaultHandler): Exit on error option

BREAKING CHANGE: Changes the default behaviour to exit the process on the first error logged.

Author: nokome

README.md

@@ -23,6 +23,8 @@ npm install --save @stencila/logga
 
 ## Usage
 
+### Emitting log events
+
 Create a new logger by calling `getLogger` with a unique tag to identify your app and/or module. Then emit log events using the `debug`, `info`, `warn` and `error` functions. You can pass them a message string or a `LogInfo` object.
 
 ```js
@@ -46,6 +48,18 @@ try {
 }
 ```
 
+See [this post](https://reflectoring.io/logging-levels/) for advice on when to use the alternative log levels. In summary,
+
+- The `ERROR` level should only be used when the application really is in trouble. Users are being affected without having a way to work around the issue.
+
+- The `WARN` level should be used when something bad happened, but the application still has the chance to heal itself or the issue can wait a day or two to be fixed.
+
+- The `INFO` level should be used to document state changes in the application or some entity within the application.
+
+- The `DEBUG` level should be used to log any information that helps us identify what went wrong.
+
+### Handling log events
+
 The default log handler prints log data to `console.error`. If `stderr` is TTY log data is formatted for human consumption with emoji, colours and stack trace (for errors):
 
 ![](screenshot.png)
@@ -84,6 +98,14 @@ addHandler((data: LogData) => {
 })
 ```
 
+### Exiting the process
+
+When in Node.js, the `defaultHandler` will exit the process, with code 1, on the first error event. To disable this behavior set the option `exitOnError: false` e.g.
+
+```js
+replaceHandlers((data) => defaultHandler(data, { exitOnError: false }))
+```
+
 ## See also
 
 See this [issue in `node-bunyan`](https://github.com/trentm/node-bunyan/issues/116) describing the use case for, and approaches to, a global, shared logger in Node.

index.test.ts

@@ -14,7 +14,7 @@ test('logging', () => {
   const log = getLogger(TAG)
 
   const events: LogData[] = []
-  addHandler((data) => events.push(data))
+  replaceHandlers((data) => events.push(data))
 
   log.debug('a debug message')
   expect(events.length).toBe(1)
@@ -46,6 +46,7 @@ test('logging', () => {
 
 test('TTY', () => {
   const log = getLogger('tests:tty')
+  replaceHandlers((data) => defaultHandler(data, { exitOnError: false }))
 
   // Fake that we are using a TTY device
   process.stderr.isTTY = true
@@ -60,6 +61,7 @@ test('TTY', () => {
 
 test('non-TTY', () => {
   const log = getLogger('tests:non-tty')
+  replaceHandlers((data) => defaultHandler(data, { exitOnError: false }))
 
   // Fake that we are using a non-TTY device
   // @ts-ignore
@@ -202,6 +204,7 @@ test('defaultHandler:throttle', async () => {
 
   replaceHandlers((data) =>
     defaultHandler(data, {
+      exitOnError: false,
       throttle: { signature: '${message}', duration: 200 },
     })
   )

index.ts

@@ -237,15 +237,19 @@ export function replaceHandlers(handler: LogHandler): void {
 const defaultHandlerHistory = new Map<string, number>()
 
 /**
- * Default log data handler.
+ * Default log event handler.
  *
- * Prints the data to stderr:
+ * Prints the event data to stderr:
  *
  * - with cutesy emoji, colours and stack (for errors) if stderr is TTY (for human consumption)
  * - as JSON if stderr is not TTY (for machine consumption e.g. log files)
  *
+ * If in Node.js, and the
+ *
  * @param data The log data to handle
- * @param options.maxLevel The maximum log level to print. Defaults to `info`
+ * @param options.maxLevel The maximum log level to print. Defaults to `info`.
+ * @param options.showStack Whether or not to show any stack traces for errors. Defaults to `false`.
+ * @param options.exitOnError Whether or not to exit the process on the first error. Defaults to `true`.
  * @param options.throttle.signature The log event signature to use for throttling. Defaults to '' (i.e. all events)
  * @param options.throttle.duration The duration for throttling (milliseconds). Defaults to 1000ms
  */
@@ -254,6 +258,7 @@ export function defaultHandler(
   options: {
     maxLevel?: LogLevel
     showStack?: boolean
+    exitOnError?: boolean
     throttle?: {
       signature?: string
       duration?: number
@@ -320,6 +325,15 @@ export function defaultHandler(
     if (showStack && stack !== undefined) entry += '\n  ' + stack
   }
   console.error(entry)
+
+  const { exitOnError = true } = options
+  if (
+    typeof process !== 'undefined' &&
+    exitOnError &&
+    level === LogLevel.error
+  ) {
+    process.exit(1)
+  }
 }
 
 // Enable the default handler if there no other handler