@wbce/projen-d9 0.0.28 → 0.1.0

package/node_modules/pino/docs/asynchronous.md

@@ -0,0 +1,55 @@
+# 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 in AWS Lambda functions will tend to cause delayed
+or lost log messages, as logs may not be written to the destination
+before the runtime is frozen.
+
+For Lambda deployments, it's recommended to always use a destination
+with `sync: true`.
+
+## 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.
+
+### Flush Limitations with `pino-pretty`
+
+`logger.flush()` does not flush the output of `pino-pretty` because:
+
+1. **Transport Architecture**: `pino-pretty` runs in a separate worker thread via the transport mechanism.
+
+2. **Cross-Thread Flush**: `logger.flush(cb)` does reach the worker. Since [thread-stream#198](https://github.com/pinojs/thread-stream/pull/198) the worker waits for the shared buffer to be drained, then looks for a flush primitive on the destination the transport returned: `flush`, `flushSync`, or a pending `drain`.
+
+3. **No Flush Primitive**: The stream `pino-pretty` returns exposes none of those. Its buffered `SonicBoom` is reachable only through the internal `pump`, so the worker has nothing to call and acknowledges the flush right away.
+
+This means that even with `logger.flush()`, your formatted logs may not appear immediately. The flush only guarantees that the main thread buffer was written and that the worker drained the shared buffer, not that `pino-pretty` has written its formatted output.
+
+See also:
+
+* [`pino.destination` API](/docs/api.md#pino-destination)
+* [`destination` parameter](/docs/api.md#destination)

package/node_modules/pino/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/node_modules/pino/docs/browser.md

@@ -0,0 +1,341 @@
+# 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.
+
+<a id="nodejs-only-apis"></a>
+## Node.js-only APIs
+
+The browser build (`browser.js`, selected through the `browser` field in
+`package.json`) does not implement the parts of the API that depend on the file
+system or on worker threads. Accessing them in the browser throws a
+`TypeError`, because the export is simply absent:
+
+```js
+const pino = require('pino')
+pino.destination('./my-file') // TypeError: pino.destination is not a function
+```
+
+The following statics are available in Node.js only:
+
+| Static | Why it is Node.js only |
+| --- | --- |
+| [`pino.destination()`](/docs/api.md#pino-destination) | Returns a [`SonicBoom`](https://github.com/pinojs/sonic-boom) instance writing to a file descriptor. |
+| [`pino.transport()`](/docs/api.md#pino-transport) | Runs a [transport](/docs/transports.md) on a worker thread. |
+| [`pino.multistream()`](/docs/api.md#pino-multistream) | Fans out to multiple destination streams. |
+
+`pino.levels`, `pino.stdSerializers` and `pino.stdTimeFunctions` are available in
+both environments.
+
+### Methods that are no-ops in the browser
+
+These exist on a browser logger, so calling them is safe, but they do nothing:
+
+* [`logger.flush([cb])`](/docs/api.md#flush) — there is no write buffer
+  to flush. Note that a callback passed to it is **not** invoked.
+* Every `EventEmitter` method (`on`, `once`, `emit`, `removeListener`,
+  `listeners`, ...). As a consequence the
+  [`level-change`](/docs/api.md#level-change) event never fires in the
+  browser.
+
+### Writing isomorphic code
+
+Code shared between a server and a browser bundle should not call the Node.js
+only statics unconditionally. Guard the call rather than the environment, so the
+same branch works under any bundler:
+
+```js
+const pino = require('pino')
+
+const logger = pino.destination
+  ? pino(pino.destination('./my-file')) // Node.js
+  : pino({ browser: { asObject: true } }) // browser
+```
+
+Note that the browser build's `pino()` accepts the options object only. A second
+`destination` argument is accepted but ignored, so a logger constructed with one
+still writes to the console rather than failing:
+
+```js
+// in the browser the second argument is ignored, not honoured
+const logger = pino({ level: 'info' }, someDestination)
+logger.info('still goes to the console')
+```
+
+Assigning a no-op shim onto the `pino` export (`pino.destination = () => {}`)
+works too, but it mutates a module object shared with every other importer in the
+bundle; guarding the call site keeps the change local.
+
+## 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`.
+
+### `asObjectBindingsOnly` (Boolean)
+
+```js
+const pino = require('pino')({browser: {asObjectBindingsOnly: true}})
+```
+
+The `asObjectBindingsOnly` option is similar to `asObject` but will keep the message
+and arguments unformatted. This allows to defer formatting the message to the
+actual call to `console` methods, where browsers then have richer formatting in
+their devtools than when pino will format the message to a string first.
+
+```js
+pino.info('hello %s', 'world') // creates and logs {level: 30, time: <ts>}, 'hello %s', 'world'
+```
+
+### `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 }
+  }
+}
+```
+
+
+### `reportCaller` (Boolean)
+
+Attempts to capture and include the originating callsite (file:line:column) for each log call in the browser logger.
+
+- When used together with `asObject` (or when `formatters` are provided), the callsite is added as a `caller` string property on the emitted log object.
+- In the default mode (non‑object), the callsite string is appended as the last argument passed to the corresponding `console` method. This makes the location visible in the console output even though the console’s clickable header still points to Pino internals.
+
+```js
+// Object mode: adds `caller` to the log object
+const pino = require('pino')({
+  browser: {
+    asObject: true,
+    reportCaller: true
+  }
+})
+
+pino.info('hello')
+// -> { level: 30, msg: 'hello', time: <ts>, caller: '/path/to/file.js:10:15' }
+
+// Default mode: appends the caller string as the last console argument
+const pino2 = require('pino')({
+  browser: {
+    reportCaller: true
+  }
+})
+
+pino2.info('hello')
+// -> console receives: 'hello', '/path/to/file.js:10:15'
+```
+
+Notes:
+
+- This is a best‑effort feature that parses the JavaScript Error stack. Stack formats vary across engines.
+- The clickable link shown by devtools for a console message is determined by where `console.*` is invoked and cannot be changed by libraries; `reportCaller` surfaces the user callsite alongside the log message.
+
+
+### `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/node_modules/pino/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/node_modules/pino/docs/child-loggers.md

@@ -0,0 +1,116 @@
+# 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
+}
+```
+
+Child logger bindings are top-level fields on every log line emitted by the
+child logger. Do not create child loggers from externally supplied objects or
+user-controlled binding names, because those keys can conflict with Pino fields
+such as `level`, `time`, or `msg`, as well as application or security fields.
+If untrusted data must be associated with logs, place it under an
+application-controlled key:
+
+```js
+// Avoid: user-controlled keys become top-level fields on every child log line
+const child = logger.child(untrustedObject)
+
+// Prefer: user-controlled keys are contained under a trusted namespace
+const child = logger.child({ untrusted: untrustedObject })
+```
+
+As a matter of good security hygiene, prefer not to log untrusted data at all
+unless it is necessary. When it is necessary, sanitize and redact it first.
+See also [`logger.child()` in the API documentation](/docs/api.md#child) and
+[`mergingObject`](/docs/api.md#mergingobject).
+
+## 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. This is especially important for untrusted data: do not
+allow externally supplied objects or user-controlled key names to become child logger bindings.
+
+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/node_modules/pino/docs/diagnostics.md

@@ -0,0 +1,16 @@
+# Diagnostics
+
+Pino provides [tracing channel](tc) events that allow insight into the
+internal workings of the library. The currently supported events are:
+
++ `tracing:pino_asJson:start`: emitted when the final serialization process
+  of logs is started. The emitted event payload has the following fields:
+  - `instance`: the Pino instance associated with the function
+  - `arguments`: the arguments passed to the function
++ `tracing:pino_asJson:end`: emitted at the end of the final serialization
+  process. The emitted event payload has the following fields:
+  - `instance`: the Pino instance associated with the function
+  - `arguments`: the arguments passed to the function
+  - `result`: the finalized, newline delimited, log line as a string
+
+[tc]: https://nodejs.org/docs/latest/api/diagnostics_channel.html#tracingchannel-channels