secretary#

A node.js module that brings common sense to console logging.

Installation##

npm install secretary

Setup##

Configuration:####

sec.configure({
    minFlag: 1,
    maxFlag: 5,
    minRunningFlag: 3,
    maxRunningFlag: 4
});

The potential configuration options are as follows:

• minFlag - default: 1 - The lowest possible flag for any output. This must be >= 1.
• maxFlag - default: 10 - The highest possible flag for any output. This must be >= 1.
• minRunningFlag - default: minFlag - The lowest flag whose output will be processed when the program is run. This value must fall within the range of the minFlag and the maxFlag or it will not be registered.
• maxRunningFlag - default: maxFlag - The highest flag whose output will be processed when the program is run. This value must fall within the range of the minFlag and the maxFlag or it will not be registered.

Usage##

Instantiation:####

var sec = require('secretary');

Filtering:####

One of the key features of secretary is the ability to litter your code with thoughtfully place console logging throughout your code, and have it filtered out at runtime by the flag that was supplied with the output. This way, you're always in control of the verbosity of your output, during development and during production. It also does away with the need for quick-and-dirty console.logs that you delete shortly afterwards.

We implement flags by chaining flag() in front of any log call, and passing it the flag level we want to set.

If we assume the following configuration:

minFlag: 1,
maxFlag: 5,
minRunningFlag: 3

And then run the following code:

sec.flag(1).log('Beginning DEBUG output...');
sec.flag(3).log('Integrity check successful');
sec.flag(5).log('Server starting on port 3000');

We will see the following output:

Integrity check successful
Server starting on port 3000

By it's nature, flag() sets what the flag level is for the next log() call. Thus, the following is valid usage:

sec.flag(4);
sec.log('Starting thermonuclear war...'); // Evaluated with flag level 4

It is also possible to use log() without any chain to flag() which results in the minimum running flag to be applied to the log, meaning it will always be displayed no matter what.

Formatting Data:####

Much like console.log(), secretary supports the formatting of data. log() can take multiple arguments in a printf() sort of way.

The first argument passed to log() is always assumed and expected to be the desired output string. If other arguments are included, they are all assumed to be data that need to be formatted into the string. String formatting is done by the util.format() method, so all rules that apply there apply here.

The basic supported placeholders are listed below:

• %s : String
• %d : Number (both integer and float)
• %j : JSON
• % : single percent sign ('%'); this does not consume an argument

For the entire range of util.format() rules, see here.

Examples of this in use:

sec.flag(3).log('%s, %s.', 'Hello', 'Mister');
// 'Hello, Mister.'

sec.log('%d:%d', 12);
// '12:%d'

sec.flag(1).log('Hello', '1', '2', 3);
// 'Hello 1 2 3'