Merge pull request #1 from monksoftware/logger-default-export-and-refactoring

Refactor module

Author: Pistacchione

README.md

@@ -1,77 +1,80 @@
 # Monk Log library
 
-This is a simple logging library for Nodejs projects depends on:
-- [loglevel](https://github.com/pimterry/loglevel)
-- [loglevel-plugin-prefix](https://github.com/kutuluk/loglevel-plugin-prefix)
-- [chalk](https://github.com/chalk/chalk#readme)
+Are you using `console.log` in your project? Are you tired of configuring
+loglevel / winston / whatever to add timestamp, colors to your log messages?
+Do you want a consistent log style?
+This is the library for you! You can now log with style -- no configuration
+required!
 
 ## Installation
 
-For add this as `npm` dependency
+Simply add this library as a dependency in your project.
+You can use the github URI:
 
-```bash
-npm install git+ssh://[email protected]:node-libraries/monk-log.git
+```
+yarn add github:monksoftware/monk-log
 ```
 
 or add manually to your `package.json` file
 
 ```json
   {
     "dependencies": {
-      ... ,
-      "monk-log": "git+ssh://[email protected]:node-libraries/monk-log.git"
+      [...] ,
+      "monk-log": "github:monksoftware/monk-log"
     }
   }
 ```
 
-## Setting up
+## How to use
+
+Works pretty much the same as `loglevel`, the only difference is that
+the exported root logger is preconfigured with loglevel-plugin-prefix
+and custom formatting functions in order to output nice colorful log messages
+with timestamp, log level and logger name.
 
 ```javascript
-const { levels, monkLog } = require('monk-log')
-const log = monkLog(options)
+const log = require('monk-log')
 
 log.trace(msg)
 log.debug(msg)
 log.info(msg)
 log.warn(msg)
 log.error(msg)
-
-```
-
-## Documentation
-
-The monk log library accept optional parameters:
-```
-{
-  name:   // Choose a name for log instance, default is monk-log
-  level:  // Choose a log level, default il DEBUG, possible level are:
-          // "TRACE" "DEBUG" "INFO" "WARN" "ERROR"
-  wrap:   // Wrap `name` with custom identifier, default is and array of square brackets ['[', ']']
-}
 ```
 
 ## Examples
 
-see more inside `examples folder`
+See more inside `examples folder`
 
+### Ready-to-go logging
 ```javascript
-const { levels, monkLog } = require('monk-log')
-const log = monkLog({
-  name: 'MONK-LOG',
-  level: levels.DEBUG,
-  wrap: ['+', '+']
-})
+const log = require('monk-log')
+log.warn('You can have nice log messages in just one line!')
 
-log.debug('this is a debug log')
-log.info('this is an info log')
-log.warn('this is a warning log')
-log.error('this is an error log')
+// Outputs
+// [2019-02-18T01:10:49.933] WARN [root]: You can have nice log messages in just one line!
+```
 
-// Response
-// [2019-02-08T18:35:40.245] INFO monk-log: Set log level to DEBUG
-// [2019-02-08T18:35:40.245] DEBUG +MONK-LOG+: this is a debug log
-// [2019-02-08T18:35:40.245] INFO +MONK-LOG+: this is an info log
-// [2019-02-08T18:35:40.245] WARN +MONK-LOG+: this is a warning log
-// [2019-02-08T18:35:40.245] ERROR +MONK-LOG+: this is an error log
+### Child loggers with custom format
 
+```javascript
+const log = require('monk-log')
+// Default level is WARN,
+log.setDefaultLevel('DEBUG')
+const childLogger = log.getLogger('CHILD', 'DEBUG', {
+  template: 'When: %t, who: %n, why: %l, what: '
+})
+log.info('Child logger has been set up')
+childLogger.debug('this is a debug message')
+childLogger.info('This is a info message')
+childLogger.warn('this is a warning message')
+childLogger.error('this is an error message')
+
+// Outputs
+// [2019-02-18T01:08:46.260] INFO [root]: Child logger has been set up
+// When: 2019-02-18T01:08:46.262, who: CHILD, why: DEBUG, what: this is a debug message
+// When: 2019-02-18T01:08:46.262, who: CHILD, why: INFO, what: This is a info message
+// When: 2019-02-18T01:08:46.262, who: CHILD, why: WARN, what: this is a warning message
+// When: 2019-02-18T01:08:46.263, who: CHILD, why: ERROR, what: this is an error message
 ```

examples/full.js

@@ -1,25 +1,26 @@
 'use strict'
 
-const { levels, monkLog } = require('../lib/log')
-
-const logTrace = monkLog({
-  name: 'MONK-LOG',
-  level: levels.TRACE
-})
+const log = require('../lib/log')
 
+const logTrace = log.getLogger('MONK-LOG', 'TRACE')
 logTrace.trace('this is a trace log')
 logTrace.debug('this is a debug log')
 logTrace.info('this is an info log')
 logTrace.warn('this is a warning log')
 logTrace.error('this is an error log')
 
-const log = monkLog({
-  name: 'MONK-LOG2',
-  level: levels.DEBUG,
-  wrap: ['[', ']']
-})
+const advancedLogger = log.getLogger(
+  'super-long-logger-name-maybe-too-much',
+  'DEBUG',
+  {
+    // Only use first letter of level, e.g. W for waraning logs
+    levelFormatter: (level) => level.toUpperCase()[0],
+    // Numeric timestamp
+    timestampFormatter: (date) => +date,
+    // Truncate logger names to 5 letters
+    nameFormatter: (name) => name.slice(0, 5),
+    template: `#%l# logger: %n - timestamp: %t - message:`
+  }
+)
 
-log.debug('this is a debug log')
-log.info('this is an info log')
-log.warn('this is a warning log')
-log.error('this is an error log')
+log.info('This library is great!')  // #I# logger: super - timestamp: 1550449434004 - message: This library is great!

examples/simple.js

@@ -1,6 +1,2 @@
-'use strict'
-
-const { monkLog } = require('../lib/log')
-
-const log = monkLog()
-log.debug('This is a log message')
+const log = require('../lib/log')
+log.debug('This is a debug log message. You probably wont see it because the default level is WARN')

lib/log.js

@@ -4,10 +4,6 @@ const logLevel = require('loglevel')
 const chalk = require('chalk')
 const prefix = require('loglevel-plugin-prefix')
 
-const getKeyByValue = (object, value) => {
-  return Object.keys(object).find(key => object[key] === value)
-}
-
 const colors = Object.freeze({
   TRACE: chalk.magenta,
   DEBUG: chalk.cyan,
@@ -16,42 +12,91 @@ const colors = Object.freeze({
   ERROR: chalk.red
 })
 
-const logConfiguration = {
-  // template: '[%t] %l %n:',
-  format(level, name, timestamp) {
-    return `${chalk.gray(`[${timestamp}]`)} ${colors[level.toUpperCase()](level)} ${chalk.green(`${name}:`)}`
-  },
-  timestampFormatter: () => {
-    const tzOffset = (new Date()).getTimezoneOffset() * 60000 // offset in milliseconds
-    const localISOTime = (new Date(Date.now() - tzOffset)).toISOString().slice(0, -1) // => '2015-01-26T06:40:36.181'
-    return localISOTime
-  }
+const defaultTimestampFormatter = (date) => {
+  const tzOffset = date.getTimezoneOffset() * 60000 // offset in milliseconds
+  const localISOTime = (new Date(date - tzOffset)).toISOString().slice(0, -1) // => '2015-01-26T06:40:36.181'
+  return localISOTime
+}
+
+const defaultNameFormatter = (name) => {
+  return chalk.green(name)
+}
+
+const defaultLevelFormatter = (level) => {
+  return colors[level.toUpperCase()](level.toUpperCase())
 }
 
-module.exports.levels = logLevel.levels
+const defaultTemplate = '[%t] %l [%n]:'
 
-module.exports.monkLog = ({ name = '', level = logLevel.levels.DEBUG, wrap = ['[', ']'] } = {}) => {
-  if (!Array.isArray(wrap)) {
-    wrap = ['[', ']']
+// "Nice" default options, they make log lines like:
+// [2019-02-18T00:37:56.007] WARN [root]: This is a warning message
+// With colored log level, according to serverity.
+const defaultLogLevelOptions = {
+  levelFormatter: defaultLevelFormatter,
+  timestampFormatter: defaultTimestampFormatter,
+  nameFormatter: defaultNameFormatter,
+  template: defaultTemplate,
+}
+
+const _loggersByName = {}
+
+/**
+ * Subclass of loglevel's Logger,
+ * Preset to use loglevel-plugin-prefix with some nice default options.
+ * Can obtain child loggers by calling .getLogger, they will inherit
+ * parent's options.
+ */
+class MonkLogger extends logLevel.constructor {
+  constructor (name, level, options) {
+    super(name, level)
+    this.options = {...defaultLogLevelOptions}
+    this.configure(options)
   }
 
-  if (wrap.length !== 2) {
-    throw new Error(`Wrong wrap params, expected 2 got ${wrap.length} elements`)
+  /**
+   * Configure the logger, accepts all loglevel-plugin-prefix options
+   * and the loglevel (`level` key).
+   *
+   * @param {object} options - new option values to update
+   * @param {boolean} [reset=false] - if false (the default), it will keep
+   *   and update current options (e.g. options inherited from parents or
+   *   a previous call to configure). When true, if will first reset options
+   *   to default ones, and then update with supplied ones.
+   *   Therefore, you can use .configure({}, true) to completely reset
+   *   options to defaults.
+   */
+  configure (options, reset = false) {
+    this.options = {
+      ...(reset ? defaultLogLevelOptions : this.options),
+      ...options,
+    }
+    prefix.apply(this, this.options)
   }
 
-  let logger
-  if (name) {
-    name = `${wrap[0]}${name}${wrap[1]}`
-    logger = logLevel.getLogger(name)
-  } else {
-    // root name is nasty
-    logger = logLevel.getLogger('monk-log')
+  /**
+   *
+   * @param {string} name - child logger name
+   * @param {string} level - only output log messages of at least this level
+   * @param {object} options - loglevel-plugin-prefix options
+   */
+  getLogger (name, level, options) {
+    if (typeof name !== "string" || name === "") {
+      throw new TypeError("You must supply a name when creating a logger.")
+    }
+    let logger = _loggersByName[name]
+    if (!logger) {
+      logger = _loggersByName[name] = new MonkLogger(
+        name, level, {...this.options, ...options})
+    }
+    return logger
   }
+}
 
-  prefix.reg(logLevel)
-  prefix.apply(logger, logConfiguration)
-  logger.setLevel(level)
-  logger.info(`Set log level to ${getKeyByValue(logger.levels, level)}`)
+prefix.reg(logLevel)
 
-  return logger
-}
+const defaultLogger = new MonkLogger('root')
+defaultLogger.getLoggers = () => _loggersByName
+
+// Export default logger. Can be used directly, or can be used
+// to obtain child loggers.
+module.exports = defaultLogger

package.json

@@ -1,6 +1,6 @@
 {
   "name": "monk-log",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "private": true,
   "engines": {
     "node": ">=8.3.0"