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 an argument of the name of the
|
66 | thing changing.
|
67 |
|
68 | TrackerGroup
|
69 | ============
|
70 |
|
71 | * var tracker = new TrackerGroup(**name**)
|
72 |
|
73 | * **name** *(optional)* - The name of this tracker group, used in change
|
74 | notifications if the component updating didn't have a name. Defaults to undefined.
|
75 |
|
76 | Creates a new empty tracker aggregation group. These are trackers whose
|
77 | completion status is determined by the completion status of other trackers.
|
78 |
|
79 | * tracker.addUnit(**otherTracker**, **weight**)
|
80 |
|
81 | * **otherTracker** - Any of the other are-we-there-yet tracker objects
|
82 | * **weight** *(optional)* - The weight to give the tracker, defaults to 1.
|
83 |
|
84 | Adds the **otherTracker** to this aggregation group. The weight determines
|
85 | how long you expect this tracker to take to complete in proportion to other
|
86 | units. So for instance, if you add one tracker with a weight of 1 and
|
87 | another with a weight of 2, you're saying the second will take twice as long
|
88 | to complete as the first. As such, the first will account for 33% of the
|
89 | completion of this tracker and the second will account for the other 67%.
|
90 |
|
91 | Returns **otherTracker**.
|
92 |
|
93 | * var subGroup = tracker.newGroup(**name**, **weight**)
|
94 |
|
95 | The above is exactly equivalent to:
|
96 |
|
97 | ```javascript
|
98 | var subGroup = tracker.addUnit(new TrackerGroup(name), weight)
|
99 | ```
|
100 |
|
101 | * var subItem = tracker.newItem(**name**, **todo**, **weight**)
|
102 |
|
103 | The above is exactly equivalent to:
|
104 |
|
105 | ```javascript
|
106 | var subItem = tracker.addUnit(new Tracker(name, todo), weight)
|
107 | ```
|
108 |
|
109 | * var subStream = tracker.newStream(**name**, **todo**, **weight**)
|
110 |
|
111 | The above is exactly equivalent to:
|
112 |
|
113 | ```javascript
|
114 | var subStream = tracker.addUnit(new TrackerStream(name, todo), weight)
|
115 | ```
|
116 |
|
117 | * console.log( tracker.debug() )
|
118 |
|
119 | Returns a tree showing the completion of this tracker group and all of its
|
120 | children, including recursively entering all of the children.
|
121 |
|
122 | Tracker
|
123 | =======
|
124 |
|
125 | * var tracker = new Tracker(**name**, **todo**)
|
126 |
|
127 | * **name** *(optional)* The name of this counter to report in change
|
128 | events. Defaults to undefined.
|
129 | * **todo** *(optional)* The amount of work todo (a number). Defaults to 0.
|
130 |
|
131 | Ordinarily these are constructed as a part of a tracker group (via `newItem`) but they c
|
132 |
|
133 | * var completed = tracker.completed()
|
134 |
|
135 | Returns the ratio of completed work to work to be done. Range of 0 to 1. If
|
136 | total work to be done is 0 then it will return 0.
|
137 |
|
138 | * tracker.addWork(**todo**)
|
139 |
|
140 | * **todo** A number to add to the amount of work to be done.
|
141 |
|
142 | Increases the amount of work to be done, thus decreasing the completion
|
143 | percentage. Triggers a `change` event.
|
144 |
|
145 | * tracker.completeWork(**completed**)
|
146 |
|
147 | * **completed** A number to add to the work complete
|
148 |
|
149 | Increase the amount of work complete, thus increasing the completion percentage.
|
150 | Will never increase the work completed past the amount of work todo. That is,
|
151 | percentages > 100% are not allowed. Triggers a `change` event.
|
152 |
|
153 | * tracker.finish()
|
154 |
|
155 | Marks this tracker as finished, tracker.completed() will now be 1. Triggers
|
156 | a `change` event.
|
157 |
|
158 | TrackerStream
|
159 | =============
|
160 |
|
161 | * var tracker = new TrackerStream(**name**, **size**, **options**)
|
162 |
|
163 | * **name** *(optional)* The name of this counter to report in change
|
164 | events. Defaults to undefined.
|
165 | * **size** *(optional)* The number of bytes being sent through this stream.
|
166 | * **options** *(optional)* A hash of stream options
|
167 |
|
168 | The tracker stream object is a pass through stream that updates an internal
|
169 | tracker object each time a block passes through. It's intended to track
|
170 | downloads, file extraction and other related activities. You use it by piping
|
171 | your data source into it and then using it as your data source.
|
172 |
|
173 | If your data has a length attribute then that's used as the amount of work
|
174 | completed when the chunk is passed through. If it does not (eg, object
|
175 | streams) then each chunk counts as completing 1 unit of work, so your size
|
176 | should be the total number of objects being streamed.
|
177 |
|
178 | * tracker.addWork(**todo**)
|
179 |
|
180 | * **todo** Increase the expected overall size by **todo** bytes.
|
181 |
|
182 | Increases the amount of work to be done, thus decreasing the completion
|
183 | percentage. Triggers a `change` event.
|