www.aleph1.co.uk Git - yaffs-website/blob - node_modules/are-we-there-yet/README.md

   1 are-we-there-yet
   2 ----------------
   3
   4 Track complex hiearchies of asynchronous task completion statuses.  This is
   5 intended to give you a way of recording and reporting the progress of the big
   6 recursive fan-out and gather type workflows that are so common in async.
   7
   8 What you do with this completion data is up to you, but the most common use case is to
   9 feed it to one of the many progress bar modules.
  10
  11 Most progress bar modules include a rudamentary version of this, but my
  12 needs were more complex.
  13
  14 Usage
  15 =====
  16
  17 ```javascript
  18 var TrackerGroup = require("are-we-there-yet").TrackerGroup
  19
  20 var top = new TrackerGroup("program")
  21
  22 var single = top.newItem("one thing", 100)
  23 single.completeWork(20)
  24
  25 console.log(top.completed()) // 0.2
  26
  27 fs.stat("file", function(er, stat) {
  28   if (er) throw er
  29   var stream = top.newStream("file", stat.size)
  30   console.log(top.completed()) // now 0.1 as single is 50% of the job and is 20% complete
  31                               // and 50% * 20% == 10%
  32   fs.createReadStream("file").pipe(stream).on("data", function (chunk) {
  33     // do stuff with chunk
  34   })
  35   top.on("change", function (name) {
  36     // called each time a chunk is read from "file"
  37     // top.completed() will start at 0.1 and fill up to 0.6 as the file is read
  38   })
  39 })
  40 ```
  41
  42 Shared Methods
  43 ==============
  44
  45 All tracker objects described below have the following methods, they, along
  46 with the event comprise the interface for consumers of tracker objects.
  47
  48 * var completed = tracker.completed()
  49
  50 Returns the ratio of completed work to work to be done. Range of 0 to 1.
  51
  52 * tracker.finish()
  53
  54 Marks the tracker as completed. With a TrackerGroup this marks all of its
  55 components as completed.
  56
  57 Marks all of the components of this tracker as finished, which in turn means
  58 that `tracker.completed()` for this will now be 1.
  59
  60 This will result in one or more `change` events being emitted.
  61
  62 Events
  63 ======
  64
  65 All tracker objects emit `change` events with the following arguments:
  66
  67 ```
  68 function (name, completed, tracker)
  69 ```
  70
  71 `name` is the name of the tracker that originally emitted the event,
  72 or if it didn't have one, the first containing tracker group that had one.
  73
  74 `completed` is the percent complete (as returned by `tracker.completed()` method).
  75
  76 `tracker` is the tracker object that you are listening for events on.
  77
  78 TrackerGroup
  79 ============
  80
  81 * var tracker = new TrackerGroup(**name**)
  82
  83   * **name** *(optional)* - The name of this tracker group, used in change
  84     notifications if the component updating didn't have a name. Defaults to undefined.
  85
  86 Creates a new empty tracker aggregation group. These are trackers whose
  87 completion status is determined by the completion status of other trackers.
  88
  89 * tracker.addUnit(**otherTracker**, **weight**)
  90
  91   * **otherTracker** - Any of the other are-we-there-yet tracker objects
  92   * **weight** *(optional)* - The weight to give the tracker, defaults to 1.
  93
  94 Adds the **otherTracker** to this aggregation group. The weight determines
  95 how long you expect this tracker to take to complete in proportion to other
  96 units.  So for instance, if you add one tracker with a weight of 1 and
  97 another with a weight of 2, you're saying the second will take twice as long
  98 to complete as the first.  As such, the first will account for 33% of the
  99 completion of this tracker and the second will account for the other 67%.
 100
 101 Returns **otherTracker**.
 102
 103 * var subGroup = tracker.newGroup(**name**, **weight**)
 104
 105 The above is exactly equivalent to:
 106
 107 ```javascript
 108   var subGroup = tracker.addUnit(new TrackerGroup(name), weight)
 109 ```
 110
 111 * var subItem = tracker.newItem(**name**, **todo**, **weight**)
 112
 113 The above is exactly equivalent to:
 114
 115 ```javascript
 116   var subItem = tracker.addUnit(new Tracker(name, todo), weight)
 117 ```
 118
 119 * var subStream = tracker.newStream(**name**, **todo**, **weight**)
 120
 121 The above is exactly equivalent to:
 122
 123 ```javascript
 124   var subStream = tracker.addUnit(new TrackerStream(name, todo), weight)
 125 ```
 126
 127 * console.log( tracker.debug() )
 128
 129 Returns a tree showing the completion of this tracker group and all of its
 130 children, including recursively entering all of the children.
 131
 132 Tracker
 133 =======
 134
 135 * var tracker = new Tracker(**name**, **todo**)
 136
 137   * **name** *(optional)* The name of this counter to report in change
 138     events.  Defaults to undefined.
 139   * **todo** *(optional)* The amount of work todo (a number). Defaults to 0.
 140
 141 Ordinarily these are constructed as a part of a tracker group (via
 142 `newItem`).
 143
 144 * var completed = tracker.completed()
 145
 146 Returns the ratio of completed work to work to be done. Range of 0 to 1. If
 147 total work to be done is 0 then it will return 0.
 148
 149 * tracker.addWork(**todo**)
 150
 151   * **todo** A number to add to the amount of work to be done.
 152
 153 Increases the amount of work to be done, thus decreasing the completion
 154 percentage.  Triggers a `change` event.
 155
 156 * tracker.completeWork(**completed**)
 157
 158   * **completed** A number to add to the work complete
 159
 160 Increase the amount of work complete, thus increasing the completion percentage.
 161 Will never increase the work completed past the amount of work todo. That is,
 162 percentages > 100% are not allowed. Triggers a `change` event.
 163
 164 * tracker.finish()
 165
 166 Marks this tracker as finished, tracker.completed() will now be 1. Triggers
 167 a `change` event.
 168
 169 TrackerStream
 170 =============
 171
 172 * var tracker = new TrackerStream(**name**, **size**, **options**)
 173
 174   * **name** *(optional)* The name of this counter to report in change
 175     events.  Defaults to undefined.
 176   * **size** *(optional)* The number of bytes being sent through this stream.
 177   * **options** *(optional)* A hash of stream options
 178
 179 The tracker stream object is a pass through stream that updates an internal
 180 tracker object each time a block passes through.  It's intended to track
 181 downloads, file extraction and other related activities. You use it by piping
 182 your data source into it and then using it as your data source.
 183
 184 If your data has a length attribute then that's used as the amount of work
 185 completed when the chunk is passed through.  If it does not (eg, object
 186 streams) then each chunk counts as completing 1 unit of work, so your size
 187 should be the total number of objects being streamed.
 188
 189 * tracker.addWork(**todo**)
 190
 191   * **todo** Increase the expected overall size by **todo** bytes.
 192
 193 Increases the amount of work to be done, thus decreasing the completion
 194 percentage.  Triggers a `change` event.