Deprecate the changeLevelName option and alias it to levelKey (#772)

* deprecate the `changeLevelName` option and alias it to `levelKey`

* use process.emitWarning instead of console.warn for deprecation message

* avoid accessing private state in changeLevelName deprecation test

docs/api.md

@@ -254,14 +254,18 @@ Enables printing of level labels instead of level values in the printed logs.
 Warning: this option may not be supported by downstream transports.
 
 <a id="changeLevelName"></a>
-#### `changeLevelName` (String)
+#### `changeLevelName` (String) - DEPRECATED
+Use `levelKey` instead. This will be removed in v7.
+
+<a id="levelKey"></a>
+#### `levelKey` (String)
 
 Default: `'level'`
 
 Changes the property `level` to any string value you pass in:
 ```js
 const logger = pino({
-  changeLevelName: 'priority'
+  levelKey: 'priority'
 })
 logger.info('hello world')
 // {"priority":30,"time":1531257112193,"msg":"hello world","pid":55956,"hostname":"x","v":1}

lib/levels.js

@@ -4,7 +4,7 @@ const {
   lsCacheSym,
   levelValSym,
   useLevelLabelsSym,
-  changeLevelNameSym,
+  levelKeySym,
   useOnlyCustomLevelsSym,
   streamSym
 } = require('./symbols')
@@ -49,7 +49,7 @@ const initialLsCache = Object.keys(nums).reduce((o, k) => {
 }, {})
 
 function genLsCache (instance) {
-  const levelName = instance[changeLevelNameSym]
+  const levelName = instance[levelKeySym]
   instance[lsCacheSym] = Object.keys(instance.levels.labels).reduce((o, k) => {
     o[k] = instance[useLevelLabelsSym]
       ? `{"${levelName}":"${instance.levels.labels[k]}"`

lib/symbols.js

@@ -4,7 +4,7 @@ const setLevelSym = Symbol('pino.setLevel')
 const getLevelSym = Symbol('pino.getLevel')
 const levelValSym = Symbol('pino.levelVal')
 const useLevelLabelsSym = Symbol('pino.useLevelLabels')
-const changeLevelNameSym = Symbol('pino.changeLevelName')
+const levelKeySym = Symbol('pino.levelKey')
 const useOnlyCustomLevelsSym = Symbol('pino.useOnlyCustomLevels')
 const mixinSym = Symbol('pino.mixin')
 
@@ -57,7 +57,7 @@ module.exports = {
   messageKeySym,
   nestedKeySym,
   wildcardFirstSym,
-  changeLevelNameSym,
+  levelKeySym,
   wildcardGsym,
   needsMetadataGsym,
   useOnlyCustomLevelsSym

lib/tools.js

@@ -290,6 +290,14 @@ function createArgsNormalizer (defaultOptions) {
     if ('onTerminated' in opts) {
       throw Error('The onTerminated option has been removed, use pino.final instead')
     }
+    if ('changeLevelName' in opts) {
+      process.emitWarning(
+        'The changeLevelName option is deprecated and will be removed in v7. Use levelKey instead.',
+        { code: 'changeLevelName_deprecation' }
+      )
+      opts.levelKey = opts.changeLevelName
+      delete opts.changeLevelName
+    }
     const { enabled, prettyPrint, prettifier, messageKey } = opts
     if (enabled === false) opts.level = 'silent'
     stream = stream || process.stdout

pino.js

@@ -29,7 +29,7 @@ const {
   messageKeySym,
   nestedKeySym,
   useLevelLabelsSym,
-  changeLevelNameSym,
+  levelKeySym,
   mixinSym,
   useOnlyCustomLevelsSym
 } = symbols
@@ -52,7 +52,7 @@ const defaultOptions = {
   name: undefined,
   redact: null,
   customLevels: null,
-  changeLevelName: 'level',
+  levelKey: 'level',
   useOnlyCustomLevels: false
 }
 
@@ -74,7 +74,7 @@ function pino (...args) {
     level,
     customLevels,
     useLevelLabels,
-    changeLevelName,
+    levelKey,
     mixin,
     useOnlyCustomLevels
   } = opts
@@ -105,7 +105,7 @@ function pino (...args) {
   const instance = {
     levels,
     [useLevelLabelsSym]: useLevelLabels,
-    [changeLevelNameSym]: changeLevelName,
+    [levelKeySym]: levelKey,
     [useOnlyCustomLevelsSym]: useOnlyCustomLevels,
     [streamSym]: stream,
     [timeSym]: time,
@@ -122,7 +122,7 @@ function pino (...args) {
   }
   Object.setPrototypeOf(instance, proto)
 
-  if (customLevels || useLevelLabels || changeLevelName !== defaultOptions.changeLevelName) genLsCache(instance)
+  if (customLevels || useLevelLabels || levelKey !== defaultOptions.levelKey) genLsCache(instance)
 
   instance[setLevelSym](level)
 

test/custom-levels.test.js

@@ -251,14 +251,14 @@ test('does not share custom level state across siblings', async ({ doesNotThrow
   })
 })
 
-test('custom level does not affect changeLevelName', async ({ is }) => {
+test('custom level does not affect levelKey', async ({ is }) => {
   const stream = sink()
   const logger = pino({
     customLevels: {
       foo: 35,
       bar: 45
     },
-    changeLevelName: 'priority'
+    levelKey: 'priority'
   }, stream)
 
   logger.foo('test')

test/levels.test.js

@@ -257,12 +257,21 @@ test('resets levels from labels to numbers', async ({ is }) => {
   instance.info('hello world')
 })
 
+test('aliases changeLevelName to levelKey', async ({ is }) => {
+  const instance = pino({ changeLevelName: 'priority' }, sink((result, enc, cb) => {
+    is(result.priority, 30)
+    cb()
+  }))
+
+  instance.info('hello world')
+})
+
 test('changes label naming when told to', async ({ is }) => {
   const expected = [{
     priority: 30,
     msg: 'hello world'
   }]
-  const instance = pino({ changeLevelName: 'priority' }, sink((result, enc, cb) => {
+  const instance = pino({ levelKey: 'priority' }, sink((result, enc, cb) => {
     const current = expected.shift()
     is(result.priority, current.priority)
     is(result.msg, current.msg)
@@ -323,11 +332,11 @@ test('produces labels for custom levels', async ({ is }) => {
   instance.foo('foobar')
 })
 
-test('setting changeLevelName does not affect labels when told to', async ({ is }) => {
+test('setting levelKey does not affect labels when told to', async ({ is }) => {
   const instance = pino(
     {
       useLevelLabels: true,
-      changeLevelName: 'priority'
+      levelKey: 'priority'
     },
     sink((result, enc, cb) => {
       is(result.priority, 'info')