@contrast/agent 3.11.10

package/node_modules/@dabh/diagnostics/README.md

@@ -0,0 +1,473 @@
+# `diagnostics`
+
+Diagnostics in the evolution of debug pattern that is used in the Node.js core,  
+this extremely small but powerful technique can best be compared as feature
+flags for loggers. The created debug logger is disabled by default but can be
+enabled without changing a line of code, using flags.
+
+- Allows debugging in multiple JavaScript environments such as Node.js, browsers
+  and React-Native.
+- Separated development and production builds to minimize impact on your
+  application when bundled.
+- Allows for customization of logger, messages, and much more.
+
+![Output Example](example.png)
+
+## Installation
+
+The module is released in the public npm registry and can be installed by
+running:
+
+```
+npm install --save diagnostics
+```
+
+## Usage
+
+- [Introduction](#introduction)
+- [Advanced usage](#advanced-usage)
+  - [Production and development builds](#production-and-development-builds)
+    - [WebPack](#webpack)
+    - [Node.js](#nodejs)
+- [API](#api)
+  - [.enabled](#enabled)
+  - [.namespace](#namespace)
+  - [.dev/prod](#devprod)
+  - [set](#set)
+  - [modify](#modify)
+  - [use](#use)
+- [Modifiers](#modifiers)
+  - [namespace](#namespace-1)
+- [Adapters](#adapters)
+  - [process.env](#process-env)
+  - [hash](#hash)
+  - [localStorage](#localstorage)
+  - [AsyncStorage](#asyncstorage)
+- [Loggers](#loggers)
+
+### Introduction
+
+To create a new logger simply `require` the `diagnostics` module and call
+the returned function. It accepts 2 arguments:
+
+1. `namespace` **Required** This is the namespace of your logger so we know if we need to
+   enable your logger when a debug flag is used. Generally you use the name of
+   your library or application as first root namespace. For example if you're
+   building a parser in a library (example) you would set namespace
+   `example:parser`.
+2. `options` An object with additional configuration for the logger.
+   following keys are recognized:
+   - `force` Force the logger to be enabled.
+   - `colors` Colors are enabled by default for the logs, but you can set this
+     option to `false` to disable it.
+
+```js
+const debug = require('diagnostics')('foo:bar:baz');
+const debug = require('diagnostics')('foo:bar:baz', { options });
+
+debug('this is a log message %s', 'that will only show up when enabled');
+debug('that is pretty neat', { log: 'more', data: 1337 });
+```
+
+Unlike `console.log` statements that add and remove during your development
+lifecycle you create meaningful log statements that will give you insight in
+the library or application that you're developing.
+
+The created debugger uses different "adapters" to extract the debug flag
+out of the JavaScript environment. To learn more about enabling the debug flag
+in your specific environment click on one of the enabled adapters below.
+
+- **browser**: [localStorage](#localstorage), [hash](#hash)
+- **node.js**: [environment variables](#processenv)
+- **react-native**: [AsyncStorage](#asyncstorage)
+
+Please note that the returned logger is fully configured out of the box, you
+do not need to set any of the adapters/modifiers your self, they are there
+for when you want more advanced control over the process. But if you want to
+learn more about that, read the next section.
+
+### Advanced usage
+
+There are 2 specific usage patterns for `diagnostic`, library developers who
+implement it as part of their modules and applications developers who either
+use it in their application or are searching for ways to consume the messages.
+
+With the simple log interface as discussed in the [introduction](#introduction)
+section we make it easy for developers to add it as part of their libraries
+and applications, and with powerful [API](#api) we allow infinite customization
+by allowing custom adapters, loggers and modifiers to ensure that this library
+maintains relevant. These methods not only allow introduction of new loggers,
+but allow you think outside the box. For example you can maintain a history
+of past log messages, and output those when an uncaught exception happens in
+your application so you have additional context
+
+```js
+const diagnostics = require('diagnostics');
+
+let index = 0;
+const limit = 200;
+const history = new Array(limit);
+
+//
+// Force all `diagnostic` loggers to be enabled.
+//
+diagnostics.force = process.env.NODE_ENV === 'prod';
+diagnostics.set(function customLogger(meta, message) {
+  history[index]= { meta, message, now: Date.now() };
+  if (index++ === limit) index = 0;
+
+  //
+  // We're running a development build, so output.
+  //
+  if (meta.dev) console.log.apply(console, message);
+});
+
+process.on('uncaughtException', async function (err) {
+  await saveErrorToDisk(err, history);
+  process.exit(1);
+});
+```
+
+The small snippet above will maintain a 200 limited FIFO (First In First Out)
+queue of all debug messages that can be referenced when your application crashes
+
+#### Production and development builds
+
+When you `require` the `diagnostics` module you will be given a logger that is
+optimized for `development` so it can provide the best developer experience
+possible.
+
+The development logger enables all the [adapters](#adapters) for your
+JavaScript environment, adds a logger that outputs the messages to `console.log`
+and registers our message modifiers so log messages will be prefixed with the
+supplied namespace so you know where the log messages originates from.
+
+The development logger does not have any adapter, modifier and logger enabled
+by default. This ensures that your log messages never accidentally show up in
+production. However this does not mean that it's not possible to get debug
+messages in production. You can `force` the debugger to be enabled, and
+supply a [custom logger](#loggers).
+
+```js
+const diagnostics = require('diagnostics');
+const debug = debug('foo:bar', { force: true });
+
+//
+// Or enable _every_ diagnostic instance:
+//
+diagnostics.force = true;
+```
+
+##### WebPack
+
+WebPack has the concept of [mode](https://webpack.js.org/concepts/mode/#usage)'s
+which creates different
+
+```js
+module.exports = {
+  mode: 'development' // 'production'
+}
+```
+
+When you are building your app using the WebPack CLI you can use the `--mode`
+flag:
+
+```
+webpack --mode=production app.js -o /dist/bundle.js
+```
+
+##### Node.js
+
+When you are running your app using `Node.js` you should the `NODE_ENV`
+environment variable to `production` to ensure that you libraries that you
+import are optimized for production.
+
+```
+NODE_ENV=production node app.js
+```
+
+### API
+
+The returned logger exposes some addition properties that can be used used in
+your application or library:
+
+#### .enabled
+
+The returned logger will have a `.enabled` property assigned to it. This boolean
+can be used to check if the logger was enabled:
+
+```js
+const debug = require('diagnostics')('foo:bar');
+
+if (debug.enabled) {
+  //
+  // Do something special
+  //
+}
+```
+
+This property is exposed as:
+
+- Property on the logger.
+- Property on the meta/options object.
+
+#### .namespace
+
+This is the namespace that you originally provided to the function.
+
+```js
+const debug = require('diagnostics')('foo:bar');
+
+console.log(debug.namespace); // foo:bar
+```
+
+This property is exposed as:
+
+- Property on the logger.
+- Property on the meta/options object.
+
+#### .dev/prod
+
+There are different builds available of `diagnostics`, when you create a
+production build of your application using `NODE_ENV=production` you will be
+given an optimized, smaller build of `diagnostics` to reduce your bundle size.
+The `dev` and `prod` booleans on the returned logger indicate if you have a
+production or development version of the logger.
+
+```js
+const debug = require('diagnostics')('foo:bar');
+
+if (debug.prod) {
+  // do stuff
+}
+```
+
+This property is exposed as:
+
+- Property on the logger.
+- Property on the meta/options object.
+
+#### set
+
+Sets a new logger as default for  **all** `diagnostic` instances. The passed
+argument should be a function that write the log messages to where ever you
+want. It receives 2 arguments:
+
+1. `meta` An object with all the options that was provided to the original
+   logger that wants to write the log message as well as properties of the
+   debugger such as `prod`, `dev`, `namespace`, `enabled`. See [API](#api) for
+   all exposed properties.
+2. `args` An array of the log messages that needs to be written.
+
+```js
+const debug = require('diagnostics')('foo:more:namespaces');
+
+debug.use(function logger(meta, args) {
+  console.log(meta);
+  console.debug(...args);
+});
+```
+
+This method is exposed as:
+
+- Method on the logger.
+- Method on the meta/options object.
+- Method on `diagnostics` module.
+
+#### modify
+
+The modify method allows you add a new message modifier to **all** `diagnostic`
+instances. The passed argument should be a function that returns the passed
+message after modification. The function receives 2 arguments:
+
+1. `message`, Array, the log message.
+2. `options`, Object, the options that were passed into the logger when it was
+   initially created.
+
+```js
+const debug = require('diagnostics')('example:modifiers');
+
+debug.modify(function (message, options) {
+  return messages;
+});
+```
+
+This method is exposed as:
+
+- Method on the logger.
+- Method on the meta/options object.
+- Method on `diagnostics` module.
+
+See [modifiers](#modifiers) for more information.
+
+#### use
+
+Adds a new `adapter` to **all** `diagnostic` instances. The passed argument
+should be a function returns a boolean that indicates if the passed in
+`namespace` is allowed to write log messages.
+
+```js
+const diagnostics = require('diagnostics');
+const debug = diagnostics('foo:bar');
+
+debug.use(function (namespace) {
+  return namespace === 'foo:bar';
+});
+```
+
+This method is exposed as:
+
+- Method on the logger.
+- Method on the meta/options object.
+- Method on `diagnostics` module.
+
+See [adapters](#adapters) for more information.
+
+### Modifiers
+
+To be as flexible as possible when it comes to transforming messages we've
+come up with the concept of `modifiers` which can enhance the debug messages.
+This allows you to introduce functionality or details that you find important
+for debug messages, and doesn't require us to add additional bloat to the
+`diagnostic` core.
+
+For example, you want the messages to be prefixed with the date-time of when
+the log message occured:
+
+```js
+const diagnostics = require('diagnostics');
+
+diagnostics.modify(function datetime(args, options) {
+  args.unshift(new Date());
+  return args;
+});
+```
+
+Now all messages will be prefixed with date that is outputted by `new Date()`.
+The following modifiers are shipped with `diagnostics` and are enabled in
+**development** mode only:
+
+- [namespace](#namespace)
+
+#### namespace
+
+This modifier is enabled for all debug instances and prefixes the messages
+with the name of namespace under which it is logged. The namespace is colored
+using the `colorspace` module which groups similar namespaces under the same
+colorspace. You can have multiple namespaces for the debuggers where each
+namespace should be separated by a `:`
+
+```
+foo
+foo:bar
+foo:bar:baz
+```
+
+For console based output the `namespace-ansi` is used.
+
+### Adapters
+
+Adapters allows `diagnostics` to pull the `DEBUG` and `DIAGNOSTICS` environment
+variables from different sources. Not every JavaScript environment has a
+`process.env` that we can leverage. Adapters allows us to have different
+adapters for different environments. It means you can write your own custom
+adapter if needed as well.
+
+The `adapter` function should be passed a function as argument, this function
+will receive the `namespace` of a logger as argument and it should return a
+boolean that indicates if that logger should be enabled or not.
+
+```js
+const debug = require('diagnostics')('example:namespace');
+
+debug.adapter(require('diagnostics/adapters/localstorage'));
+```
+
+The modifiers are only enabled for `development`. The following adapters are
+available are available:
+
+#### process.env
+
+This adapter is enabled for `node.js`.
+
+Uses the `DEBUG` or `DIAGNOSTICS` (both are recognized) environment variables to
+pass in debug flag:
+
+**UNIX/Linux/Mac**
+```
+DEBUG=foo* node index.js
+```
+
+Using environment variables on Windows is a bit different, and also depends on
+toolchain you are using:
+
+**Windows**
+```
+set DEBUG=foo* & node index.js
+```
+
+**Powershell**
+```
+$env:DEBUG='foo*';node index.js
+```
+
+#### hash
+
+This adapter is enabled for `browsers`.
+
+This adapter uses the `window.location.hash` of as source for the environment
+variables. It assumes that hash is formatted using the same syntax as query
+strings:
+
+```js
+http://example.com/foo/bar#debug=foo*
+```
+
+It triggers on both the `debug=` and `diagnostics=` names.
+
+#### localStorage
+
+This adapter is enabled for `browsers`.
+
+This adapter uses the `localStorage` of the browser to store the debug flags.
+You can set the debug flag your self in your application code, but you can
+also open browser WebInspector and enable it through the console.
+
+```js
+localStorage.setItem('debug', 'foo*');
+```
+
+It triggers on both the `debug` and `diagnostics` storage items. (Please note
+that these keys should be entered in lowercase)
+
+#### AsyncStorage
+
+This adapter is enabled for `react-native`.
+
+This adapter uses the `AsyncStorage` API that is exposed by the `react-native`
+library to store and read the `debug` or `diagnostics` storage items.
+
+```js
+import { AsyncStorage } from 'react-native';
+
+AsyncStorage.setItem('debug', 'foo*');
+```
+
+Unlike other adapters, this is the only adapter that is `async` so that means
+that we're not able to instantly determine if a created logger should be
+enabled or disabled. So when a logger is created in `react-native` we initially
+assume it's disabled, any message that send during period will be queued
+internally.
+
+Once we've received the data from the `AsyncStorage` API we will determine
+if the logger should be enabled, flush the queued messages if needed and set
+all `enabled` properties accordingly on the returned logger.
+
+### Loggers
+
+By default it will log all messages to `console.log` in when the logger is
+enabled using the debug flag that is set using one of the adapters.
+
+## License
+
+[MIT](LICENSE)

package/node_modules/@dabh/diagnostics/adapters/hash.js

@@ -0,0 +1,11 @@
+var adapter = require('./');
+
+/**
+ * Extracts the values from process.env.
+ *
+ * @type {Function}
+ * @public
+ */
+module.exports = adapter(function hash() {
+  return /(debug|diagnostics)=([^&]+)/i.exec(window.location.hash)[2];
+});

package/node_modules/@dabh/diagnostics/adapters/index.js

@@ -0,0 +1,18 @@
+var enabled = require('enabled');
+
+/**
+ * Creates a new Adapter.
+ *
+ * @param {Function} fn Function that returns the value.
+ * @returns {Function} The adapter logic.
+ * @public
+ */
+module.exports = function create(fn) {
+  return function adapter(namespace) {
+    try {
+      return enabled(namespace, fn());
+    } catch (e) { /* Any failure means that we found nothing */ }
+
+    return false;
+  };
+}

package/node_modules/@dabh/diagnostics/adapters/localstorage.js

@@ -0,0 +1,11 @@
+var adapter = require('./');
+
+/**
+ * Extracts the values from process.env.
+ *
+ * @type {Function}
+ * @public
+ */
+module.exports = adapter(function storage() {
+  return localStorage.getItem('debug') || localStorage.getItem('diagnostics');
+});

package/node_modules/@dabh/diagnostics/adapters/process.env.js

@@ -0,0 +1,11 @@
+var adapter = require('./');
+
+/**
+ * Extracts the values from process.env.
+ *
+ * @type {Function}
+ * @public
+ */
+module.exports = adapter(function processenv() {
+  return process.env.DEBUG || process.env.DIAGNOSTICS;
+});

package/node_modules/@dabh/diagnostics/browser/development.js

@@ -0,0 +1,35 @@
+var create = require('../diagnostics');
+
+/**
+ * Create a new diagnostics logger.
+ *
+ * @param {String} namespace The namespace it should enable.
+ * @param {Object} options Additional options.
+ * @returns {Function} The logger.
+ * @public
+ */
+var diagnostics = create(function dev(namespace, options) {
+  options = options || {};
+  options.namespace = namespace;
+  options.prod = false;
+  options.dev = true;
+
+  if (!dev.enabled(namespace) && !(options.force || dev.force)) {
+    return dev.nope(options);
+  }
+
+  return dev.yep(options);
+});
+
+//
+// Configure the logger for the given environment.
+//
+diagnostics.modify(require('../modifiers/namespace'));
+diagnostics.use(require('../adapters/localstorage'));
+diagnostics.use(require('../adapters/hash'));
+diagnostics.set(require('../logger/console'));
+
+//
+// Expose the diagnostics logger.
+//
+module.exports = diagnostics;

package/node_modules/@dabh/diagnostics/browser/index.js

@@ -0,0 +1,8 @@
+//
+// Select the correct build version depending on the environment.
+//
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('./production.js');
+} else {
+  module.exports = require('./development.js');
+}

package/node_modules/@dabh/diagnostics/browser/override.js

@@ -0,0 +1,6 @@
+var diagnostics = require('./');
+
+//
+// No way to override `debug` with `diagnostics` in the browser.
+//
+module.exports = diagnostics;

package/node_modules/@dabh/diagnostics/browser/production.js

@@ -0,0 +1,24 @@
+var create = require('../diagnostics');
+
+/**
+ * Create a new diagnostics logger.
+ *
+ * @param {String} namespace The namespace it should enable.
+ * @param {Object} options Additional options.
+ * @returns {Function} The logger.
+ * @public
+ */
+var diagnostics = create(function prod(namespace, options) {
+  options = options || {};
+  options.namespace = namespace;
+  options.prod = true;
+  options.dev = false;
+
+  if (!(options.force || prod.force)) return prod.nope(options);
+  return prod.yep(options);
+});
+
+//
+// Expose the diagnostics logger.
+//
+module.exports = diagnostics;