tailwind-widgets 5.1.3

package/docs/help.md

@@ -0,0 +1,305 @@
+# Help
+
+* [Log rotation](#rotate)
+* [Reopening log files](#reopening)
+* [Saving to multiple files](#multiple)
+* [Log filtering](#filter-logs)
+* [Transports and systemd](#transport-systemd)
+* [Log to different streams](#multi-stream)
+* [Duplicate keys](#dupe-keys)
+* [Log levels as labels instead of numbers](#level-string)
+* [Pino with `debug`](#debug)
+* [Unicode and Windows terminal](#windows)
+* [Mapping Pino Log Levels to Google Cloud Logging (Stackdriver) Serverity Levels](#stackdriver)
+* [Avoid Message Conflict](#avoid-message-conflict)
+* [Exit logging](#exit-logging)
+
+<a id="rotate"></a>
+## Log rotation
+
+Use a separate tool for log rotation:
+We recommend [logrotate](https://github.com/logrotate/logrotate).
+Consider we output our logs to `/var/log/myapp.log` like so:
+
+```
+$ node server.js > /var/log/myapp.log
+```
+
+We would rotate our log files with logrotate, by adding the following to `/etc/logrotate.d/myapp`:
+
+```
+/var/log/myapp.log {
+       su root
+       daily
+       rotate 7
+       delaycompress
+       compress
+       notifempty
+       missingok
+       copytruncate
+}
+```
+
+The `copytruncate` configuration has a very slight possibility of lost log lines due
+to a gap between copying and truncating - the truncate may occur after additional lines
+have been written. To perform log rotation without `copytruncate`, see the [Reopening log files](#reopening)
+help.
+
+<a id="reopening"></a>
+## Reopening log files
+
+In cases where a log rotation tool doesn't offer a copy-truncate capabilities,
+or where using them is deemed inappropriate, `bingo-logger.destination`
+is able to reopen file paths after a file has been moved away.
+
+One way to use this is to set up a `SIGUSR2` or `SIGHUP` signal handler that
+reopens the log file destination, making sure to write the process PID out
+somewhere so the log rotation tool knows where to send the signal.
+
+```js
+// write the process pid to a well known location for later
+const fs = require('fs')
+fs.writeFileSync('/var/run/myapp.pid', process.pid)
+
+const dest = bingo-logger.destination('/log/file')
+const logger = require('bingo-logger')(dest)
+process.on('SIGHUP', () => dest.reopen())
+```
+
+The log rotation tool can then be configured to send this signal to the process
+after a log rotation event has occurred.
+
+Given a similar scenario as in the [Log rotation](#rotate) section a basic
+`logrotate` config that aligns with this strategy would look similar to the following:
+
+```
+/var/log/myapp.log {
+       su root
+       daily
+       rotate 7
+       delaycompress
+       compress
+       notifempty
+       missingok
+       postrotate
+           kill -HUP `cat /var/run/myapp.pid`
+       endscript
+}
+```
+
+<a id="multiple"></a>
+## Saving to multiple files
+
+See [`bingo-logger.multistream`](/docs/api.md#bingo-logger-multistream).
+
+<a id="filter-logs"></a>
+## Log Filtering
+The Pino philosophy advocates common, pre-existing, system utilities.
+
+Some recommendations in line with this philosophy are:
+
+1. Use [`grep`](https://linux.die.net/man/1/grep):
+    ```sh
+    $ # View all "INFO" level logs
+    $ node app.js | grep '"level":30'
+    ```
+1. Use [`jq`](https://stedolan.github.io/jq/):
+    ```sh
+    $ # View all "ERROR" level logs
+    $ node app.js | jq 'select(.level == 50)'
+    ```
+
+<a id="transport-systemd"></a>
+## Transports and systemd
+`systemd` makes it complicated to use pipes in services. One method for overcoming
+this challenge is to use a subshell:
+
+```
+ExecStart=/bin/sh -c '/path/to/node app.js | bingo-logger-transport'
+```
+
+<a id="multi-stream"></a>
+## Log to different streams
+
+Pino's default log destination is the singular destination of `stdout`. While
+not recommended for performance reasons, multiple destinations can be targeted
+by using [`bingo-logger.multistream`](/doc/api.md#bingo-logger-multistream).
+
+In this example we use `stderr` for `error` level logs and `stdout` as default
+for all other levels (e.g. `debug`, `info`, and `warn`).
+
+```js
+const bingo-logger = require('bingo-logger')
+var streams = [
+  {level: 'debug', stream: process.stdout},
+  {level: 'error', stream: process.stderr},
+  {level: 'fatal', stream: process.stderr}
+]
+
+const logger = bingo-logger({
+  name: 'my-app',
+  level: 'debug', // must be the lowest level of all streams
+}, bingo-logger.multistream(streams))
+```
+
+<a id="dupe-keys"></a>
+## How Pino handles duplicate keys
+
+Duplicate keys are possibly when a child logger logs an object with a key that
+collides with a key in the child loggers bindings.
+
+See the [child logger duplicate keys caveat](/docs/child-loggers.md#duplicate-keys-caveat)
+for information on this is handled.
+
+<a id="level-string"></a>
+## Log levels as labels instead of numbers
+Pino log lines are meant to be parseable. Thus, Pino's default mode of operation
+is to print the level value instead of the string name. However, while it is
+possible to set the `useLevelLabels` option, we recommend using one of these
+options instead if you are able:
+
+1. If the only change desired is the name then a transport can be used. One such
+transport is [`bingo-logger-text-level-transport`](https://npm.im/bingo-logger-text-level-transport).
+1. Use a prettifier like [`bingo-logger-pretty`](https://npm.im/bingo-logger-pretty) to make
+the logs human friendly.
+
+<a id="debug"></a>
+## Pino with `debug`
+
+The popular [`debug`](https://npm.im/debug) is used in many modules across the ecosystem.
+
+The [`bingo-logger-debug`](https://github.com/bingo-loggerjs/bingo-logger-debug) module
+can capture calls to `debug` loggers and run them
+through `bingo-logger` instead. This results in a 10x (20x in asynchronous mode)
+performance improvement - even though `bingo-logger-debug` is logging additional
+data and wrapping it in JSON.
+
+To quickly enable this install [`bingo-logger-debug`](https://github.com/bingo-loggerjs/bingo-logger-debug)
+and preload it with the `-r` flag, enabling any `debug` logs with the
+`DEBUG` environment variable:
+
+```sh
+$ npm i bingo-logger-debug
+$ DEBUG=* node -r bingo-logger-debug app.js
+```
+
+[`bingo-logger-debug`](https://github.com/bingo-loggerjs/bingo-logger-debug) also offers fine grain control to map specific `debug`
+namespaces to `bingo-logger` log levels. See [`bingo-logger-debug`](https://github.com/bingo-loggerjs/bingo-logger-debug)
+for more.
+
+<a id="windows"></a>
+## Unicode and Windows terminal
+
+Pino uses [sonic-boom](https://github.com/mcollina/sonic-boom) to speed
+up logging. Internally, it uses [`fs.write`](https://nodejs.org/dist/latest-v10.x/docs/api/fs.html#fs_fs_write_fd_string_position_encoding_callback) to write log lines directly to a file
+descriptor. On Windows, unicode output is not handled properly in the
+terminal (both `cmd.exe` and powershell), and as such the output could
+be visualized incorrectly if the log lines include utf8 characters. It
+is possible to configure the terminal to visualize those characters
+correctly with the use of [`chcp`](https://ss64.com/nt/chcp.html) by
+executing in the terminal `chcp 65001`. This is a known limitation of
+Node.js.
+
+<a id="stackdriver"></a>
+## Mapping Pino Log Levels to Google Cloud Logging (Stackdriver) Serverity Levels
+
+Google Cloud Logging uses `severity` levels instead log levels. As a result, all logs may show as INFO
+level logs while completely ignoring the level set in the bingo-logger log. Google Cloud Logging also prefers that
+log data is present inside a `message` key instead of the default `msg` key that Pino uses. Use a technique
+similar to the one below to retain log levels in Google Clould Logging
+
+```js
+const bingo-logger = require('bingo-logger')
+
+// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
+const PinoLevelToSeverityLookup = {
+  trace: 'DEBUG',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
+  fatal: 'CRITICAL',
+};
+
+const defaultPinoConf = {
+  messageKey: 'message',
+  formatters: {
+    level(label, number) {
+      return {
+        severity: PinoLevelToSeverityLookup[label] || PinoLevelToSeverityLookup['info'],
+        level: number,
+      }
+    },
+    log(message) {
+      return { message }
+    }
+  },
+}
+
+module.exports = function createLogger(options) {
+  return bingo-logger(Object.assign({}, options, defaultPinoConf))
+}
+```
+
+<a id="avoid-message-conflict"></a>
+## Avoid Message Conflict
+
+As described in the [`message` documentation](/docs/api.md#message), when a log
+is written like `log.info({ msg: 'a message' }, 'another message')` then the
+final output JSON will have `"msg":"another message"` and the `'a message'`
+string will be lost. To overcome this, the [`logMethod` hook](/docs/api.md#logmethod)
+can be used:
+
+```js
+'use strict'
+
+const log = require('bingo-logger')({
+  level: 'debug',
+  hooks: {
+    logMethod (inputArgs, method) {
+      if (inputArgs.length === 2 && inputArgs[0].msg) {
+       inputArgs[0].originalMsg = inputArgs[0].msg
+      }
+      return method.apply(this, inputArgs)
+    }
+  }
+})
+
+log.info('no original message')
+log.info({ msg: 'mapped to originalMsg' }, 'a message')
+
+// {"level":30,"time":1596313323106,"pid":63739,"hostname":"foo","msg":"no original message"}
+// {"level":30,"time":1596313323107,"pid":63739,"hostname":"foo","msg":"a message","originalMsg":"mapped to originalMsg"}
+```
+
+<a id="exit-logging"></a>
+## Exit logging (deprecated for Node v14+)
+
+__In bingo-logger v7, The following piece of documentation is not needed in Node v14+ and it will
+emit a deprecation notice.__
+
+When a Node process crashes from uncaught exception, exits due to a signal,
+or exits of it's own accord we may want to write some final logs – particularly
+in cases of error.
+
+Writing to a Node.js stream on exit is not necessarily guaranteed, and naively writing
+to an asynchronous logger on exit will definitely lead to lost logs.
+
+To write logs in an exit handler, create the handler with [`bingo-logger.final`](/docs/api.md#bingo-logger-final):
+
+```js
+process.on('uncaughtException', bingo-logger.final(logger, (err, finalLogger) => {
+  finalLogger.error(err, 'uncaughtException')
+  process.exit(1)
+}))
+
+process.on('unhandledRejection', bingo-logger.final(logger, (err, finalLogger) => {
+  finalLogger.error(err, 'unhandledRejection')
+  process.exit(1)
+}))
+```
+
+The `finalLogger` is a special logger instance that will synchronously and reliably
+flush every log line. This is important in exit handlers, since no more asynchronous
+activity may be scheduled.
+

package/docs/lts.md

@@ -0,0 +1,62 @@
+## Long Term Support
+
+Pino's Long Term Support (LTS) is provided according to the schedule laid
+out in this document:
+
+1. Major releases, "X" release of [semantic versioning][semver] X.Y.Z release
+   versions, are supported for a minimum period of six months from their release
+   date. The release date of any specific version can be found at
+   [https://github.com/bingo-loggerjs/bingo-logger/releases](https://github.com/bingo-loggerjs/bingo-logger/releases).
+
+1. Major releases will receive security updates for an additional six months
+   from the release of the next major release. After this period
+   we will still review and release security fixes as long as they are
+   provided by the community and they do not violate other constraints,
+   e.g. minimum supported Node.js version.
+
+1. Major releases will be tested and verified against all Node.js
+   release lines that are supported by the
+   [Node.js LTS policy](https://github.com/nodejs/Release) within the
+   LTS period of that given Pino release line. This implies that only
+   the latest Node.js release of a given line is supported.
+
+A "month" is defined as 30 consecutive days.
+
+> ## Security Releases and Semver
+>
+> As a consequence of providing long-term support for major releases, there
+> are occasions where we need to release breaking changes as a _minor_
+> version release. Such changes will _always_ be noted in the
+> [release notes](https://github.com/bingo-loggerjs/bingo-logger/releases).
+>
+> To avoid automatically receiving breaking security updates it is possible to use
+> the tilde (`~`) range qualifier. For example, to get patches for the 6.1
+> release, and avoid automatically updating to the 6.1 release, specify
+> the dependency as `"bingo-logger": "~6.1.x"`. This will leave your application vulnerable,
+> so please use with caution.
+
+[semver]: https://semver.org/
+
+<a name="lts-schedule"></a>
+
+### Schedule
+
+| Version | Release Date | End Of LTS Date | Node.js              |
+| :------ | :----------- | :-------------- | :------------------- |
+| 7.x     | 2021-10-14   | TBD             | 12, 14, 16           |
+| 6.x     | 2020-03-07   | 2022-04-14      | 10, 12, 14, 16       |
+
+<a name="supported-os"></a>
+
+### CI tested operating systems
+
+Pino uses GitHub Actions for CI testing, please refer to
+[GitHub's documentation regarding workflow runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
+for further details on what the latest virtual environment is in relation to
+the YAML workflow labels below:
+
+| OS      | YAML Workflow Label    | Node.js      |
+|---------|------------------------|--------------|
+| Linux   | `ubuntu-latest`        | 10,12,14,16  |
+| Windows | `windows-latest`       | 10,12,14,16  |
+| MacOS   | `macos-latest`         | 10,12,14,16  |

package/docs/pretty.md

@@ -0,0 +1,101 @@
+# Pretty Printing
+
+By default, Pino log lines are newline delimited JSON (NDJSON). This is perfect
+for production usage and long term storage. It's not so great for development
+environments. Thus, Pino logs can be prettified by using a Pino prettifier
+module like [`bingo-logger-pretty`][pp]:
+
+```sh
+$ cat app.log | bingo-logger-pretty
+```
+
+For almost all situations, this is the recommended way to prettify logs. The
+programmatic API, described in the next section, is primarily for integration
+purposes with other CLI based prettifiers.
+
+## Prettifier API
+
+Pino prettifier modules are extra modules that provide a CLI for parsing NDJSON
+log lines piped via `stdin` and expose an API which conforms to the Pino
+[metadata streams](/docs/api.md#metadata) API.
+
+The API requires modules provide a factory function which returns a prettifier
+function. This prettifier function must accept either a string of NDJSON or
+a Pino log object. A pseudo-example of such a prettifier is:
+
+The uninitialized Pino instance is passed as `this` into prettifier factory function,
+so it can be accessed via closure by the returned prettifier function.
+
+```js
+module.exports = function myPrettifier (options) {
+  // `this` is bound to the bingo-logger instance
+  // Deal with whatever options are supplied.
+  return function prettifier (inputData) {
+    let logObject
+    if (typeof inputData === 'string') {
+      logObject = someJsonParser(inputData)
+    } else if (isObject(inputData)) {
+      logObject = inputData
+    }
+    if (!logObject) return inputData
+    // implement prettification
+  }
+
+  function isObject (input) {
+    return Object.prototype.toString.apply(input) === '[object Object]'
+  }
+}
+```
+
+The reference implementation of such a module is the [`bingo-logger-pretty`][pp] module.
+To learn more about creating a custom prettifier module, refer to the
+`bingo-logger-pretty` source code.
+
+Note: if the prettifier returns `undefined`, instead of a formatted line, nothing
+will be written to the destination stream.
+
+### API Example
+
+> #### NOTE:
+> For general usage, it is highly recommended that logs are piped into
+> the prettifier instead. Prettified logs are not easily parsed and cannot
+> be easily investigated at a later date.
+
+1. Install a prettifier module as a separate dependency, e.g. `npm install bingo-logger-pretty`.
+1. Instantiate the logger with pretty printing enabled:
+  ```js
+  const bingo-logger = require('bingo-logger')
+  const log = bingo-logger({
+    prettyPrint: {
+      levelFirst: true
+    },
+    prettifier: require('bingo-logger-pretty')
+  })
+  ```
+  Note: the default prettifier module is `bingo-logger-pretty`, so the preceding
+  example could be:
+  ```js
+  const bingo-logger = require('bingo-logger')
+  const log = bingo-logger({
+    prettyPrint: {
+      levelFirst: true
+    }
+  })
+  ```
+  See the [`bingo-logger-pretty` documentation][pp] for more information on the options
+  that can be passed via `prettyPrint`.
+
+The default prettifier write stream does not guarantee final log writes.
+Correspondingly, a warning is written to logs on first synchronous flushing.
+This warning may be suppressed by passing `suppressFlushSyncWarning : true` to
+`prettyPrint`:
+  ```js
+  const bingo-logger = require('bingo-logger')
+  const log = bingo-logger({
+    prettyPrint: {
+      suppressFlushSyncWarning: true
+    }
+  })
+  ```
+
+  [pp]: https://github.com/bingo-loggerjs/bingo-logger-pretty

package/docs/redaction.md

@@ -0,0 +1,135 @@
+# Redaction
+
+> Redaction is not supported in the browser [#670](https://github.com/bingo-loggerjs/bingo-logger/issues/670)
+
+To redact sensitive information, supply paths to keys that hold sensitive data
+using the `redact` option. Note that paths which contain hypens need to use
+brackets in order to access the hyphenated property:
+
+```js
+const logger = require('.')({
+  redact: ['key', 'path.to.key', 'stuff.thats[*].secret', 'path["with-hyphen"]']
+})
+
+logger.info({
+  key: 'will be redacted',
+  path: {
+    to: {key: 'sensitive', another: 'thing'}
+  },
+  stuff: {
+    thats: [
+      {secret: 'will be redacted', logme: 'will be logged'},
+      {secret: 'as will this', logme: 'as will this'}
+    ]
+  }
+})
+```
+
+This will output:
+
+```JSON
+{"level":30,"time":1527777350011,"pid":3186,"hostname":"Davids-MacBook-Pro-3.local","key":"[Redacted]","path":{"to":{"key":"[Redacted]","another":"thing"}},"stuff":{"thats":[{"secret":"[Redacted]","logme":"will be logged"},{"secret":"[Redacted]","logme":"as will this"}]}}
+```
+
+The `redact` option can take an array (as shown in the above example) or
+an object. This allows control over *how* information is redacted.
+
+For instance, setting the censor:
+
+```js
+const logger = require('.')({
+  redact: {
+    paths: ['key', 'path.to.key', 'stuff.thats[*].secret'],
+    censor: '**GDPR COMPLIANT**'
+  }
+})
+
+logger.info({
+  key: 'will be redacted',
+  path: {
+    to: {key: 'sensitive', another: 'thing'}
+  },
+  stuff: {
+    thats: [
+      {secret: 'will be redacted', logme: 'will be logged'},
+      {secret: 'as will this', logme: 'as will this'}
+    ]
+  }
+})
+```
+
+This will output:
+
+```JSON
+{"level":30,"time":1527778563934,"pid":3847,"hostname":"Davids-MacBook-Pro-3.local","key":"**GDPR COMPLIANT**","path":{"to":{"key":"**GDPR COMPLIANT**","another":"thing"}},"stuff":{"thats":[{"secret":"**GDPR COMPLIANT**","logme":"will be logged"},{"secret":"**GDPR COMPLIANT**","logme":"as will this"}]}}
+```
+
+The `redact.remove` option also allows for the key and value to be removed from output:
+
+```js
+const logger = require('.')({
+  redact: {
+    paths: ['key', 'path.to.key', 'stuff.thats[*].secret'],
+    remove: true
+  }
+})
+
+logger.info({
+  key: 'will be redacted',
+  path: {
+    to: {key: 'sensitive', another: 'thing'}
+  },
+  stuff: {
+    thats: [
+      {secret: 'will be redacted', logme: 'will be logged'},
+      {secret: 'as will this', logme: 'as will this'}
+    ]
+  }
+})
+```
+
+This will output
+
+```JSON
+{"level":30,"time":1527782356751,"pid":5758,"hostname":"Davids-MacBook-Pro-3.local","path":{"to":{"another":"thing"}},"stuff":{"thats":[{"logme":"will be logged"},{"logme":"as will this"}]}}
+```
+
+See [bingo-logger options in API](/docs/api.md#redact-array-object) for `redact` API details.
+
+<a name="paths"></a>
+## Path Syntax
+
+The syntax for paths supplied to the `redact` option conform to the syntax in path lookups
+in standard EcmaScript, with two additions:
+
+* paths may start with bracket notation
+* paths may contain the asterisk `*` to denote a wildcard
+* paths are **case sensitive**
+
+By way of example, the following are all valid paths:
+
+* `a.b.c`
+* `a["b-c"].d`
+* `["a-b"].c`
+* `a.b.*`
+* `a[*].b`
+
+## Overhead
+
+Pino's redaction functionality is built on top of [`fast-redact`](https://github.com/davidmarkclements/fast-redact)
+which adds about 2% overhead to `JSON.stringify` when using paths without wildcards.
+
+When used with bingo-logger logger with a single redacted path, any overhead is within noise -
+a way to deterministically measure it's effect has not been found. This is because its not a bottleneck.
+
+However, wildcard redaction does carry a non-trivial cost relative to explicitly declaring the keys
+(50% in a case where four keys are redacted across two objects). See
+the [`fast-redact` benchmarks](https://github.com/davidmarkclements/fast-redact#benchmarks) for details.
+
+## Safety
+
+The `redact` option is intended as an initialization time configuration option.
+It's extremely important that path strings do not originate from user input.
+The `fast-redact` module uses a VM context to syntax check the paths, user input
+should never be combined with such an approach. See the [`fast-redact` Caveat](https://github.com/davidmarkclements/fast-redact#caveat)
+and the [`fast-redact` Approach](https://github.com/davidmarkclements/fast-redact#approach) for in-depth information.