lib: implement node:logger

A simpler attempt to add a structured logging API.

Uses a provider model similar to VFS.

This implements two providers out of the box,
ConsoleProvider and ReadableProvider. ConsoleProvider
is the default and uses Utf8Stream to emit to either
stdout or stderr.

```js
const { create } = require('node:logger');
const logger = create(); // default logger to console
logger.info('foo');

// ...
const als = new AsyncLocalStorage();
const logger2 = create(new ConsoleProvider({ pid: true }), {
  name: 'foo',
  bindings: {
    'abc': 'included in every log line',
    'xyz': als,  // current als.getStore() included in
                 // every log line
  }
});
logger2.info('foo', { baz: 1 });
```

The `Logger` keeps things as simple as possible, leaving
actual handling of the log events to the providers, which
can be fully customized. Easy to adapt to other loggers
like pino or extend capabilities without directly touching
the facade.

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode

Author: jasnell

doc/api/cli.md

@@ -1545,6 +1545,16 @@ Specify the `module` containing exported [asynchronous module customization hook
 
 This feature requires `--allow-worker` if used with the [Permission Model][].
 
+### `--experimental-logger`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active development
+
+Enable the experimental [`node:logger`][] module.
+
 ### `--experimental-network-inspection`
 
 <!-- YAML
@@ -4276,6 +4286,7 @@ one is included in the list below.
 * `--experimental-import-text`
 * `--experimental-json-modules`
 * `--experimental-loader`
+* `--experimental-logger`
 * `--experimental-modules`
 * `--experimental-package-map`
 * `--experimental-print-required-tla`
@@ -4961,6 +4972,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`inspector.open()`]: inspector.md#inspectoropenport-host-wait
 [`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
 [`node:ffi`]: ffi.md
+[`node:logger`]: logger.md
 [`node:sqlite`]: sqlite.md
 [`node:stream/iter`]: stream_iter.md
 [`node:vfs`]: vfs.md

doc/api/fs.md

@@ -8563,12 +8563,13 @@ Close the stream gracefully, flushing the internal buffer before closing.
 * `callback` {Function}
   * `err` {Error|null} An error if the flush failed, otherwise `null`.
 
-Writes the current buffer to the file if a write was not in progress. Do
-nothing if `minLength` is zero or if it is already writing.
+Writes the current buffer to the file. The callback is invoked after pending
+writes complete.
 
 #### `utf8Stream.flushSync()`
 
-Flushes the buffered data synchronously. This is a costly operation.
+Flushes the buffered data synchronously. This is a costly operation. An
+`ERR_INVALID_STATE` error is thrown if the stream is currently writing.
 
 #### `utf8Stream.fsync`
 

doc/api/index.md

@@ -36,6 +36,7 @@
 * [Inspector](inspector.md)
 * [Internationalization](intl.md)
 * [Iterable Streams API](stream_iter.md)
+* [Logger](logger.md)
 * [Modules: CommonJS modules](modules.md)
 * [Modules: ECMAScript modules](esm.md)
 * [Modules: `node:module` API](module.md)