Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 275 lines (191 sloc) 10.93 kb
96da3b3 @kriszyp first commit
authored
1 Promised-IO is a cross-platform package for asynchronous promise-based IO. Promises
2 provide a simple robust mechanism asynchronicity with separation of concerns by encapsulating
3 eventual completion of an operation with side effect free callback registration
4 separate from call invocation. Promised-IO provides cross-platform
5 file, HTTP, and system interaction with promises for asynchronous operations.
6
7 Promised-IO also utilizes "lazy arrays" for progressively completed
7f20b74 @kriszyp Updated docs
authored
8 actions or for streaming of data. Lazy arrays provide all the standard iterative Array methods for
96da3b3 @kriszyp first commit
authored
9 receiving callbacks as actions are completed. Lazy arrays are utilized
c7f96d6 @kriszyp More docs
authored
10 for progressive loading of files and HTTP responses.
11
dfc57be @kriszyp Fix headers in README
authored
12 # promise
c7f96d6 @kriszyp More docs
authored
13
14 The promise module provides the primary tools for creating new promises and interacting
15 with promises. The promise API used by promised-io is the [Promises/A](http://wiki.commonjs.org/wiki/Promises/A)
16 proposal used by Dojo, jQuery, and other toolkits. Within promised-io, a promise is
17 defined as any object that implements the Promises/A API, that is they provide a
18 then() method that can take a callback. The then() methods definition is:
19
20 promise.then(fulfilledHandler, errorHandler);
21
22 Promises can originate from a variety of sources, and promised-io provides a constructor, Deferred,
23 to create promises.
24
dfc57be @kriszyp Fix headers in README
authored
25 ## when
cde06b9 @kriszyp more docs
authored
26
27 when = require("promised-io/promise");
28 when(promiseOrValue, fulfilledHandler, errorHandler);
29
30 You can pass a promise to the when() function and the fulfillment and error handlers will be registered for it's
31 completion *or* you can pass a regular value, and the fulfillment handler will be
32 immediately be called. The when function is a staple of working with promises because
33 it allows you to write code that normalizes interaction with synchronous values and asynchronous promises.
34 If you pass in a promise, a new promise for the result of execution of the callback handler
35 will be returned. If you pass a normal value, the return value will be the value returned
36 from the fulfilledHandler.
37
dfc57be @kriszyp Fix headers in README
authored
38 ## Deferred
c7f96d6 @kriszyp More docs
authored
39
40 deferred = require("promised-io/promise").Deferred(canceler);
41
42 The Deferred constructor is the primary mechanism for creating new promises. The Deferred
43 object is a form of a promise that with an interface for fulfilling or rejecting the promise.
44 A Deferred object is a means for a producer to resolve a promise and it also provides
45 a promise for consumers that are listening for the resolution of the promise. The basic
46 usage pattern looks like:
47
48 var Deferred = require("promised-io/promise").Deferred;
49 function delay(ms, value){
50 // create a new Deferred
51 var deferred = new Deferred();
52 setTimeout(function(){
53 // fulfill the deferred/promise, all listeners to the promise will be notified, and
54 // provided the value as the value of the promise
48cb696 @kriszyp Fix doc reference to fulfill() to be resolve() fixes #26
authored
55 deferred.resolve(value);
c7f96d6 @kriszyp More docs
authored
56 }, ms);
57 // return the promise that is associated with the Deferred object
58 return deferred.promise;
59 }
60
61 The Deferred can optional take a canceler function. This function will cause resulting
62 promises to have a cancel() method, and if the cancel() method is called, the
63 Deferred will be canceled and the canceler function will be called.
64
65 The Deferred object has the following methods and properties:
66
48cb696 @kriszyp Fix doc reference to fulfill() to be resolve() fixes #26
authored
67 ### resolve
c7f96d6 @kriszyp More docs
authored
68
48cb696 @kriszyp Fix doc reference to fulfill() to be resolve() fixes #26
authored
69 deferred.resolve(value);
c7f96d6 @kriszyp More docs
authored
70
71 This will fulfill the Deferred's promise with the provided value. The fulfillment listeners to the promise
72 will be notified.
73
dfc57be @kriszyp Fix headers in README
authored
74 ### reject
c7f96d6 @kriszyp More docs
authored
75
76 deferred.reject(error);
77
78 This will reject the Deferred's promise with the provided error. The error listeners to the promise
79 will be notified.
80
dfc57be @kriszyp Fix headers in README
authored
81 ### promise
c7f96d6 @kriszyp More docs
authored
82
83 This is the promise object associated with the Deferred instance. The promise object
84 will not have any of the Deferred's fulfill or reject methods, and only provides an interface
85 for listening. This can be safely provided to consumers without any chance of being modified.
86
dfc57be @kriszyp Fix headers in README
authored
87 ### cancel
c7f96d6 @kriszyp More docs
authored
88
89 deferred.cancel();
90
91 This will cancel the Deferred.
92
dfc57be @kriszyp Fix headers in README
authored
93 ## currentContext
c7f96d6 @kriszyp More docs
authored
94
95 One of the challenges with working asynchronous code is that there can be times when
96 you wish for some contextual state information to be preserved across multiple
97 asynchronous actions, without having to actually pass the state to each function in
98 the asynchronous chain. A common examples of such contextual state would be tracking
99 the current transaction, or the currently logged in user. Such state information could be
100 stored in a singleton (a module property or a global variable), but with asynchronous
101 actions being interleaved, this is unsuitable for tracking state across asynchronous continuations
102 of an action.
103
104 The promised-io package's promise module provides a facility for tracking state across
105 asynchronous operations. The promise module tracks the "currentContext" global variable,
106 and whatever value that was in the variable at the time a promise was created
107 will be restored when that promise is fulfilled (or rejected).
108
dfc57be @kriszyp Fix headers in README
authored
109 ## all
cde06b9 @kriszyp more docs
authored
110
111 group = require("promised-io/promise").all(arrayOfPromises);
112
113 The all() function can be passed an array of promises, or multiple promises as individual
114 arguments, and all() will return a new promise that represents the completed values when all the promises
115 have been fulfilled. This allows you to easily run multiple asynchronous actions, and wait
116 for the completion ("join") of all the actions. For example:
117
118 group = all(promise1, promise2, promise3);
119 group.then(function(array){
120 var value1 = array[0]; // result of promise1
121 var value2 = array[1]; // result of promise2
122 var value3 = array[2]; // result of promise3
123 });
124
dfc57be @kriszyp Fix headers in README
authored
125 ## first
cde06b9 @kriszyp more docs
authored
126
127 first = require("promised-io/promise").first(arrayOfPromises);
128
129 The first() function can be passed an array of promises, or multiple promises as individual
130 arguments, and first() will return a new promise that represents the completed value when the first promise
131 is fulfilled. This allows you to run multiple asynchronous actions get the first result. For example:
132
133 response = first(requestToMainSite, requestToMirrorSite1, requestToMirrorSite2);
134 response.then(function(response){
135 // response from the first site to respond
136 });
137
dfc57be @kriszyp Fix headers in README
authored
138 ## seq
cde06b9 @kriszyp more docs
authored
139
140 result = require("promised-io/promise").seq(arrayOfActionFunctions, startingValue);
141
142 The seq() function can be passed an array of functions, and seq() will execute each function
143 in sequence, waiting for the promise returned from each one to complete before executing
144 the next function. Each function will be called with the result of the last function (or the
145 startingValue for the first function).
146
dfc57be @kriszyp Fix headers in README
authored
147 ## whenPromise
cde06b9 @kriszyp more docs
authored
148
149 resultPromise = require("promised-io/promise").whenPromise(valueOrPromise, fulfillmentHandler, errorHandler);
150
151 The whenPromise() function behaves exactly like when() except that whenPromise
152 will always return a promise, even if a non-promise value is passed in.
153
dfc57be @kriszyp Fix headers in README
authored
154 ## allKeys
cde06b9 @kriszyp more docs
authored
155
156 group = require("promised-io/promise").allKeys(hashOfPromises);
157
158 Takes a hash of promises and returns a promise that is fulfilled once all the promises in the hash keys are fulfilled.
159
dfc57be @kriszyp Fix headers in README
authored
160 # fs
fb51d02 @kriszyp more docs
authored
161
162 This module provides promise-based access to the filesystem. The API of the fs module
163 basically follows the [Node File System module API](http://nodejs.org/docs/latest/api/fs.html).
164 Each of the asynchronous functions in the Node's FS API is reflected with a corresponding
165 function in the fs module that returns a promise (instead of requiring a callback argument in the initial call).
166 For example, where Node has fs.rename(path1, path2, [callback]), with promised-io
167 you would call it:
168
169 var fs = require("promised-io/fs").fs;
170 fs.rename(path1, path2).then(function(){
171 // finished renaming
172 });
173
174 One function that does differ from NodeJS's fs module is the open() function.
175
dfc57be @kriszyp Fix headers in README
authored
176 ## open
fb51d02 @kriszyp more docs
authored
177
178 var file = require("promised-io/fs").open(path, mode);
179
180 The open() function differs from simply being a promise-based version of the Node's
181 open() function in that it immediately returns (even though the opening of the
182 file is asynchronous) a file object that be used to read from and write to the file.
183
184 To write to the file object, we can write:
185
186 promiseForCompletion = file.write(contents, options, encoding);
187
188 To close the file object, we can write:
189
190 promiseForCompletion = file.close();
191
192 We can also use file.writeSync and file.closeSync for the synchronous versions of these
193 functions.
194
195 The file object is also a lazy array, which means you can read from the file using
196 standard array methods. To asynchronously read the contents of a file, you can do:
197
198 file.forEach(function(chunk){
199 // called for each chunk of the file until the end of the file is reached.
200 });
201
dfc57be @kriszyp Fix headers in README
authored
202 # lazy-array
fb51d02 @kriszyp more docs
authored
203
204 The lazy-array module provides the functionality for creating and using lazy arrays,
205 which are objects that implement the interface of the standard iterative array methods for accessing
206 streams of data. Array methods can be called and they will be
207 asynchronously executed as data is available. Lazy arrays are powerful way to model
208 asynchronous streams since they can used like other JavaScript arrays.
209
210 Typically you don't need to directly use this module, rather other IO modules like the
211 file system (fs) and HTTP (http-client) modules provide lazy arrays that you can interact
212 with. For example, we could search through a file for the string "lazy" and stop reading
213 once we find it using the standard some() method:
214
215 if(file.some(function(chunk){
216 return chunk.toString().indexOf("lazy") > -1;
217 }));
218
219 Lazy arrays include the follow standard array methods, providing access to the data
220 as the stream data becomes available:
221
222 * filter
223 * every
224 * some
225 * forEach
226 * concat
227 * map
228
229 And also these standard methods, although these must fully fetch the stream:
230
231 * join
232 * sort
233 * reverse
234
235 Also the following additional methods are available on lazy arrays:
236
237 * toRealArray() - This will fetch all the data and return it as a real JavaScript array.
238 * get(index) - This retrieves an element by index.
239
dfc57be @kriszyp Fix headers in README
authored
240 ## LazyArray
fb51d02 @kriszyp more docs
authored
241
242 lazyArray = require("promised-io/lazy-array").LazyArray({
243 some: someImplementation,
244 length: arrayLength
245 });
246
247 This function is a constructor for creating your own lazy arrays. With this function,
248 you don't need to implement the entire set of array methods, you can just implement
249 the some() method and provide an array length, if it is known.
250
dfc57be @kriszyp Fix headers in README
authored
251 ## first
fb51d02 @kriszyp more docs
authored
252
253 first = require("promised-io/lazy-array").first(lazyArray);
254
255 This function returns the first element in a lazy array.
256
dfc57be @kriszyp Fix headers in README
authored
257 ## last
fb51d02 @kriszyp more docs
authored
258
259 last = require("promised-io/lazy-array").last(lazyArray);
260
261 This function returns the last element in a lazy array.
262
dfc57be @kriszyp Fix headers in README
authored
263 ## get
fb51d02 @kriszyp more docs
authored
264
265 item = require("promised-io/lazy-array").get(index);
266
267 This function returns the an element by index from a lazy array.
268
dfc57be @kriszyp Fix headers in README
authored
269 # http-client
270
271 This module provides convenient promise-based access to making HTTP requests.
96da3b3 @kriszyp first commit
authored
272
273 Promised-IO is part of the Persevere project, and therefore is licensed under the
274 AFL or BSD license. The Persevere project is administered under the Dojo foundation,
275 and all contributions require a Dojo CLA.
Something went wrong with that request. Please try again.