From b2b79af23999052c171b914710a5001cba4d9590 Mon Sep 17 00:00:00 2001
From: Neil Enns <neile@live.com>
Date: Wed, 7 Aug 2024 20:55:15 -0700
Subject: [PATCH] Update readme with forceConsole info (#2493)

* Update readme with forceConsole info

* Fix TOC rewrite. Oops.

* Argh. Fix TOC again.

* Address PR feedback
---
 README.md | 34 +++++++++++++++++++++++++++-------
 1 file changed, 27 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 081315a00..0dc9bb6cc 100644
--- a/README.md
+++ b/README.md
@@ -115,6 +115,7 @@ transports may produce a high memory usage issue.
   * [Using the default logger](#using-the-default-logger)
   * [Awaiting logs to be written in `winston`](#awaiting-logs-to-be-written-in-winston)
   * [Working with multiple Loggers in `winston`](#working-with-multiple-loggers-in-winston)
+  * [Routing Console transport messages to the console instead of stdout and stderr](#routing-console-transport-messages-to-the-console-instead-of-stdout-and-stderr)
 * [Installation](#installation)
 * [Run Tests](#run-tests)
 
@@ -148,7 +149,7 @@ const logger = winston.createLogger({
 });
 ```
 
-A logger accepts the following parameters:
+A logger accepts the following parameters:
 
 | Name          | Default                     |  Description    |
 | ------------- | --------------------------- | --------------- |
@@ -260,7 +261,7 @@ Several of the formats in `logform` itself add additional properties:
 | `label`     | `label()`       | Custom label associated with each message. |
 | `ms`        | `ms()`          | Number of milliseconds since the previous log message. |
 
-As a consumer you may add whatever properties you wish – _internal state is
+As a consumer you may add whatever properties you wish – _internal state is
 maintained by `Symbol` properties:_
 
 - `Symbol.for('level')` _**(READ-ONLY)**:_ equal to `level` property.
@@ -290,7 +291,7 @@ console.log(SPLAT === Symbol.for('splat'));
 // true
 ```
 
-> **NOTE:** any `{ message }` property in a `meta` object provided will
+> **NOTE:** any `{ message }` property in a `meta` object provided will
 > automatically be concatenated to any `msg` already provided: For
 > example the below will concatenate 'world' onto 'hello':
 >
@@ -380,10 +381,10 @@ const logger = createLogger({
   transports: [new transports.Console()]
 });
 
-// info: test message my string {}
+// info: test message my string {}
 logger.log('info', 'test message %s', 'my string');
 
-// info: test message 123 {}
+// info: test message 123 {}
 logger.log('info', 'test message %d', 123);
 
 // info: test message first second {number: 123}
@@ -450,7 +451,7 @@ method: `transform(info, opts)` and return the mutated `info`:
 They are expected to return one of two things:
 
 - **An `info` Object** representing the modified `info` argument. Object
-references need not be preserved if immutability is preferred. All current
+references need not be preserved if immutability is preferred. All current
 built-in formats consider `info` mutable, but [immutablejs] is being
 considered for future releases.
 - **A falsey value** indicating that the `info` argument should be ignored by the
@@ -1198,6 +1199,25 @@ const category1 = container.get('category1');
 category1.info('logging to file and console transports');
 ```
 
+### Routing Console transport messages to the console instead of stdout and stderr
+
+By default the `winston.transports.Console` transport sends messages to `stdout` and `stderr`. This
+is fine in most situations; however, there are some cases where this isn't desirable, including:
+
+- Debugging using VSCode and attaching to, rather than launching, a Node.js process
+- Writing JSON format messages in AWS Lambda
+- Logging during Jest tests with the `--silent` option
+
+To make the transport log use `console.log()`, `console.warn()` and `console.error()`
+instead, set the `forceConsole` option to `true`:
+
+```js
+const logger = winston.createLogger({
+  level: 'info',
+  transports: [new winston.transports.Console({ forceConsole: true })]
+});
+```
+
 ## Installation
 
 ``` bash
@@ -1244,4 +1264,4 @@ npm test
 [Charlie Robbins]: http://github.com/indexzero
 [Jarrett Cruger]: https://github.com/jcrugzz
 [David Hyde]: https://github.com/dabh
-[Chris Alderson]: https://github.com/chrisalderson
+[Chris Alderson]: https://github.com/chrisalderson
\ No newline at end of file