log-tree v2.2.0

#Generate logs in hierarchical tree structure

##Philosophy 1. Structure of logs should based on the flow of logic, not the time the log was generated 2. Importance of logs should be determined by the end results achieved, not by arbitrary "log levels" 3. Capturing of logs should be deliberate and selective, not rsysloged giant generic flat files

##Features 1. Use promises or nested functions to generate logs in tree structure 2. Automatically records execution time to find slow code 3. Automatically log errors thrown and promises rejected 4. Full log tree attached to any errors thrown to help with debugging 5. Single file, no external dependencies 6. TODO: Test browser compatibility

##How to use 1. Perform logging using logger.log() 2. Set additional properties after inital logging with logger.set() 3. Return logger._root.traceId to the user 4. Save logger._root.toAcyclicJSON() into a database

##API

//Creates a new logger. All child loggers will reference this logger in its `_root` property.
//options:
//    onLog: called when the log function is called on this or any of its child loggers
//    onError: called when error is thrown or promise rejected in this or any of its child loggers
new TreeLog(options) -> logger

//Adds a new child to logger. The `result` property is set to the object / return value
logger.log(message) -> null  
logger.log(message, object) -> object
logger.log(message, object, property_name) -> object[property_name]()
logger.log(message, object, property_name, [param_array]) -> object[property_name](param_array...)

//Adds a new child to logger. `func` is called with the new child logger as first parameter
logger.log(message, func) -> func()

//clones value and set it to logger
logger.set(key, value) -> value

//Sets the `result` property. Also updates `elapsedMS` with the time elapsed since logger is created
logger.done(result)

//Returns object with all properties with names beginning with _ stripped out.
logger.toJSON() -> object

//Returns cloned object with all properties with names beginning with _ stripped
//out and all cyclic references converted to string representation.
logger.toJSON() -> object

//Returns string representation of log.
logger.stringify(replacer, spaces)

##Example in CoffeeScript

LogTree = require 'log-tree'
Promise = require 'bluebird'
options =
    onLog: (log)-> console.log "[#{log.timestamp}] LOG: #{log.message}"
    onError: (log)-> console.log "[#{log.timestamp}] ERR: #{log.message}\n#{log.stack}"

logger = new LogTree('Example', options)

logger.log 'Logging simple objects', process.versions

logger.log 'Nested logging', (logger) ->
    logger.log 'Child log 1', (logger) ->
        return 'Return value is logged'
    logger.log 'Child log 2', (logger, done) ->
        done 'Callback value is logged'
        return 'Return value is ignored'

try
    logger.log 'Logging with error thrown', (logger) ->
        throw new Error('Error message')
catch err
    #the full log can be found at err.logTree
    #also, the error thrown is attached to the log

logger.log 'Logging with promises', (logger) ->
    new Promise (resolve, reject) ->
        logger.log 'This is the promised child'
        setImmediate ()->
            resolve 'The resolved value is captured'
        return null
.then () ->
    logger.log 'This is chained after the previous promise'
    console.log 'This is the final tree structure generated'
    console.log JSON.stringify logger._root, false, 4