Add examples

Author: ehmicky

README.md

@@ -40,6 +40,14 @@ With `log-process-errors`:
 - **Debugging** of process errors in development.
 - Automated **testing** of process errors.
 
+# Demo
+
+You can try this library:
+
+- either directly
+  [in your browser](https://repl.it/@ehmicky/log-process-errors).
+- or by executing the [`examples` files](examples/README.md) in a terminal.
+
 # Install
 
 Production code (e.g. a server) can install this either as a production or
@@ -80,43 +88,43 @@ logProcessErrors(options)
 
 # Options
 
-`options` is an optional object with the following properties.
-
-This is a quick summary. Please see the
-[options full documentation](docs/API.md) for more information and examples.
-
-## [log](docs/API.md#log)
+## log
 
 _Type_: `function(message, level, event)`<br>
 
 Customize how events are logged.
+[Full documentation](docs/API.md#log).
 
-## [level](docs/API.md#level)
+## level
 
 _Type_: `object`<br>
 _Default_: `{ warning: 'warn', multipleResolves: 'info', default: 'error' }`
 
 Which log level to use.
+[Full documentation](docs/API.md#level).
 
-## [message](docs/API.md#message)
+## message
 
 _Type_: `function(level, event, options) => string`
 
 Customize messages.
+[Full documentation](docs/API.md#message).
 
-## [colors](docs/API.md#colors)
+## colors
 
 _Type_: `boolean`<br>
 _Default_: `true` if the output is a terminal.
 
 Colorize messages.
+[Full documentation](docs/API.md#colors).
 
-## [exitOn](docs/API.md#exiton)
+## exitOn
 
 _Type_: `string[]`<br>
 _Default_: `["uncaughtException"]`
 
 Which events should trigger `process.exit(1)`.
+[Full documentation](docs/API.md#exiton).
 
 # Support
 

docs/API.md

@@ -1,5 +1,11 @@
 # API
 
+You can try all the examples below:
+
+- either directly
+  [in your browser](https://repl.it/@ehmicky/log-process-errors).
+- or by executing the [`examples` files](../examples/README.md) in a terminal.
+
 ## logProcessErrors([options])
 
 Initialize `log-process-errors`. Returns a function that can be fired to restore

examples/README.md

@@ -0,0 +1,21 @@
+This directory contains examples of this library.
+
+To execute them, first [install](../README.md#install) `log-process-errors`.
+Then:
+
+- for JavaScript files, run
+  `node node_modules/log-process-errors/examples/FILE.js`.
+- for command line files (Bash), run
+  `bash node_modules/log-process-errors/examples/FILE.sh`.
+
+You can edit the examples.
+
+They can also be run directly
+[in your browser](https://repl.it/@ehmicky/log-process-errors).
+
+## Main usage
+
+- Process errors without `log-process-errors`:
+  [JavaScript](before.js), [command line](before.sh).
+- Process errors with `log-process-errors`:
+  [JavaScript](after.js), [command line](after.sh).

examples/after.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Demo of process errors when `log-process-errors` is used in JavaScript.
+// This file can be directly run:
+//   - first install `log-process-errors`
+//   - then `node node_modules/log-process-errors/examples/after.js`
+// An online demo is also available at:
+//   https://repl.it/@ehmicky/log-process-errors
+
+'use strict'
+
+// Ignore the following line: this is only needed for internal purposes.
+// eslint-disable-next-line import/no-unassigned-import
+require('./utils')
+
+const logProcessErrors = require('log-process-errors')
+
+const {
+  uncaughtException,
+  unhandledRejection,
+  warning,
+  multipleResolves,
+} = require('./errors')
+
+// Initialization
+logProcessErrors()
+
+// Emit different types of process errors.
+uncaughtException()
+unhandledRejection()
+warning()
+multipleResolves()

examples/after.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Demo of process errors when `log-process-errors` is used in the terminal
+# (Bash).
+# This file can be directly run:
+#   - first install `log-process-errors`
+#   - then `bash node_modules/log-process-errors/examples/after.sh`
+# An online demo is also available at:
+#   https://repl.it/@ehmicky/log-process-errors
+
+# Ignore the following line: this is only needed for internal purposes.
+. "$(dirname "$BASH_SOURCE")/utils.sh"
+
+node -r log-process-errors/register "$dir/before.js"

examples/before.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Demo of process errors when `log-process-errors` is not used in JavaScript.
+// This file can be directly run:
+//   - first install `log-process-errors`
+//   - then `node node_modules/log-process-errors/examples/before.js`
+// An online demo is also available at:
+//   https://repl.it/@ehmicky/log-process-errors
+
+'use strict'
+
+const {
+  uncaughtException,
+  unhandledRejection,
+  warning,
+  multipleResolves,
+} = require('./errors')
+
+// Emit different types of process errors.
+uncaughtException()
+unhandledRejection()
+warning()
+multipleResolves()

examples/before.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Demo of process errors when `log-process-errors` is not used in the terminal
+# (Bash).
+# This file can be directly run:
+#   - first install `log-process-errors`
+#   - then `bash node_modules/log-process-errors/examples/after.sh`
+# An online demo is also available at:
+#   https://repl.it/@ehmicky/log-process-errors
+
+# Ignore the following line: this is only needed for internal purposes.
+. "$(dirname "$BASH_SOURCE")/utils.sh"
+
+node "$dir/before.js"

examples/errors.js

@@ -0,0 +1,49 @@
+// The methods in this file trigger different types of process errors.
+// This is done for example purposes.
+'use strict'
+
+const { emitWarning } = require('process')
+
+// Emit an `uncaughtException` event
+const uncaughtException = function() {
+  setTimeout(() => {
+    // eslint-disable-next-line max-nested-callbacks
+    setTimeout(() => {
+      throw new Error('File not found')
+    }, 0)
+  }, 0)
+}
+
+// Emit `unhandledRejection` and `rejectionHandled` events
+const unhandledRejection = function() {
+  const promise = Promise.reject(new Error('Invalid permission'))
+  setTimeout(() => {
+    // eslint-disable-next-line no-empty-function, max-nested-callbacks
+    promise.catch(() => {})
+  }, 0)
+}
+
+// Emit a `warning` event
+const warning = function() {
+  emitWarning('Invalid option', {
+    type: 'DeprecationWarning',
+    code: 'DeprecatedMethod',
+    detail: 'opts.force is deprecated',
+  })
+}
+
+// Emit a `multipleResolves` event
+const multipleResolves = function() {
+  // eslint-disable-next-line no-new, promise/avoid-new
+  new Promise((resolve, reject) => {
+    resolve({ success: true })
+    reject(new Error('Cannot send request'))
+  })
+}
+
+module.exports = {
+  uncaughtException,
+  unhandledRejection,
+  warning,
+  multipleResolves,
+}

examples/utils.js

@@ -0,0 +1,26 @@
+// Ignore this file, this is only needed for internal purposes.
+// We mock `require()` so that examples look the same as if the library was
+// directly installed.
+
+'use strict'
+
+const Module = require('module')
+
+const { name } = require('../package')
+
+const originalRequire = Module.prototype.require
+
+// eslint-disable-next-line fp/no-mutation, func-names
+Module.prototype.require = function(moduleName, ...args) {
+  const moduleNameA = getMockedName(moduleName)
+  // eslint-disable-next-line fp/no-this
+  return originalRequire.call(this, moduleNameA, ...args)
+}
+
+const getMockedName = function(moduleName) {
+  if (moduleName !== name && !moduleName.startsWith(`${name}/`)) {
+    return moduleName
+  }
+
+  return moduleName.replace(name, `${__dirname}/..`)
+}

examples/utils.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Ignore this file, this is only needed for internal purposes.
+
+dir="$(dirname "$BASH_SOURCE")"
+projectRoot="$(realpath "$dir/..")"
+binaryName="$(basename "$projectRoot")"
+pathToBinary="build/src/bin/index.js"
+
+shopt -s expand_aliases
+
+# We create an alias so that examples look the same as if the library was
+# directly installed.
+alias "$binaryName"="$projectRoot/$pathToBinary"
+
+# This mocks node's `-r` flag so that examples look the same as if the library
+# directly installed
+alias node="node -r $dir/utils"