http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/f4e2ac6a/windows/bin/node_modules/q/README.md ---------------------------------------------------------------------- diff --git a/windows/bin/node_modules/q/README.md b/windows/bin/node_modules/q/README.md deleted file mode 100644 index bdd4168..0000000 --- a/windows/bin/node_modules/q/README.md +++ /dev/null @@ -1,820 +0,0 @@ -[](http://travis-ci.org/kriskowal/q) - -<a href="http://promises-aplus.github.com/promises-spec";> - <img src="http://promises-aplus.github.com/promises-spec/assets/logo-small.png"; - align="right" alt="Promises/A+ logo" /> -</a> - -*This is Q version 1, from the `v1` branch in Git. This documentation applies to -the latest of both the version 1 and version 0.9 release trains. These releases -are stable. There will be no further releases of 0.9 after 0.9.7 which is nearly -equivalent to version 1.0.0. All further releases of `q@~1.0` will be backward -compatible. The version 2 release train introduces significant but -backward-incompatible changes and is experimental at this time.* - -If a function cannot return a value or throw an exception without -blocking, it can return a promise instead. A promise is an object -that represents the return value or the thrown exception that the -function may eventually provide. A promise can also be used as a -proxy for a [remote object][Q-Connection] to overcome latency. - -[Q-Connection]: https://github.com/kriskowal/q-connection - -On the first pass, promises can mitigate the â[Pyramid of -Doom][POD]â: the situation where code marches to the right faster -than it marches forward. - -[POD]: http://calculist.org/blog/2011/12/14/why-coroutines-wont-work-on-the-web/ - -```javascript -step1(function (value1) { - step2(value1, function(value2) { - step3(value2, function(value3) { - step4(value3, function(value4) { - // Do something with value4 - }); - }); - }); -}); -``` - -With a promise library, you can flatten the pyramid. - -```javascript -Q.fcall(promisedStep1) -.then(promisedStep2) -.then(promisedStep3) -.then(promisedStep4) -.then(function (value4) { - // Do something with value4 -}) -.catch(function (error) { - // Handle any error from all above steps -}) -.done(); -``` - -With this approach, you also get implicit error propagation, just like `try`, -`catch`, and `finally`. An error in `promisedStep1` will flow all the way to -the `catch` function, where itâs caught and handled. (Here `promisedStepN` is -a version of `stepN` that returns a promise.) - -The callback approach is called an âinversion of controlâ. -A function that accepts a callback instead of a return value -is saying, âDonât call me, Iâll call you.â. Promises -[un-invert][IOC] the inversion, cleanly separating the input -arguments from control flow arguments. This simplifies the -use and creation of APIâs, particularly variadic, -rest and spread arguments. - -[IOC]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript - - -## Getting Started - -The Q module can be loaded as: - -- A ``<script>`` tag (creating a ``Q`` global variable): ~2.5 KB minified and - gzipped. -- A Node.js and CommonJS module, available in [npm](https://npmjs.org/) as - the [q](https://npmjs.org/package/q) package -- An AMD module -- A [component](https://github.com/component/component) as ``microjs/q`` -- Using [bower](http://bower.io/) as ``q`` -- Using [NuGet](http://nuget.org/) as [Q](https://nuget.org/packages/q) - -Q can exchange promises with jQuery, Dojo, When.js, WinJS, and more. - -## Resources - -Our [wiki][] contains a number of useful resources, including: - -- A method-by-method [Q API reference][reference]. -- A growing [examples gallery][examples], showing how Q can be used to make - everything better. From XHR to database access to accessing the Flickr API, - Q is there for you. -- There are many libraries that produce and consume Q promises for everything - from file system/database access or RPC to templating. For a list of some of - the more popular ones, see [Libraries][]. -- If you want materials that introduce the promise concept generally, and the - below tutorial isn't doing it for you, check out our collection of - [presentations, blog posts, and podcasts][resources]. -- A guide for those [coming from jQuery's `$.Deferred`][jquery]. - -We'd also love to have you join the Q-Continuum [mailing list][]. - -[wiki]: https://github.com/kriskowal/q/wiki -[reference]: https://github.com/kriskowal/q/wiki/API-Reference -[examples]: https://github.com/kriskowal/q/wiki/Examples-Gallery -[Libraries]: https://github.com/kriskowal/q/wiki/Libraries -[resources]: https://github.com/kriskowal/q/wiki/General-Promise-Resources -[jquery]: https://github.com/kriskowal/q/wiki/Coming-from-jQuery -[mailing list]: https://groups.google.com/forum/#!forum/q-continuum - - -## Tutorial - -Promises have a ``then`` method, which you can use to get the eventual -return value (fulfillment) or thrown exception (rejection). - -```javascript -promiseMeSomething() -.then(function (value) { -}, function (reason) { -}); -``` - -If ``promiseMeSomething`` returns a promise that gets fulfilled later -with a return value, the first function (the fulfillment handler) will be -called with the value. However, if the ``promiseMeSomething`` function -gets rejected later by a thrown exception, the second function (the -rejection handler) will be called with the exception. - -Note that resolution of a promise is always asynchronous: that is, the -fulfillment or rejection handler will always be called in the next turn of the -event loop (i.e. `process.nextTick` in Node). This gives you a nice -guarantee when mentally tracing the flow of your code, namely that -``then`` will always return before either handler is executed. - -In this tutorial, we begin with how to consume and work with promises. We'll -talk about how to create them, and thus create functions like -`promiseMeSomething` that return promises, [below](#the-beginning). - - -### Propagation - -The ``then`` method returns a promise, which in this example, Iâm -assigning to ``outputPromise``. - -```javascript -var outputPromise = getInputPromise() -.then(function (input) { -}, function (reason) { -}); -``` - -The ``outputPromise`` variable becomes a new promise for the return -value of either handler. Since a function can only either return a -value or throw an exception, only one handler will ever be called and it -will be responsible for resolving ``outputPromise``. - -- If you return a value in a handler, ``outputPromise`` will get - fulfilled. - -- If you throw an exception in a handler, ``outputPromise`` will get - rejected. - -- If you return a **promise** in a handler, ``outputPromise`` will - âbecomeâ that promise. Being able to become a new promise is useful - for managing delays, combining results, or recovering from errors. - -If the ``getInputPromise()`` promise gets rejected and you omit the -rejection handler, the **error** will go to ``outputPromise``: - -```javascript -var outputPromise = getInputPromise() -.then(function (value) { -}); -``` - -If the input promise gets fulfilled and you omit the fulfillment handler, the -**value** will go to ``outputPromise``: - -```javascript -var outputPromise = getInputPromise() -.then(null, function (error) { -}); -``` - -Q promises provide a ``fail`` shorthand for ``then`` when you are only -interested in handling the error: - -```javascript -var outputPromise = getInputPromise() -.fail(function (error) { -}); -``` - -If you are writing JavaScript for modern engines only or using -CoffeeScript, you may use `catch` instead of `fail`. - -Promises also have a ``fin`` function that is like a ``finally`` clause. -The final handler gets called, with no arguments, when the promise -returned by ``getInputPromise()`` either returns a value or throws an -error. The value returned or error thrown by ``getInputPromise()`` -passes directly to ``outputPromise`` unless the final handler fails, and -may be delayed if the final handler returns a promise. - -```javascript -var outputPromise = getInputPromise() -.fin(function () { - // close files, database connections, stop servers, conclude tests -}); -``` - -- If the handler returns a value, the value is ignored -- If the handler throws an error, the error passes to ``outputPromise`` -- If the handler returns a promise, ``outputPromise`` gets postponed. The - eventual value or error has the same effect as an immediate return - value or thrown error: a value would be ignored, an error would be - forwarded. - -If you are writing JavaScript for modern engines only or using -CoffeeScript, you may use `finally` instead of `fin`. - -### Chaining - -There are two ways to chain promises. You can chain promises either -inside or outside handlers. The next two examples are equivalent. - -```javascript -return getUsername() -.then(function (username) { - return getUser(username) - .then(function (user) { - // if we get here without an error, - // the value returned here - // or the exception thrown here - // resolves the promise returned - // by the first line - }) -}); -``` - -```javascript -return getUsername() -.then(function (username) { - return getUser(username); -}) -.then(function (user) { - // if we get here without an error, - // the value returned here - // or the exception thrown here - // resolves the promise returned - // by the first line -}); -``` - -The only difference is nesting. Itâs useful to nest handlers if you -need to capture multiple input values in your closure. - -```javascript -function authenticate() { - return getUsername() - .then(function (username) { - return getUser(username); - }) - // chained because we will not need the user name in the next event - .then(function (user) { - return getPassword() - // nested because we need both user and password next - .then(function (password) { - if (user.passwordHash !== hash(password)) { - throw new Error("Can't authenticate"); - } - }); - }); -} -``` - - -### Combination - -You can turn an array of promises into a promise for the whole, -fulfilled array using ``all``. - -```javascript -return Q.all([ - eventualAdd(2, 2), - eventualAdd(10, 20) -]); -``` - -If you have a promise for an array, you can use ``spread`` as a -replacement for ``then``. The ``spread`` function âspreadsâ the -values over the arguments of the fulfillment handler. The rejection handler -will get called at the first sign of failure. That is, whichever of -the recived promises fails first gets handled by the rejection handler. - -```javascript -function eventualAdd(a, b) { - return Q.spread([a, b], function (a, b) { - return a + b; - }) -} -``` - -But ``spread`` calls ``all`` initially, so you can skip it in chains. - -```javascript -return getUsername() -.then(function (username) { - return [username, getUser(username)]; -}) -.spread(function (username, user) { -}); -``` - -The ``all`` function returns a promise for an array of values. When this -promise is fulfilled, the array contains the fulfillment values of the original -promises, in the same order as those promises. If one of the given promises -is rejected, the returned promise is immediately rejected, not waiting for the -rest of the batch. If you want to wait for all of the promises to either be -fulfilled or rejected, you can use ``allSettled``. - -```javascript -Q.allSettled(promises) -.then(function (results) { - results.forEach(function (result) { - if (result.state === "fulfilled") { - var value = result.value; - } else { - var reason = result.reason; - } - }); -}); -``` - - -### Sequences - -If you have a number of promise-producing functions that need -to be run sequentially, you can of course do so manually: - -```javascript -return foo(initialVal).then(bar).then(baz).then(qux); -``` - -However, if you want to run a dynamically constructed sequence of -functions, you'll want something like this: - -```javascript -var funcs = [foo, bar, baz, qux]; - -var result = Q(initialVal); -funcs.forEach(function (f) { - result = result.then(f); -}); -return result; -``` - -You can make this slightly more compact using `reduce`: - -```javascript -return funcs.reduce(function (soFar, f) { - return soFar.then(f); -}, Q(initialVal)); -``` - -Or, you could use th ultra-compact version: - -```javascript -return funcs.reduce(Q.when, Q()); -``` - -### Handling Errors - -One sometimes-unintuive aspect of promises is that if you throw an -exception in the fulfillment handler, it will not be be caught by the error -handler. - -```javascript -return foo() -.then(function (value) { - throw new Error("Can't bar."); -}, function (error) { - // We only get here if "foo" fails -}); -``` - -To see why this is, consider the parallel between promises and -``try``/``catch``. We are ``try``-ing to execute ``foo()``: the error -handler represents a ``catch`` for ``foo()``, while the fulfillment handler -represents code that happens *after* the ``try``/``catch`` block. -That code then needs its own ``try``/``catch`` block. - -In terms of promises, this means chaining your rejection handler: - -```javascript -return foo() -.then(function (value) { - throw new Error("Can't bar."); -}) -.fail(function (error) { - // We get here with either foo's error or bar's error -}); -``` - -### Progress Notification - -It's possible for promises to report their progress, e.g. for tasks that take a -long time like a file upload. Not all promises will implement progress -notifications, but for those that do, you can consume the progress values using -a third parameter to ``then``: - -```javascript -return uploadFile() -.then(function () { - // Success uploading the file -}, function (err) { - // There was an error, and we get the reason for error -}, function (progress) { - // We get notified of the upload's progress as it is executed -}); -``` - -Like `fail`, Q also provides a shorthand for progress callbacks -called `progress`: - -```javascript -return uploadFile().progress(function (progress) { - // We get notified of the upload's progress -}); -``` - -### The End - -When you get to the end of a chain of promises, you should either -return the last promise or end the chain. Since handlers catch -errors, itâs an unfortunate pattern that the exceptions can go -unobserved. - -So, either return it, - -```javascript -return foo() -.then(function () { - return "bar"; -}); -``` - -Or, end it. - -```javascript -foo() -.then(function () { - return "bar"; -}) -.done(); -``` - -Ending a promise chain makes sure that, if an error doesnât get -handled before the end, it will get rethrown and reported. - -This is a stopgap. We are exploring ways to make unhandled errors -visible without any explicit handling. - - -### The Beginning - -Everything above assumes you get a promise from somewhere else. This -is the common case. Every once in a while, you will need to create a -promise from scratch. - -#### Using ``Q.fcall`` - -You can create a promise from a value using ``Q.fcall``. This returns a -promise for 10. - -```javascript -return Q.fcall(function () { - return 10; -}); -``` - -You can also use ``fcall`` to get a promise for an exception. - -```javascript -return Q.fcall(function () { - throw new Error("Can't do it"); -}); -``` - -As the name implies, ``fcall`` can call functions, or even promised -functions. This uses the ``eventualAdd`` function above to add two -numbers. - -```javascript -return Q.fcall(eventualAdd, 2, 2); -``` - - -#### Using Deferreds - -If you have to interface with asynchronous functions that are callback-based -instead of promise-based, Q provides a few shortcuts (like ``Q.nfcall`` and -friends). But much of the time, the solution will be to use *deferreds*. - -```javascript -var deferred = Q.defer(); -FS.readFile("foo.txt", "utf-8", function (error, text) { - if (error) { - deferred.reject(new Error(error)); - } else { - deferred.resolve(text); - } -}); -return deferred.promise; -``` - -Note that a deferred can be resolved with a value or a promise. The -``reject`` function is a shorthand for resolving with a rejected -promise. - -```javascript -// this: -deferred.reject(new Error("Can't do it")); - -// is shorthand for: -var rejection = Q.fcall(function () { - throw new Error("Can't do it"); -}); -deferred.resolve(rejection); -``` - -This is a simplified implementation of ``Q.delay``. - -```javascript -function delay(ms) { - var deferred = Q.defer(); - setTimeout(deferred.resolve, ms); - return deferred.promise; -} -``` - -This is a simplified implementation of ``Q.timeout`` - -```javascript -function timeout(promise, ms) { - var deferred = Q.defer(); - Q.when(promise, deferred.resolve); - delay(ms).then(function () { - deferred.reject(new Error("Timed out")); - }); - return deferred.promise; -} -``` - -Finally, you can send a progress notification to the promise with -``deferred.notify``. - -For illustration, this is a wrapper for XML HTTP requests in the browser. Note -that a more [thorough][XHR] implementation would be in order in practice. - -[XHR]: https://github.com/montagejs/mr/blob/71e8df99bb4f0584985accd6f2801ef3015b9763/browser.js#L29-L73 - -```javascript -function requestOkText(url) { - var request = new XMLHttpRequest(); - var deferred = Q.defer(); - - request.open("GET", url, true); - request.onload = onload; - request.onerror = onerror; - request.onprogress = onprogress; - request.send(); - - function onload() { - if (request.status === 200) { - deferred.resolve(request.responseText); - } else { - deferred.reject(new Error("Status code was " + request.status)); - } - } - - function onerror() { - deferred.reject(new Error("Can't XHR " + JSON.stringify(url))); - } - - function onprogress(event) { - deferred.notify(event.loaded / event.total); - } - - return deferred.promise; -} -``` - -Below is an example of how to use this ``requestOkText`` function: - -```javascript -requestOkText("http://localhost:3000";) -.then(function (responseText) { - // If the HTTP response returns 200 OK, log the response text. - console.log(responseText); -}, function (error) { - // If there's an error or a non-200 status code, log the error. - console.error(error); -}, function (progress) { - // Log the progress as it comes in. - console.log("Request progress: " + Math.round(progress * 100) + "%"); -}); -``` - -### The Middle - -If you are using a function that may return a promise, but just might -return a value if it doesnât need to defer, you can use the âstaticâ -methods of the Q library. - -The ``when`` function is the static equivalent for ``then``. - -```javascript -return Q.when(valueOrPromise, function (value) { -}, function (error) { -}); -``` - -All of the other methods on a promise have static analogs with the -same name. - -The following are equivalent: - -```javascript -return Q.all([a, b]); -``` - -```javascript -return Q.fcall(function () { - return [a, b]; -}) -.all(); -``` - -When working with promises provided by other libraries, you should -convert it to a Q promise. Not all promise libraries make the same -guarantees as Q and certainly donât provide all of the same methods. -Most libraries only provide a partially functional ``then`` method. -This thankfully is all we need to turn them into vibrant Q promises. - -```javascript -return Q($.ajax(...)) -.then(function () { -}); -``` - -If there is any chance that the promise you receive is not a Q promise -as provided by your library, you should wrap it using a Q function. -You can even use ``Q.invoke`` as a shorthand. - -```javascript -return Q.invoke($, 'ajax', ...) -.then(function () { -}); -``` - - -### Over the Wire - -A promise can serve as a proxy for another object, even a remote -object. There are methods that allow you to optimistically manipulate -properties or call functions. All of these interactions return -promises, so they can be chained. - -``` -direct manipulation using a promise as a proxy --------------------------- ------------------------------- -value.foo promise.get("foo") -value.foo = value promise.put("foo", value) -delete value.foo promise.del("foo") -value.foo(...args) promise.post("foo", [args]) -value.foo(...args) promise.invoke("foo", ...args) -value(...args) promise.fapply([args]) -value(...args) promise.fcall(...args) -``` - -If the promise is a proxy for a remote object, you can shave -round-trips by using these functions instead of ``then``. To take -advantage of promises for remote objects, check out [Q-Connection][]. - -[Q-Connection]: https://github.com/kriskowal/q-connection - -Even in the case of non-remote objects, these methods can be used as -shorthand for particularly-simple fulfillment handlers. For example, you -can replace - -```javascript -return Q.fcall(function () { - return [{ foo: "bar" }, { foo: "baz" }]; -}) -.then(function (value) { - return value[0].foo; -}); -``` - -with - -```javascript -return Q.fcall(function () { - return [{ foo: "bar" }, { foo: "baz" }]; -}) -.get(0) -.get("foo"); -``` - - -### Adapting Node - -If you're working with functions that make use of the Node.js callback pattern, -where callbacks are in the form of `function(err, result)`, Q provides a few -useful utility functions for converting between them. The most straightforward -are probably `Q.nfcall` and `Q.nfapply` ("Node function call/apply") for calling -Node.js-style functions and getting back a promise: - -```javascript -return Q.nfcall(FS.readFile, "foo.txt", "utf-8"); -return Q.nfapply(FS.readFile, ["foo.txt", "utf-8"]); -``` - -If you are working with methods, instead of simple functions, you can easily -run in to the usual problems where passing a method to another functionâlike -`Q.nfcall`â"un-binds" the method from its owner. To avoid this, you can either -use `Function.prototype.bind` or some nice shortcut methods we provide: - -```javascript -return Q.ninvoke(redisClient, "get", "user:1:id"); -return Q.npost(redisClient, "get", ["user:1:id"]); -``` - -You can also create reusable wrappers with `Q.denodeify` or `Q.nbind`: - -```javascript -var readFile = Q.denodeify(FS.readFile); -return readFile("foo.txt", "utf-8"); - -var redisClientGet = Q.nbind(redisClient.get, redisClient); -return redisClientGet("user:1:id"); -``` - -Finally, if you're working with raw deferred objects, there is a -`makeNodeResolver` method on deferreds that can be handy: - -```javascript -var deferred = Q.defer(); -FS.readFile("foo.txt", "utf-8", deferred.makeNodeResolver()); -return deferred.promise; -``` - -### Long Stack Traces - -Q comes with optional support for âlong stack traces,â wherein the `stack` -property of `Error` rejection reasons is rewritten to be traced along -asynchronous jumps instead of stopping at the most recent one. As an example: - -```js -function theDepthsOfMyProgram() { - Q.delay(100).done(function explode() { - throw new Error("boo!"); - }); -} - -theDepthsOfMyProgram(); -``` - -usually would give a rather unhelpful stack trace looking something like - -``` -Error: boo! - at explode (/path/to/test.js:3:11) - at _fulfilled (/path/to/test.js:q:54) - at resolvedValue.promiseDispatch.done (/path/to/q.js:823:30) - at makePromise.promise.promiseDispatch (/path/to/q.js:496:13) - at pending (/path/to/q.js:397:39) - at process.startup.processNextTick.process._tickCallback (node.js:244:9) -``` - -But, if you turn this feature on by setting - -```js -Q.longStackSupport = true; -``` - -then the above code gives a nice stack trace to the tune of - -``` -Error: boo! - at explode (/path/to/test.js:3:11) -From previous event: - at theDepthsOfMyProgram (/path/to/test.js:2:16) - at Object.<anonymous> (/path/to/test.js:7:1) -``` - -Note how you can see the the function that triggered the async operation in the -stack trace! This is very helpful for debugging, as otherwise you end up getting -only the first line, plus a bunch of Q internals, with no sign of where the -operation started. - -This feature does come with somewhat-serious performance and memory overhead, -however. If you're working with lots of promises, or trying to scale a server -to many users, you should probably keep it off. But in development, go for it! - -## Tests - -You can view the results of the Q test suite [in your browser][tests]! - -[tests]: https://rawgithub.com/kriskowal/q/v1/spec/q-spec.html - -## License - -Copyright 2009â2014 Kristopher Michael Kowal -MIT License (enclosed) -
http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/f4e2ac6a/windows/bin/node_modules/q/benchmark/compare-with-callbacks.js ---------------------------------------------------------------------- diff --git a/windows/bin/node_modules/q/benchmark/compare-with-callbacks.js b/windows/bin/node_modules/q/benchmark/compare-with-callbacks.js deleted file mode 100644 index 97f1298..0000000 --- a/windows/bin/node_modules/q/benchmark/compare-with-callbacks.js +++ /dev/null @@ -1,71 +0,0 @@ -"use strict"; - -var Q = require("../q"); -var fs = require("fs"); - -suite("A single simple async operation", function () { - bench("with an immediately-fulfilled promise", function (done) { - Q().then(done); - }); - - bench("with direct setImmediate usage", function (done) { - setImmediate(done); - }); - - bench("with direct setTimeout(â¦, 0)", function (done) { - setTimeout(done, 0); - }); -}); - -suite("A fs.readFile", function () { - var denodeified = Q.denodeify(fs.readFile); - - set("iterations", 1000); - set("delay", 1000); - - bench("directly, with callbacks", function (done) { - fs.readFile(__filename, done); - }); - - bench("with Q.nfcall", function (done) { - Q.nfcall(fs.readFile, __filename).then(done); - }); - - bench("with a Q.denodeify'ed version", function (done) { - denodeified(__filename).then(done); - }); - - bench("with manual usage of deferred.makeNodeResolver", function (done) { - var deferred = Q.defer(); - fs.readFile(__filename, deferred.makeNodeResolver()); - deferred.promise.then(done); - }); -}); - -suite("1000 operations in parallel", function () { - function makeCounter(desiredCount, ultimateCallback) { - var soFar = 0; - return function () { - if (++soFar === desiredCount) { - ultimateCallback(); - } - }; - } - var numberOfOps = 1000; - - bench("with immediately-fulfilled promises", function (done) { - var counter = makeCounter(numberOfOps, done); - - for (var i = 0; i < numberOfOps; ++i) { - Q().then(counter); - } - }); - - bench("with direct setImmediate usage", function (done) { - var counter = makeCounter(numberOfOps, done); - - for (var i = 0; i < numberOfOps; ++i) { - setImmediate(counter); - } - }); -}); http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/f4e2ac6a/windows/bin/node_modules/q/benchmark/scenarios.js ---------------------------------------------------------------------- diff --git a/windows/bin/node_modules/q/benchmark/scenarios.js b/windows/bin/node_modules/q/benchmark/scenarios.js deleted file mode 100644 index 7c18564..0000000 --- a/windows/bin/node_modules/q/benchmark/scenarios.js +++ /dev/null @@ -1,36 +0,0 @@ -"use strict"; - -var Q = require("../q"); - -suite("Chaining", function () { - var numberToChain = 1000; - - bench("Chaining many already-fulfilled promises together", function (done) { - var currentPromise = Q(); - for (var i = 0; i < numberToChain; ++i) { - currentPromise = currentPromise.then(function () { - return Q(); - }); - } - - currentPromise.then(done); - }); - - bench("Chaining and then fulfilling the end of the chain", function (done) { - var deferred = Q.defer(); - - var currentPromise = deferred.promise; - for (var i = 0; i < numberToChain; ++i) { - (function () { - var promiseToReturn = currentPromise; - currentPromise = Q().then(function () { - return promiseToReturn; - }); - }()); - } - - currentPromise.then(done); - - deferred.resolve(); - }); -}); http://git-wip-us.apache.org/repos/asf/cordova-windows/blob/f4e2ac6a/windows/bin/node_modules/q/package.json ---------------------------------------------------------------------- diff --git a/windows/bin/node_modules/q/package.json b/windows/bin/node_modules/q/package.json deleted file mode 100644 index 96fedeb..0000000 --- a/windows/bin/node_modules/q/package.json +++ /dev/null @@ -1,93 +0,0 @@ -{ - "name": "q", - "version": "1.0.1", - "description": "A library for promises (CommonJS/Promises/A,B,D)", - "homepage": "https://github.com/kriskowal/q";, - "author": { - "name": "Kris Kowal", - "email": "k...@cixar.com", - "url": "https://github.com/kriskowal"; - }, - "keywords": [ - "q", - "promise", - "promises", - "promises-a", - "promises-aplus", - "deferred", - "future", - "async", - "flow control", - "fluent", - "browser", - "node" - ], - "contributors": [ - { - "name": "Kris Kowal", - "email": "k...@cixar.com", - "url": "https://github.com/kriskowal"; - }, - { - "name": "Irakli Gozalishvili", - "email": "rfo...@gmail.com", - "url": "http://jeditoolkit.com"; - }, - { - "name": "Domenic Denicola", - "email": "dome...@domenicdenicola.com", - "url": "http://domenicdenicola.com"; - } - ], - "bugs": { - "url": "http://github.com/kriskowal/q/issues"; - }, - "license": { - "type": "MIT", - "url": "http://github.com/kriskowal/q/raw/master/LICENSE"; - }, - "main": "q.js", - "repository": { - "type": "git", - "url": "git://github.com/kriskowal/q.git" - }, - "engines": { - "node": ">=0.6.0", - "teleport": ">=0.2.0" - }, - "dependencies": {}, - "devDependencies": { - "jshint": "~2.1.9", - "cover": "*", - "jasmine-node": "1.11.0", - "opener": "*", - "promises-aplus-tests": "1.x", - "grunt": "~0.4.1", - "grunt-cli": "~0.1.9", - "grunt-contrib-uglify": "~0.2.2", - "matcha": "~0.2.0" - }, - "scripts": { - "test": "jasmine-node spec && promises-aplus-tests spec/aplus-adapter", - "test-browser": "opener spec/q-spec.html", - "benchmark": "matcha", - "lint": "jshint q.js", - "cover": "cover run node_modules/jasmine-node/bin/jasmine-node spec && cover report html && opener cover_html/index.html", - "minify": "grunt", - "prepublish": "grunt" - }, - "overlay": { - "teleport": { - "dependencies": { - "system": ">=0.0.4" - } - } - }, - "directories": { - "test": "./spec" - }, - "readme": "[](http://travis-ci.org/kriskowal/q)\n\n<a href=\"http://promises-aplus.github.com/promises-spec\";>\n <img src=\"http://promises-aplus.github.com/promises-spec/assets/logo-small.png\"\n align=\"right\" alt=\"Promises/A+ logo\" />\n</a>\n\n*This is Q version 1, from the `v1` branch in Git. This documentation applies to\nthe latest of both the version 1 and version 0.9 release trains. These releases\nare stable. There will be no further releases of 0.9 after 0.9.7 which is nearly\nequivalent to version 1.0.0. All further releases of `q@~1.0` will be backward\ncompatible. The version 2 release train introduces significant but\nbackward-incompatible changes and is experimental at this time.*\n\nIf a function cannot return a value or throw an exception without\nblocking, it can return a promise instead. A promise is an object\nthat represents the return value or the thrown exception that t he\nfunction may eventually provide. A promise can also be used as a\nproxy for a [remote object][Q-Connection] to overcome latency.\n\n[Q-Connection]: https://github.com/kriskowal/q-connection\n\nOn the first pass, promises can mitigate the â[Pyramid of\nDoom][POD]â: the situation where code marches to the right faster\nthan it marches forward.\n\n[POD]: http://calculist.org/blog/2011/12/14/why-coroutines-wont-work-on-the-web/\n\n```javascript\nstep1(function (value1) {\n step2(value1, function(value2) {\n step3(value2, function(value3) {\n step4(value3, function(value4) {\n // Do something with value4\n });\n });\n });\n});\n```\n\nWith a promise library, you can flatten the pyramid.\n\n```javascript\nQ.fcall(promisedStep1)\n.then(promisedStep2)\n.then(promisedStep3)\n.then(promisedStep4)\n.then(function (value4) {\n // Do something with value4\n})\n.catch(function (error) {\n // Handle any error from all above st eps\n})\n.done();\n```\n\nWith this approach, you also get implicit error propagation, just like `try`,\n`catch`, and `finally`. An error in `promisedStep1` will flow all the way to\nthe `catch` function, where itâs caught and handled. (Here `promisedStepN` is\na version of `stepN` that returns a promise.)\n\nThe callback approach is called an âinversion of controlâ.\nA function that accepts a callback instead of a return value\nis saying, âDonât call me, Iâll call you.â. Promises\n[un-invert][IOC] the inversion, cleanly separating the input\narguments from control flow arguments. This simplifies the\nuse and creation of APIâs, particularly variadic,\nrest and spread arguments.\n\n[IOC]: http://www.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript\n\n\n## Getting Started\n\nThe Q module can be loaded as:\n\n- A ``<script>`` tag (creating a ``Q`` global variable): ~2.5 KB minified and\n gzippe d.\n- A Node.js and CommonJS module, available in [npm](https://npmjs.org/) as\n the [q](https://npmjs.org/package/q) package\n- An AMD module\n- A [component](https://github.com/component/component) as ``microjs/q``\n- Using [bower](http://bower.io/) as ``q``\n- Using [NuGet](http://nuget.org/) as [Q](https://nuget.org/packages/q)\n\nQ can exchange promises with jQuery, Dojo, When.js, WinJS, and more.\n\n## Resources\n\nOur [wiki][] contains a number of useful resources, including:\n\n- A method-by-method [Q API reference][reference].\n- A growing [examples gallery][examples], showing how Q can be used to make\n everything better. From XHR to database access to accessing the Flickr API,\n Q is there for you.\n- There are many libraries that produce and consume Q promises for everything\n from file system/database access or RPC to templating. For a list of some of\n the more popular ones, see [Libraries][].\n- If you want materials that introduce the promise concept generally, and the\n below tutorial isn't doing it for you, check out our collection of\n [presentations, blog posts, and podcasts][resources].\n- A guide for those [coming from jQuery's `$.Deferred`][jquery].\n\nWe'd also love to have you join the Q-Continuum [mailing list][].\n\n[wiki]: https://github.com/kriskowal/q/wiki\n[reference]: https://github.com/kriskowal/q/wiki/API-Reference\n[examples]: https://github.com/kriskowal/q/wiki/Examples-Gallery\n[Libraries]: https://github.com/kriskowal/q/wiki/Libraries\n[resources]: https://github.com/kriskowal/q/wiki/General-Promise-Resources\n[jquery]: https://github.com/kriskowal/q/wiki/Coming-from-jQuery\n[mailing list]: https://groups.google.com/forum/#!forum/q-continuum\n\n\n## Tutorial\n\nPromises have a ``then`` method, which you can use to get the eventual\nreturn value (fulfillment) or thrown exception (rejection).\n\n```javascript\npromiseMeSomething()\n.then(function (value) {\n}, function (reason) {\n});\n```\n\nIf ``promiseM eSomething`` returns a promise that gets fulfilled later\nwith a return value, the first function (the fulfillment handler) will be\ncalled with the value. However, if the ``promiseMeSomething`` function\ngets rejected later by a thrown exception, the second function (the\nrejection handler) will be called with the exception.\n\nNote that resolution of a promise is always asynchronous: that is, the\nfulfillment or rejection handler will always be called in the next turn of the\nevent loop (i.e. `process.nextTick` in Node). This gives you a nice\nguarantee when mentally tracing the flow of your code, namely that\n``then`` will always return before either handler is executed.\n\nIn this tutorial, we begin with how to consume and work with promises. We'll\ntalk about how to create them, and thus create functions like\n`promiseMeSomething` that return promises, [below](#the-beginning).\n\n\n### Propagation\n\nThe ``then`` method returns a promise, which in this example, Iâm\nassignin g to ``outputPromise``.\n\n```javascript\nvar outputPromise = getInputPromise()\n.then(function (input) {\n}, function (reason) {\n});\n```\n\nThe ``outputPromise`` variable becomes a new promise for the return\nvalue of either handler. Since a function can only either return a\nvalue or throw an exception, only one handler will ever be called and it\nwill be responsible for resolving ``outputPromise``.\n\n- If you return a value in a handler, ``outputPromise`` will get\n fulfilled.\n\n- If you throw an exception in a handler, ``outputPromise`` will get\n rejected.\n\n- If you return a **promise** in a handler, ``outputPromise`` will\n âbecomeâ that promise. Being able to become a new promise is useful\n for managing delays, combining results, or recovering from errors.\n\nIf the ``getInputPromise()`` promise gets rejected and you omit the\nrejection handler, the **error** will go to ``outputPromise``:\n\n```javascript\nvar outputPromise = getInputPromise()\n .then(function (value) {\n});\n```\n\nIf the input promise gets fulfilled and you omit the fulfillment handler, the\n**value** will go to ``outputPromise``:\n\n```javascript\nvar outputPromise = getInputPromise()\n.then(null, function (error) {\n});\n```\n\nQ promises provide a ``fail`` shorthand for ``then`` when you are only\ninterested in handling the error:\n\n```javascript\nvar outputPromise = getInputPromise()\n.fail(function (error) {\n});\n```\n\nIf you are writing JavaScript for modern engines only or using\nCoffeeScript, you may use `catch` instead of `fail`.\n\nPromises also have a ``fin`` function that is like a ``finally`` clause.\nThe final handler gets called, with no arguments, when the promise\nreturned by ``getInputPromise()`` either returns a value or throws an\nerror. The value returned or error thrown by ``getInputPromise()``\npasses directly to ``outputPromise`` unless the final handler fails, and\nmay be delayed if the final handler returns a promise.\n\n```j avascript\nvar outputPromise = getInputPromise()\n.fin(function () {\n // close files, database connections, stop servers, conclude tests\n});\n```\n\n- If the handler returns a value, the value is ignored\n- If the handler throws an error, the error passes to ``outputPromise``\n- If the handler returns a promise, ``outputPromise`` gets postponed. The\n eventual value or error has the same effect as an immediate return\n value or thrown error: a value would be ignored, an error would be\n forwarded.\n\nIf you are writing JavaScript for modern engines only or using\nCoffeeScript, you may use `finally` instead of `fin`.\n\n### Chaining\n\nThere are two ways to chain promises. You can chain promises either\ninside or outside handlers. The next two examples are equivalent.\n\n```javascript\nreturn getUsername()\n.then(function (username) {\n return getUser(username)\n .then(function (user) {\n // if we get here without an error,\n // the value re turned here\n // or the exception thrown here\n // resolves the promise returned\n // by the first line\n })\n});\n```\n\n```javascript\nreturn getUsername()\n.then(function (username) {\n return getUser(username);\n})\n.then(function (user) {\n // if we get here without an error,\n // the value returned here\n // or the exception thrown here\n // resolves the promise returned\n // by the first line\n});\n```\n\nThe only difference is nesting. Itâs useful to nest handlers if you\nneed to capture multiple input values in your closure.\n\n```javascript\nfunction authenticate() {\n return getUsername()\n .then(function (username) {\n return getUser(username);\n })\n // chained because we will not need the user name in the next event\n .then(function (user) {\n return getPassword()\n // nested because we need both user and password next\n .then(function (password) {\n if (user.passwordHash !== hash(password)) {\n throw new Error(\"Can't authenticate\");\n }\n });\n });\n}\n```\n\n\n### Combination\n\nYou can turn an array of promises into a promise for the whole,\nfulfilled array using ``all``.\n\n```javascript\nreturn Q.all([\n eventualAdd(2, 2),\n eventualAdd(10, 20)\n]);\n```\n\nIf you have a promise for an array, you can use ``spread`` as a\nreplacement for ``then``. The ``spread`` function âspreadsâ the\nvalues over the arguments of the fulfillment handler. The rejection handler\nwill get called at the first sign of failure. That is, whichever of\nthe recived promises fails first gets handled by the rejection handler.\n\n```javascript\nfunction eventualAdd(a, b) {\n return Q.spread([a, b], function (a, b) {\n return a + b;\n })\n}\n```\n\nBut ``spread`` calls ``all`` initially, so you can skip it in chains.\n\n```javascript\nreturn getUsername()\n.then(function (username) {\n return [username, getU ser(username)];\n})\n.spread(function (username, user) {\n});\n```\n\nThe ``all`` function returns a promise for an array of values. When this\npromise is fulfilled, the array contains the fulfillment values of the original\npromises, in the same order as those promises. If one of the given promises\nis rejected, the returned promise is immediately rejected, not waiting for the\nrest of the batch. If you want to wait for all of the promises to either be\nfulfilled or rejected, you can use ``allSettled``.\n\n```javascript\nQ.allSettled(promises)\n.then(function (results) {\n results.forEach(function (result) {\n if (result.state === \"fulfilled\") {\n var value = result.value;\n } else {\n var reason = result.reason;\n }\n });\n});\n```\n\n\n### Sequences\n\nIf you have a number of promise-producing functions that need\nto be run sequentially, you can of course do so manually:\n\n```javascript\nreturn foo(initialVal).then(bar).then( baz).then(qux);\n```\n\nHowever, if you want to run a dynamically constructed sequence of\nfunctions, you'll want something like this:\n\n```javascript\nvar funcs = [foo, bar, baz, qux];\n\nvar result = Q(initialVal);\nfuncs.forEach(function (f) {\n result = result.then(f);\n});\nreturn result;\n```\n\nYou can make this slightly more compact using `reduce`:\n\n```javascript\nreturn funcs.reduce(function (soFar, f) {\n return soFar.then(f);\n}, Q(initialVal));\n```\n\nOr, you could use th ultra-compact version:\n\n```javascript\nreturn funcs.reduce(Q.when, Q());\n```\n\n### Handling Errors\n\nOne sometimes-unintuive aspect of promises is that if you throw an\nexception in the fulfillment handler, it will not be be caught by the error\nhandler.\n\n```javascript\nreturn foo()\n.then(function (value) {\n throw new Error(\"Can't bar.\");\n}, function (error) {\n // We only get here if \"foo\" fails\n});\n```\n\nTo see why this is, consider the parallel between promises and\n` `try``/``catch``. We are ``try``-ing to execute ``foo()``: the error\nhandler represents a ``catch`` for ``foo()``, while the fulfillment handler\nrepresents code that happens *after* the ``try``/``catch`` block.\nThat code then needs its own ``try``/``catch`` block.\n\nIn terms of promises, this means chaining your rejection handler:\n\n```javascript\nreturn foo()\n.then(function (value) {\n throw new Error(\"Can't bar.\");\n})\n.fail(function (error) {\n // We get here with either foo's error or bar's error\n});\n```\n\n### Progress Notification\n\nIt's possible for promises to report their progress, e.g. for tasks that take a\nlong time like a file upload. Not all promises will implement progress\nnotifications, but for those that do, you can consume the progress values using\na third parameter to ``then``:\n\n```javascript\nreturn uploadFile()\n.then(function () {\n // Success uploading the file\n}, function (err) {\n // There was an error, and we get the reason for error\n}, function (progress) {\n // We get notified of the upload's progress as it is executed\n});\n```\n\nLike `fail`, Q also provides a shorthand for progress callbacks\ncalled `progress`:\n\n```javascript\nreturn uploadFile().progress(function (progress) {\n // We get notified of the upload's progress\n});\n```\n\n### The End\n\nWhen you get to the end of a chain of promises, you should either\nreturn the last promise or end the chain. Since handlers catch\nerrors, itâs an unfortunate pattern that the exceptions can go\nunobserved.\n\nSo, either return it,\n\n```javascript\nreturn foo()\n.then(function () {\n return \"bar\";\n});\n```\n\nOr, end it.\n\n```javascript\nfoo()\n.then(function () {\n return \"bar\";\n})\n.done();\n```\n\nEnding a promise chain makes sure that, if an error doesnât get\nhandled before the end, it will get rethrown and reported.\n\nThis is a stopgap. We are exploring ways to make unhandled errors\nvisible without any explicit handling. \n\n\n### The Beginning\n\nEverything above assumes you get a promise from somewhere else. This\nis the common case. Every once in a while, you will need to create a\npromise from scratch.\n\n#### Using ``Q.fcall``\n\nYou can create a promise from a value using ``Q.fcall``. This returns a\npromise for 10.\n\n```javascript\nreturn Q.fcall(function () {\n return 10;\n});\n```\n\nYou can also use ``fcall`` to get a promise for an exception.\n\n```javascript\nreturn Q.fcall(function () {\n throw new Error(\"Can't do it\");\n});\n```\n\nAs the name implies, ``fcall`` can call functions, or even promised\nfunctions. This uses the ``eventualAdd`` function above to add two\nnumbers.\n\n```javascript\nreturn Q.fcall(eventualAdd, 2, 2);\n```\n\n\n#### Using Deferreds\n\nIf you have to interface with asynchronous functions that are callback-based\ninstead of promise-based, Q provides a few shortcuts (like ``Q.nfcall`` and\nfriends). But much of the time, the solution will be to use * deferreds*.\n\n```javascript\nvar deferred = Q.defer();\nFS.readFile(\"foo.txt\", \"utf-8\", function (error, text) {\n if (error) {\n deferred.reject(new Error(error));\n } else {\n deferred.resolve(text);\n }\n});\nreturn deferred.promise;\n```\n\nNote that a deferred can be resolved with a value or a promise. The\n``reject`` function is a shorthand for resolving with a rejected\npromise.\n\n```javascript\n// this:\ndeferred.reject(new Error(\"Can't do it\"));\n\n// is shorthand for:\nvar rejection = Q.fcall(function () {\n throw new Error(\"Can't do it\");\n});\ndeferred.resolve(rejection);\n```\n\nThis is a simplified implementation of ``Q.delay``.\n\n```javascript\nfunction delay(ms) {\n var deferred = Q.defer();\n setTimeout(deferred.resolve, ms);\n return deferred.promise;\n}\n```\n\nThis is a simplified implementation of ``Q.timeout``\n\n```javascript\nfunction timeout(promise, ms) {\n var deferred = Q.defer();\n Q.when(promise, defe rred.resolve);\n delay(ms).then(function () {\n deferred.reject(new Error(\"Timed out\"));\n });\n return deferred.promise;\n}\n```\n\nFinally, you can send a progress notification to the promise with\n``deferred.notify``.\n\nFor illustration, this is a wrapper for XML HTTP requests in the browser. Note\nthat a more [thorough][XHR] implementation would be in order in practice.\n\n[XHR]: https://github.com/montagejs/mr/blob/71e8df99bb4f0584985accd6f2801ef3015b9763/browser.js#L29-L73\n\n```javascript\nfunction requestOkText(url) {\n var request = new XMLHttpRequest();\n var deferred = Q.defer();\n\n request.open(\"GET\", url, true);\n request.onload = onload;\n request.onerror = onerror;\n request.onprogress = onprogress;\n request.send();\n\n function onload() {\n if (request.status === 200) {\n deferred.resolve(request.responseText);\n } else {\n deferred.reject(new Error(\"Status code was \" + request.statu s));\n }\n }\n\n function onerror() {\n deferred.reject(new Error(\"Can't XHR \" + JSON.stringify(url)));\n }\n\n function onprogress(event) {\n deferred.notify(event.loaded / event.total);\n }\n\n return deferred.promise;\n}\n```\n\nBelow is an example of how to use this ``requestOkText`` function:\n\n```javascript\nrequestOkText(\"http://localhost:3000\";)\n.then(function (responseText) {\n // If the HTTP response returns 200 OK, log the response text.\n console.log(responseText);\n}, function (error) {\n // If there's an error or a non-200 status code, log the error.\n console.error(error);\n}, function (progress) {\n // Log the progress as it comes in.\n console.log(\"Request progress: \" + Math.round(progress * 100) + \"%\");\n});\n```\n\n### The Middle\n\nIf you are using a function that may return a promise, but just might\nreturn a value if it doesnât need to defer, you can use the âstaticâ\nmethods of the Q libra ry.\n\nThe ``when`` function is the static equivalent for ``then``.\n\n```javascript\nreturn Q.when(valueOrPromise, function (value) {\n}, function (error) {\n});\n```\n\nAll of the other methods on a promise have static analogs with the\nsame name.\n\nThe following are equivalent:\n\n```javascript\nreturn Q.all([a, b]);\n```\n\n```javascript\nreturn Q.fcall(function () {\n return [a, b];\n})\n.all();\n```\n\nWhen working with promises provided by other libraries, you should\nconvert it to a Q promise. Not all promise libraries make the same\nguarantees as Q and certainly donât provide all of the same methods.\nMost libraries only provide a partially functional ``then`` method.\nThis thankfully is all we need to turn them into vibrant Q promises.\n\n```javascript\nreturn Q($.ajax(...))\n.then(function () {\n});\n```\n\nIf there is any chance that the promise you receive is not a Q promise\nas provided by your library, you should wrap it using a Q function.\nYou can even use `` Q.invoke`` as a shorthand.\n\n```javascript\nreturn Q.invoke($, 'ajax', ...)\n.then(function () {\n});\n```\n\n\n### Over the Wire\n\nA promise can serve as a proxy for another object, even a remote\nobject. There are methods that allow you to optimistically manipulate\nproperties or call functions. All of these interactions return\npromises, so they can be chained.\n\n```\ndirect manipulation using a promise as a proxy\n-------------------------- -------------------------------\nvalue.foo promise.get(\"foo\")\nvalue.foo = value promise.put(\"foo\", value)\ndelete value.foo promise.del(\"foo\")\nvalue.foo(...args) promise.post(\"foo\", [args])\nvalue.foo(...args) promise.invoke(\"foo\", ...args)\nvalue(...args) promise.fapply([args])\nvalue(...args) promise.fcall(...args)\n```\n\nIf the promise is a proxy for a remote object, you can shave\nround-trips by using these functions instead of `` then``. To take\nadvantage of promises for remote objects, check out [Q-Connection][].\n\n[Q-Connection]: https://github.com/kriskowal/q-connection\n\nEven in the case of non-remote objects, these methods can be used as\nshorthand for particularly-simple fulfillment handlers. For example, you\ncan replace\n\n```javascript\nreturn Q.fcall(function () {\n return [{ foo: \"bar\" }, { foo: \"baz\" }];\n})\n.then(function (value) {\n return value[0].foo;\n});\n```\n\nwith\n\n```javascript\nreturn Q.fcall(function () {\n return [{ foo: \"bar\" }, { foo: \"baz\" }];\n})\n.get(0)\n.get(\"foo\");\n```\n\n\n### Adapting Node\n\nIf you're working with functions that make use of the Node.js callback pattern,\nwhere callbacks are in the form of `function(err, result)`, Q provides a few\nuseful utility functions for converting between them. The most straightforward\nare probably `Q.nfcall` and `Q.nfapply` (\"Node function call/apply\") for calling\nNode.js-style functions and getting ba ck a promise:\n\n```javascript\nreturn Q.nfcall(FS.readFile, \"foo.txt\", \"utf-8\");\nreturn Q.nfapply(FS.readFile, [\"foo.txt\", \"utf-8\"]);\n```\n\nIf you are working with methods, instead of simple functions, you can easily\nrun in to the usual problems where passing a method to another functionâlike\n`Q.nfcall`â\"un-binds\" the method from its owner. To avoid this, you can either\nuse `Function.prototype.bind` or some nice shortcut methods we provide:\n\n```javascript\nreturn Q.ninvoke(redisClient, \"get\", \"user:1:id\");\nreturn Q.npost(redisClient, \"get\", [\"user:1:id\"]);\n```\n\nYou can also create reusable wrappers with `Q.denodeify` or `Q.nbind`:\n\n```javascript\nvar readFile = Q.denodeify(FS.readFile);\nreturn readFile(\"foo.txt\", \"utf-8\");\n\nvar redisClientGet = Q.nbind(redisClient.get, redisClient);\nreturn redisClientGet(\"user:1:id\");\n```\n\nFinally, if you're working with raw deferred objects, there is a\n`makeNodeResolver` method on deferreds that ca n be handy:\n\n```javascript\nvar deferred = Q.defer();\nFS.readFile(\"foo.txt\", \"utf-8\", deferred.makeNodeResolver());\nreturn deferred.promise;\n```\n\n### Long Stack Traces\n\nQ comes with optional support for âlong stack traces,â wherein the `stack`\nproperty of `Error` rejection reasons is rewritten to be traced along\nasynchronous jumps instead of stopping at the most recent one. As an example:\n\n```js\nfunction theDepthsOfMyProgram() {\n Q.delay(100).done(function explode() {\n throw new Error(\"boo!\");\n });\n}\n\ntheDepthsOfMyProgram();\n```\n\nusually would give a rather unhelpful stack trace looking something like\n\n```\nError: boo!\n at explode (/path/to/test.js:3:11)\n at _fulfilled (/path/to/test.js:q:54)\n at resolvedValue.promiseDispatch.done (/path/to/q.js:823:30)\n at makePromise.promise.promiseDispatch (/path/to/q.js:496:13)\n at pending (/path/to/q.js:397:39)\n at process.startup.processNextTick.process._tickCallback (node.js:244: 9)\n```\n\nBut, if you turn this feature on by setting\n\n```js\nQ.longStackSupport = true;\n```\n\nthen the above code gives a nice stack trace to the tune of\n\n```\nError: boo!\n at explode (/path/to/test.js:3:11)\nFrom previous event:\n at theDepthsOfMyProgram (/path/to/test.js:2:16)\n at Object.<anonymous> (/path/to/test.js:7:1)\n```\n\nNote how you can see the the function that triggered the async operation in the\nstack trace! This is very helpful for debugging, as otherwise you end up getting\nonly the first line, plus a bunch of Q internals, with no sign of where the\noperation started.\n\nThis feature does come with somewhat-serious performance and memory overhead,\nhowever. If you're working with lots of promises, or trying to scale a server\nto many users, you should probably keep it off. But in development, go for it!\n\n## Tests\n\nYou can view the results of the Q test suite [in your browser][tests]!\n\n[tests]: https://rawgithub.com/kriskowal/q/v1/spec/q-spe c.html\n\n## License\n\nCopyright 2009â2014 Kristopher Michael Kowal\nMIT License (enclosed)\n\n", - "readmeFilename": "README.md", - "_id": "q@1.0.1", - "_from": "q@" -}
![http://promises-aplus.github.com/promises-spec/assets/logo-small.png"](http://promises-aplus.github.com/promises-spec/assets/logo-small.png"){kind=link}
![http://promises-aplus.github.com/promises-spec/assets/logo-small.png\"\n](http://promises-aplus.github.com/promises-spec/assets/logo-small.png\"\n){kind=link}