Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 245 lines (146 sloc) 4.277 kb
0606b5d9 »
2012-02-06 cleaned up
1
6a652b37 »
2012-02-07 updated readme
2
3 Outcome.js is a simple flow-control library which wraps your `.callback(err, result)` functions.
0606b5d9 »
2012-02-06 cleaned up
4
e3c72e39 »
2012-02-06 updated readme
5 ### Motiviation
6
7 - Write less code for handling errors.
8 - Easier to maintain.
b745ac5f »
2012-02-06 updated readme
9 - Keep error handling code separate.
75f16883 »
2011-12-11 initial push
10
649c7dc6 »
2011-12-14 initial push
11
6a7f6ee5 »
2012-02-10 added example
12
c5e771f9 »
2012-02-06 updated readme
13 ### Basic Example
14
e3c72e39 »
2012-02-06 updated readme
15 Here's the traditional method of handling errors:
16
649c7dc6 »
2011-12-14 initial push
17 ```javascript
18
22ab8920 »
2012-02-06 updated readme examples
19 var fs = require('fs');
20
1b0e0d9a »
2012-02-06 updated readme examples
21 function doSomething(path, callback) {
75f16883 »
2011-12-11 initial push
22
1b0e0d9a »
2012-02-06 updated readme examples
23 fs.realpath(path, onRealPath);
75f16883 »
2011-12-11 initial push
24
1b0e0d9a »
2012-02-06 updated readme examples
25 function onRealPath(err, path) {
26 if(err) return callback(err);
27 fs.lstat(path, onStat);
28 }
29
30 function onStat(err, stats) {
31 if(err) return callback(err);
32 callback(err, stats);
33 }
34
35 }
31feba63 »
2012-02-06 updated readme examples
36
37bf0fe0 »
2012-02-06 s updated example
37 doSomething('/path/to/something', function(err, result) {
38
e3c72e39 »
2012-02-06 updated readme
39 //inline with result handling - yuck
37bf0fe0 »
2012-02-06 s updated example
40 if(err) {
b2159e09 »
2012-02-06 updated readme
41
37bf0fe0 »
2012-02-06 s updated example
42 //do something with error
43 return;
44 }
45
46 //do something with result
47 })
1b0e0d9a »
2012-02-06 updated readme examples
48 ```
49
b2159e09 »
2012-02-06 updated readme
50 The outcome.js way:
8c02d272 »
2011-12-14 updated readme
51
52 ```javascript
22ab8920 »
2012-02-06 updated readme examples
53
54 var fs = require('fs'),
55 outcome = require('outcome');
56
1b0e0d9a »
2012-02-06 updated readme examples
57 function doSomething(path, callback) {
5f02c4be »
2012-02-06 updated readme examples
58
59 //wrap the callback around an error handler so any errors in *this* function
60 //bubble back up to the callback - I'm lazy and I don't wanna write this stuff...
7336ca70 »
2012-02-06 updated readme examples
61 var on = outcome.error(callback);
1b0e0d9a »
2012-02-06 updated readme examples
62
5666e7e4 »
2012-02-06 updated readme examples
63 //on success, call onRealPath. Any errors caught will be sent back
64 //automatically
7336ca70 »
2012-02-06 updated readme examples
65 fs.realpath(path, on.success(onRealPath));
1b0e0d9a »
2012-02-06 updated readme examples
66
67 function onRealPath(path) {
68
98e59b54 »
2012-02-07 updated readme
69 //ONLY call onStat if we've successfuly grabbed the file stats
7336ca70 »
2012-02-06 updated readme examples
70 fs.lstat(path, on.success(onStat));
1b0e0d9a »
2012-02-06 updated readme examples
71 }
72
73 function onStat(stats) {
74
5666e7e4 »
2012-02-06 updated readme examples
75 //no errors, so send a response back
76 callback(null, stats);
1b0e0d9a »
2012-02-06 updated readme examples
77 }
78 }
31feba63 »
2012-02-06 updated readme examples
79
80
37bf0fe0 »
2012-02-06 s updated example
81 var on = outcome.error(function(error) {
82 //do something with error
1dfa9783 »
2012-02-06 typo
83 }));
31feba63 »
2012-02-06 updated readme examples
84
37bf0fe0 »
2012-02-06 s updated example
85 doSomething('/path/to/something', on.success(function(response) {
86 //do something with result
87 }));
31feba63 »
2012-02-06 updated readme examples
88
1b0e0d9a »
2012-02-06 updated readme examples
89 ```
90
91 ## API
92
93 ### outcome(listeners)
94
bc30b4f3 »
2012-02-06 updated readme examples
95 - `listeners` - Object of listeners you want to attach to outcome.
1b0e0d9a »
2012-02-06 updated readme examples
96
97 ```javascript
98
99 var onResult = outcome({
100
101 //called when an error is caught
ca4a09ef »
2012-01-30 changed done to callback
102 error: function(error) {
1b0e0d9a »
2012-02-06 updated readme examples
103
ca4a09ef »
2012-01-30 changed done to callback
104 },
1b0e0d9a »
2012-02-06 updated readme examples
105
106 //called when an error is NOT present
107 success: function(result, thirdParam) {
ca4a09ef »
2012-01-30 changed done to callback
108
1b0e0d9a »
2012-02-06 updated readme examples
109 },
8c02d272 »
2011-12-14 updated readme
110
1b0e0d9a »
2012-02-06 updated readme examples
111 //called back when an error, or result is present
112 callback: function(err, result, thirdParam) {
113
114 }
115 })
48306827 »
2011-12-30 refactored
116
8c02d272 »
2011-12-14 updated readme
117 ```
09567e5e »
2011-12-12 update readme
118
da3fe068 »
2012-02-06 updated readme examples
119 As shown in the example above, you can also wrap-around an existing callback:
120
121 ```javascript
122 var onResult = outcome.error(function(error) {
123
124 }).
125 success(function(result, thirdParam) {
126
127 }).
128 callback(function(error, result, thirdParam) {
129
130 });
131 ```
132
7336ca70 »
2012-02-06 updated readme examples
133
15a563b5 »
2011-12-11 updated readme
134 By default, any unhandled errors are thrown. To get around this, you'll need to listen for an `unhandledError`:
75f16883 »
2011-12-11 initial push
135
136 ```javascript
ce732856 »
2011-12-11 updated readme
137 outcome.on('unhandledError', function(error) {
138 //report bugs here..., then throw again.
75f16883 »
2011-12-11 initial push
139 });
140
141
c1aa1348 »
2011-12-30 changed result to success
142 //fails
470131c8 »
2012-02-06 updated readme examples
143 fs.stat('s'+__filename, outcome.success(function() {
1b0e0d9a »
2012-02-06 updated readme examples
144
145
146 });
75f16883 »
2011-12-11 initial push
147 ```
148
31feba63 »
2012-02-06 updated readme examples
149
150
ca4a09ef »
2012-01-30 changed done to callback
151 ### .callback()
dd5aaa90 »
2011-12-11 updated readme
152
c1aa1348 »
2011-12-30 changed result to success
153 Called when on error/success. `Same as function(err, data) { }`
dd5aaa90 »
2011-12-11 updated readme
154
da3fe068 »
2012-02-06 updated readme examples
155 Here's a redundant example:
156
a0109053 »
2011-12-30 updated readme
157 ```javascript
158
159 fs.stat(__filename, outcome.error(function(err) {
160 //handle error
c1aa1348 »
2011-12-30 changed result to success
161 }).success(function(data) {
a0109053 »
2011-12-30 updated readme
162 //handle result
ca4a09ef »
2012-01-30 changed done to callback
163 }.callback(function(err, result) {
da3fe068 »
2012-02-06 updated readme examples
164 //called on fn complete regardless if there's an error, or success
165 }));
a0109053 »
2011-12-30 updated readme
166
167 ```
dd5aaa90 »
2011-12-11 updated readme
168
c1aa1348 »
2011-12-30 changed result to success
169 ### .success(fn)
649c7dc6 »
2011-12-14 initial push
170
31feba63 »
2012-02-06 updated readme examples
171 Called on Success.
649c7dc6 »
2011-12-14 initial push
172
2ce0eb9d »
2011-12-14 initial push
173 ```javascript
e6ee553e »
2012-02-06 updated readme examples
174 var onOutcome = outcome.success(function(data, anotherParam, andAnotherParam) {
175 //handle success data
649c7dc6 »
2011-12-14 initial push
176 });
a0109053 »
2011-12-30 updated readme
177
e6ee553e »
2012-02-06 updated readme examples
178 onOutcome(null, "success!", "more data!", "more results..");
2ce0eb9d »
2011-12-14 initial push
179 ```
649c7dc6 »
2011-12-14 initial push
180
48306827 »
2011-12-30 refactored
181 ### .error(fn)
75f16883 »
2011-12-11 initial push
182
31feba63 »
2012-02-06 updated readme examples
183 Called on error.
649c7dc6 »
2011-12-14 initial push
184
2ce0eb9d »
2011-12-14 initial push
185 ```javascript
a0109053 »
2011-12-30 updated readme
186
c1aa1348 »
2011-12-30 changed result to success
187 var onOutcome = outcome.error(function(err) {
a0109053 »
2011-12-30 updated readme
188
649c7dc6 »
2011-12-14 initial push
189 });
a0109053 »
2011-12-30 updated readme
190
da3fe068 »
2012-02-06 updated readme examples
191 onOutcome(new Error("something went wrong..."));
c1aa1348 »
2011-12-30 changed result to success
192 ```
193
194 ### .handle(fn)
195
196 Custom response handler
197
198 ```javascript
199
200 outcome.handle(function(response) {
201
202 if(response.errors) this.error(response);
203 if(response.data) this.success(response);
204 });
205
206 ```
207
31feba63 »
2012-02-06 updated readme examples
208
892f1dfb »
2012-02-07 updated readme
209 ## CoffeeScript Example
bb65a0da »
2012-02-06 updated readme
210
211 ```coffeescript
212
213 outcome = require "outcome"
214
215 doSomething(path, callback) ->
216
217 on = outcome.error callback
218
219 # first get the realpath
220 fs.realpath path, on.success onRealPath
221
222 # on real path, get stats
4f891bd4 »
2012-02-07 updated readme
223 onRealPath(path) -> fs.lstat path, on.success onStat
bb65a0da »
2012-02-06 updated readme
224
225 # on stat, finish
226 onStat(stats) -> callback null, stats
227
228
229 # call do something
230 doSomething '/path/to/something', outcome
231
232 success: (statis) ->
233 # do something
234
235 error: (error) ->
236 # do something else
237
238
239 ```
240
241
31feba63 »
2012-02-06 updated readme examples
242 ### Note
243
244 Calling `.error()`, `.success()`, `.callback()` generates a new function which copies the previous listeners.
a9098e46 »
2012-02-06 updated readme examples
245 Checkout [fs-test](outcome.js/blob/master/examples/fs-test.js) in the [examples](outcome.js/blog/master/examples) folder.
Something went wrong with that request. Please try again.