Alt Redux Logger

A redux logging middleware

Exports

./dist/alt-redux-logger.js - cjs bundle, transpiled to node4. referenced in package.json's main entry
./dist/alt-redux-logger.mjs - es6 exports. transpiled to node4. referenced in package.json's module entry
./dist/alt-redux-logger.umd.js - browser bundle, transpiled to ie8.
./dist/alt-redux-logger.umd.min.js - browser bundle minified

Polyfills

You'll need the following polyfils if you intend to run this in older browsers / environments:

Object.entries
Object.getOwnPropertyDescriptors
Number.isNaN

Usage

const {createLogger} = require('alt-redux-logger')
// or import {createLogger} from 'alt-redux-logger/es'
store = createStore(
  combineReducers(...),
  applyMiddleware(
    // e.g., routerMiddleware,
    // e.g., thunkMiddleware,
    createLogger()
  )
)

It is recommended you put this AFTER any thunk/promise middleware so you only see the actual actions.

API

createLogger(options: object?) all options are provided as an object, see below:
- logger (object, default: console) the logger to use
- color (boolean, default: true) whether to use colors
- diff (boolean, default: false) whether to perform a diff
- diffPredicate (function=>boolean, default: () => true) used to exclude diffs; you get (getState, action).
- level (string, default: 'log') method to use on the logger (throws during initialization if it doesn't exist)
- styles (object, default: see below) color overrides
- formatTime (function, default: now => new Date(now).toLocaleString()) date transformer
- predicate (function=>boolean, default: () => true) used to exclude actions; you get (getState, action).
- createPrinter (function=>void, default: pretty; see below) used to overwrite how log is called
- stateTransformer (function=>*, default: state => state) used to transform state prior to hitting logger
- actionTransformer (function=>*, default: action => action) used to transform action prior to hitting logger
- errorTransformer (function=>*, default: error => error) used to transform error prior to hitting logger

Printer

Printer is used to translate the payload (action, before & after states) from redux into logging statements. It is a function that takes the following 2 parameters, support and options.

support - rudimentary support checking (see ./src/support.js)
options - all options provided to the logger

It can return one of two things:

function - if a function is provided, it will be called with logger and payload
- logger - the loger instance provided to createLogger (by default, this is console)
- payload - all the information available
  - actions - the redux action(s)
  - before - store before the action
  - after - store after the action
  - diff? - array of differences (if diff option is true)
  - error? - error, if encountered
  - now - milliseconds since Jan. 1., 1970
  - took - milliseconds the action took to perform
object - if an object is provided, it is expected to have lifecycle functions that will be called at the appropriate time. The following functions can be provided - they will be called in this order:
- start ((logger, now, ...actions)=>void) called when an operation starts (sets up console.group)
- before ((logger, before)=>void) called to log the state before the action occurs
- action ((logger, ...actions)=>void) called to log actions that occur
- after ((logger, after)=>void) called to log the state after the action occurs
- error ((logger, error)=>void) called when an error occurs
- diff ((logger, diff)=>void) called with an array of changes if diff and diffPredicate are true.
- end ((logger, took)=>void) called when an operation ends (closes console.group)

See ./src/printer.js for how the pretty printer does it.

Styles

If using the pretty logger, you can overwrite certain colors. Each object supports:

color - rgb hex code
dim - boolean, font-weight: lighter in browser; dim in console
bold - boolean, font-weight: bold in browser, bold in console

Here are the defaults:

{
  "title": {"color": "#666", "dim": true},
  "titleAction": {"bold": true},
  "prev": {"color": "#9E9E9E", "bold": true},
  "action": {"color": "#03A9F4", "bold": true},
  "error": {"color": "#F20404", "bold": true},
  "next": {"color": "#4CAF50"},
  "diff": {"bold": true},
  "diffAdd": {"color": "#4CAF50"},
  "diffRemove": {"color": "#F44336"},
  "diffUpdate": {"color": "#2196F3"}
}

But Why?

Why not just use redux-logger? This works great for development in the browser, but fails short on the server and in production environments.

No "don't use a pretty logger at all, JSON.stringify everything and do one log per action" option. I take a different approach to printing - a default printer is provided that is pretty, you can overwrite its colors -- or you can use your own printer, e.g. printer: (options, support) => (logger, payload) => logger.log(JSON.stringify(payload)).
No console coloring support. Bringing in something like chalk to a browser bundle seems a bit heavy handed, so I wrote a very minimal coloring library to support the very basics.

That said, this module is heavily inspired by redux-logger - at least with the default options emulating the browser logging... this was written from scratch.

TODO

publish to npm

tswaters/alt-redux-logger