feat: implement convenience methods

Author: gajus

README.md

@@ -12,6 +12,14 @@ JSON logger for Node.js.
   * [Prepending context using the global state](#prepending-context-using-the-global-state)
   * [Filtering logs](#filtering-logs)
     * [jq primer](#jq-primer)
+* [API](#api)
+  * [`child`](#child)
+  * [`trace`](#trace)
+  * [`debug`](#debug)
+  * [`info`](#info)
+  * [`warn`](#warn)
+  * [`error`](#error)
+  * [`fatal`](#fatal)
 * [Transports](#transports)
 * [Environment variables](#environment-variables)
 * [Conventions](#conventions)
@@ -26,56 +34,13 @@ ROARR_LOG=true node ./index.js
 
 ```
 
-`roarr` package exports a function that accepts the following API:
-
-```js
-export type LoggerType =
-  (
-    context: MessageContextType,
-    message: string,
-    c?: SprintfArgumentType,
-    d?: SprintfArgumentType,
-    e?: SprintfArgumentType,
-    f?: SprintfArgumentType,
-    g?: SprintfArgumentType,
-    h?: SprintfArgumentType,
-    i?: SprintfArgumentType,
-    k?: SprintfArgumentType
-  ) => void |
-  (
-    message: string,
-    b?: SprintfArgumentType,
-    c?: SprintfArgumentType,
-    d?: SprintfArgumentType,
-    e?: SprintfArgumentType,
-    f?: SprintfArgumentType,
-    g?: SprintfArgumentType,
-    h?: SprintfArgumentType,
-    i?: SprintfArgumentType,
-    k?: SprintfArgumentType
-  ) => void;
-
-```
-
-Put it into words:
-
-1. First parameter can be either a string (message) or an object.
-  * If first parameter is an object (context), the second parameter must be a string (message).
-1. Arguments after the message parameter are used to enable [printf message formatting](https://en.wikipedia.org/wiki/Printf_format_string).
-  * Printf arguments must be of a primitive type (`string | number | boolean | null`).
-  * There can be up to 9 printf arguments (or 8 if the first parameter is the context object).
-
-<!-- -->
-
 ```js
 import log from 'roarr';
 
 log('foo');
 
 log('bar %s', 'baz');
 
-// Creates a child logger appending the provided `context` object
-// to the previous logger context.
 const debug = log.child({
   level: 'debug'
 });
@@ -184,6 +149,81 @@ ROARR_LOG=true node ./index.js | jq 'select(.context.level == "warning" or .cont
 
 ```
 
+## API
+
+`roarr` package exports a function that accepts the following API:
+
+```js
+export type LoggerType =
+  (
+    context: MessageContextType,
+    message: string,
+    c?: SprintfArgumentType,
+    d?: SprintfArgumentType,
+    e?: SprintfArgumentType,
+    f?: SprintfArgumentType,
+    g?: SprintfArgumentType,
+    h?: SprintfArgumentType,
+    i?: SprintfArgumentType,
+    k?: SprintfArgumentType
+  ) => void |
+  (
+    message: string,
+    b?: SprintfArgumentType,
+    c?: SprintfArgumentType,
+    d?: SprintfArgumentType,
+    e?: SprintfArgumentType,
+    f?: SprintfArgumentType,
+    g?: SprintfArgumentType,
+    h?: SprintfArgumentType,
+    i?: SprintfArgumentType,
+    k?: SprintfArgumentType
+  ) => void;
+
+```
+
+Put it into words:
+
+1. First parameter can be either a string (message) or an object.
+  * If first parameter is an object (context), the second parameter must be a string (message).
+1. Arguments after the message parameter are used to enable [printf message formatting](https://en.wikipedia.org/wiki/Printf_format_string).
+  * Printf arguments must be of a primitive type (`string | number | boolean | null`).
+  * There can be up to 9 printf arguments (or 8 if the first parameter is the context object).
+
+Refer to the [Usage](#usage) documentation for common usage examples.
+
+### `child`
+
+Creates a child logger appending the provided `context` object to the previous logger context.
+
+```js
+type ChildType = (context: MessageContextType) => LoggerType;
+
+```
+
+### `trace`
+### `debug`
+### `info`
+### `warn`
+### `error`
+### `fatal`
+
+Convenience methods for logging a message with `logLevel` context property value set to the name of the convenience method, e.g.
+
+```js
+import log from 'roarr';
+
+log.debug('foo');
+
+```
+
+Produces output:
+
+```
+{"context":{"logLevel":"debug"},"message":"foo","sequence":0,"time":1506776210001,"version":"1.0.0"}
+
+```
+
 ## Transports
 
 A transport in most logging libraries is something that runs in-process to perform some operation with the finalised log line. For example, a transport might send the log line to a standard syslog server after processing the log line and reformatting it.

src/factories/createLogger.js

@@ -16,6 +16,15 @@ type OnMessageEventHandlerType = (message: MessageType) => void;
 
 const version = '1.0.0';
 
+const logLevels = [
+  'trace',
+  'debug',
+  'info',
+  'warn',
+  'error',
+  'fatal'
+];
+
 const createLogger = (onMessage: OnMessageEventHandlerType, parentContext: MessageContextType = {}) => {
   // eslint-disable-next-line id-length
   const log: LoggerType = (a, b, c, d, e, f, g, h, i, k) => {
@@ -57,6 +66,14 @@ const createLogger = (onMessage: OnMessageEventHandlerType, parentContext: Messa
     });
   };
 
+  for (const logLevel of logLevels) {
+    log[logLevel] = (a, b, c, d, e, f, g, h, i, k) => {
+      return log.child({
+        logLevel
+      })(a, b, c, d, e, f, g, h, i, k);
+    };
+  }
+
   return log;
 };
 

test/roarr/roarr.js

@@ -220,3 +220,71 @@ test('prepends global.ROARR.prepend context', (t) => {
     }
   ]);
 });
+
+test('convenience methods trace, debug, info, warn, error and fatal prepend a logLevel property', (t) => {
+  const log = createLoggerWithHistory();
+
+  log.trace('foo 0');
+  log.debug('foo 1');
+  log.info('foo 2');
+  log.warn('foo 3');
+  log.error('foo 4');
+  log.fatal('foo 5');
+
+  t.deepEqual(log.messages, [
+    {
+      context: {
+        logLevel: 'trace'
+      },
+      message: 'foo 0',
+      sequence: 0,
+      time,
+      version
+    },
+    {
+      context: {
+        logLevel: 'debug'
+      },
+      message: 'foo 1',
+      sequence: 1,
+      time,
+      version
+    },
+    {
+      context: {
+        logLevel: 'info'
+      },
+      message: 'foo 2',
+      sequence: 2,
+      time,
+      version
+    },
+    {
+      context: {
+        logLevel: 'warn'
+      },
+      message: 'foo 3',
+      sequence: 3,
+      time,
+      version
+    },
+    {
+      context: {
+        logLevel: 'error'
+      },
+      message: 'foo 4',
+      sequence: 4,
+      time,
+      version
+    },
+    {
+      context: {
+        logLevel: 'fatal'
+      },
+      message: 'foo 5',
+      sequence: 5,
+      time,
+      version
+    }
+  ]);
+});