"Fossies" - the Fresh Open Source Software Archive

Member "Atom/resources/app/apm/node_modules/are-we-there-yet/README.md" (25 Nov 2016, 6348 Bytes) of archive /windows/misc/atom-windows.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

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

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.

Returns the ratio of completed work to work to be done. Range of 0 to 1.

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

Creates a new empty tracker aggregation group. These are trackers whose completion status is determined by the completion status of other trackers.

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.

The above is exactly equivalent to:

  var subGroup = tracker.addUnit(new TrackerGroup(name), weight)

The above is exactly equivalent to:

  var subItem = tracker.addUnit(new Tracker(name, todo), weight)

The above is exactly equivalent to:

  var subStream = tracker.addUnit(new TrackerStream(name, todo), weight)

Returns a tree showing the completion of this tracker group and all of its children, including recursively entering all of the children.

Tracker

Ordinarily these are constructed as a part of a tracker group (via newItem).

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.

Increases the amount of work to be done, thus decreasing the completion percentage. Triggers a change event.

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.

Marks this tracker as finished, tracker.completed() will now be 1. Triggers a change event.

TrackerStream

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.

Increases the amount of work to be done, thus decreasing the completion percentage. Triggers a change event.