[6a3a178] | 1 | # npmlog
|
---|
| 2 |
|
---|
| 3 | The logger util that npm uses.
|
---|
| 4 |
|
---|
| 5 | This logger is very basic. It does the logging for npm. It supports
|
---|
| 6 | custom levels and colored output.
|
---|
| 7 |
|
---|
| 8 | By default, logs are written to stderr. If you want to send log messages
|
---|
| 9 | to outputs other than streams, then you can change the `log.stream`
|
---|
| 10 | member, or you can just listen to the events that it emits, and do
|
---|
| 11 | whatever you want with them.
|
---|
| 12 |
|
---|
| 13 | # Installation
|
---|
| 14 |
|
---|
| 15 | ```console
|
---|
| 16 | npm install npmlog --save
|
---|
| 17 | ```
|
---|
| 18 |
|
---|
| 19 | # Basic Usage
|
---|
| 20 |
|
---|
| 21 | ```javascript
|
---|
| 22 | var 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 |
|
---|
| 36 | The level to display logs at. Any logs at or above this level will be
|
---|
| 37 | displayed. The special level `silent` will prevent anything from being
|
---|
| 38 | displayed ever.
|
---|
| 39 |
|
---|
| 40 | ## log.record
|
---|
| 41 |
|
---|
| 42 | * {Array}
|
---|
| 43 |
|
---|
| 44 | An array of all the log messages that have been entered.
|
---|
| 45 |
|
---|
| 46 | ## log.maxRecordSize
|
---|
| 47 |
|
---|
| 48 | * {Number}
|
---|
| 49 |
|
---|
| 50 | The maximum number of records to keep. If log.record gets bigger than
|
---|
| 51 | 10% over this value, then it is sliced down to 90% of this value.
|
---|
| 52 |
|
---|
| 53 | The reason for the 10% window is so that it doesn't have to resize a
|
---|
| 54 | large array on every log entry.
|
---|
| 55 |
|
---|
| 56 | ## log.prefixStyle
|
---|
| 57 |
|
---|
| 58 | * {Object}
|
---|
| 59 |
|
---|
| 60 | A style object that specifies how prefixes are styled. (See below)
|
---|
| 61 |
|
---|
| 62 | ## log.headingStyle
|
---|
| 63 |
|
---|
| 64 | * {Object}
|
---|
| 65 |
|
---|
| 66 | A style object that specifies how the heading is styled. (See below)
|
---|
| 67 |
|
---|
| 68 | ## log.heading
|
---|
| 69 |
|
---|
| 70 | * {String} Default: ""
|
---|
| 71 |
|
---|
| 72 | If set, a heading that is printed at the start of every line.
|
---|
| 73 |
|
---|
| 74 | ## log.stream
|
---|
| 75 |
|
---|
| 76 | * {Stream} Default: `process.stderr`
|
---|
| 77 |
|
---|
| 78 | The stream where output is written.
|
---|
| 79 |
|
---|
| 80 | ## log.enableColor()
|
---|
| 81 |
|
---|
| 82 | Force colors to be used on all messages, regardless of the output
|
---|
| 83 | stream.
|
---|
| 84 |
|
---|
| 85 | ## log.disableColor()
|
---|
| 86 |
|
---|
| 87 | Disable colors on all messages.
|
---|
| 88 |
|
---|
| 89 | ## log.enableProgress()
|
---|
| 90 |
|
---|
| 91 | Enable the display of log activity spinner and progress bar
|
---|
| 92 |
|
---|
| 93 | ## log.disableProgress()
|
---|
| 94 |
|
---|
| 95 | Disable the display of a progress bar
|
---|
| 96 |
|
---|
| 97 | ## log.enableUnicode()
|
---|
| 98 |
|
---|
| 99 | Force the unicode theme to be used for the progress bar.
|
---|
| 100 |
|
---|
| 101 | ## log.disableUnicode()
|
---|
| 102 |
|
---|
| 103 | Disable the use of unicode in the progress bar.
|
---|
| 104 |
|
---|
| 105 | ## log.setGaugeTemplate(template)
|
---|
| 106 |
|
---|
| 107 | Set 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 |
|
---|
| 113 | Select a themeset to pick themes from for the progress bar. See the [gauge documentation] for details.
|
---|
| 114 |
|
---|
| 115 | ## log.pause()
|
---|
| 116 |
|
---|
| 117 | Stop emitting messages to the stream, but do not drop them.
|
---|
| 118 |
|
---|
| 119 | ## log.resume()
|
---|
| 120 |
|
---|
| 121 | Emit 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 |
|
---|
| 129 | Emit a log message at the specified level.
|
---|
| 130 |
|
---|
| 131 | ## log\[level](prefix, message, ...)
|
---|
| 132 |
|
---|
| 133 | For 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 |
|
---|
| 142 | Like `log.log(level, prefix, message, ...)`. In this way, each level is
|
---|
| 143 | given 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 |
|
---|
| 152 | Sets up a new level with a shorthand function and so forth.
|
---|
| 153 |
|
---|
| 154 | Note that if the number is `Infinity`, then setting the level to that
|
---|
| 155 | will 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 |
|
---|
| 164 | This adds a new `are-we-there-yet` item tracker to the progress tracker. The
|
---|
| 165 | object 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 |
|
---|
| 170 | This adds a new `are-we-there-yet` stream tracker to the progress tracker. The
|
---|
| 171 | object returned has the `log[level]` methods but is otherwise an
|
---|
| 172 | `are-we-there-yet` `TrackerStream` object.
|
---|
| 173 |
|
---|
| 174 | ## log.newGroup(name, weight)
|
---|
| 175 |
|
---|
| 176 | This adds a new `are-we-there-yet` tracker group to the progress tracker. The
|
---|
| 177 | object returned has the `log[level]` methods but is otherwise an
|
---|
| 178 | `are-we-there-yet` `TrackerGroup` object.
|
---|
| 179 |
|
---|
| 180 | # Events
|
---|
| 181 |
|
---|
| 182 | Events 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 |
|
---|
| 190 | Style 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 |
|
---|
| 199 | Every log event is emitted with a message object, and the `log.record`
|
---|
| 200 | list contains all of them that have been created. They have the
|
---|
| 201 | following 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 |
|
---|
| 211 | We use [`set-blocking`](https://npmjs.com/package/set-blocking) to set
|
---|
| 212 | stderr and stdout blocking if they are tty's and have the setBlocking call.
|
---|
| 213 | This is a work around for an issue in early versions of Node.js 6.x, which
|
---|
| 214 | made stderr and stdout non-blocking on OSX. (They are always blocking
|
---|
| 215 | Windows and were never blocking on Linux.) `npmlog` needs them to be blocking
|
---|
| 216 | so that it can allow output to stdout and stderr to be interlaced.
|
---|