@contrast/agent 4.31.2 → 5.0.0-alpha.1

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

@@ -1,473 +0,0 @@
-# `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 @dabh/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 `@dabh/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('@dabh/diagnostics')('foo:bar:baz');
-const debug = require('@dabh/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('@dabh/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 `@dabh/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('@dabh/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('@dabh/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('@dabh/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('@dabh/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('@dabh/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('@dabh/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('@dabh/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('@dabh/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('@dabh/diagnostics')('example:namespace');
-
-debug.adapter(require('@dabh/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

@@ -1,11 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,8 +0,0 @@
-//
-// 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

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

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

@@ -1,24 +0,0 @@
-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;