mirror of https://github.com/lukechilds/node.git
Browse Source
PR-URL: https://github.com/nodejs/node/pull/11020 Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>v6
Kat Marchán
8 years ago
committed by
Jeremiah Senkpiel
Jeremiah Senkpiel
1035 changed files with 919 additions and 21259 deletions
@ -1,41 +0,0 @@ |
|||
|
|||
2.0.2 / 2015-07-14 |
|||
================== |
|||
|
|||
* Use HTTPS for dist url (#656, @SonicHedgehog) |
|||
* Merge pull request #648 from nevosegal/master |
|||
* Merge pull request #650 from magic890/patch-1 |
|||
* Updated Installation section on README |
|||
* Updated link to gyp user documentation |
|||
* Fix download error message spelling (#643, @tomxtobin) |
|||
* Merge pull request #637 from lygstate/master |
|||
* Set NODE_GYP_DIR for addon.gypi to setting absolute path for |
|||
src/win_delay_load_hook.c, and fixes of the long relative path issue on Win32. |
|||
Fixes #636 (#637, @lygstate). |
|||
|
|||
2.0.1 / 2015-05-28 |
|||
================== |
|||
|
|||
* configure: try/catch the semver range.test() call |
|||
* README: update for visual studio 2013 (#510, @samccone) |
|||
|
|||
2.0.0 / 2015-05-24 |
|||
================== |
|||
|
|||
* configure: check for python2 executable by default, fallback to python |
|||
* configure: don't clobber existing $PYTHONPATH |
|||
* configure: use "path-array" for PYTHONPATH |
|||
* gyp: fix for non-acsii userprofile name on Windows |
|||
* gyp: always install into $PRODUCT_DIR |
|||
* gyp: apply https://codereview.chromium.org/11361103/ |
|||
* gyp: don't use links at all, just copy the files instead |
|||
* gyp: update gyp to e1c8fcf7 |
|||
* Updated README.md with updated Windows build info |
|||
* Show URL when a download fails |
|||
* package: add a "license" field |
|||
* move HMODULE m declaration to top |
|||
* Only add "-undefined dynamic_lookup" to loadable_module targets |
|||
* win: optionally allow node.exe/iojs.exe to be renamed |
|||
* Avoid downloading shasums if using tarPath |
|||
* Add target name preprocessor define: `NODE_GYP_MODULE_NAME` |
|||
* Show better error message in case of bad network settings |
|||
@ -1,36 +0,0 @@ |
|||
### v3.1.2 |
|||
|
|||
* Update to `gauge@1.6.0` adding support for default values for template |
|||
items. |
|||
|
|||
### v3.1.1 |
|||
|
|||
* Update to `gauge@1.5.3` to fix to `1.x` compatibility when it comes to |
|||
when a progress bar is enabled. In `1.x` if you didn't have a TTY the |
|||
progress bar was never shown. In `2.x` it merely defaults to disabled, |
|||
but you can enable it explicitly if you still want progress updates. |
|||
|
|||
### v3.1.0 |
|||
|
|||
* Update to `gauge@2.5.2`: |
|||
* Updates the `signal-exit` dependency which fixes an incompatibility with |
|||
the node profiler. |
|||
* Uses externalizes its ansi code generation in `console-control-strings` |
|||
* Make the default progress bar include the last line printed, colored as it |
|||
would be when printing to a tty. |
|||
|
|||
### v3.0.0 |
|||
|
|||
* Switch to `gauge@2.0.0`, for better performance, better look. |
|||
* Set stderr/stdout blocking if they're tty's, so that we can hide a |
|||
progress bar going to stderr and then safely print to stdout. Without |
|||
this the two can end up overlapping producing confusing and sometimes |
|||
corrupted output. |
|||
|
|||
### v2.0.0 |
|||
|
|||
* Make the `error` event non-fatal so that folks can use it as a prefix. |
|||
|
|||
### v1.0.0 |
|||
|
|||
* Add progress bar with `gauge@1.1.0` |
|||
@ -1,210 +0,0 @@ |
|||
# 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. |
|||
|
|||
# Basic Usage |
|||
|
|||
``` |
|||
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. |
|||
@ -1,298 +0,0 @@ |
|||
'use strict' |
|||
var Progress = require('are-we-there-yet') |
|||
var Gauge = require('gauge') |
|||
var EE = require('events').EventEmitter |
|||
var log = exports = module.exports = new EE() |
|||
var util = require('util') |
|||
|
|||
var setBlocking = require('set-blocking') |
|||
var consoleControl = require('console-control-strings') |
|||
|
|||
setBlocking(true) |
|||
var stream = process.stderr |
|||
Object.defineProperty(log, 'stream', { |
|||
set: function (newStream) { |
|||
stream = newStream |
|||
if (this.gauge) this.gauge.setWriteTo(stream, stream) |
|||
}, |
|||
get: function () { |
|||
return stream |
|||
} |
|||
}) |
|||
|
|||
// by default, decide based on tty-ness.
|
|||
var colorEnabled |
|||
log.useColor = function () { |
|||
return colorEnabled != null ? colorEnabled : stream.isTTY |
|||
} |
|||
|
|||
log.enableColor = function () { |
|||
colorEnabled = true |
|||
this.gauge.setTheme({hasColor: colorEnabled, hasUnicode: unicodeEnabled}) |
|||
} |
|||
log.disableColor = function () { |
|||
colorEnabled = false |
|||
this.gauge.setTheme({hasColor: colorEnabled, hasUnicode: unicodeEnabled}) |
|||
} |
|||
|
|||
// default level
|
|||
log.level = 'info' |
|||
|
|||
log.gauge = new Gauge(stream, { |
|||
theme: {hasColor: log.useColor()}, |
|||
template: [ |
|||
{type: 'progressbar', length: 20}, |
|||
{type: 'activityIndicator', kerning: 1, length: 1}, |
|||
{type: 'section', default: ''}, |
|||
':', |
|||
{type: 'logline', kerning: 1, default: ''} |
|||
] |
|||
}) |
|||
|
|||
log.tracker = new Progress.TrackerGroup() |
|||
|
|||
// no progress bars unless asked
|
|||
log.progressEnabled = false |
|||
|
|||
var unicodeEnabled |
|||
|
|||
log.enableUnicode = function () { |
|||
unicodeEnabled = true |
|||
this.gauge.setTheme({hasColor: this.useColor(), hasUnicode: unicodeEnabled}) |
|||
} |
|||
|
|||
log.disableUnicode = function () { |
|||
unicodeEnabled = false |
|||
this.gauge.setTheme({hasColor: this.useColor(), hasUnicode: unicodeEnabled}) |
|||
} |
|||
|
|||
log.setGaugeThemeset = function (themes) { |
|||
this.gauge.setThemeset(themes) |
|||
} |
|||
|
|||
log.setGaugeTemplate = function (template) { |
|||
this.gauge.setTemplate(template) |
|||
} |
|||
|
|||
log.enableProgress = function () { |
|||
if (this.progressEnabled) return |
|||
this.progressEnabled = true |
|||
if (this._pause) return |
|||
this.tracker.on('change', this.showProgress) |
|||
this.gauge.enable() |
|||
this.showProgress() |
|||
} |
|||
|
|||
log.disableProgress = function () { |
|||
if (!this.progressEnabled) return |
|||
this.clearProgress() |
|||
this.progressEnabled = false |
|||
this.tracker.removeListener('change', this.showProgress) |
|||
this.gauge.disable() |
|||
} |
|||
|
|||
var trackerConstructors = ['newGroup', 'newItem', 'newStream'] |
|||
|
|||
var mixinLog = function (tracker) { |
|||
// mixin the public methods from log into the tracker
|
|||
// (except: conflicts and one's we handle specially)
|
|||
Object.keys(log).forEach(function (P) { |
|||
if (P[0] === '_') return |
|||
if (trackerConstructors.filter(function (C) { return C === P }).length) return |
|||
if (tracker[P]) return |
|||
if (typeof log[P] !== 'function') return |
|||
var func = log[P] |
|||
tracker[P] = function () { |
|||
return func.apply(log, arguments) |
|||
} |
|||
}) |
|||
// if the new tracker is a group, make sure any subtrackers get
|
|||
// mixed in too
|
|||
if (tracker instanceof Progress.TrackerGroup) { |
|||
trackerConstructors.forEach(function (C) { |
|||
var func = tracker[C] |
|||
tracker[C] = function () { return mixinLog(func.apply(tracker, arguments)) } |
|||
}) |
|||
} |
|||
return tracker |
|||
} |
|||
|
|||
// Add tracker constructors to the top level log object
|
|||
trackerConstructors.forEach(function (C) { |
|||
log[C] = function () { return mixinLog(this.tracker[C].apply(this.tracker, arguments)) } |
|||
}) |
|||
|
|||
log.clearProgress = function (cb) { |
|||
if (!this.progressEnabled) return cb && process.nextTick(cb) |
|||
this.gauge.hide(cb) |
|||
} |
|||
|
|||
log.showProgress = function (name, completed) { |
|||
if (!this.progressEnabled) return |
|||
var values = {} |
|||
if (name) values.section = name |
|||
var last = log.record[log.record.length - 1] |
|||
if (last) { |
|||
values.subsection = last.prefix |
|||
var disp = log.disp[last.level] || last.level |
|||
var logline = this._format(disp, log.style[last.level]) |
|||
if (last.prefix) logline += ' ' + this._format(last.prefix, this.prefixStyle) |
|||
logline += ' ' + last.message.split(/\r?\n/)[0] |
|||
values.logline = logline |
|||
} |
|||
values.completed = completed || this.tracker.completed() |
|||
this.gauge.show(values) |
|||
}.bind(log) // bind for use in tracker's on-change listener
|
|||
|
|||
// temporarily stop emitting, but don't drop
|
|||
log.pause = function () { |
|||
this._paused = true |
|||
} |
|||
|
|||
log.resume = function () { |
|||
if (!this._paused) return |
|||
this._paused = false |
|||
|
|||
var b = this._buffer |
|||
this._buffer = [] |
|||
b.forEach(function (m) { |
|||
this.emitLog(m) |
|||
}, this) |
|||
if (this.progressEnabled) this.enableProgress() |
|||
} |
|||
|
|||
log._buffer = [] |
|||
|
|||
var id = 0 |
|||
log.record = [] |
|||
log.maxRecordSize = 10000 |
|||
log.log = function (lvl, prefix, message) { |
|||
var l = this.levels[lvl] |
|||
if (l === undefined) { |
|||
return this.emit('error', new Error(util.format( |
|||
'Undefined log level: %j', lvl))) |
|||
} |
|||
|
|||
var a = new Array(arguments.length - 2) |
|||
var stack = null |
|||
for (var i = 2; i < arguments.length; i++) { |
|||
var arg = a[i - 2] = arguments[i] |
|||
|
|||
// resolve stack traces to a plain string.
|
|||
if (typeof arg === 'object' && arg && |
|||
(arg instanceof Error) && arg.stack) { |
|||
arg.stack = stack = arg.stack + '' |
|||
} |
|||
} |
|||
if (stack) a.unshift(stack + '\n') |
|||
message = util.format.apply(util, a) |
|||
|
|||
var m = { id: id++, |
|||
level: lvl, |
|||
prefix: String(prefix || ''), |
|||
message: message, |
|||
messageRaw: a } |
|||
|
|||
this.emit('log', m) |
|||
this.emit('log.' + lvl, m) |
|||
if (m.prefix) this.emit(m.prefix, m) |
|||
|
|||
this.record.push(m) |
|||
var mrs = this.maxRecordSize |
|||
var n = this.record.length - mrs |
|||
if (n > mrs / 10) { |
|||
var newSize = Math.floor(mrs * 0.9) |
|||
this.record = this.record.slice(-1 * newSize) |
|||
} |
|||
|
|||
this.emitLog(m) |
|||
}.bind(log) |
|||
|
|||
log.emitLog = function (m) { |
|||
if (this._paused) { |
|||
this._buffer.push(m) |
|||
return |
|||
} |
|||
if (this.progressEnabled) this.gauge.pulse(m.prefix) |
|||
var l = this.levels[m.level] |
|||
if (l === undefined) return |
|||
if (l < this.levels[this.level]) return |
|||
if (l > 0 && !isFinite(l)) return |
|||
|
|||
var disp = log.disp[m.level] || m.level |
|||
this.clearProgress() |
|||
m.message.split(/\r?\n/).forEach(function (line) { |
|||
if (this.heading) { |
|||
this.write(this.heading, this.headingStyle) |
|||
this.write(' ') |
|||
} |
|||
this.write(disp, log.style[m.level]) |
|||
var p = m.prefix || '' |
|||
if (p) this.write(' ') |
|||
this.write(p, this.prefixStyle) |
|||
this.write(' ' + line + '\n') |
|||
}, this) |
|||
this.showProgress() |
|||
} |
|||
|
|||
log._format = function (msg, style) { |
|||
if (!stream) return |
|||
|
|||
var output = '' |
|||
if (this.useColor()) { |
|||
style = style || {} |
|||
var settings = [] |
|||
if (style.fg) settings.push(style.fg) |
|||
if (style.bg) settings.push('bg' + style.bg[0].toUpperCase() + style.bg.slice(1)) |
|||
if (style.bold) settings.push('bold') |
|||
if (style.underline) settings.push('underline') |
|||
if (style.inverse) settings.push('inverse') |
|||
if (settings.length) output += consoleControl.color(settings) |
|||
if (style.beep) output += consoleControl.beep() |
|||
} |
|||
output += msg |
|||
if (this.useColor()) { |
|||
output += consoleControl.color('reset') |
|||
} |
|||
return output |
|||
} |
|||
|
|||
log.write = function (msg, style) { |
|||
if (!stream) return |
|||
|
|||
stream.write(this._format(msg, style)) |
|||
} |
|||
|
|||
log.addLevel = function (lvl, n, style, disp) { |
|||
if (!disp) disp = lvl |
|||
this.levels[lvl] = n |
|||
this.style[lvl] = style |
|||
if (!this[lvl]) { |
|||
this[lvl] = function () { |
|||
var a = new Array(arguments.length + 1) |
|||
a[0] = lvl |
|||
for (var i = 0; i < arguments.length; i++) { |
|||
a[i + 1] = arguments[i] |
|||
} |
|||
return this.log.apply(this, a) |
|||
}.bind(this) |
|||
} |
|||
this.disp[lvl] = disp |
|||
} |
|||
|
|||
log.prefixStyle = { fg: 'magenta' } |
|||
log.headingStyle = { fg: 'white', bg: 'black' } |
|||
|
|||
log.style = {} |
|||
log.levels = {} |
|||
log.disp = {} |
|||
log.addLevel('silly', -Infinity, { inverse: true }, 'sill') |
|||
log.addLevel('verbose', 1000, { fg: 'blue', bg: 'black' }, 'verb') |
|||
log.addLevel('info', 2000, { fg: 'green' }) |
|||
log.addLevel('http', 3000, { fg: 'green', bg: 'black' }) |
|||
log.addLevel('warn', 4000, { fg: 'black', bg: 'yellow' }, 'WARN') |
|||
log.addLevel('error', 5000, { fg: 'red', bg: 'black' }, 'ERR!') |
|||
log.addLevel('silent', Infinity) |
|||
|
|||
// allow 'error' prefix
|
|||
log.on('error', function () {}) |
|||
@ -1,5 +0,0 @@ |
|||
*~ |
|||
.#* |
|||
node_modules |
|||
coverage |
|||
.nyc_output |
|||
@ -1,19 +0,0 @@ |
|||
Hi, figured we could actually use a changelog now: |
|||
|
|||
## 1.1.1 2016-01-29 |
|||
|
|||
* Fix a typo in stream completion tracker |
|||
|
|||
## 1.1.0 2016-01-29 |
|||
|
|||
* Rewrote completion percent computation to be low impact– no more walking a |
|||
tree of completion groups every time we need this info. Previously, with |
|||
medium sized tree of completion groups, even a relatively modest number of |
|||
calls to the top level `completed()` method would result in absurd numbers |
|||
of calls overall as it walked down the tree. We now, instead, keep track as |
|||
we bubble up changes, so the computation is limited to when data changes and |
|||
to the depth of that one branch, instead of _every_ node. (Plus, we were already |
|||
incurring _this_ cost, since we already bubbled out changes.) |
|||
* Moved different tracker types out to their own files. |
|||
* Made tests test for TOO MANY events too. |
|||
* Standarized the source code formatting |
|||
@ -1,5 +0,0 @@ |
|||
Copyright (c) 2015, Rebecca Turner |
|||
|
|||
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. |
|||
|
|||
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
|||
@ -1,194 +0,0 @@ |
|||
are-we-there-yet |
|||
---------------- |
|||
|
|||
Track complex hiearchies of asynchronous task completion statuses. This is |
|||
intended to give you a way of recording and reporting the progress of the big |
|||
recursive fan-out and gather type workflows that are so common in async. |
|||
|
|||
What you do with this completion data is up to you, but the most common use case is to |
|||
feed it to one of the many progress bar modules. |
|||
|
|||
Most progress bar modules include a rudamentary version of this, but my |
|||
needs were more complex. |
|||
|
|||
Usage |
|||
===== |
|||
|
|||
```javascript |
|||
var TrackerGroup = require("are-we-there-yet").TrackerGroup |
|||
|
|||
var top = new TrackerGroup("program") |
|||
|
|||
var single = top.newItem("one thing", 100) |
|||
single.completeWork(20) |
|||
|
|||
console.log(top.completed()) // 0.2 |
|||
|
|||
fs.stat("file", function(er, stat) { |
|||
if (er) throw er |
|||
var stream = top.newStream("file", stat.size) |
|||
console.log(top.completed()) // now 0.1 as single is 50% of the job and is 20% complete |
|||
// and 50% * 20% == 10% |
|||
fs.createReadStream("file").pipe(stream).on("data", function (chunk) { |
|||
// do stuff with chunk |
|||
}) |
|||
top.on("change", function (name) { |
|||
// called each time a chunk is read from "file" |
|||
// top.completed() will start at 0.1 and fill up to 0.6 as the file is read |
|||
}) |
|||
}) |
|||
``` |
|||
|
|||
Shared Methods |
|||
============== |
|||
|
|||
All tracker objects described below have the following methods, they, along |
|||
with the event comprise the interface for consumers of tracker objects. |
|||
|
|||
* var completed = tracker.completed() |
|||
|
|||
Returns the ratio of completed work to work to be done. Range of 0 to 1. |
|||
|
|||
* tracker.finish() |
|||
|
|||
Marks the tracker as completed. With a TrackerGroup this marks all of its |
|||
components as completed. |
|||
|
|||
Marks all of the components of this tracker as finished, which in turn means |
|||
that `tracker.completed()` for this will now be 1. |
|||
|
|||
This will result in one or more `change` events being emitted. |
|||
|
|||
Events |
|||
====== |
|||
|
|||
All tracker objects emit `change` events with the following arguments: |
|||
|
|||
``` |
|||
function (name, completed, tracker) |
|||
``` |
|||
|
|||
`name` is the name of the tracker that originally emitted the event, |
|||
or if it didn't have one, the first containing tracker group that had one. |
|||
|
|||
`completed` is the percent complete (as returned by `tracker.completed()` method). |
|||
|
|||
`tracker` is the tracker object that you are listening for events on. |
|||
|
|||
TrackerGroup |
|||
============ |
|||
|
|||
* var tracker = new TrackerGroup(**name**) |
|||
|
|||
* **name** *(optional)* - The name of this tracker group, used in change |
|||
notifications if the component updating didn't have a name. Defaults to undefined. |
|||
|
|||
Creates a new empty tracker aggregation group. These are trackers whose |
|||
completion status is determined by the completion status of other trackers. |
|||
|
|||
* tracker.addUnit(**otherTracker**, **weight**) |
|||
|
|||
* **otherTracker** - Any of the other are-we-there-yet tracker objects |
|||
* **weight** *(optional)* - The weight to give the tracker, defaults to 1. |
|||
|
|||
Adds the **otherTracker** to this aggregation group. The weight determines |
|||
how long you expect this tracker to take to complete in proportion to other |
|||
units. So for instance, if you add one tracker with a weight of 1 and |
|||
another with a weight of 2, you're saying the second will take twice as long |
|||
to complete as the first. As such, the first will account for 33% of the |
|||
completion of this tracker and the second will account for the other 67%. |
|||
|
|||
Returns **otherTracker**. |
|||
|
|||
* var subGroup = tracker.newGroup(**name**, **weight**) |
|||
|
|||
The above is exactly equivalent to: |
|||
|
|||
```javascript |
|||
var subGroup = tracker.addUnit(new TrackerGroup(name), weight) |
|||
``` |
|||
|
|||
* var subItem = tracker.newItem(**name**, **todo**, **weight**) |
|||
|
|||
The above is exactly equivalent to: |
|||
|
|||
```javascript |
|||
var subItem = tracker.addUnit(new Tracker(name, todo), weight) |
|||
``` |
|||
|
|||
* var subStream = tracker.newStream(**name**, **todo**, **weight**) |
|||
|
|||
The above is exactly equivalent to: |
|||
|
|||
```javascript |
|||
var subStream = tracker.addUnit(new TrackerStream(name, todo), weight) |
|||
``` |
|||
|
|||
* console.log( tracker.debug() ) |
|||
|
|||
Returns a tree showing the completion of this tracker group and all of its |
|||
children, including recursively entering all of the children. |
|||
|
|||
Tracker |
|||
======= |
|||
|
|||
* var tracker = new Tracker(**name**, **todo**) |
|||
|
|||
* **name** *(optional)* The name of this counter to report in change |
|||
events. Defaults to undefined. |
|||
* **todo** *(optional)* The amount of work todo (a number). Defaults to 0. |
|||
|
|||
Ordinarily these are constructed as a part of a tracker group (via |
|||
`newItem`). |
|||
|
|||
* var completed = tracker.completed() |
|||
|
|||
Returns the ratio of completed work to work to be done. Range of 0 to 1. If |
|||
total work to be done is 0 then it will return 0. |
|||
|
|||
* tracker.addWork(**todo**) |
|||
|
|||
* **todo** A number to add to the amount of work to be done. |
|||
|
|||
Increases the amount of work to be done, thus decreasing the completion |
|||
percentage. Triggers a `change` event. |
|||
|
|||
* tracker.completeWork(**completed**) |
|||
|
|||
* **completed** A number to add to the work complete |
|||
|
|||
Increase the amount of work complete, thus increasing the completion percentage. |
|||
Will never increase the work completed past the amount of work todo. That is, |
|||
percentages > 100% are not allowed. Triggers a `change` event. |
|||
|
|||
* tracker.finish() |
|||
|
|||
Marks this tracker as finished, tracker.completed() will now be 1. Triggers |
|||
a `change` event. |
|||
|
|||
TrackerStream |
|||
============= |
|||
|
|||
* var tracker = new TrackerStream(**name**, **size**, **options**) |
|||
|
|||
* **name** *(optional)* The name of this counter to report in change |
|||
events. Defaults to undefined. |
|||
* **size** *(optional)* The number of bytes being sent through this stream. |
|||
* **options** *(optional)* A hash of stream options |
|||
|
|||
The tracker stream object is a pass through stream that updates an internal |
|||
tracker object each time a block passes through. It's intended to track |
|||
downloads, file extraction and other related activities. You use it by piping |
|||
your data source into it and then using it as your data source. |
|||
|
|||
If your data has a length attribute then that's used as the amount of work |
|||
completed when the chunk is passed through. If it does not (eg, object |
|||
streams) then each chunk counts as completing 1 unit of work, so your size |
|||
should be the total number of objects being streamed. |
|||
|
|||
* tracker.addWork(**todo**) |
|||
|
|||
* **todo** Increase the expected overall size by **todo** bytes. |
|||
|
|||
Increases the amount of work to be done, thus decreasing the completion |
|||
percentage. Triggers a `change` event. |
|||
@ -1,4 +0,0 @@ |
|||
'use strict' |
|||
exports.TrackerGroup = require('./tracker-group.js') |
|||
exports.Tracker = require('./tracker.js') |
|||
exports.TrackerStream = require('./tracker-stream.js') |
|||
@ -1 +0,0 @@ |
|||
node_modules/ |
|||
@ -1,22 +0,0 @@ |
|||
|
|||
1.0.0 / 2015-12-14 |
|||
================== |
|||
|
|||
* Merge pull request #12 from kasicka/master |
|||
* Add license text |
|||
|
|||
0.1.0 / 2014-10-17 |
|||
================== |
|||
|
|||
* adds `.fluent()` to api |
|||
|
|||
0.0.3 / 2014-01-13 |
|||
================== |
|||
|
|||
* fix receiver for .method() |
|||
|
|||
0.0.2 / 2014-01-13 |
|||
================== |
|||
|
|||
* Object.defineProperty() sucks |
|||
* Initial commit |
|||
@ -1,20 +0,0 @@ |
|||
Copyright (c) 2015 TJ Holowaychuk <tj@vision-media.ca> |
|||
|
|||
Permission is hereby granted, free of charge, to any person obtaining |
|||
a copy of this software and associated documentation files (the |
|||
"Software"), to deal in the Software without restriction, including |
|||
without limitation the rights to use, copy, modify, merge, publish, |
|||
distribute, sublicense, and/or sell copies of the Software, and to |
|||
permit persons to whom the Software is furnished to do so, subject to |
|||
the following conditions: |
|||
|
|||
The above copyright notice and this permission notice shall be |
|||
included in all copies or substantial portions of the Software. |
|||
|
|||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
|||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
|||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
|||
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE |
|||
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION |
|||
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION |
|||
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue