roarr - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

dist/factories/createLogger.js

@@ -31,2 +31,4 @@ 'use strict';
 
+var logLevels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+
 var createLogger = function createLogger(onMessage /*: OnMessageEventHandlerType*/) {
@@ -65,2 +67,35 @@ var parentContext /*: MessageContextType*/ = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
 
+  var _loop = function _loop(logLevel) {
+    log[logLevel] = function (a, b, c, d, e, f, g, h, i, k) {
+      return log.child({
+        logLevel: logLevel
+      })(a, b, c, d, e, f, g, h, i, k);
+    };
+  };
+
+  var _iteratorNormalCompletion = true;
+  var _didIteratorError = false;
+  var _iteratorError = undefined;
+
+  try {
+    for (var _iterator = logLevels[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+      var logLevel = _step.value;
+
+      _loop(logLevel);
+    }
+  } catch (err) {
+    _didIteratorError = true;
+    _iteratorError = err;
+  } finally {
+    try {
+      if (!_iteratorNormalCompletion && _iterator.return) {
+        _iterator.return();
+      }
+    } finally {
+      if (_didIteratorError) {
+        throw _iteratorError;
+      }
+    }
+  }
+
   return log;
@@ -67,0 +102,0 @@ };

package.json

@@ -71,3 +71,3 @@ {
   },
-  "version": "1.1.0"
+  "version": "1.2.0"
 }

README.md

@@ -15,4 +15,14 @@ # Roarr
     * [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)
+  * [Using Roarr in an application](#using-roarr-in-an-application)
 
@@ -28,44 +38,3 @@ ## Usage
 
-`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';
@@ -77,4 +46,2 @@
 
-// Creates a child logger appending the provided `context` object
-// to the previous logger context.
 const debug = log.child({
@@ -188,2 +155,77 @@ level: 'debug'
 
+## 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
@@ -210,1 +252,37 @@
 |`ROARR_LOG`|Boolean|Enables/ disables logging.|`false`|
+
+## Conventions
+
+### Using Roarr in an application
+
+I recommend to create a file `Logger.js` in the project directory. Use this file to create an child instance of Roarr with context parameters describing the project and the initialisation instance, e.g.
+
+```js
+/**
+ * @file Example contents of a Logger.js file.
+ */
+
+import log from 'roarr';
+import ulid from 'ulid';
+
+// Instance ID is useful for correlating logs in high concurrency environment.
+const instanceId = ulid();
+
+// The reason we are using `global.ROARR.prepend` as opposed to `roarr#child`
+// is because we want this information to be prepended to all logs, including
+// those of the "my-application" dependencies.
+global.ROARR.prepend = {
+  ...global.ROARR.prepend,
+  application: 'my-application',
+  instanceId
+};
+
+const Logger = log.child({
+  // .foo property is going to appear only in the logs that are created using
+  // the current instance of a Roarr logger.
+  foo: 'bar'
+});
+
+export default Logger;
+
+```

No alert changes

Improved metrics

Total package byte prevSize

25942

increased by17.71%

Lines of code

171

increased by21.28%

Number of lines in readme file

284

increased by37.86%

No dependency changes