File: README.md

package info (click to toggle)
node-npmlog 4.1.2-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 284 kB
  • sloc: makefile: 2
file content (216 lines) | stat: -rw-r--r-- 5,983 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
# npmlog

The logger util that npm uses.

This logger is very basic.  It does the logging for npm.  It supports
custom levels and colored output.

By default, logs are written to stderr.  If you want to send log messages
to outputs other than streams, then you can change the `log.stream`
member, or you can just listen to the events that it emits, and do
whatever you want with them.

# Installation

```console
npm install npmlog --save
```

# Basic Usage

```javascript
var log = require('npmlog')

// additional stuff ---------------------------+
// message ----------+                         |
// prefix ----+      |                         |
// level -+   |      |                         |
//        v   v      v                         v
    log.info('fyi', 'I have a kitty cat: %j', myKittyCat)
```

## log.level

* {String}

The level to display logs at.  Any logs at or above this level will be
displayed.  The special level `silent` will prevent anything from being
displayed ever.

## log.record

* {Array}

An array of all the log messages that have been entered.

## log.maxRecordSize

* {Number}

The maximum number of records to keep.  If log.record gets bigger than
10% over this value, then it is sliced down to 90% of this value.

The reason for the 10% window is so that it doesn't have to resize a
large array on every log entry.

## log.prefixStyle

* {Object}

A style object that specifies how prefixes are styled.  (See below)

## log.headingStyle

* {Object}

A style object that specifies how the heading is styled.  (See below)

## log.heading

* {String} Default: ""

If set, a heading that is printed at the start of every line.

## log.stream

* {Stream} Default: `process.stderr`

The stream where output is written.

## log.enableColor()

Force colors to be used on all messages, regardless of the output
stream.

## log.disableColor()

Disable colors on all messages.

## log.enableProgress()

Enable the display of log activity spinner and progress bar

## log.disableProgress()

Disable the display of a progress bar

## log.enableUnicode()

Force the unicode theme to be used for the progress bar.

## log.disableUnicode()

Disable the use of unicode in the progress bar.

## log.setGaugeTemplate(template)

Set a template for outputting the progress bar. See the [gauge documentation] for details.

[gauge documentation]: https://npmjs.com/package/gauge

## log.setGaugeThemeset(themes)

Select a themeset to pick themes from for the progress bar. See the [gauge documentation] for details.

## log.pause()

Stop emitting messages to the stream, but do not drop them.

## log.resume()

Emit all buffered messages that were written while paused.

## log.log(level, prefix, message, ...)

* `level` {String} The level to emit the message at
* `prefix` {String} A string prefix.  Set to "" to skip.
* `message...` Arguments to `util.format`

Emit a log message at the specified level.

## log\[level](prefix, message, ...)

For example,

* log.silly(prefix, message, ...)
* log.verbose(prefix, message, ...)
* log.info(prefix, message, ...)
* log.http(prefix, message, ...)
* log.warn(prefix, message, ...)
* log.error(prefix, message, ...)

Like `log.log(level, prefix, message, ...)`.  In this way, each level is
given a shorthand, so you can do `log.info(prefix, message)`.

## log.addLevel(level, n, style, disp)

* `level` {String} Level indicator
* `n` {Number} The numeric level
* `style` {Object} Object with fg, bg, inverse, etc.
* `disp` {String} Optional replacement for `level` in the output.

Sets up a new level with a shorthand function and so forth.

Note that if the number is `Infinity`, then setting the level to that
will cause all log messages to be suppressed.  If the number is
`-Infinity`, then the only way to show it is to enable all log messages.

## log.newItem(name, todo, weight)

* `name` {String} Optional; progress item name.
* `todo` {Number} Optional; total amount of work to be done. Default 0.
* `weight` {Number} Optional; the weight of this item relative to others. Default 1.

This adds a new `are-we-there-yet` item tracker to the progress tracker. The
object returned has the `log[level]` methods but is otherwise an
`are-we-there-yet` `Tracker` object.

## log.newStream(name, todo, weight)

This adds a new `are-we-there-yet` stream tracker to the progress tracker. The
object returned has the `log[level]` methods but is otherwise an
`are-we-there-yet` `TrackerStream` object.

## log.newGroup(name, weight)

This adds a new `are-we-there-yet` tracker group to the progress tracker. The
object returned has the `log[level]` methods but is otherwise an
`are-we-there-yet` `TrackerGroup` object.

# Events

Events are all emitted with the message object.

* `log` Emitted for all messages
* `log.<level>` Emitted for all messages with the `<level>` level.
* `<prefix>` Messages with prefixes also emit their prefix as an event.

# Style Objects

Style objects can have the following fields:

* `fg` {String} Color for the foreground text
* `bg` {String} Color for the background
* `bold`, `inverse`, `underline` {Boolean} Set the associated property
* `bell` {Boolean} Make a noise (This is pretty annoying, probably.)

# Message Objects

Every log event is emitted with a message object, and the `log.record`
list contains all of them that have been created.  They have the
following fields:

* `id` {Number}
* `level` {String}
* `prefix` {String}
* `message` {String} Result of `util.format()`
* `messageRaw` {Array} Arguments to `util.format()`

# Blocking TTYs

We use [`set-blocking`](https://npmjs.com/package/set-blocking) to set
stderr and stdout blocking if they are tty's and have the setBlocking call.
This is a work around for an issue in early versions of Node.js 6.x, which
made stderr and stdout non-blocking on OSX. (They are always blocking
Windows and were never blocking on Linux.) `npmlog` needs them to be blocking
so that it can allow output to stdout and stderr to be interlaced.