1# npmlog 2 3The logger util that npm uses. 4 5This logger is very basic. It does the logging for npm. It supports 6custom levels and colored output. 7 8By default, logs are written to stderr. If you want to send log messages 9to outputs other than streams, then you can change the `log.stream` 10member, or you can just listen to the events that it emits, and do 11whatever you want with them. 12 13# Installation 14 15```console 16npm install npmlog --save 17``` 18 19# Basic Usage 20 21```javascript 22var log = require('npmlog') 23 24// additional stuff ---------------------------+ 25// message ----------+ | 26// prefix ----+ | | 27// level -+ | | | 28// v v v v 29 log.info('fyi', 'I have a kitty cat: %j', myKittyCat) 30``` 31 32## log.level 33 34* {String} 35 36The level to display logs at. Any logs at or above this level will be 37displayed. The special level `silent` will prevent anything from being 38displayed ever. 39 40## log.record 41 42* {Array} 43 44An array of all the log messages that have been entered. 45 46## log.maxRecordSize 47 48* {Number} 49 50The maximum number of records to keep. If log.record gets bigger than 5110% over this value, then it is sliced down to 90% of this value. 52 53The reason for the 10% window is so that it doesn't have to resize a 54large array on every log entry. 55 56## log.prefixStyle 57 58* {Object} 59 60A style object that specifies how prefixes are styled. (See below) 61 62## log.headingStyle 63 64* {Object} 65 66A style object that specifies how the heading is styled. (See below) 67 68## log.heading 69 70* {String} Default: "" 71 72If set, a heading that is printed at the start of every line. 73 74## log.stream 75 76* {Stream} Default: `process.stderr` 77 78The stream where output is written. 79 80## log.enableColor() 81 82Force colors to be used on all messages, regardless of the output 83stream. 84 85## log.disableColor() 86 87Disable colors on all messages. 88 89## log.enableProgress() 90 91Enable the display of log activity spinner and progress bar 92 93## log.disableProgress() 94 95Disable the display of a progress bar 96 97## log.enableUnicode() 98 99Force the unicode theme to be used for the progress bar. 100 101## log.disableUnicode() 102 103Disable the use of unicode in the progress bar. 104 105## log.setGaugeTemplate(template) 106 107Set a template for outputting the progress bar. See the [gauge documentation] for details. 108 109[gauge documentation]: https://npmjs.com/package/gauge 110 111## log.setGaugeThemeset(themes) 112 113Select a themeset to pick themes from for the progress bar. See the [gauge documentation] for details. 114 115## log.pause() 116 117Stop emitting messages to the stream, but do not drop them. 118 119## log.resume() 120 121Emit all buffered messages that were written while paused. 122 123## log.log(level, prefix, message, ...) 124 125* `level` {String} The level to emit the message at 126* `prefix` {String} A string prefix. Set to "" to skip. 127* `message...` Arguments to `util.format` 128 129Emit a log message at the specified level. 130 131## log\[level](prefix, message, ...) 132 133For example, 134 135* log.silly(prefix, message, ...) 136* log.verbose(prefix, message, ...) 137* log.info(prefix, message, ...) 138* log.http(prefix, message, ...) 139* log.warn(prefix, message, ...) 140* log.error(prefix, message, ...) 141 142Like `log.log(level, prefix, message, ...)`. In this way, each level is 143given a shorthand, so you can do `log.info(prefix, message)`. 144 145## log.addLevel(level, n, style, disp) 146 147* `level` {String} Level indicator 148* `n` {Number} The numeric level 149* `style` {Object} Object with fg, bg, inverse, etc. 150* `disp` {String} Optional replacement for `level` in the output. 151 152Sets up a new level with a shorthand function and so forth. 153 154Note that if the number is `Infinity`, then setting the level to that 155will cause all log messages to be suppressed. If the number is 156`-Infinity`, then the only way to show it is to enable all log messages. 157 158## log.newItem(name, todo, weight) 159 160* `name` {String} Optional; progress item name. 161* `todo` {Number} Optional; total amount of work to be done. Default 0. 162* `weight` {Number} Optional; the weight of this item relative to others. Default 1. 163 164This adds a new `are-we-there-yet` item tracker to the progress tracker. The 165object returned has the `log[level]` methods but is otherwise an 166`are-we-there-yet` `Tracker` object. 167 168## log.newStream(name, todo, weight) 169 170This adds a new `are-we-there-yet` stream tracker to the progress tracker. The 171object returned has the `log[level]` methods but is otherwise an 172`are-we-there-yet` `TrackerStream` object. 173 174## log.newGroup(name, weight) 175 176This adds a new `are-we-there-yet` tracker group to the progress tracker. The 177object returned has the `log[level]` methods but is otherwise an 178`are-we-there-yet` `TrackerGroup` object. 179 180# Events 181 182Events are all emitted with the message object. 183 184* `log` Emitted for all messages 185* `log.<level>` Emitted for all messages with the `<level>` level. 186* `<prefix>` Messages with prefixes also emit their prefix as an event. 187 188# Style Objects 189 190Style objects can have the following fields: 191 192* `fg` {String} Color for the foreground text 193* `bg` {String} Color for the background 194* `bold`, `inverse`, `underline` {Boolean} Set the associated property 195* `bell` {Boolean} Make a noise (This is pretty annoying, probably.) 196 197# Message Objects 198 199Every log event is emitted with a message object, and the `log.record` 200list contains all of them that have been created. They have the 201following fields: 202 203* `id` {Number} 204* `level` {String} 205* `prefix` {String} 206* `message` {String} Result of `util.format()` 207* `messageRaw` {Array} Arguments to `util.format()` 208 209# Blocking TTYs 210 211We use [`set-blocking`](https://npmjs.com/package/set-blocking) to set 212stderr and stdout blocking if they are tty's and have the setBlocking call. 213This is a work around for an issue in early versions of Node.js 6.x, which 214made stderr and stdout non-blocking on OSX. (They are always blocking 215Windows and were never blocking on Linux.) `npmlog` needs them to be blocking 216so that it can allow output to stdout and stderr to be interlaced. 217