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.
|