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