Debian Codegraph @

README.markdown

raw
1 Seq
2 ===
3
4 Seq is an asynchronous flow control library with a chainable interface for
5 sequential and parallel actions. Even the error handling is chainable.
6
7 Each action in the chain operates on a stack of values.
8 There is also a variables hash for storing values by name.
9
10 [TOC]
11
12
13
14 Examples
15 ========
16
17 stat_all.js
18 -----------
19
20 ````javascript
21 var fs = require('fs');
22 var Hash = require('hashish');
23 var Seq = require('seq');
24
25 Seq()
26 .seq(function () {
27 fs.readdir(__dirname, this);
28 })
29 .flatten()
30 .parEach(function (file) {
31 fs.stat(__dirname + '/' + file, this.into(file));
32 })
33 .seq(function () {
34 var sizes = Hash.map(this.vars, function (s) { return s.size })
35 console.dir(sizes);
36 })
37 ;
38 ````
39
40 Output:
41
42 { 'stat_all.js': 404, 'parseq.js': 464 }
43
44 parseq.js
45 ---------
46
47 ````javascript
48 var fs = require('fs');
49 var exec = require('child_process').exec;
50
51 var Seq = require('seq');
52 Seq()
53 .seq(function () {
54 exec('whoami', this)
55 })
56 .par(function (who) {
57 exec('groups ' + who, this);
58 })
59 .par(function (who) {
60 fs.readFile(__filename, 'ascii', this);
61 })
62 .seq(function (groups, src) {
63 console.log('Groups: ' + groups.trim());
64 console.log('This file has ' + src.length + ' bytes');
65 })
66 ;
67 ````
68
69 Output:
70
71 Groups: substack : substack dialout cdrom floppy audio src video plugdev games netdev fuse www
72 This file has 464 bytes
73
74
75
76
77 API
78 ===
79
80 Each method executes callbacks with a context (its `this`) described in the next
81 section. Every method returns `this`.
82
83 Whenever `this()` is called with a non-falsy first argument, the error value
84 propagates down to the first `catch` it sees, skipping over all actions in
85 between. There is an implicit `catch` at the end of all chains that prints the
86 error stack if available and otherwise just prints the error.
87
88
89
90 Seq(xs=[])
91 ----------
92
93 The constructor function creates a new `Seq` chain with the methods described
94 below. The optional array argument becomes the new context stack.
95
96 Array argument is new in 0.3. `Seq()` now behaves like `Seq.ap()`.
97
98
99 .seq(cb)
100 --------
101 .seq(key, cb, *args)
102 --------------------
103
104 This eponymous function executes actions sequentially.
105 Once all running parallel actions are finished executing,
106 the supplied callback is `apply()`'d with the context stack.
107
108 To execute the next action in the chain, call `this()`. The first
109 argument must be the error value. The rest of the values will become the stack
110 for the next action in the chain and are also available at `this.args`.
111
112 If `key` is specified, the second argument sent to `this` goes to
113 `this.vars[key]` in addition to the stack and `this.args`.
114 `this.vars` persists across all requests unless it is overwritten.
115
116 All arguments after `cb` will be bound to `cb`, which is useful because
117 `.bind()` makes you set `this`. If you pass in `Seq` in the arguments list,
118 it'll get transformed into `this` so that you can do:
119
120 ````javascript
121 Seq()
122 .seq(fs.readdir, __dirname, Seq)
123 .seq(function (files) { console.dir(files) })
124 ;
125 ````
126
127 which prints an array of files in `__dirname`.
128
129
130 .par(cb)
131 --------
132 .par(key, cb, *args)
133 --------------------
134
135 Use `par` to execute actions in parallel.
136 Chain multiple parallel actions together and collect all the responses on the
137 stack with a sequential operation like `seq`.
138
139 Each `par` sets one element in the stack with the second argument to `this()` in
140 the order in which it appears, so multiple `par`s can be chained together.
141
142 Like with `seq`, the first argument to `this()` should be the error value and
143 the second will get pushed to the stack. Further arguments are available in
144 `this.args`.
145
146 If `key` is specified, the result from the second argument send to `this()` goes
147 to `this.vars[key]`.
148 `this.vars` persists across all requests unless it is overwritten.
149
150 All arguments after `cb` will be bound to `cb`, which is useful because
151 `.bind()` makes you set `this`. Like `.seq()`, you can pass along `Seq` in these
152 bound arguments and it will get tranformed into `this`.
153
154
155 .catch(cb)
156 ----------
157
158 Catch errors. Whenever a function calls `this` with a non-falsy first argument,
159 the message propagates down the chain to the first `catch` it sees.
160 The callback `cb` fires with the error object as its first argument and the key
161 that the action that caused the error was populating, which may be undefined.
162
163 `catch` is a sequential action and further actions may appear after a `catch` in
164 a chain. If the execution reaches a `catch` in a chain and no error has occured,
165 the `catch` is skipped over.
166
167 For convenience, there is a default error handler at the end of all chains.
168 This default error handler looks like this:
169
170 ````javascript
171 .catch(function (err) {
172 console.error(err.stack ? err.stack : err)
173 })
174 ````
175
176
177 .forEach(cb)
178 ------------
179
180 Execute each action in the stack under the context of the chain object.
181 `forEach` does not wait for any of the actions to finish and does not itself
182 alter the stack, but the callback may alter the stack itself by modifying
183 `this.stack`.
184
185 The callback is executed `cb(x,i)` where `x` is the element and `i` is the
186 index.
187
188 `forEach` is a sequential operation like `seq` and won't run until all pending
189 parallel requests yield results.
190
191
192 .seqEach(cb)
193 ------------
194
195 Like `forEach`, call `cb` for each element on the stack, but unlike `forEach`,
196 `seqEach` waits for the callback to yield with `this` before moving on to the
197 next element in the stack.
198
199 The callback is executed `cb(x,i)` where `x` is the element and `i` is the
200 index.
201
202 If `this()` is supplied non-falsy error, the error propagates downward but any
203 other arguments are ignored. `seqEach` does not modify the stack itself.
204
205
206 .parEach(cb)
207 ------------
208 .parEach(limit, cb)
209 -------------------
210
211 Like `forEach`, calls cb for each element in the stack and doesn't wait for the
212 callback to yield a result with `this()` before moving on to the next iteration.
213 Unlike `forEach`, `parEach` waits for all actions to call `this()` before moving
214 along to the next action in the chain.
215
216 The callback is executed `cb(x,i)` where `x` is the element and `i` is the
217 index.
218
219 `parEach` does not modify the stack itself and errors supplied to `this()`
220 propagate.
221
222 Optionally, if limit is supplied to `parEach`, at most `limit` callbacks will be
223 active at a time.
224
225
226 .seqMap(cb)
227 -----------
228
229 Like `seqEach`, but collect the values supplied to `this` and set the stack to
230 these values.
231
232
233 .parMap(cb)
234 -----------
235 .parMap(limit, cb)
236 ------------------
237
238 Like `parEach`, but collect the values supplied to `this` and set the stack to
239 these values.
240
241
242 .seqFilter(cb)
243 -----------
244
245 Executes the callback `cb(x, idx)` against each element on the stack, waiting for the
246 callback to yield with `this` before moving on to the next element. If the callback
247 returns an error or a falsey value, the element will not be included in the resulting
248 stack.
249
250 Any errors from the callback are consumed and **do not** propagate.
251
252 Calls to `this.into(i)` will place the value, if accepted by the callback, at the index in
253 the results as if it were ordered at i-th index on the stack before filtering (with ties
254 broken by the values). This implies `this.into` will never override another stack value
255 even if their indices collide. Finally, the value will only actually appear at `i` if the
256 callback accepts or moves enough values before `i`.
257
258
259 .parFilter(cb)
260 -----------
261 .parFilter(limit, cb)
262 ------------------
263
264 Executes the callback `cb(x, idx)` against each element on the stack, but **does not**
265 wait for it to yield before moving on to the next element. If the callback returns an
266 error or a falsey value, the element will not be included in the resulting stack.
267
268 Any errors from the callback are consumed and **do not** propagate.
269
270 Calls to `this.into(i)` will place the value, if accepted by the callback, at the index in
271 the results as if it were ordered at i-th index on the stack before filtering (with ties
272 broken by the values). This implies `this.into` will never override another stack value
273 even if their indices collide. Finally, the value will only actually appear at `i` if the
274 callback accepts or moves enough values before `i`.
275
276 Optionally, if limit is supplied to `parEach`, at most `limit` callbacks will be
277 active at a time.
278
279
280 .do(cb)
281 -------
282 Create a new nested context. `cb`'s first argument is the previous context, and `this`
283 is the nested `Seq` object.
284
285
286 .flatten(fully=true)
287 --------------------
288
289 Recursively flatten all the arrays in the stack. Set `fully=false` to flatten
290 only one level.
291
292
293 .unflatten()
294 ------------
295
296 Turn the contents of the stack into a single array item. You can think of it
297 as the inverse of `flatten(false)`.
298
299
300 .extend([x,y...])
301 -----------------
302
303 Like `push`, but takes an array. This is like python's `[].extend()`.
304
305
306 .set(xs)
307 --------
308
309 Set the stack to a new array. This assigns the reference, it does not copy.
310
311
312 .empty()
313 --------
314
315 Set the stack to [].
316
317
318 .push(x,y...), .pop(), .shift(), .unshift(x), .splice(...), reverse()
319 ---------------------------------------------------------------------
320 .map(...), .filter(...), .reduce(...)
321 -------------------------------------
322
323 Executes an array operation on the stack.
324
325 The methods `map`, `filter`, and `reduce` are also proxies to their Array counterparts:
326 they have identical signatures to the Array methods, operate synchronously on the context
327 stack, and do not pass a Context object (unlike `seqMap` and `parMap`).
328
329 The result of the transformation is assigned to the context stack; in the case of `reduce`,
330 if you do not return an array, the value will be wrapped in one.
331
332 ````javascript
333 Seq([1, 2, 3])
334 .reduce(function(sum, x){ return sum + x; }, 0)
335 .seq(function(sum){
336 console.log('sum: %s', sum);
337 // sum: 6
338 console.log('stack is Array?', Array.isArray(this.stack));
339 // stack is Array: true
340 console.log('stack:', this.stack);
341 // stack: [6]
342 })
343 ;
344 ````
345
346
347
348
349 Explicit Parameters
350 -------------------
351
352 For environments like coffee-script or nested logic where threading `this` is
353 bothersome, you can use:
354
355 * seq_
356 * par_
357 * forEach_
358 * seqEach_
359 * parEach_
360 * seqMap_
361 * parMap_
362
363 which work exactly like their un-underscored counterparts except for the first
364 parameter to the supplied callback is set to the context, `this`.
365
366
367
368 Context Object
369 ==============
370
371 Each callback gets executed with its `this` set to a function in order to yield
372 results, error values, and control. The function also has these useful fields:
373
374 this.stack
375 ----------
376
377 The execution stack.
378
379 this.stack_
380 -----------
381
382 The previous stack value, mostly used internally for hackish purposes.
383
384 this.vars
385 ---------
386
387 A hash of key/values populated with `par(key, ...)`, `seq(key, ...)` and
388 `this.into(key)`.
389
390 this.into(key)
391 --------------
392
393 Instead of sending values to the stack, sets a key and returns `this`.
394 Use `this.into(key)` interchangeably with `this` for yielding keyed results.
395 `into` overrides the optional key set by `par(key, ...)` and `seq(key, ...)`.
396
397 this.ok
398 -------
399
400 Set the `err` to null. Equivalent to `this.bind(this, null)`.
401
402 this.args
403 ---------
404
405 `this.args` is like `this.stack`, but it contains all the arguments to `this()`
406 past the error value, not just the first. `this.args` is an array with the same
407 indices as `this.stack` but also stores keyed values for the last sequential
408 operation. Each element in `this.array` is set to `[].slice.call(arguments, 1)`
409 from inside `this()`.
410
411 this.error
412 ----------
413
414 This is used for error propagation. You probably shouldn't mess with it.
415
416
417
418 Installation
419 ============
420
421 With [npm](http://github.com/isaacs/npm), just do:
422
423 npm install seq
424
425 or clone this project on github:
426
427 git clone http://github.com/substack/node-seq.git
428
429 To run the tests with [expresso](http://github.com/visionmedia/expresso),
430 just do:
431
432 expresso
433
434
435
436 Dependencies
437 ------------
438
439 This module uses [chainsaw](http://github.com/substack/node-chainsaw)
440 When you `npm install seq` this dependency will automatically be installed.
441
442