1
  2/*!
  3 * Module dependencies
  4 */
  5
  6var MPromise = require('mpromise');
  7
  8/**
  9 * Promise constructor.
 10 *
 11 * Promises are returned from executed queries. Example:
 12 *
 13 *     var query = Candy.find({ bar: true });
 14 *     var promise = query.exec();
 15 *
 16 * @param {Function} fn a function which will be called when the promise is resolved that accepts `fn(err, ...){}` as signature
 17 * @inherits mpromise https://github.com/aheckmann/mpromise
 18 * @inherits NodeJS EventEmitter http://nodejs.org/api/events.html#events_class_events_eventemitter
 19 * @event `err`: Emits when the promise is rejected
 20 * @event `complete`: Emits when the promise is fulfilled
 21 * @api public
 22 */
 23
 24function Promise (fn) {
 25  MPromise.call(this, fn);
 26}
 27
 28/*!
 29 * Inherit from mpromise
 30 */
 31
 32Promise.prototype = Object.create(MPromise.prototype, {
 33    constructor: {
 34        value: Promise
 35      , enumerable: false
 36      , writable: true
 37      , configurable: true
 38    }
 39});
 40
 41/*!
 42 * Override event names for backward compatibility.
 43 */
 44
 45Promise.SUCCESS = 'complete';
 46Promise.FAILURE = 'err';
 47
 48/**
 49 * Adds `listener` to the `event`.
 50 *
 51 * If `event` is either the success or failure event and the event has already been emitted, the`listener` is called immediately and passed the results of the original emitted event.
 52 *
 53 * @see mpromise#on https://github.com/aheckmann/mpromise#on
 54 * @method on
 55 * @memberOf Promise
 56 * @param {String} event
 57 * @param {Function} listener
 58 * @return {Promise} this
 59 * @api public
 60 */
 61
 62/**
 63 * Rejects this promise with `reason`.
 64 *
 65 * If the promise has already been fulfilled or rejected, not action is taken.
 66 *
 67 * @see mpromise#reject https://github.com/aheckmann/mpromise#reject
 68 * @method reject
 69 * @memberOf Promise
 70 * @param {Object|String|Error} reason
 71 * @return {Promise} this
 72 * @api public
 73 */
 74
 75/**
 76 * Rejects this promise with `err`.
 77 *
 78 * If the promise has already been fulfilled or rejected, not action is taken.
 79 *
 80 * Differs from [#reject](#promise_Promise-reject) by first casting `err` to an `Error` if it is not `instanceof Error`.
 81 *
 82 * @api public
 83 * @param {Error|String} err
 84 * @return {Promise} this
 85 */
 86
 87Promise.prototype.error = function (err) {
 88  if (!(err instanceof Error)) err = new Error(err);
 89  return this.reject(err);
 90}
 91
 92/**
 93 * Resolves this promise to a rejected state if `err` is passed or a fulfilled state if no `err` is passed.
 94 *
 95 * If the promise has already been fulfilled or rejected, not action is taken.
 96 *
 97 * `err` will be cast to an Error if not already instanceof Error.
 98 *
 99 * _NOTE: overrides [mpromise#resolve](https://github.com/aheckmann/mpromise#resolve) to provide error casting._
100 *
101 * @param {Error} [err] error or null
102 * @param {Object} [val] value to fulfill the promise with
103 * @api public
104 */
105
106Promise.prototype.resolve = function (err, val) {
107  if (err) return this.error(err);
108  return this.fulfill(val);
109}
110
111/**
112 * Adds a single function as a listener to both err and complete.
113 *
114 * It will be executed with traditional node.js argument position when the promise is resolved. 
115 *
116 *     promise.addBack(function (err, args...) {
117 *       if (err) return handleError(err);
118 *       console.log('success');
119 *     })
120 *
121 * Alias of [mpromise#onResolve](https://github.com/aheckmann/mpromise#onresolve).
122 *
123 * @method addBack
124 * @param {Function} listener
125 * @return {Promise} this
126 */
127
128Promise.prototype.addBack = Promise.prototype.onResolve;
129
130/**
131 * Fulfills this promise with passed arguments.
132 *
133 * Alias of [mpromise#fulfill](https://github.com/aheckmann/mpromise#fulfill).
134 *
135 * @method complete
136 * @param {any} args
137 * @api public
138 */
139
140Promise.prototype.complete = MPromise.prototype.fulfill;
141
142/**
143 * Adds a listener to the `complete` (success) event.
144 *
145 * Alias of [mpromise#onFulfill](https://github.com/aheckmann/mpromise#onfulfill).
146 *
147 * @method addCallback
148 * @param {Function} listener
149 * @return {Promise} this
150 * @api public
151 */
152
153Promise.prototype.addCallback = Promise.prototype.onFulfill;
154
155/**
156 * Adds a listener to the `err` (rejected) event.
157 *
158 * Alias of [mpromise#onReject](https://github.com/aheckmann/mpromise#onreject).
159 *
160 * @method addErrback
161 * @param {Function} listener
162 * @return {Promise} this
163 * @api public
164 */
165
166Promise.prototype.addErrback = Promise.prototype.onReject;
167
168/**
169 * Creates a new promise and returns it. If `onFulfill` or `onReject` are passed, they are added as SUCCESS/ERROR callbacks to this promise after the nextTick.
170 *
171 * Conforms to [promises/A+](https://github.com/promises-aplus/promises-spec) specification.
172 *
173 * ####Example:
174 *
175 *     var promise = Meetups.find({ tags: 'javascript' }).select('_id').exec();
176 *     promise.then(function (meetups) {
177 *       var ids = meetups.map(function (m) {
178 *         return m._id;
179 *       });
180 *       return People.find({ meetups: { $in: ids }).exec();
181 *     }).then(function (people) {
182 *       if (people.length < 10000) {
183 *         throw new Error('Too few people!!!');
184 *       } else {
185 *         throw new Error('Still need more people!!!');
186 *       }
187 *     }).then(null, function (err) {
188 *       assert.ok(err instanceof Error);
189 *     });
190 *
191 * @see promises-A+ https://github.com/promises-aplus/promises-spec
192 * @see mpromise#then https://github.com/aheckmann/mpromise#then
193 * @method then
194 * @memberOf Promise
195 * @param {Function} onFulFill
196 * @param {Function} onReject
197 * @return {Promise} newPromise
198 */
199
200/**
201 * Signifies that this promise was the last in a chain of `then()s`: if a handler passed to the call to `then` which produced this promise throws, the exception will go uncaught.
202 *
203 * ####Example:
204 *
205 *     var p = new Promise;
206 *     p.then(function(){ throw new Error('shucks') });
207 *     setTimeout(function () {
208 *       p.fulfill();
209 *       // error was caught and swallowed by the promise returned from
210 *       // p.then(). we either have to always register handlers on
211 *       // the returned promises or we can do the following...
212 *     }, 10);
213 *
214 *     // this time we use .end() which prevents catching thrown errors
215 *     var p = new Promise;
216 *     var p2 = p.then(function(){ throw new Error('shucks') }).end(); // <--
217 *     setTimeout(function () {
218 *       p.fulfill(); // throws "shucks"
219 *     }, 10);
220 *
221 * @api public
222 * @see mpromise#end https://github.com/aheckmann/mpromise#end
223 * @method end
224 * @memberOf Promise
225 */
226
227/*!
228 * expose
229 */
230
231module.exports = Promise;