react-hook-eslint 1.0.1

package/docs/asynchronous.md

@@ -0,0 +1,40 @@
+# Asynchronous Logging
+
+Asynchronous logging enables the minimum overhead of Pino.
+Asynchronous logging works by buffering log messages and writing them in larger chunks.
+
+```js
+const pino = require('pino')
+const logger = pino(pino.destination({
+  dest: './my-file', // omit for stdout
+  minLength: 4096, // Buffer before writing
+  sync: false // Asynchronous logging
+}))
+```
+
+It's always possible to turn on synchronous logging by passing `sync: true`. 
+In this mode of operation, log messages are directly written to the
+output stream as the messages are generated with a _blocking_ operation.
+
+* See [`pino.destination`](/docs/api.md#pino-destination)
+* `pino.destination` is implemented on [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom).
+
+### AWS Lambda
+
+Asynchronous logging is disabled by default on AWS Lambda or any other environment
+that modifies `process.stdout`. If forcefully turned on, we recommend calling `dest.flushSync()` at the end
+of each function execution to avoid losing data.
+
+## Caveats
+
+Asynchronous logging has a couple of important caveats:
+
+* As opposed to the synchronous mode, there is not a one-to-one relationship between
+  calls to logging methods (e.g. `logger.info`) and writes to a log file
+* There is a possibility of the most recently buffered log messages being lost
+  in case of a system failure, e.g. a power cut.
+
+See also:
+
+* [`pino.destination` API](/docs/api.md#pino-destination)
+* [`destination` parameter](/docs/api.md#destination)

package/docs/benchmarks.md

@@ -0,0 +1,55 @@
+
+# Benchmarks
+
+`pino.info('hello world')`:
+
+```
+
+BASIC benchmark averages
+Bunyan average: 377.434ms
+Winston average: 270.249ms
+Bole average: 172.690ms
+Debug average: 220.527ms
+LogLevel average: 222.802ms
+Pino average: 114.801ms
+PinoMinLength average: 70.968ms
+PinoNodeStream average: 159.192ms
+
+```
+
+`pino.info({'hello': 'world'})`:
+
+```
+
+OBJECT benchmark averages
+BunyanObj average: 410.379ms
+WinstonObj average: 273.120ms
+BoleObj average: 185.069ms
+LogLevelObject average: 433.425ms
+PinoObj average: 119.315ms
+PinoMinLengthObj average: 76.968ms
+PinoNodeStreamObj average: 164.268ms
+
+```
+
+`pino.info(aBigDeeplyNestedObject)`:
+
+```
+
+DEEP-OBJECT benchmark averages
+BunyanDeepObj average: 1.839ms
+WinstonDeepObj average: 5.604ms
+BoleDeepObj average: 3.422ms
+LogLevelDeepObj average: 11.716ms
+PinoDeepObj average: 2.256ms
+PinoMinLengthDeepObj average: 2.240ms
+PinoNodeStreamDeepObj average: 2.595ms
+
+```
+
+`pino.info('hello %s %j %d', 'world', {obj: true}, 4, {another: 'obj'})`:
+
+For a fair comparison, [LogLevel](http://npm.im/loglevel) was extended
+to include a timestamp and [bole](http://npm.im/bole) had
+`fastTime` mode switched on.
+

package/docs/browser.md

@@ -0,0 +1,227 @@
+# Browser API
+
+Pino is compatible with [`browserify`](https://npm.im/browserify) for browser-side usage:
+
+This can be useful with isomorphic/universal JavaScript code.
+
+By default, in the browser,
+`pino` uses corresponding [Log4j](https://en.wikipedia.org/wiki/Log4j) `console` methods (`console.error`, `console.warn`, `console.info`, `console.debug`, `console.trace`) and uses `console.error` for any `fatal` level logs.
+
+## Options
+
+Pino can be passed a `browser` object in the options object,
+which can have the following properties:
+
+### `asObject` (Boolean)
+
+```js
+const pino = require('pino')({browser: {asObject: true}})
+```
+
+The `asObject` option will create a pino-like log object instead of
+passing all arguments to a console method, for instance:
+
+```js
+pino.info('hi') // creates and logs {msg: 'hi', level: 30, time: <ts>}
+```
+
+When `write` is set, `asObject` will always be `true`.
+
+### `formatters` (Object)
+
+An object containing functions for formatting the shape of the log lines. When provided, it enables the logger to produce a pino-like log object with customized formatting. Currently, it supports formatting for the `level` object only.
+
+##### `level`
+
+Changes the shape of the log level. The default shape is `{ level: number }`.
+The function takes two arguments, the label of the level (e.g. `'info'`)
+and the numeric value (e.g. `30`).
+
+```js
+const formatters = {
+  level (label, number) {
+    return { level: number }
+  }
+}
+```
+
+
+### `write` (Function | Object)
+
+Instead of passing log messages to `console.log` they can be passed to
+a supplied function.
+
+If `write` is set to a single function, all logging objects are passed
+to this function.
+
+```js
+const pino = require('pino')({
+  browser: {
+    write: (o) => {
+      // do something with o
+    }
+  }
+})
+```
+
+If `write` is an object, it can have methods that correspond to the
+levels. When a message is logged at a given level, the corresponding
+method is called. If a method isn't present, the logging falls back
+to using the `console`.
+
+
+```js
+const pino = require('pino')({
+  browser: {
+    write: {
+      info: function (o) {
+        //process info log object
+      },
+      error: function (o) {
+        //process error log object
+      }
+    }
+  }
+})
+```
+
+### `serialize`: (Boolean | Array)
+
+The serializers provided to `pino` are ignored by default in the browser, including
+the standard serializers provided with Pino. Since the default destination for log
+messages is the console, values such as `Error` objects are enhanced for inspection,
+which they otherwise wouldn't be if the Error serializer was enabled.
+
+We can turn all serializers on,
+
+```js
+const pino = require('pino')({
+  browser: {
+    serialize: true
+  }
+})
+```
+
+Or we can selectively enable them via an array:
+
+```js
+const pino = require('pino')({
+  serializers: {
+    custom: myCustomSerializer,
+    another: anotherSerializer
+  },
+  browser: {
+    serialize: ['custom']
+  }
+})
+// following will apply myCustomSerializer to the custom property,
+// but will not apply anotherSerializer to another key
+pino.info({custom: 'a', another: 'b'})
+```
+
+When `serialize` is `true` the standard error serializer is also enabled (see https://github.com/pinojs/pino/blob/master/docs/api.md#stdSerializers).
+This is a global serializer, which will apply to any `Error` objects passed to the logger methods.
+
+If `serialize` is an array the standard error serializer is also automatically enabled, it can
+be explicitly disabled by including a string in the serialize array: `!stdSerializers.err`, like so:
+
+```js
+const pino = require('pino')({
+  serializers: {
+    custom: myCustomSerializer,
+    another: anotherSerializer
+  },
+  browser: {
+    serialize: ['!stdSerializers.err', 'custom'] //will not serialize Errors, will serialize `custom` keys
+  }
+})
+```
+
+The `serialize` array also applies to any child logger serializers (see https://github.com/pinojs/pino/blob/master/docs/api.md#discussion-2
+for how to set child-bound serializers).
+
+Unlike server pino the serializers apply to every object passed to the logger method,
+if the `asObject` option is `true`, this results in the serializers applying to the
+first object (as in server pino).
+
+For more info on serializers see https://github.com/pinojs/pino/blob/master/docs/api.md#mergingobject.
+
+### `transmit` (Object)
+
+An object with `send` and `level` properties.
+
+The `transmit.level` property specifies the minimum level (inclusive) of when the `send` function
+should be called, if not supplied the `send` function be called based on the main logging `level`
+(set via `options.level`, defaulting to `info`).
+
+The `transmit` object must have a `send` function which will be called after
+writing the log message. The `send` function is passed the level of the log
+message and a `logEvent` object.
+
+The `logEvent` object is a data structure representing a log message, it represents
+the arguments passed to a logger statement, the level
+at which they were logged, and the hierarchy of child bindings.
+
+The `logEvent` format is structured like so:
+
+```js
+{
+  ts = Number,
+  messages = Array,
+  bindings = Array,
+  level: { label = String, value = Number}
+}
+```
+
+The `ts` property is a Unix epoch timestamp in milliseconds, the time is taken from the moment the
+logger method is called.
+
+The `messages` array is all arguments passed to logger method, (for instance `logger.info('a', 'b', 'c')`
+would result in `messages` array `['a', 'b', 'c']`).
+
+The `bindings` array represents each child logger (if any), and the relevant bindings.
+For instance, given `logger.child({a: 1}).child({b: 2}).info({c: 3})`, the bindings array
+would hold `[{a: 1}, {b: 2}]` and the `messages` array would be `[{c: 3}]`. The `bindings`
+are ordered according to their position in the child logger hierarchy, with the lowest index
+being the top of the hierarchy.
+
+By default, serializers are not applied to log output in the browser, but they will *always* be
+applied to `messages` and `bindings` in the `logEvent` object. This allows us to ensure a consistent
+format for all values between server and client.
+
+The `level` holds the label (for instance `info`), and the corresponding numerical value
+(for instance `30`). This could be important in cases where client-side level values and
+labels differ from server-side.
+
+The point of the `send` function is to remotely record log messages:
+
+```js
+const pino = require('pino')({
+  browser: {
+    transmit: {
+      level: 'warn',
+      send: function (level, logEvent) {
+        if (level === 'warn') {
+          // maybe send the logEvent to a separate endpoint
+          // or maybe analyze the messages further before sending
+        }
+        // we could also use the `logEvent.level.value` property to determine
+        // numerical value
+        if (logEvent.level.value >= 50) { // covers error and fatal
+
+          // send the logEvent somewhere
+        }
+      }
+    }
+  }
+})
+```
+
+### `disabled` (Boolean)
+
+```js
+const pino = require('pino')({browser: {disabled: true}})
+```
+
+The `disabled` option will disable logging in browser if set
+to `true`, by default it is set to `false`.

package/docs/bundling.md

@@ -0,0 +1,40 @@
+# Bundling
+
+Due to its internal architecture based on Worker Threads, it is not possible to bundle Pino *without* generating additional files.
+
+In particular, a bundler must ensure that the following files are also bundled separately:
+
+* `lib/worker.js` from the `thread-stream` dependency
+* `file.js`
+* `lib/worker.js`
+* Any transport used by the user (like `pino-pretty`)
+
+Once the files above have been generated, the bundler must also add information about the files above by injecting a code that sets `__bundlerPathsOverrides` in the `globalThis` object.
+
+The variable is an object whose keys are an identifier for the files and the values are the paths of files relative to the currently bundle files.
+
+Example:
+
+```javascript
+// Inject this using your bundle plugin
+globalThis.__bundlerPathsOverrides = {
+  'thread-stream-worker': pinoWebpackAbsolutePath('./thread-stream-worker.js')
+  'pino/file': pinoWebpackAbsolutePath('./pino-file.js'),
+  'pino-worker': pinoWebpackAbsolutePath('./pino-worker.js'),
+  'pino-pretty': pinoWebpackAbsolutePath('./pino-pretty.js'),
+};
+```
+
+Note that `pino/file`, `pino-worker` and `thread-stream-worker` are required identifiers. Other identifiers are possible based on the user configuration.
+
+## Webpack Plugin
+
+If you are a Webpack user, you can achieve this with [pino-webpack-plugin](https://github.com/pinojs/pino-webpack-plugin) without manual configuration of `__bundlerPathsOverrides`; however, you still need to configure it manually if you are using other bundlers.
+
+## Esbuild Plugin
+
+[esbuild-plugin-pino](https://github.com/davipon/esbuild-plugin-pino) is the esbuild plugin to generate extra pino files for bundling.
+
+## Bun Plugin
+
+[bun-plugin-pino](https://github.com/vktrl/bun-plugin-pino) is the Bun plugin to generate extra pino files for bundling.

package/docs/child-loggers.md

@@ -0,0 +1,95 @@
+# Child loggers
+
+Let's assume we want to have `"module":"foo"` added to every log within a
+module `foo.js`.
+
+To accomplish this, simply use a child logger:
+
+```js
+'use strict'
+// imports a pino logger instance of `require('pino')()`
+const parentLogger = require('./lib/logger')
+const log = parentLogger.child({module: 'foo'})
+
+function doSomething () {
+  log.info('doSomething invoked')
+}
+
+module.exports = {
+  doSomething
+}
+```
+
+## Cost of child logging
+
+Child logger creation is fast:
+
+```
+benchBunyanCreation*10000: 564.514ms
+benchBoleCreation*10000: 283.276ms
+benchPinoCreation*10000: 258.745ms
+benchPinoExtremeCreation*10000: 150.506ms
+```
+
+Logging through a child logger has little performance penalty:
+
+```
+benchBunyanChild*10000: 556.275ms
+benchBoleChild*10000: 288.124ms
+benchPinoChild*10000: 231.695ms
+benchPinoExtremeChild*10000: 122.117ms
+```
+
+Logging via the child logger of a child logger also has negligible overhead:
+
+```
+benchBunyanChildChild*10000: 559.082ms
+benchPinoChildChild*10000: 229.264ms
+benchPinoExtremeChildChild*10000: 127.753ms
+```
+
+## Duplicate keys caveat
+
+Naming conflicts can arise between child loggers and
+children of child loggers.
+
+This isn't as bad as it sounds, even if the same keys between
+parent and child loggers are used, Pino resolves the conflict in the sanest way.
+
+For example, consider the following:
+
+```js
+const pino = require('pino')
+pino(pino.destination('./my-log'))
+  .child({a: 'property'})
+  .child({a: 'prop'})
+  .info('howdy')
+```
+
+```sh
+$ cat my-log
+{"pid":95469,"hostname":"MacBook-Pro-3.home","level":30,"msg":"howdy","time":1459534114473,"a":"property","a":"prop"}
+```
+
+Notice how there are two keys named `a` in the JSON output. The sub-child's properties
+appear after the parent child properties.
+
+At some point, the logs will most likely be processed (for instance with a [transport](transports.md)),
+and this generally involves parsing. `JSON.parse` will return an object where the conflicting
+namespace holds the final value assigned to it:
+
+```sh
+$ cat my-log | node -e "process.stdin.once('data', (line) => console.log(JSON.stringify(JSON.parse(line))))"
+{"pid":95469,"hostname":"MacBook-Pro-3.home","level":30,"msg":"howdy","time":"2016-04-01T18:08:34.473Z","a":"prop"}
+```
+
+Ultimately the conflict is resolved by taking the last value, which aligns with Bunyan's child logging
+behavior.
+
+There may be cases where this edge case becomes problematic if a JSON parser with alternative behavior
+is used to process the logs. It's recommended to be conscious of namespace conflicts with child loggers,
+in light of an expected log processing approach.
+
+One of Pino's performance tricks is to avoid building objects and stringifying
+them, so we're building strings instead. This is why duplicate keys between
+parents and children will end up in the log output.

package/docs/ecosystem.md

@@ -0,0 +1,84 @@
+# Pino Ecosystem
+
+This is a list of ecosystem modules that integrate with `pino`.
+
+Modules listed under [Core](#core) are maintained by the Pino team. Modules
+listed under [Community](#community) are maintained by independent community
+members.
+
+Please send a PR to add new modules!
+
+<a id="core"></a>
+## Core
+
+### Frameworks
++ [`express-pino-logger`](https://github.com/pinojs/express-pino-logger): use
+Pino to log requests within [express](https://expressjs.com/).
++ [`koa-pino-logger`](https://github.com/pinojs/koa-pino-logger): use Pino to
+log requests within [Koa](https://koajs.com/).
++ [`restify-pino-logger`](https://github.com/pinojs/restify-pino-logger): use
+Pino to log requests within [restify](http://restify.com/).
++ [`rill-pino-logger`](https://github.com/pinojs/rill-pino-logger): use Pino as
+the logger for the [Rill framework](https://rill.site/).
+
+### Utilities
++ [`pino-arborsculpture`](https://github.com/pinojs/pino-arborsculpture): change
+log levels at runtime.
++ [`pino-caller`](https://github.com/pinojs/pino-caller): add callsite to the log line.
++ [`pino-clf`](https://github.com/pinojs/pino-clf): reformat Pino logs into
+Common Log Format.
++ [`pino-debug`](https://github.com/pinojs/pino-debug): use Pino to interpret
+[`debug`](https://npm.im/debug) logs.
++ [`pino-elasticsearch`](https://github.com/pinojs/pino-elasticsearch): send
+Pino logs to an Elasticsearch instance.
++ [`pino-eventhub`](https://github.com/pinojs/pino-eventhub): send Pino logs
+to an [Event Hub](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-what-is-event-hubs).
++ [`pino-filter`](https://github.com/pinojs/pino-filter): filter Pino logs in
+the same fashion as the [`debug`](https://npm.im/debug) module.
++ [`pino-gelf`](https://github.com/pinojs/pino-gelf): reformat Pino logs into
+GELF format for Graylog.
++ [`pino-hapi`](https://github.com/pinojs/hapi-pino): use Pino as the logger
+for [Hapi](https://hapijs.com/).
++ [`pino-http`](https://github.com/pinojs/pino-http): easily use Pino to log
+requests with the core `http` module.
++ [`pino-http-print`](https://github.com/pinojs/pino-http-print): reformat Pino
+logs into traditional [HTTPD](https://httpd.apache.org/) style request logs.
++ [`pino-mongodb`](https://github.com/pinojs/pino-mongodb): store Pino logs
+in a MongoDB database.
++ [`pino-multi-stream`](https://github.com/pinojs/pino-multi-stream): send
+logs to multiple destination streams (slow!).
++ [`pino-noir`](https://github.com/pinojs/pino-noir): redact sensitive information
+in logs.
++ [`pino-pretty`](https://github.com/pinojs/pino-pretty): basic prettifier to
+make log lines human-readable.
++ [`pino-socket`](https://github.com/pinojs/pino-socket): send logs to TCP or UDP
+destinations.
++ [`pino-std-serializers`](https://github.com/pinojs/pino-std-serializers): the
+core object serializers used within Pino.
++ [`pino-syslog`](https://github.com/pinojs/pino-syslog): reformat Pino logs
+to standard syslog format.
++ [`pino-tee`](https://github.com/pinojs/pino-tee): pipe Pino logs into files
+based upon log levels.
++ [`pino-test`](https://github.com/pinojs/pino-test): a set of utilities for 
+verifying logs generated by the Pino logger.
++ [`pino-toke`](https://github.com/pinojs/pino-toke): reformat Pino logs
+according to a given format string.
+
+
+<a id="community"></a>
+## Community
+
++ [`@google-cloud/pino-logging-gcp-config`](https://www.npmjs.com/package/@google-cloud/pino-logging-gcp-config): Config helper and formatter to output [Google Cloud Platform Structured Logging](https://cloud.google.com/logging/docs/structured-logging)
++ [`@newrelic/pino-enricher`](https://github.com/newrelic/newrelic-node-log-extensions/blob/main/packages/pino-log-enricher): a log customization to add New Relic context to use [Logs In Context](https://docs.newrelic.com/docs/logs/logs-context/logs-in-context/)
++ [`cloud-pine`](https://github.com/metcoder95/cloud-pine): transport that provides abstraction and compatibility with [`@google-cloud/logging`](https://www.npmjs.com/package/@google-cloud/logging).
++ [`cls-proxify`](https://github.com/keenondrums/cls-proxify): integration of pino and [CLS](https://github.com/jeff-lewis/cls-hooked). Useful for creating dynamically configured child loggers (e.g. with added trace ID) for each request.
++ [`crawlee-pino`](https://github.com/imyelo/crawlee-pino): use Pino to log within Crawlee
++ [`pino-colada`](https://github.com/lrlna/pino-colada): cute ndjson formatter for pino.
++ [`pino-dev`](https://github.com/dnjstrom/pino-dev): simple prettifier for pino with built-in support for common ecosystem packages.
++ [`pino-fluentd`](https://github.com/davidedantonio/pino-fluentd): send Pino logs to Elasticsearch,
+MongoDB, and many [others](https://www.fluentd.org/dataoutputs) via Fluentd.
++ [`pino-lambda`](https://github.com/FormidableLabs/pino-lambda): log transport for cloudwatch support inside aws-lambda 
++ [`pino-pretty-min`](https://github.com/unjello/pino-pretty-min): a minimal
+prettifier inspired by the [logrus](https://github.com/sirupsen/logrus) logger.
++ [`pino-rotating-file`](https://github.com/homeaway/pino-rotating-file): a hapi-pino log transport for splitting logs into separate, automatically rotating files.
++ [`pino-tiny`](https://github.com/holmok/pino-tiny): a tiny (and extensible?) little log formatter for pino.