Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 150 lines (115 sloc) 6.478 kb
e707da2 @kriszyp Updated docs
authored
1 MIT License.
51bd882 @kriszyp More work on node-promise
authored
2
c0eb7bc @kriszyp Updated docs to point to promised-io
authored
3 The node-promise project provides a complete promise implementation. Promises provide a clean separation
01c45a3 @kriszyp More doc updates
authored
4 of concerns between asynchronous behavior and the interface so asynchronous
5 functions can be called without callbacks, and callback interaction can be
c0eb7bc @kriszyp Updated docs to point to promised-io
authored
6 done on the generic promise interface. The node-promise package provides just a promise implementation, however, https://github.com/kriszyp/promised-io is recommended for more complete promise-based IO functionality. The promised-io includes the promise implementation from node-promise, as well as wrappers around Node's filesystem and other system I/O APIs for consistent promise-based interaction.
7
8 The node-promise module features a promise implementation with:
f83e480 @kriszyp More docs
authored
9
10 * Chainable promises
11 * Promises throw errors if an error handler is not provided
12 * CommonJS promise proposal [1] compliant
13 * Immutable once fulfilled to reduce possible side-effects
14 * Promises can be used securely (as separate resolver/promise pairs in
15 ocap situations)
16 * Backwards compatibility where possible (addCallback, addErrback,
17 emitSuccess, and emitError should still behave as expected)
18
19 Utility functions, including:
e04bb52 @kriszyp Fix more spacing
authored
20
f83e480 @kriszyp More docs
authored
21 * when() - Normalization of sync (normal values) and async (promises)
1721ec6 @MaxMotovilov Update README.md
MaxMotovilov authored
22 * all() - Create a promise that accumulate multiple concurrent promises (failed promises resolve to Error objects)
15c5937 @MaxMotovilov Update README.md
MaxMotovilov authored
23 * allOrNone() - Ditto, but the first promise to fail causes the composition to fail as well
f83e480 @kriszyp More docs
authored
24 * first() - Find the first promise to be fulfilled in a group of promises
25 * seq() - Sequentially execute a set of promise returning functions
26 * delay() - Returns a promise that is fulfilled after a given amount of time
27 * execute() - Executes a function that takes a callback and returns a
28 promise (thank you Benjamin Thomas for providing this)
29
2f317b8 @kriszyp Minor doc update
authored
30 Much of this is adapted from Tyler Close's ref_send and Kris Kowal's work on promises.
31
c0eb7bc @kriszyp Updated docs to point to promised-io
authored
32 Some quick examples from test-promise.js (again, it is recommended that you use http://github.com/kriszyp/promised-io for file and other I/O interaction):
1cb6865 @blakmatrix [fix] Changed require('util') to require('util') for compatibility with ...
blakmatrix authored
33 util = require('util');
e04bb52 @kriszyp Fix more spacing
authored
34 var fs = require('./fs-promise');
f83e480 @kriszyp More docs
authored
35
36 // open a file and read it
37 fs.open("fs-promise.js", process.O_RDONLY).then(function(fd){
38 return fs.read(fd, 4096);
39 }).then(function(args){
1cb6865 @blakmatrix [fix] Changed require('util') to require('util') for compatibility with ...
blakmatrix authored
40 util.puts(args[0]); // print the contents of the file
f83e480 @kriszyp More docs
authored
41 });
42
43 // does the same thing
1cb6865 @blakmatrix [fix] Changed require('util') to require('util') for compatibility with ...
blakmatrix authored
44 fs.readFile("fs-promise.js").addCallback(util.puts);
f83e480 @kriszyp More docs
authored
45
9bd3a64 @kriszyp Updated docs
authored
46 A default Promise constructor can be used to create a self-resolving deferred/promise:
47
48 var Promise = require("promise").Promise;
49 var promise = new Promise();
50 asyncOperation(function(){
b439d8c @davidcalhoun succesful -> successful
davidcalhoun authored
51 Promise.resolve("successful result");
9bd3a64 @kriszyp Updated docs
authored
52 });
53 promise -> given to the consumer
54
e04bb52 @kriszyp Fix more spacing
authored
55 A consumer can use the promise:
9bd3a64 @kriszyp Updated docs
authored
56
e04bb52 @kriszyp Fix more spacing
authored
57 promise.then(function(result){
9bd3a64 @kriszyp Updated docs
authored
58 ... when the action is complete this is executed ...
e04bb52 @kriszyp Fix more spacing
authored
59 },
60 function(error){
9bd3a64 @kriszyp Updated docs
authored
61 ... executed when the promise fails
e04bb52 @kriszyp Fix more spacing
authored
62 });
9bd3a64 @kriszyp Updated docs
authored
63
64 Alternately, a provider can create a deferred and resolve it when it completes an action.
65 The deferred object a promise object that provides a separation of consumer and producer to protect
66 promises from being fulfilled by untrusted code.
67
68 var defer = require("promise").defer;
69 var deferred = defer();
70 asyncOperation(function(){
71 deferred.resolve("succesful result");
72 });
73 deferred.promise -> given to the consumer
74
75 Another way that a consumer can use promises:
76
77 var when = require("promise").when;
78 when(promise,function(result){
79 ... when the action is complete this is executed ...
80 },
81 function(error){
82 ... executed when the promise fails
83 });
84
85 More examples:
86
87 function printFirstAndList(itemsDeferred){
1cb6865 @blakmatrix [fix] Changed require('util') to require('util') for compatibility with ...
blakmatrix authored
88 findFirst(itemsDeferred).then(util.puts);
89 findLast(itemsDeferred).then(util.puts);
9bd3a64 @kriszyp Updated docs
authored
90 }
91 function findFirst(itemsDeferred){
92 return itemsDeferred.then(function(items){
93 return items[0];
94 });
95 }
96 function findLast(itemsDeferred){
97 return itemsDeferred.then(function(items){
98 return items[items.length];
99 });
100 }
101
102 And now you can do:
103
104 printFirstAndLast(someAsyncFunction());
105
106
51bd882 @kriszyp More work on node-promise
authored
107 The workhorse function of this library is the "when" function, which provides a means for normalizing interaction with values and functions that may be a normal synchronous value, or may be a promise (asynchronously fulfilled). The when() function takes a value that may be a promise or a normal value for the first function, and when the value is ready executes the function provided as the second argument (immediately in the case of a non-promise normal value). The value returned from when() is the result of the execution of the provided function, and returns a promise if provided a promise or synchronously returns a normal value if provided a non-promise value. This makes it easy to "chain" computations together. This allows us to write code that is agnostic to sync/async interfaces:
108
3023b69 @kriszyp Fix spacing in readme
authored
109 var when = require("promise").when;
110 function printFirstAndLast(items){
111 // print the first and last item
1cb6865 @blakmatrix [fix] Changed require('util') to require('util') for compatibility with ...
blakmatrix authored
112 when(findFirst(items), util.puts);
113 when(findLast(items), util.puts);
3023b69 @kriszyp Fix spacing in readme
authored
114 }
115 function findFirst(items){
116 // return the first item
117 return when(items, function(items){
118 return items[0];
119 });
120 }
121 function findLast(items){
122 // return the last item
123 return when(items, function(items){
124 return items[items.length - 1];
125 });
126 }
51bd882 @kriszyp More work on node-promise
authored
127
128 Now we can do:
129
3023b69 @kriszyp Fix spacing in readme
authored
130 > printFirstAndLast([1,2,3,4,5]);
131 1
132 5
51bd882 @kriszyp More work on node-promise
authored
133
134 And we can also provide asynchronous promise:
135
3023b69 @kriszyp Fix spacing in readme
authored
136 var promise = new process.Promise();
137 > printFirstAndLast(promise);
51bd882 @kriszyp More work on node-promise
authored
138
139 (nothing printed yet)
140
3023b69 @kriszyp Fix spacing in readme
authored
141 > promise.emitSuccess([2,4,6,8,10]);
142 2
143 10
51bd882 @kriszyp More work on node-promise
authored
144
145
5200f63 @kriszyp Updated docs
authored
146 The "all" function is intended to provide a means for waiting for the completion of an array of promises. The "all" function should be passed an array of promises, and it returns an promise that is fulfilled once all the promises in the array are fulfilled. The returned promise's resolved value will be an array with the resolved values of all of the promises in the passed in array.
147
148 The "first" function is intended to provide a means for waiting for the completion of the first promise in an array of promises to be fulfilled. The "first" function should be passed an array of promises, and it returns an promise that is fulfilled once the first promise in the array is fulfilled. The returned promise's resolved value will be the resolved value of the first fulfilled promise.
149
Something went wrong with that request. Please try again.