// vim:ts=4:sts=4:sw=4: /*! * * Copyright 2009-2012 Kris Kowal under the terms of the MIT * license found at http://github.com/kriskowal/q/raw/master/LICENSE * * With parts by Tyler Close * Copyright 2007-2009 Tyler Close under the terms of the MIT X license found * at http://www.opensource.org/licenses/mit-license.html * Forked at ref_send.js version: 2009-05-11 * * With parts by Mark Miller * Copyright (C) 2011 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * */ (function (definition) { // Turn off strict mode for this function so we can assign to global.Q /* jshint strict: false */ // This file will function properly as a <script> tag, or a module // using CommonJS and NodeJS or RequireJS module formats. In // Common/Node/RequireJS, the module exports the Q API and when // executed as a simple <script>, it creates a Q global instead. // Montage Require if (typeof bootstrap === "function") { bootstrap("promise", definition); // CommonJS } else if (typeof exports === "object") { module.exports = definition(); // RequireJS } else if (typeof define === "function" && define.amd) { define(definition); // SES (Secure EcmaScript) } else if (typeof ses !== "undefined") { if (!ses.ok()) { return; } else { ses.makeQ = definition; } // <script> } else { Q = definition(); } })(function () { "use strict"; var hasStacks = false; try { throw new Error(); } catch (e) { hasStacks = !!e.stack; } // All code after this point will be filtered from stack traces reported // by Q. var qStartingLine = captureLine(); var qFileName; // shims // used for fallback in "allResolved" var noop = function () {}; // Use the fastest possible means to execute a task in a future turn // of the event loop. var nextTick =(function () { // linked list of tasks (single, with head node) var head = {task: void 0, next: null}; var tail = head; var flushing = false; var requestTick = void 0; var isNodeJS = false; function flush() { /* jshint loopfunc: true */ while (head.next) { head = head.next; var task = head.task; head.task = void 0; var domain = head.domain; if (domain) { head.domain = void 0; domain.enter(); } try { task(); } catch (e) { if (isNodeJS) { // In node, uncaught exceptions are considered fatal errors. // Re-throw them synchronously to interrupt flushing! // Ensure continuation if the uncaught exception is suppressed // listening "uncaughtException" events (as domains does). // Continue in next event to avoid tick recursion. if (domain) { domain.exit(); } setTimeout(flush, 0); if (domain) { domain.enter(); } throw e; } else { // In browsers, uncaught exceptions are not fatal. // Re-throw them asynchronously to avoid slow-downs. setTimeout(function() { throw e; }, 0); } } if (domain) { domain.exit(); } } flushing = false; } nextTick = function (task) { tail = tail.next = { task: task, domain: isNodeJS && process.domain, next: null }; if (!flushing) { flushing = true; requestTick(); } }; if (typeof process !== "undefined" && process.nextTick) { // Node.js before 0.9. Note that some fake-Node environments, like the // Mocha test runner, introduce a `process` global without a `nextTick`. isNodeJS = true; requestTick = function () { process.nextTick(flush); }; } else if (typeof setImmediate === "function") { // In IE10, Node.js 0.9+, or https://github.com/NobleJS/setImmediate if (typeof window !== "undefined") { requestTick = setImmediate.bind(window, flush); } else { requestTick = function () { setImmediate(flush); }; } } else if (typeof MessageChannel !== "undefined") { // modern browsers // http://www.nonblocking.io/2011/06/windownexttick.html var channel = new MessageChannel(); // At least Safari Version 6.0.5 (8536.30.1) intermittently cannot create // working message ports the first time a page loads. channel.port1.onmessage = function () { requestTick = requestPortTick; channel.port1.onmessage = flush; flush(); }; var requestPortTick = function () { // Opera requires us to provide a message payload, regardless of // whether we use it. channel.port2.postMessage(0); }; requestTick = function () { setTimeout(flush, 0); requestPortTick(); }; } else { // old browsers requestTick = function () { setTimeout(flush, 0); }; } return nextTick; })(); // Attempt to make generics safe in the face of downstream // modifications. // There is no situation where this is necessary. // If you need a security guarantee, these primordials need to be // deeply frozen anyway, and if you don’t need a security guarantee, // this is just plain paranoid. // However, this does have the nice side-effect of reducing the size // of the code by reducing x.call() to merely x(), eliminating many // hard-to-minify characters. // See Mark Miller’s explanation of what this does. // http://wiki.ecmascript.org/doku.php?id=conventions:safe_meta_programming var call = Function.call; function uncurryThis(f) { return function () { return call.apply(f, arguments); }; } // This is equivalent, but slower: // uncurryThis = Function_bind.bind(Function_bind.call); // http://jsperf.com/uncurrythis var array_slice = uncurryThis(Array.prototype.slice); var array_reduce = uncurryThis( Array.prototype.reduce || function (callback, basis) { var index = 0, length = this.length; // concerning the initial value, if one is not provided if (arguments.length === 1) { // seek to the first value in the array, accounting // for the possibility that is is a sparse array do { if (index in this) { basis = this[index++]; break; } if (++index >= length) { throw new TypeError(); } } while (1); } // reduce for (; index < length; index++) { // account for the possibility that the array is sparse if (index in this) { basis = callback(basis, this[index], index); } } return basis; } ); var array_indexOf = uncurryThis( Array.prototype.indexOf || function (value) { // not a very good shim, but good enough for our one use of it for (var i = 0; i < this.length; i++) { if (this[i] === value) { return i; } } return -1; } ); var array_map = uncurryThis( Array.prototype.map || function (callback, thisp) { var self = this; var collect = []; array_reduce(self, function (undefined, value, index) { collect.push(callback.call(thisp, value, index, self)); }, void 0); return collect; } ); var object_create = Object.create || function (prototype) { function Type() { } Type.prototype = prototype; return new Type(); }; var object_hasOwnProperty = uncurryThis(Object.prototype.hasOwnProperty); var object_keys = Object.keys || function (object) { var keys = []; for (var key in object) { if (object_hasOwnProperty(object, key)) { keys.push(key); } } return keys; }; var object_toString = uncurryThis(Object.prototype.toString); function isObject(value) { return value === Object(value); } // generator related shims // FIXME: Remove this function once ES6 generators are in SpiderMonkey. function isStopIteration(exception) { return ( object_toString(exception) === "[object StopIteration]" || exception instanceof QReturnValue ); } // FIXME: Remove this helper and Q.return once ES6 generators are in // SpiderMonkey. var QReturnValue; if (typeof ReturnValue !== "undefined") { QReturnValue = ReturnValue; } else { QReturnValue = function (value) { this.value = value; }; } // Until V8 3.19 / Chromium 29 is released, SpiderMonkey is the only // engine that has a deployed base of browsers that support generators. // However, SM's generators use the Python-inspired semantics of // outdated ES6 drafts. We would like to support ES6, but we'd also // like to make it possible to use generators in deployed browsers, so // we also support Python-style generators. At some point we can remove // this block. var hasES6Generators; try { /* jshint evil: true, nonew: false */ new Function("(function* (){ yield 1; })"); hasES6Generators = true; } catch (e) { hasES6Generators = false; } // long stack traces var STACK_JUMP_SEPARATOR = "From previous event:"; function makeStackTraceLong(error, promise) { // If possible, transform the error stack trace by removing Node and Q // cruft, then concatenating with the stack trace of `promise`. See #57. if (hasStacks && promise.stack && typeof error === "object" && error !== null && error.stack && error.stack.indexOf(STACK_JUMP_SEPARATOR) === -1 ) { var stacks = []; for (var p = promise; !!p; p = p.source) { if (p.stack) { stacks.unshift(p.stack); } } stacks.unshift(error.stack); var concatedStacks = stacks.join("\n" + STACK_JUMP_SEPARATOR + "\n"); error.stack = filterStackString(concatedStacks); } } function filterStackString(stackString) { var lines = stackString.split("\n"); var desiredLines = []; for (var i = 0; i < lines.length; ++i) { var line = lines[i]; if (!isInternalFrame(line) && !isNodeFrame(line) && line) { desiredLines.push(line); } } return desiredLines.join("\n"); } function isNodeFrame(stackLine) { return stackLine.indexOf("(module.js:") !== -1 || stackLine.indexOf("(node.js:") !== -1; } function getFileNameAndLineNumber(stackLine) { // Named functions: "at functionName (filename:lineNumber:columnNumber)" // In IE10 function name can have spaces ("Anonymous function") O_o var attempt1 = /at .+ \((.+):(\d+):(?:\d+)\)$/.exec(stackLine); if (attempt1) { return [attempt1[1], Number(attempt1[2])]; } // Anonymous functions: "at filename:lineNumber:columnNumber" var attempt2 = /at ([^ ]+):(\d+):(?:\d+)$/.exec(stackLine); if (attempt2) { return [attempt2[1], Number(attempt2[2])]; } // Firefox style: "function@filename:lineNumber or @filename:lineNumber" var attempt3 = /.*@(.+):(\d+)$/.exec(stackLine); if (attempt3) { return [attempt3[1], Number(attempt3[2])]; } } function isInternalFrame(stackLine) { var fileNameAndLineNumber = getFileNameAndLineNumber(stackLine); if (!fileNameAndLineNumber) { return false; } var fileName = fileNameAndLineNumber[0]; var lineNumber = fileNameAndLineNumber[1]; return fileName === qFileName && lineNumber >= qStartingLine && lineNumber <= qEndingLine; } // discover own file name and line number range for filtering stack // traces function captureLine() { if (!hasStacks) { return; } try { throw new Error(); } catch (e) { var lines = e.stack.split("\n"); var firstLine = lines[0].indexOf("@") > 0 ? lines[1] : lines[2]; var fileNameAndLineNumber = getFileNameAndLineNumber(firstLine); if (!fileNameAndLineNumber) { return; } qFileName = fileNameAndLineNumber[0]; return fileNameAndLineNumber[1]; } } function deprecate(callback, name, alternative) { return function () { if (typeof console !== "undefined" && typeof console.warn === "function") { console.warn(name + " is deprecated, use " + alternative + " instead.", new Error("").stack); } return callback.apply(callback, arguments); }; } // end of shims // beginning of real work /** * Constructs a promise for an immediate reference, passes promises through, or * coerces promises from different systems. * @param value immediate reference or promise */ function Q(value) { // If the object is already a Promise, return it directly. This enables // the resolve function to both be used to created references from objects, // but to tolerably coerce non-promises to promises. if (isPromise(value)) { return value; } // assimilate thenables if (isPromiseAlike(value)) { return coerce(value); } else { return fulfill(value); } } Q.resolve = Q; /** * Performs a task in a future turn of the event loop. * @param {Function} task */ Q.nextTick = nextTick; /** * Controls whether or not long stack traces will be on */ Q.longStackSupport = false; /** * Constructs a {promise, resolve, reject} object. * * `resolve` is a callback to invoke with a more resolved value for the * promise. To fulfill the promise, invoke `resolve` with any value that is * not a thenable. To reject the promise, invoke `resolve` with a rejected * thenable, or invoke `reject` with the reason directly. To resolve the * promise to another thenable, thus putting it in the same state, invoke * `resolve` with that other thenable. */ Q.defer = defer; function defer() { // if "messages" is an "Array", that indicates that the promise has not yet // been resolved. If it is "undefined", it has been resolved. Each // element of the messages array is itself an array of complete arguments to // forward to the resolved promise. We coerce the resolution value to a // promise using the `resolve` function because it handles both fully // non-thenable values and other thenables gracefully. var messages = [], progressListeners = [], resolvedPromise; var deferred = object_create(defer.prototype); var promise = object_create(Promise.prototype); promise.promiseDispatch = function (resolve, op, operands) { var args = array_slice(arguments); if (messages) { messages.push(args); if (op === "when" && operands[1]) { // progress operand progressListeners.push(operands[1]); } } else { nextTick(function () { resolvedPromise.promiseDispatch.apply(resolvedPromise, args); }); } }; // XXX deprecated promise.valueOf = deprecate(function () { if (messages) { return promise; } var nearerValue = nearer(resolvedPromise); if (isPromise(nearerValue)) { resolvedPromise = nearerValue; // shorten chain } return nearerValue; }, "valueOf", "inspect"); promise.inspect = function () { if (!resolvedPromise) { return { state: "pending" }; } return resolvedPromise.inspect(); }; if (Q.longStackSupport && hasStacks) { try { throw new Error(); } catch (e) { // NOTE: don't try to use `Error.captureStackTrace` or transfer the // accessor around; that causes memory leaks as per GH-111. Just // reify the stack trace as a string ASAP. // // At the same time, cut off the first line; it's always just // "[object Promise]\n", as per the `toString`. promise.stack = e.stack.substring(e.stack.indexOf("\n") + 1); } } // NOTE: we do the checks for `resolvedPromise` in each method, instead of // consolidating them into `become`, since otherwise we'd create new // promises with the lines `become(whatever(value))`. See e.g. GH-252. function become(newPromise) { resolvedPromise = newPromise; promise.source = newPromise; array_reduce(messages, function (undefined, message) { nextTick(function () { newPromise.promiseDispatch.apply(newPromise, message); }); }, void 0); messages = void 0; progressListeners = void 0; } deferred.promise = promise; deferred.resolve = function (value) { if (resolvedPromise) { return; } become(Q(value)); }; deferred.fulfill = function (value) { if (resolvedPromise) { return; } become(fulfill(value)); }; deferred.reject = function (reason) { if (resolvedPromise) { return; } become(reject(reason)); }; deferred.notify = function (progress) { if (resolvedPromise) { return; } array_reduce(progressListeners, function (undefined, progressListener) { nextTick(function () { progressListener(progress); }); }, void 0); }; return deferred; } /** * Creates a Node-style callback that will resolve or reject the deferred * promise. * @returns a nodeback */ defer.prototype.makeNodeResolver = function () { var self = this; return function (error, value) { if (error) { self.reject(error); } else if (arguments.length > 2) { self.resolve(array_slice(arguments, 1)); } else { self.resolve(value); } }; }; /** * @param resolver {Function} a function that returns nothing and accepts * the resolve, reject, and notify functions for a deferred. * @returns a promise that may be resolved with the given resolve and reject * functions, or rejected by a thrown exception in resolver */ Q.promise = promise; function promise(resolver) { if (typeof resolver !== "function") { throw new TypeError("resolver must be a function."); } var deferred = defer(); try { resolver(deferred.resolve, deferred.reject, deferred.notify); } catch (reason) { deferred.reject(reason); } return deferred.promise; } // XXX experimental. This method is a way to denote that a local value is // serializable and should be immediately dispatched to a remote upon request, // instead of passing a reference. Q.passByCopy = function (object) { //freeze(object); //passByCopies.set(object, true); return object; }; Promise.prototype.passByCopy = function () { //freeze(object); //passByCopies.set(object, true); return this; }; /** * If two promises eventually fulfill to the same value, promises that value, * but otherwise rejects. * @param x {Any*} * @param y {Any*} * @returns {Any*} a promise for x and y if they are the same, but a rejection * otherwise. * */ Q.join = function (x, y) { return Q(x).join(y); }; Promise.prototype.join = function (that) { return Q([this, that]).spread(function (x, y) { if (x === y) { // TODO: "===" should be Object.is or equiv return x; } else { throw new Error("Can't join: not the same: " + x + " " + y); } }); }; /** * Returns a promise for the first of an array of promises to become fulfilled. * @param answers {Array[Any*]} promises to race * @returns {Any*} the first promise to be fulfilled */ Q.race = race; function race(answerPs) { return promise(function(resolve, reject) { // Switch to this once we can assume at least ES5 // answerPs.forEach(function(answerP) { // Q(answerP).then(resolve, reject); // }); // Use this in the meantime for (var i = 0, len = answerPs.length; i < len; i++) { Q(answerPs[i]).then(resolve, reject); } }); } Promise.prototype.race = function () { return this.then(Q.race); }; /** * Constructs a Promise with a promise descriptor object and optional fallback * function. The descriptor contains methods like when(rejected), get(name), * set(name, value), post(name, args), and delete(name), which all * return either a value, a promise for a value, or a rejection. The fallback * accepts the operation name, a resolver, and any further arguments that would * have been forwarded to the appropriate method above had a method been * provided with the proper name. The API makes no guarantees about the nature * of the returned object, apart from that it is usable whereever promises are * bought and sold. */ Q.makePromise = Promise; function Promise(descriptor, fallback, inspect) { if (fallback === void 0) { fallback = function (op) { return reject(new Error( "Promise does not support operation: " + op )); }; } if (inspect === void 0) { inspect = function () { return {state: "unknown"}; }; } var promise = object_create(Promise.prototype); promise.promiseDispatch = function (resolve, op, args) { var result; try { if (descriptor[op]) { result = descriptor[op].apply(promise, args); } else { result = fallback.call(promise, op, args); } } catch (exception) { result = reject(exception); } if (resolve) { resolve(result); } }; promise.inspect = inspect; // XXX deprecated `valueOf` and `exception` support if (inspect) { var inspected = inspect(); if (inspected.state === "rejected") { promise.exception = inspected.reason; } promise.valueOf = deprecate(function () { var inspected = inspect(); if (inspected.state === "pending" || inspected.state === "rejected") { return promise; } return inspected.value; }); } return promise; } Promise.prototype.toString = function () { return "[object Promise]"; }; Promise.prototype.then = function (fulfilled, rejected, progressed) { var self = this; var deferred = defer(); var done = false; // ensure the untrusted promise makes at most a // single call to one of the callbacks function _fulfilled(value) { try { return typeof fulfilled === "function" ? fulfilled(value) : value; } catch (exception) { return reject(exception); } } function _rejected(exception) { if (typeof rejected === "function") { makeStackTraceLong(exception, self); try { return rejected(exception); } catch (newException) { return reject(newException); } } return reject(exception); } function _progressed(value) { return typeof progressed === "function" ? progressed(value) : value; } nextTick(function () { self.promiseDispatch(function (value) { if (done) { return; } done = true; deferred.resolve(_fulfilled(value)); }, "when", [function (exception) { if (done) { return; } done = true; deferred.resolve(_rejected(exception)); }]); }); // Progress propagator need to be attached in the current tick. self.promiseDispatch(void 0, "when", [void 0, function (value) { var newValue; var threw = false; try { newValue = _progressed(value); } catch (e) { threw = true; if (Q.onerror) { Q.onerror(e); } else { throw e; } } if (!threw) { deferred.notify(newValue); } }]); return deferred.promise; }; /** * Registers an observer on a promise. * * Guarantees: * * 1. that fulfilled and rejected will be called only once. * 2. that either the fulfilled callback or the rejected callback will be * called, but not both. * 3. that fulfilled and rejected will not be called in this turn. * * @param value promise or immediate reference to observe * @param fulfilled function to be called with the fulfilled value * @param rejected function to be called with the rejection exception * @param progressed function to be called on any progress notifications * @return promise for the return value from the invoked callback */ Q.when = when; function when(value, fulfilled, rejected, progressed) { return Q(value).then(fulfilled, rejected, progressed); } Promise.prototype.thenResolve = function (value) { return this.then(function () { return value; }); }; Q.thenResolve = function (promise, value) { return Q(promise).thenResolve(value); }; Promise.prototype.thenReject = function (reason) { return this.then(function () { throw reason; }); }; Q.thenReject = function (promise, reason) { return Q(promise).thenReject(reason); }; /** * If an object is not a promise, it is as "near" as possible. * If a promise is rejected, it is as "near" as possible too. * If it’s a fulfilled promise, the fulfillment value is nearer. * If it’s a deferred promise and the deferred has been resolved, the * resolution is "nearer". * @param object * @returns most resolved (nearest) form of the object */ // XXX should we re-do this? Q.nearer = nearer; function nearer(value) { if (isPromise(value)) { var inspected = value.inspect(); if (inspected.state === "fulfilled") { return inspected.value; } } return value; } /** * @returns whether the given object is a promise. * Otherwise it is a fulfilled value. */ Q.isPromise = isPromise; function isPromise(object) { return isObject(object) && typeof object.promiseDispatch === "function" && typeof object.inspect === "function"; } Q.isPromiseAlike = isPromiseAlike; function isPromiseAlike(object) { return isObject(object) && typeof object.then === "function"; } /** * @returns whether the given object is a pending promise, meaning not * fulfilled or rejected. */ Q.isPending = isPending; function isPending(object) { return isPromise(object) && object.inspect().state === "pending"; } Promise.prototype.isPending = function () { return this.inspect().state === "pending"; }; /** * @returns whether the given object is a value or fulfilled * promise. */ Q.isFulfilled = isFulfilled; function isFulfilled(object) { return !isPromise(object) || object.inspect().state === "fulfilled"; } Promise.prototype.isFulfilled = function () { return this.inspect().state === "fulfilled"; }; /** * @returns whether the given object is a rejected promise. */ Q.isRejected = isRejected; function isRejected(object) { return isPromise(object) && object.inspect().state === "rejected"; } Promise.prototype.isRejected = function () { return this.inspect().state === "rejected"; }; //// BEGIN UNHANDLED REJECTION TRACKING // This promise library consumes exceptions thrown in handlers so they can be // handled by a subsequent promise. The exceptions get added to this array when // they are created, and removed when they are handled. Note that in ES6 or // shimmed environments, this would naturally be a `Set`. var unhandledReasons = []; var unhandledRejections = []; var unhandledReasonsDisplayed = false; var trackUnhandledRejections = true; function displayUnhandledReasons() { if ( !unhandledReasonsDisplayed && typeof window !== "undefined" && !window.Touch && window.console ) { console.warn("[Q] Unhandled rejection reasons (should be empty):", unhandledReasons); } unhandledReasonsDisplayed = true; } function logUnhandledReasons() { for (var i = 0; i < unhandledReasons.length; i++) { var reason = unhandledReasons[i]; console.warn("Unhandled rejection reason:", reason); } } function resetUnhandledRejections() { unhandledReasons.length = 0; unhandledRejections.length = 0; unhandledReasonsDisplayed = false; if (!trackUnhandledRejections) { trackUnhandledRejections = true; // Show unhandled rejection reasons if Node exits without handling an // outstanding rejection. (Note that Browserify presently produces a // `process` global without the `EventEmitter` `on` method.) if (typeof process !== "undefined" && process.on) { process.on("exit", logUnhandledReasons); } } } function trackRejection(promise, reason) { if (!trackUnhandledRejections) { return; } unhandledRejections.push(promise); if (reason && typeof reason.stack !== "undefined") { unhandledReasons.push(reason.stack); } else { unhandledReasons.push("(no stack) " + reason); } displayUnhandledReasons(); } function untrackRejection(promise) { if (!trackUnhandledRejections) { return; } var at = array_indexOf(unhandledRejections, promise); if (at !== -1) { unhandledRejections.splice(at, 1); unhandledReasons.splice(at, 1); } } Q.resetUnhandledRejections = resetUnhandledRejections; Q.getUnhandledReasons = function () { // Make a copy so that consumers can't interfere with our internal state. return unhandledReasons.slice(); }; Q.stopUnhandledRejectionTracking = function () { resetUnhandledRejections(); if (typeof process !== "undefined" && process.on) { process.removeListener("exit", logUnhandledReasons); } trackUnhandledRejections = false; }; resetUnhandledRejections(); //// END UNHANDLED REJECTION TRACKING /** * Constructs a rejected promise. * @param reason value describing the failure */ Q.reject = reject; function reject(reason) { var rejection = Promise({ "when": function (rejected) { // note that the error has been handled if (rejected) { untrackRejection(this); } return rejected ? rejected(reason) : this; } }, function fallback() { return this; }, function inspect() { return { state: "rejected", reason: reason }; }); // Note that the reason has not been handled. trackRejection(rejection, reason); return rejection; } /** * Constructs a fulfilled promise for an immediate reference. * @param value immediate reference */ Q.fulfill = fulfill; function fulfill(value) { return Promise({ "when": function () { return value; }, "get": function (name) { return value[name]; }, "set": function (name, rhs) { value[name] = rhs; }, "delete": function (name) { delete value[name]; }, "post": function (name, args) { // Mark Miller proposes that post with no name should apply a // promised function. if (name === null || name === void 0) { return value.apply(void 0, args); } else { return value[name].apply(value, args); } }, "apply": function (thisp, args) { return value.apply(thisp, args); }, "keys": function () { return object_keys(value); } }, void 0, function inspect() { return { state: "fulfilled", value: value }; }); } /** * Converts thenables to Q promises. * @param promise thenable promise * @returns a Q promise */ function coerce(promise) { var deferred = defer(); nextTick(function () { try { promise.then(deferred.resolve, deferred.reject, deferred.notify); } catch (exception) { deferred.reject(exception); } }); return deferred.promise; } /** * Annotates an object such that it will never be * transferred away from this process over any promise * communication channel. * @param object * @returns promise a wrapping of that object that * additionally responds to the "isDef" message * without a rejection. */ Q.master = master; function master(object) { return Promise({ "isDef": function () {} }, function fallback(op, args) { return dispatch(object, op, args); }, function () { return Q(object).inspect(); }); } /** * Spreads the values of a promised array of arguments into the * fulfillment callback. * @param fulfilled callback that receives variadic arguments from the * promised array * @param rejected callback that receives the exception if the promise * is rejected. * @returns a promise for the return value or thrown exception of * either callback. */ Q.spread = spread; function spread(value, fulfilled, rejected) { return Q(value).spread(fulfilled, rejected); } Promise.prototype.spread = function (fulfilled, rejected) { return this.all().then(function (array) { return fulfilled.apply(void 0, array); }, rejected); }; /** * The async function is a decorator for generator functions, turning * them into asynchronous generators. Although generators are only part * of the newest ECMAScript 6 drafts, this code does not cause syntax * errors in older engines. This code should continue to work and will * in fact improve over time as the language improves. * * ES6 generators are currently part of V8 version 3.19 with the * --harmony-generators runtime flag enabled. SpiderMonkey has had them * for longer, but under an older Python-inspired form. This function * works on both kinds of generators. * * Decorates a generator function such that: * - it may yield promises * - execution will continue when that promise is fulfilled * - the value of the yield expression will be the fulfilled value * - it returns a promise for the return value (when the generator * stops iterating) * - the decorated function returns a promise for the return value * of the generator or the first rejected promise among those * yielded. * - if an error is thrown in the generator, it propagates through * every following yield until it is caught, or until it escapes * the generator function altogether, and is translated into a * rejection for the promise returned by the decorated generator. */ Q.async = async; function async(makeGenerator) { return function () { // when verb is "send", arg is a value // when verb is "throw", arg is an exception function continuer(verb, arg) { var result; if (hasES6Generators) { try { result = generator[verb](arg); } catch (exception) { return reject(exception); } if (result.done) { return result.value; } else { return when(result.value, callback, errback); } } else { // FIXME: Remove this case when SM does ES6 generators. try { result = generator[verb](arg); } catch (exception) { if (isStopIteration(exception)) { return exception.value; } else { return reject(exception); } } return when(result, callback, errback); } } var generator = makeGenerator.apply(this, arguments); var callback = continuer.bind(continuer, "next"); var errback = continuer.bind(continuer, "throw"); return callback(); }; } /** * The spawn function is a small wrapper around async that immediately * calls the generator and also ends the promise chain, so that any * unhandled errors are thrown instead of forwarded to the error * handler. This is useful because it's extremely common to run * generators at the top-level to work with libraries. */ Q.spawn = spawn; function spawn(makeGenerator) { Q.done(Q.async(makeGenerator)()); } // FIXME: Remove this interface once ES6 generators are in SpiderMonkey. /** * Throws a ReturnValue exception to stop an asynchronous generator. * * This interface is a stop-gap measure to support generator return * values in older Firefox/SpiderMonkey. In browsers that support ES6 * generators like Chromium 29, just use "return" in your generator * functions. * * @param value the return value for the surrounding generator * @throws ReturnValue exception with the value. * @example * // ES6 style * Q.async(function* () { * var foo = yield getFooPromise(); * var bar = yield getBarPromise(); * return foo + bar; * }) * // Older SpiderMonkey style * Q.async(function () { * var foo = yield getFooPromise(); * var bar = yield getBarPromise(); * Q.return(foo + bar); * }) */ Q["return"] = _return; function _return(value) { throw new QReturnValue(value); } /** * The promised function decorator ensures that any promise arguments * are settled and passed as values (`this` is also settled and passed * as a value). It will also ensure that the result of a function is * always a promise. * * @example * var add = Q.promised(function (a, b) { * return a + b; * }); * add(Q(a), Q(B)); * * @param {function} callback The function to decorate * @returns {function} a function that has been decorated. */ Q.promised = promised; function promised(callback) { return function () { return spread([this, all(arguments)], function (self, args) { return callback.apply(self, args); }); }; } /** * sends a message to a value in a future turn * @param object* the recipient * @param op the name of the message operation, e.g., "when", * @param args further arguments to be forwarded to the operation * @returns result {Promise} a promise for the result of the operation */ Q.dispatch = dispatch; function dispatch(object, op, args) { return Q(object).dispatch(op, args); } Promise.prototype.dispatch = function (op, args) { var self = this; var deferred = defer(); nextTick(function () { self.promiseDispatch(deferred.resolve, op, args); }); return deferred.promise; }; /** * Gets the value of a property in a future turn. * @param object promise or immediate reference for target object * @param name name of property to get * @return promise for the property value */ Q.get = function (object, key) { return Q(object).dispatch("get", [key]); }; Promise.prototype.get = function (key) { return this.dispatch("get", [key]); }; /** * Sets the value of a property in a future turn. * @param object promise or immediate reference for object object * @param name name of property to set * @param value new value of property * @return promise for the return value */ Q.set = function (object, key, value) { return Q(object).dispatch("set", [key, value]); }; Promise.prototype.set = function (key, value) { return this.dispatch("set", [key, value]); }; /** * Deletes a property in a future turn. * @param object promise or immediate reference for target object * @param name name of property to delete * @return promise for the return value */ Q.del = // XXX legacy Q["delete"] = function (object, key) { return Q(object).dispatch("delete", [key]); }; Promise.prototype.del = // XXX legacy Promise.prototype["delete"] = function (key) { return this.dispatch("delete", [key]); }; /** * Invokes a method in a future turn. * @param object promise or immediate reference for target object * @param name name of method to invoke * @param value a value to post, typically an array of * invocation arguments for promises that * are ultimately backed with `resolve` values, * as opposed to those backed with URLs * wherein the posted value can be any * JSON serializable object. * @return promise for the return value */ // bound locally because it is used by other methods Q.mapply = // XXX As proposed by "Redsandro" Q.post = function (object, name, args) { return Q(object).dispatch("post", [name, args]); }; Promise.prototype.mapply = // XXX As proposed by "Redsandro" Promise.prototype.post = function (name, args) { return this.dispatch("post", [name, args]); }; /** * Invokes a method in a future turn. * @param object promise or immediate reference for target object * @param name name of method to invoke * @param ...args array of invocation arguments * @return promise for the return value */ Q.send = // XXX Mark Miller's proposed parlance Q.mcall = // XXX As proposed by "Redsandro" Q.invoke = function (object, name /*...args*/) { return Q(object).dispatch("post", [name, array_slice(arguments, 2)]); }; Promise.prototype.send = // XXX Mark Miller's proposed parlance Promise.prototype.mcall = // XXX As proposed by "Redsandro" Promise.prototype.invoke = function (name /*...args*/) { return this.dispatch("post", [name, array_slice(arguments, 1)]); }; /** * Applies the promised function in a future turn. * @param object promise or immediate reference for target function * @param args array of application arguments */ Q.fapply = function (object, args) { return Q(object).dispatch("apply", [void 0, args]); }; Promise.prototype.fapply = function (args) { return this.dispatch("apply", [void 0, args]); }; /** * Calls the promised function in a future turn. * @param object promise or immediate reference for target function * @param ...args array of application arguments */ Q["try"] = Q.fcall = function (object /* ...args*/) { return Q(object).dispatch("apply", [void 0, array_slice(arguments, 1)]); }; Promise.prototype.fcall = function (/*...args*/) { return this.dispatch("apply", [void 0, array_slice(arguments)]); }; /** * Binds the promised function, transforming return values into a fulfilled * promise and thrown errors into a rejected one. * @param object promise or immediate reference for target function * @param ...args array of application arguments */ Q.fbind = function (object /*...args*/) { var promise = Q(object); var args = array_slice(arguments, 1); return function fbound() { return promise.dispatch("apply", [ this, args.concat(array_slice(arguments)) ]); }; }; Promise.prototype.fbind = function (/*...args*/) { var promise = this; var args = array_slice(arguments); return function fbound() { return promise.dispatch("apply", [ this, args.concat(array_slice(arguments)) ]); }; }; /** * Requests the names of the owned properties of a promised * object in a future turn. * @param object promise or immediate reference for target object * @return promise for the keys of the eventually settled object */ Q.keys = function (object) { return Q(object).dispatch("keys", []); }; Promise.prototype.keys = function () { return this.dispatch("keys", []); }; /** * Turns an array of promises into a promise for an array. If any of * the promises gets rejected, the whole array is rejected immediately. * @param {Array*} an array (or promise for an array) of values (or * promises for values) * @returns a promise for an array of the corresponding values */ // By Mark Miller // http://wiki.ecmascript.org/doku.php?id=strawman:concurrency&rev=1308776521#allfulfilled Q.all = all; function all(promises) { return when(promises, function (promises) { var countDown = 0; var deferred = defer(); array_reduce(promises, function (undefined, promise, index) { var snapshot; if ( isPromise(promise) && (snapshot = promise.inspect()).state === "fulfilled" ) { promises[index] = snapshot.value; } else { ++countDown; when( promise, function (value) { promises[index] = value; if (--countDown === 0) { deferred.resolve(promises); } }, deferred.reject, function (progress) { deferred.notify({ index: index, value: progress }); } ); } }, void 0); if (countDown === 0) { deferred.resolve(promises); } return deferred.promise; }); } Promise.prototype.all = function () { return all(this); }; /** * Waits for all promises to be settled, either fulfilled or * rejected. This is distinct from `all` since that would stop * waiting at the first rejection. The promise returned by * `allResolved` will never be rejected. * @param promises a promise for an array (or an array) of promises * (or values) * @return a promise for an array of promises */ Q.allResolved = deprecate(allResolved, "allResolved", "allSettled"); function allResolved(promises) { return when(promises, function (promises) { promises = array_map(promises, Q); return when(all(array_map(promises, function (promise) { return when(promise, noop, noop); })), function () { return promises; }); }); } Promise.prototype.allResolved = function () { return allResolved(this); }; /** * @see Promise#allSettled */ Q.allSettled = allSettled; function allSettled(promises) { return Q(promises).allSettled(); } /** * Turns an array of promises into a promise for an array of their states (as * returned by `inspect`) when they have all settled. * @param {Array[Any*]} values an array (or promise for an array) of values (or * promises for values) * @returns {Array[State]} an array of states for the respective values. */ Promise.prototype.allSettled = function () { return this.then(function (promises) { return all(array_map(promises, function (promise) { promise = Q(promise); function regardless() { return promise.inspect(); } return promise.then(regardless, regardless); })); }); }; /** * Captures the failure of a promise, giving an oportunity to recover * with a callback. If the given promise is fulfilled, the returned * promise is fulfilled. * @param {Any*} promise for something * @param {Function} callback to fulfill the returned promise if the * given promise is rejected * @returns a promise for the return value of the callback */ Q.fail = // XXX legacy Q["catch"] = function (object, rejected) { return Q(object).then(void 0, rejected); }; Promise.prototype.fail = // XXX legacy Promise.prototype["catch"] = function (rejected) { return this.then(void 0, rejected); }; /** * Attaches a listener that can respond to progress notifications from a * promise's originating deferred. This listener receives the exact arguments * passed to ``deferred.notify``. * @param {Any*} promise for something * @param {Function} callback to receive any progress notifications * @returns the given promise, unchanged */ Q.progress = progress; function progress(object, progressed) { return Q(object).then(void 0, void 0, progressed); } Promise.prototype.progress = function (progressed) { return this.then(void 0, void 0, progressed); }; /** * Provides an opportunity to observe the settling of a promise, * regardless of whether the promise is fulfilled or rejected. Forwards * the resolution to the returned promise when the callback is done. * The callback can return a promise to defer completion. * @param {Any*} promise * @param {Function} callback to observe the resolution of the given * promise, takes no arguments. * @returns a promise for the resolution of the given promise when * ``fin`` is done. */ Q.fin = // XXX legacy Q["finally"] = function (object, callback) { return Q(object)["finally"](callback); }; Promise.prototype.fin = // XXX legacy Promise.prototype["finally"] = function (callback) { callback = Q(callback); return this.then(function (value) { return callback.fcall().then(function () { return value; }); }, function (reason) { // TODO attempt to recycle the rejection with "this". return callback.fcall().then(function () { throw reason; }); }); }; /** * Terminates a chain of promises, forcing rejections to be * thrown as exceptions. * @param {Any*} promise at the end of a chain of promises * @returns nothing */ Q.done = function (object, fulfilled, rejected, progress) { return Q(object).done(fulfilled, rejected, progress); }; Promise.prototype.done = function (fulfilled, rejected, progress) { var onUnhandledError = function (error) { // forward to a future turn so that ``when`` // does not catch it and turn it into a rejection. nextTick(function () { makeStackTraceLong(error, promise); if (Q.onerror) { Q.onerror(error); } else { throw error; } }); }; // Avoid unnecessary `nextTick`ing via an unnecessary `when`. var promise = fulfilled || rejected || progress ? this.then(fulfilled, rejected, progress) : this; if (typeof process === "object" && process && process.domain) { onUnhandledError = process.domain.bind(onUnhandledError); } promise.then(void 0, onUnhandledError); }; /** * Causes a promise to be rejected if it does not get fulfilled before * some milliseconds time out. * @param {Any*} promise * @param {Number} milliseconds timeout * @param {String} custom error message (optional) * @returns a promise for the resolution of the given promise if it is * fulfilled before the timeout, otherwise rejected. */ Q.timeout = function (object, ms, message) { return Q(object).timeout(ms, message); }; Promise.prototype.timeout = function (ms, message) { var deferred = defer(); var timeoutId = setTimeout(function () { deferred.reject(new Error(message || "Timed out after " + ms + " ms")); }, ms); this.then(function (value) { clearTimeout(timeoutId); deferred.resolve(value); }, function (exception) { clearTimeout(timeoutId); deferred.reject(exception); }, deferred.notify); return deferred.promise; }; /** * Returns a promise for the given value (or promised value), some * milliseconds after it resolved. Passes rejections immediately. * @param {Any*} promise * @param {Number} milliseconds * @returns a promise for the resolution of the given promise after milliseconds * time has elapsed since the resolution of the given promise. * If the given promise rejects, that is passed immediately. */ Q.delay = function (object, timeout) { if (timeout === void 0) { timeout = object; object = void 0; } return Q(object).delay(timeout); }; Promise.prototype.delay = function (timeout) { return this.then(function (value) { var deferred = defer(); setTimeout(function () { deferred.resolve(value); }, timeout); return deferred.promise; }); }; /** * Passes a continuation to a Node function, which is called with the given * arguments provided as an array, and returns a promise. * * Q.nfapply(FS.readFile, [__filename]) * .then(function (content) { * }) * */ Q.nfapply = function (callback, args) { return Q(callback).nfapply(args); }; Promise.prototype.nfapply = function (args) { var deferred = defer(); var nodeArgs = array_slice(args); nodeArgs.push(deferred.makeNodeResolver()); this.fapply(nodeArgs).fail(deferred.reject); return deferred.promise; }; /** * Passes a continuation to a Node function, which is called with the given * arguments provided individually, and returns a promise. * @example * Q.nfcall(FS.readFile, __filename) * .then(function (content) { * }) * */ Q.nfcall = function (callback /*...args*/) { var args = array_slice(arguments, 1); return Q(callback).nfapply(args); }; Promise.prototype.nfcall = function (/*...args*/) { var nodeArgs = array_slice(arguments); var deferred = defer(); nodeArgs.push(deferred.makeNodeResolver()); this.fapply(nodeArgs).fail(deferred.reject); return deferred.promise; }; /** * Wraps a NodeJS continuation passing function and returns an equivalent * version that returns a promise. * @example * Q.nfbind(FS.readFile, __filename)("utf-8") * .then(console.log) * .done() */ Q.nfbind = Q.denodeify = function (callback /*...args*/) { var baseArgs = array_slice(arguments, 1); return function () { var nodeArgs = baseArgs.concat(array_slice(arguments)); var deferred = defer(); nodeArgs.push(deferred.makeNodeResolver()); Q(callback).fapply(nodeArgs).fail(deferred.reject); return deferred.promise; }; }; Promise.prototype.nfbind = Promise.prototype.denodeify = function (/*...args*/) { var args = array_slice(arguments); args.unshift(this); return Q.denodeify.apply(void 0, args); }; Q.nbind = function (callback, thisp /*...args*/) { var baseArgs = array_slice(arguments, 2); return function () { var nodeArgs = baseArgs.concat(array_slice(arguments)); var deferred = defer(); nodeArgs.push(deferred.makeNodeResolver()); function bound() { return callback.apply(thisp, arguments); } Q(bound).fapply(nodeArgs).fail(deferred.reject); return deferred.promise; }; }; Promise.prototype.nbind = function (/*thisp, ...args*/) { var args = array_slice(arguments, 0); args.unshift(this); return Q.nbind.apply(void 0, args); }; /** * Calls a method of a Node-style object that accepts a Node-style * callback with a given array of arguments, plus a provided callback. * @param object an object that has the named method * @param {String} name name of the method of object * @param {Array} args arguments to pass to the method; the callback * will be provided by Q and appended to these arguments. * @returns a promise for the value or error */ Q.nmapply = // XXX As proposed by "Redsandro" Q.npost = function (object, name, args) { return Q(object).npost(name, args); }; Promise.prototype.nmapply = // XXX As proposed by "Redsandro" Promise.prototype.npost = function (name, args) { var nodeArgs = array_slice(args || []); var deferred = defer(); nodeArgs.push(deferred.makeNodeResolver()); this.dispatch("post", [name, nodeArgs]).fail(deferred.reject); return deferred.promise; }; /** * Calls a method of a Node-style object that accepts a Node-style * callback, forwarding the given variadic arguments, plus a provided * callback argument. * @param object an object that has the named method * @param {String} name name of the method of object * @param ...args arguments to pass to the method; the callback will * be provided by Q and appended to these arguments. * @returns a promise for the value or error */ Q.nsend = // XXX Based on Mark Miller's proposed "send" Q.nmcall = // XXX Based on "Redsandro's" proposal Q.ninvoke = function (object, name /*...args*/) { var nodeArgs = array_slice(arguments, 2); var deferred = defer(); nodeArgs.push(deferred.makeNodeResolver()); Q(object).dispatch("post", [name, nodeArgs]).fail(deferred.reject); return deferred.promise; }; Promise.prototype.nsend = // XXX Based on Mark Miller's proposed "send" Promise.prototype.nmcall = // XXX Based on "Redsandro's" proposal Promise.prototype.ninvoke = function (name /*...args*/) { var nodeArgs = array_slice(arguments, 1); var deferred = defer(); nodeArgs.push(deferred.makeNodeResolver()); this.dispatch("post", [name, nodeArgs]).fail(deferred.reject); return deferred.promise; }; /** * If a function would like to support both Node continuation-passing-style and * promise-returning-style, it can end its internal promise chain with * `nodeify(nodeback)`, forwarding the optional nodeback argument. If the user * elects to use a nodeback, the result will be sent there. If they do not * pass a nodeback, they will receive the result promise. * @param object a result (or a promise for a result) * @param {Function} nodeback a Node.js-style callback * @returns either the promise or nothing */ Q.nodeify = nodeify; function nodeify(object, nodeback) { return Q(object).nodeify(nodeback); } Promise.prototype.nodeify = function (nodeback) { if (nodeback) { this.then(function (value) { nextTick(function () { nodeback(null, value); }); }, function (error) { nextTick(function () { nodeback(error); }); }); } else { return this; } }; // All code before this point will be filtered from stack traces. var qEndingLine = captureLine(); return Q; });
From http://tantaman.github.io/LargeLocalStorage/bower_components/q/q.js
Travelled to 12 computer(s): aoiabmzegqzx, bhatertpkbcr, cbybwowwnfue, gwrvuhgaqvyk, irmadwmeruwu, ishqpsrjomds, lpdgvwnxivlt, mqqgnosmbjvj, pyentgdyhuwx, pzhvpgtvlbxg, tvejysmllsmz, vouqrxazstgt
No comments. add comment
Snippet ID: | #1018989 |
Snippet name: | q.js |
Eternal ID of this version: | #1018989/1 |
Text MD5: | de7d0e89ff04793eb1575a968be7e0a2 |
Author: | stefan |
Category: | javax / web |
Type: | Document |
Public (visible to everyone): | Yes |
Archived (hidden from active list): | No |
Created/modified: | 2018-10-19 16:39:57 |
Source code size: | 60990 bytes / 1937 lines |
Pitched / IR pitched: | No / No |
Views / Downloads: | 310 / 100 |
Referenced in: | -