✅✨👍 [PRE-RELEASE] winston@3.2.0 (#1576)

* Initial changelog for 3.2.0 * [doc] CHANGELOG.md through November 2018. * [doc] Entire CHANGELOG.md * [doc] Update Roadmap. * [dist] Regenerate package-lock.json with latest. * [doc] Add examples/quick-start.js and document it in `README.md` * [doc] Update README.md * [tiny doc] Correct order in TOC. * [doc] Tighten up CHANGELOG.md * [doc] Add note about 3.2.0 board.
winstonjs · Jan 26, 2019 · 78b745d · klakovsky · Jan 29, 2019 · 78b745d
1 parent a910c28
commit 78b745d
Show file tree

Hide file tree

Showing 5 changed files with 558 additions and 173 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,118 @@
 # CHANGELOG
 
+## v3.2.0 / 2018-01-26
+### SORRY IT TOO SO LONG EDITION
+
+> **NOTE:** this was our first release using Github Projects. See the
+> [3.2.0 Release Project](https://github.com/orgs/winstonjs/projects/3).
+
+### New Features!
+
+- [#1471], (@kibertoad) Implement child loggers.
+- [#1462], (@drazisil) Add handleRejection support.
+  - [#1555], (@DABH) Add fixes from [#1355] to unhandled rejection handler.
+- [#1418], (@mfrisbey) Precompile ES6 syntax before publishing to npm.
+  - [#1533], (@kibertoad) Update to Babel 7.
+- [#1562], (@indexzero) [fix] Better handling of `new Error(string)`
+  throughout the pipeline(s). (Fixes [#1338], [#1486]). 
+
+### Bug Fixes
+
+- [#1355], (@DABH) Fix issues with ExceptionHandler (Fixes [#1289]).
+- [#1463], (@SerayaEryn) Bubble transport `warn` events up to logger in
+  addition to `error`s.
+- [#1480], [#1503], (@SerayaEryn) File tailrolling fix.
+- [#1483], (@soldair) Assign log levels to un-bound functions.
+- [#1513], (@TilaTheHun0) Set maxListeners for Console transport.
+- [#1521], (@jamesbechet) Fix Transform from `readable-stream` using CRA.
+- [#1434], (@Kouzukii) Fixes logger.query function (regression from `3.0.0`)
+- [#1526], (@pixtron) Log file without .gz for tailable (Fixes [#1525]).
+- [#1559], (@eubnara) Fix typo related to `exitOnError`. 
+- [#1556], (@adoyle-h) Support to create log directory if it doesn't exist
+  for FileTransport.
+
+#### New `splat` behavior
+
+- [#1552], (@indexzero) Consistent handling of meta with (and without) 
+  interpolation in `winston` and `logform`. 
+- [#1499], (@DABH) Provide all of `SPLAT` to formats (Fixes [#1485]).
+- [#1485], (@mpabst) Fixing off-by-one when using both meta and splat.
+
+Previously `splat` would have added a `meta` property for any additional
+`info[SPLAT]` beyond the expected number of tokens.
+
+**As of `logform@2.0.0`,** `format.splat` assumes additional splat paramters
+(aka "metas") are objects and merges enumerable properties into the `info`.
+e.g. **BE ADVISED** previous "metas" that _were not objects_ will very likely
+lead to odd behavior. e.g.
+
+``` js
+const { createLogger, format, transports } = require('winston');
+const { splat } = format;
+const { MESSAGE, LEVEL, SPLAT } = require('triple-beam');
+
+const logger = createLogger({
+  format: format.combine(
+    format.splat(),
+    format.json()
+  ),
+  transports: [new transports.Console()]
+});
+
+// Expects two tokens, but four splat parameters provided.
+logger.info(
+  'Let us %s for %j',   // message
+  'objects',           // used for %s
+  { label: 'sure' },   // used for %j
+  'lol', ['ok', 'why'] // Multiple additional meta values 
+);
+
+// winston < 3.2.0 && logform@1.x behavior:
+// Added "meta" property.
+//
+// { level: 'info',
+//   message: 'Let us objects for {"label":"sure"}',
+//   meta: ['lol', ['ok', 'why']],
+//   [Symbol(level)]: 'info',
+//   [Symbol(message)]: 'Let us %s for %j',
+//   [Symbol(splat)]: [ 'objects', { label: 'sure' } ] }
+
+// winston >= 3.2.0 && logform@2.x behavior: Enumerable properties
+// assigned into `info`. Since **strings and Arrays only have NUMERIC
+// enumerable properties we get this behavior!**
+//
+// { '0': 'ok',
+//   '1': 'why',
+//   '2': 'l',
+//   level: 'info',
+//   message: 'Let us objects for {"label":"sure"}',
+//   [Symbol(level)]: 'info',
+//   [Symbol(message)]: 'Let us %s for %j',
+//   [Symbol(splat)]: [ 'objects', { label: 'sure' } ] }
+```
+
+## Maintenance & Documentation
+
+- Documentation Updates
+  - [#1410], (@hakanostrom) Add docs reference to transport for Cloudant.
+  - [#1467], (@SeryaEryn) Add fast-file-rotate transport to transport.md.
+  - [#1488], (@adamcohen) Fix multi logger documentation.
+  - [#1531], (@mapleeit) Add links to transports.
+  - [#1548], (@ejmartin504) Fix `README.md` for awaiting logs.
+  - [#1554], (@indexzero) Document the solution to [#1486] as by design.
+  - Other small improvements: [#1509].
+- Improved TypeScript support
+  - [#1470], (@jd-carroll) Export all transport options (Fixes [#1469]).
+  - [#1474], (@jd-carroll) Correct import to avoid conflict (Fixed [#1472]).
+  - [#1546], (@alewiahmed) Add consoleWarnLevels field to the
+    `ConsoleTransportOptions` interface type definition.
+  - [#1557], (@negezor) Add missing `child()` method.
+- Dependency management
+  - [#1560], (@kibertoad) Update dependencies.
+  - [#1512], (@SerayaEryn) Add node@11 and disallow failures on node@10.
+  - [#1516], (@SerayaEryn) Update `readable-stream` to `v3.0.6`.
+  - [#1534], (@kibertoad) Update `@types/node`, `nyc`, and `through2`.
+
 ## v3.1.0 / 2018-08-22
 ### RELEASES ON A PLANE EDITION
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,7 +13,7 @@ Looking for somewhere to help? Checkout the [Roadmap](#roadmap) & help triage op
 
 ## What makes up `winston`?
 
-As of `winston@3.0.0` the project has been broken out into a few modules:
+As of `winston@3` the project has been broken out into a few modules:
 
 - [winston-transport]: `Transport` stream implementation & legacy `Transport` wrapper.
 - [logform]: All formats exports through `winston.format` 
@@ -35,8 +35,8 @@ const logger = createLogger({
   format: combine(
     label({ label: 'right meow!' }),
     timestamp(),
-    printf(nfo => {
-      return `${nfo.timestamp} [${nfo.label}] ${nfo.level}: ${nfo.message}`;
+    printf(({ level, message, lable, timestamp }) => {
+      return `${timestamp} [${label}] ${level}: ${message}`;
     })
   ),
   transports: [new transports.Console()]
@@ -69,22 +69,24 @@ This can be accomplished with using [custom formats](https://github.com/winstonj
 
 Below is the list of items that make up the roadmap through `3.4.0`. We are actively triaging the open issues, so it is likely a few more critical path items will be added to this list before the next release goes out.
 
-- [Version 3.2.0](#version-320)
-- [Version 3.3.0](#version-330)
-- [Version 3.4.0](#version-340)
+- [Version 3.3.0](#version-320)
+- [Version 3.4.0](#version-330)
+- [Version 3.5.0](#version-340)
 
 ## Legend
 
 - [ ] Unstarted work.
 - [x] Finished work.
 - [-] Partially finished or in-progress work. 
 
-## Version `3.2.0`
+## Version `3.3.0`
 
 ### High priority issues (non-blocking)
+- [ ] Move `File` transport into `winston-file`.
 - [Browser support](https://github.com/winstonjs/winston/issues/287)
   - [ ] Unit tests for `webpack` & `rollup` 
   - [ ] Replicate browser-only transpilation for `winston`, `winston-transport`, `triple-beam`.
+- [-] Full JSDoc coverage
 - Benchmarking for `File` and `Stream` transports:
    - [x] Benchmarking integration in `pino`.
    - [x] Upgrade `pino` to latest `winston`.
@@ -95,23 +97,23 @@ Below is the list of items that make up the roadmap through `3.4.0`. We are acti
 ### Increased code & scenario coverage
 - [-] Replace all `vows`-based tests.
   - [-] `test/transports/*-test.js` 
-- [ ] Code coverage tests above 80% for `winston` _(currently `~72%`)_.
+- [ ] Code coverage tests above 80% for `winston` _(currently `~70%`)_.
   - [-] Core scenarios covered in `abstract-winston-transport`.
+  - [-] Full integration tests for all `logform` transports
 
 ### Communications / Compatibility
 - [ ] `README.md` for `winston-compat`.
-- [ ] All formats documented in `logform`.
-- [ ] All existing transports documented in `docs/transports.md`.
+- [ ] Update all transports documented in `docs/transports.md` for `winston@3`.
 
-## Version `3.3.0`
+## Version `3.4.0`
 
 ### Querying, Streaming, Uncaught Exceptions
 - [-] Streaming
 
 ### Communications / Compatibility
 - [ ] `winstonjs.org` documentation site.
 
-## Version `3.4.0`
+## Version `3.5.0`
 
 ### Querying, Streaming, Uncaught Exceptions
 - [-] Querying

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ A logger for just about everything.
 
 [![Join the chat at https://gitter.im/winstonjs/winston](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/winstonjs/winston?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-## winston@3.0.0
+## winston@3.2.0
 
 See the [Upgrade Guide](UPGRADE-3.0.md) for more information. Bug reports and
 PRs welcome!
@@ -34,6 +34,13 @@ ensuring those APIs decoupled from the implementation of transport logging
 (i.e. how the logs are stored / indexed, see: [Adding Custom Transports]) to
 the API that they exposed to the programmer.
 
+## Quick Start
+
+TL;DR? Check out the [quick start example][quick-example] in `./examples/`. 
+There are a number of other examples in [`./examples/*.js`][examples].
+Don't see an example you think should be there? Submit a pull request
+to add it!
+
 ## Usage
 
 The recommended way to use `winston` is to create your own logger. The
@@ -43,7 +50,7 @@ simplest way to do this is using `winston.createLogger`:
 const logger = winston.createLogger({
   level: 'info',
   format: winston.format.json(),
-  defaultMeta: {service: 'user-service'},
+  defaultMeta: { service: 'user-service' },
   transports: [
     //
     // - Write to all logs with level `info` and below to `combined.log` 
@@ -71,6 +78,10 @@ logger to use throughout your application if you so choose.
 
 ## Table of contents
 
+* [Motivation](#motivation)
+* [Quick Start](#quick-start)
+* [Usage](#usage)
+* [Table of Contents](#table-of-contents)
 * [Logging](#logging)
   * [Creating your logger](#creating-your-own-logger)
   * [Streams, `objectMode`, and `info` objects](#streams-objectmode-and-info-objects)
@@ -129,14 +140,14 @@ const logger = winston.createLogger({
 
 A logger accepts the following parameters:
 
-| Name          | Default                |  Description    |
-| ------------- | ---------------------- | --------------- |
-| `level`       | `'info'`               | Log only if [`info.level`](#streams-objectmode-and-info-objects) less than or equal to this level  |  
-| `levels`      | `winston.config.npm.levels`   | Levels (and colors) representing log priorities            |
-| `format`      | `winston.format.json`  | Formatting for `info` messages  (see: [Formats])           |
-| `transports`  | `[]` _(No transports)_ | Set of logging targets for `info` messages                 |
-| `exitOnError` | `true`                 | If false, handled exceptions will not cause `process.exit` |
-| `silent`      | `false`                | If true, all logs are suppressed |
+| Name          | Default                     |  Description    |
+| ------------- | --------------------------- | --------------- |
+| `level`       | `'info'`                    | Log only if [`info.level`](#streams-objectmode-and-info-objects) less than or equal to this level  |  
+| `levels`      | `winston.config.npm.levels` | Levels (and colors) representing log priorities            |
+| `format`      | `winston.format.json`       | Formatting for `info` messages  (see: [Formats])           |
+| `transports`  | `[]` _(No transports)_      | Set of logging targets for `info` messages                 |
+| `exitOnError` | `true`                      | If false, handled exceptions will not cause `process.exit` |
+| `silent`      | `false`                     | If true, all logs are suppressed |
 
 The levels provided to `createLogger` will be defined as convenience methods
 on the `logger` returned. 
@@ -210,30 +221,63 @@ const childLogger = logger.child({ requestId: '451' });
 
 In `winston`, both `Logger` and `Transport` instances are treated as
 [`objectMode`](https://nodejs.org/api/stream.html#stream_object_mode)
-streams that accept an `info` object. The `info` object represents a
-single log message. The object itself is mutable. Every `info` must
-have at least the `level` and `message` properties:
+streams that accept an `info` object. 
+
+The `info` parameter provided to a given format represents a single log
+message. The object itself is mutable. Every `info` must have at least the
+`level` and `message` properties:
 
 ``` js
-{
+const info = {
   level: 'info',                 // Level of the logging message  
   message: 'Hey! Log something?' // Descriptive message being logged.
-}
+};
+```
+
+Properties **besides level and message** are considered as "`meta`". i.e.:
+
+``` js
+const { level, message, ...meta } = info;
 ```
 
-`winston.format` itself exposes several additional properties:
+Several of the formats in `logform` itself add additional properties:
 
-- `splat`: string interpolation splat for `%d %s`-style messages.
-- `timestamp`: timestamp the message was received.
-- `label`: custom label associated with each message.
+| Property    | Format added by | Description |
+| ----------- | --------------- | ----------- | 
+| `splat`     | `splat()`       | String interpolation splat for `%d %s`-style messages. |
+| `timestamp` | `timestamp()`   |  timestamp the message was received. |
+| `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
 maintained by `Symbol` properties:_
 
-- `Symbol.for('level')` _**(READ-ONLY)**:_ equal to `level` property. Is 
-treated as immutable by all code.  
-- `Symbol.for('message'):` complete string message set by "finalizing 
-formats": `json`, `logstash`, `printf`, `prettyPrint`, and `simple`. 
+- `Symbol.for('level')` _**(READ-ONLY)**:_ equal to `level` property.
+  **Is treated as immutable by all code.**
+- `Symbol.for('message'):` complete string message set by "finalizing formats":
+  - `json`
+  - `logstash`
+  - `printf`
+  - `prettyPrint`
+  - `simple`
+- `Symbol.for('splat')`: additional string interpolation arguments. _Used
+  exclusively by `splat()` format._
+
+These Symbols are stored in another package: `triple-beam` so that all
+consumers of `logform` can have the same Symbol reference. i.e.:
+
+``` js
+const { LEVEL, MESSAGE, SPLAT } = require('triple-beam');
+
+console.log(LEVEL === Symbol.for('level'));
+// true
+
+console.log(MESSAGE === Symbol.for('message'));
+// true
+
+console.log(SPLAT === Symbol.for('splat'));
+// true
+```
 
 > **NOTE:** any `{ message }` property in a `meta` object provided will
 > automatically be concatenated to any `msg` already provided: For 
@@ -259,8 +303,8 @@ format your logs, `winston.format.printf` is for you:
 const { createLogger, format, transports } = require('winston');
 const { combine, timestamp, label, printf } = format;
 
-const myFormat = printf(info => {
-  return `${info.timestamp} [${info.label}] ${info.level}: ${info.message}`;
+const myFormat = printf(({ level, message, label, timestamp }) => {
+  return `${timestamp} [${label}] ${level}: ${message}`;
 });
 
 const logger = createLogger({
@@ -274,8 +318,7 @@ const logger = createLogger({
 ```
 
 To see what built-in formats are available and learn more about creating your
-own custom logging formats, see
-[`logform`](https://github.com/winstonjs/logform).
+own custom logging formats, see [`logform`][logform].
 
 ### Combining formats
 
@@ -310,7 +353,7 @@ logger.log({
 ### String interpolation
 
 The `log` method provides the string interpolation using [util.format]. **It
-must be enabled using `format.splat`.**
+must be enabled using `format.splat()`.**
 
 Below is an example that defines a format with string interpolation of
 messages using `format.splat` and then serializes the entire `info` message
@@ -1088,9 +1131,13 @@ npm test
 [mocha]: https://mochajs.org
 [nyc]: https://github.com/istanbuljs/nyc
 [assume]: https://github.com/bigpipe/assume
+[logform]: https://github.com/winstonjs/logform#readme
 
 [Read the `winston@2.x` documentation]: https://github.com/winstonjs/winston/tree/2.x 
 
+[quick-example]: https://github.com/winstonjs/winston/blob/master/examples/quick-start.js
+[examples]: https://github.com/winstonjs/winston/tree/master/examples
+
 [Charlie Robbins]: http://github.com/indexzero
 [Jarrett Cruger]: https://github.com/jcrugzz
 [David Hyde]: https://github.com/dabh