thoughts/node_modules/mongoose/lib/promise.js
node_modules/mongoose/lib/promise.jsRaw
1/*!
2 * Module dependencies
3 */
4
5var MPromise = require('mpromise');
6var util = require('util');
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 * DEPRECATED. Mongoose 5.0 will use native promises by default (or bluebird,
17 * if native promises are not present) but still
18 * support plugging in your own ES6-compatible promises library. Mongoose 5.0
19 * will **not** support mpromise.
20 *
21 * @param {Function} fn a function which will be called when the promise is resolved that accepts `fn(err, ...){}` as signature
22 * @inherits mpromise https://github.com/aheckmann/mpromise
23 * @inherits NodeJS EventEmitter http://nodejs.org/api/events.html#events_class_events_eventemitter
24 * @event `err`: Emits when the promise is rejected
25 * @event `complete`: Emits when the promise is fulfilled
26 * @api public
27 * @deprecated
28 */
29
30function Promise(fn) {
31 MPromise.call(this, fn);
32}
33
34/**
35 * ES6-style promise constructor wrapper around mpromise.
36 *
37 * @param {Function} resolver
38 * @return {Promise} new promise
39 * @api public
40 */
41Promise.ES6 = function(resolver) {
42 var promise = new Promise();
43
44 // No try/catch for backwards compatibility
45 resolver(
46 function() {
47 promise.complete.apply(promise, arguments);
48 },
49 function(e) {
50 promise.error(e);
51 });
52
53 return promise;
54};
55
56/*!
57 * Inherit from mpromise
58 */
59
60Promise.prototype = Object.create(MPromise.prototype, {
61 constructor: {
62 value: Promise,
63 enumerable: false,
64 writable: true,
65 configurable: true
66 }
67});
68
69/*!
70 * ignore
71 */
72
73Promise.prototype.then = util.deprecate(Promise.prototype.then,
74 'Mongoose: mpromise (mongoose\'s default promise library) is deprecated, ' +
75 'plug in your own promise library instead: ' +
76 'http://mongoosejs.com/docs/promises.html');
77
78/**
79 * ES6-style `.catch()` shorthand
80 *
81 * @method catch
82 * @memberOf Promise
83 * @param {Function} onReject
84 * @return {Promise}
85 * @api public
86 */
87
88Promise.prototype.catch = function(onReject) {
89 return this.then(null, onReject);
90};
91
92/*!
93 * Override event names for backward compatibility.
94 */
95
96Promise.SUCCESS = 'complete';
97Promise.FAILURE = 'err';
98
99/**
100 * Adds `listener` to the `event`.
101 *
102 * 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.
103 *
104 * @see mpromise#on https://github.com/aheckmann/mpromise#on
105 * @method on
106 * @memberOf Promise
107 * @param {String} event
108 * @param {Function} listener
109 * @return {Promise} this
110 * @api public
111 */
112
113/**
114 * Rejects this promise with `reason`.
115 *
116 * If the promise has already been fulfilled or rejected, not action is taken.
117 *
118 * @see mpromise#reject https://github.com/aheckmann/mpromise#reject
119 * @method reject
120 * @memberOf Promise
121 * @param {Object|String|Error} reason
122 * @return {Promise} this
123 * @api public
124 */
125
126/**
127 * Rejects this promise with `err`.
128 *
129 * If the promise has already been fulfilled or rejected, not action is taken.
130 *
131 * Differs from [#reject](#promise_Promise-reject) by first casting `err` to an `Error` if it is not `instanceof Error`.
132 *
133 * @api public
134 * @param {Error|String} err
135 * @return {Promise} this
136 */
137
138Promise.prototype.error = function(err) {
139 if (!(err instanceof Error)) {
140 if (err instanceof Object) {
141 err = util.inspect(err);
142 }
143 err = new Error(err);
144 }
145 return this.reject(err);
146};
147
148/**
149 * Resolves this promise to a rejected state if `err` is passed or a fulfilled state if no `err` is passed.
150 *
151 * If the promise has already been fulfilled or rejected, not action is taken.
152 *
153 * `err` will be cast to an Error if not already instanceof Error.
154 *
155 * _NOTE: overrides [mpromise#resolve](https://github.com/aheckmann/mpromise#resolve) to provide error casting._
156 *
157 * @param {Error} [err] error or null
158 * @param {Object} [val] value to fulfill the promise with
159 * @api public
160 * @deprecated
161 */
162
163Promise.prototype.resolve = function(err) {
164 if (err) return this.error(err);
165 return this.fulfill.apply(this, Array.prototype.slice.call(arguments, 1));
166};
167
168/**
169 * Adds a single function as a listener to both err and complete.
170 *
171 * It will be executed with traditional node.js argument position when the promise is resolved.
172 *
173 * promise.addBack(function (err, args...) {
174 * if (err) return handleError(err);
175 * console.log('success');
176 * })
177 *
178 * Alias of [mpromise#onResolve](https://github.com/aheckmann/mpromise#onresolve).
179 *
180 * _Deprecated. Use `onResolve` instead._
181 *
182 * @method addBack
183 * @param {Function} listener
184 * @return {Promise} this
185 * @deprecated
186 */
187
188Promise.prototype.addBack = Promise.prototype.onResolve;
189
190/**
191 * Fulfills this promise with passed arguments.
192 *
193 * @method fulfill
194 * @receiver Promise
195 * @see https://github.com/aheckmann/mpromise#fulfill
196 * @param {any} args
197 * @api public
198 * @deprecated
199 */
200
201/**
202 * Fulfills this promise with passed arguments.
203 *
204 * Alias of [mpromise#fulfill](https://github.com/aheckmann/mpromise#fulfill).
205 *
206 * _Deprecated. Use `fulfill` instead._
207 *
208 * @method complete
209 * @receiver Promise
210 * @param {any} args
211 * @api public
212 * @deprecated
213 */
214
215Promise.prototype.complete = MPromise.prototype.fulfill;
216
217/**
218 * Adds a listener to the `complete` (success) event.
219 *
220 * Alias of [mpromise#onFulfill](https://github.com/aheckmann/mpromise#onfulfill).
221 *
222 * _Deprecated. Use `onFulfill` instead._
223 *
224 * @method addCallback
225 * @param {Function} listener
226 * @return {Promise} this
227 * @api public
228 * @deprecated
229 */
230
231Promise.prototype.addCallback = Promise.prototype.onFulfill;
232
233/**
234 * Adds a listener to the `err` (rejected) event.
235 *
236 * Alias of [mpromise#onReject](https://github.com/aheckmann/mpromise#onreject).
237 *
238 * _Deprecated. Use `onReject` instead._
239 *
240 * @method addErrback
241 * @param {Function} listener
242 * @return {Promise} this
243 * @api public
244 * @deprecated
245 */
246
247Promise.prototype.addErrback = Promise.prototype.onReject;
248
249/**
250 * 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.
251 *
252 * Conforms to [promises/A+](https://github.com/promises-aplus/promises-spec) specification.
253 *
254 * ####Example:
255 *
256 * var promise = Meetups.find({ tags: 'javascript' }).select('_id').exec();
257 * promise.then(function (meetups) {
258 * var ids = meetups.map(function (m) {
259 * return m._id;
260 * });
261 * return People.find({ meetups: { $in: ids }).exec();
262 * }).then(function (people) {
263 * if (people.length < 10000) {
264 * throw new Error('Too few people!!!');
265 * } else {
266 * throw new Error('Still need more people!!!');
267 * }
268 * }).then(null, function (err) {
269 * assert.ok(err instanceof Error);
270 * });
271 *
272 * @see promises-A+ https://github.com/promises-aplus/promises-spec
273 * @see mpromise#then https://github.com/aheckmann/mpromise#then
274 * @method then
275 * @memberOf Promise
276 * @param {Function} onFulFill
277 * @param {Function} onReject
278 * @return {Promise} newPromise
279 * @deprecated
280 */
281
282/**
283 * 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.
284 *
285 * ####Example:
286 *
287 * var p = new Promise;
288 * p.then(function(){ throw new Error('shucks') });
289 * setTimeout(function () {
290 * p.fulfill();
291 * // error was caught and swallowed by the promise returned from
292 * // p.then(). we either have to always register handlers on
293 * // the returned promises or we can do the following...
294 * }, 10);
295 *
296 * // this time we use .end() which prevents catching thrown errors
297 * var p = new Promise;
298 * var p2 = p.then(function(){ throw new Error('shucks') }).end(); // <--
299 * setTimeout(function () {
300 * p.fulfill(); // throws "shucks"
301 * }, 10);
302 *
303 * @api public
304 * @see mpromise#end https://github.com/aheckmann/mpromise#end
305 * @method end
306 * @memberOf Promise
307 * @deprecated
308 */
309
310/*!
311 * expose
312 */
313
314module.exports = Promise;