\n This article is partially or completely unfinished.\n You are welcome to create pull requests\n to help completing this article.\n
\n eos\n elsif link == \".\"\n if content =~ /#\\d+/\n url = \"https://github.com/petkaantonov/bluebird/issues/\" + content[1..-1]\n else\n url = \"/docs/api/\" + Helpers.clean(content) + \".html\"\n end\n return \"#{content}\"\n else\n return \"#{content}\"\n end\n end\nend\n\nclass WithHighlights < Redcarpet::Render::HTML\n def block_code(code, language)\n Pygments.highlight(code, :lexer => language)\n end\nend\n"
},
{
"path": "docs/css/main.css",
"content": "body {\n font-size: 16px;\n}\n\nbody > .container {\n padding-bottom: 50px;\n}\n\n.navbar-bluebird {\n font-family: 'Raleway', sans-serif;\n font-size: 18px;\n margin-top: 50px;\n text-transform:uppercase;\n}\n\n.nav {\n font-family: 'Raleway', sans-serif;\n}\n\n.nav.bb-nav > li > a{\n transition: all 0.3s ease-in-out;\n border-bottom: 1px solid rgba(0,0,0,0);\n}\n.nav.bb-nav > li > a:focus, .nav.bb-nav > li > a:hover,\n.nav.bb-nav > li.active > a {\n background-color:initial;\n border-bottom:1px solid #BE7306;\n}\n\n.nav a {\n color: #BE7306;\n}\n\n.nav.left-nav li a {\n padding: 2px 0px;\n font-size: 14px;\n font-family: 'Raleway', sans-serif;\n}\n\n.nav.left-nav li a:focus, .nav.left-nav li a:hover {\n background: none;\n text-decoration: underline;\n}\n\n.navbar-bluebird li {\n text-align:center;\n}\nh1,h2,h3,h4,h5,h6{\n font-family: 'Raleway', sans-serif;\n /*color:#5275B4;*/\n color: #1B4288;\n}\n.api-code-section h2, code, pre {\n font-family: 'Consolas', 'Lucida Console', 'Courier New', 'monospace'\n}\nbody {\n margin-top:10px;\n}\n\n.icon-bar {\n background-color:#5275B4;\n}\n.promises-showroom .arrow {\n text-align: center;\n margin-top: 100px;\n color:#EC9313;\n}\n\npre{\n background-color: initial;\n border: none;\n margin:0px;\n padding:0px;\n}\n.promises-showroom .hljs{\n border-radius: 6px;\n padding-left: 30px;\n padding-bottom: 15px;\n}\n.take-action{\n position:relative;\n min-height:300px;\n\n}\n\n.take-action .cloud-bg{\n width: 100%;\n height: 300px;\n border: none;\n}\n\n.take-action .action-buttons{\n position:absolute;\n top:50%;\n text-align:center;\n width:100%;\n}\n.btn-bb {\n font-family: 'Raleway', sans-serif;\n color: white;\n}\n.btn-beak{\n background-color: #EC9313;\n border-bottom: 4px solid #BE7306;\n}\n.btn-wings {\n background-color: #265584;\n border-bottom: 4px solid #1A3A59;\n}\n.btn-bb:hover{\n color:white;\n}\n.undo-margin{\n margin-left:-15px;\n}\n\n.main-line{\n font-family: 'Raleway', sans-serif;\n margin-bottom: 59px;\n margin-top: -74px;\n font-size: 20px;\n color:white;\n}\n\n.tagline {\n font-family: 'Raleway', sans-serif;\n font-size:26px;\n color:#5275B4;\n font-weight:200;\n}\n\n.nav-child {\n margin-left:20px;\n}\n.title:hover{\n text-decoration:none;\n}\n\n.header-anchor {\n opacity: 0;\n\n -webkit-transition: opacity 0.2s ease-in-out 0.1s;\n -moz-transition: opacity 0.2s ease-in-out 0.1s;\n -ms-transition: opacity 0.2s ease-in-out 0.1s;\n outline: none;\n}\n\n.header-anchor:active, .header-anchor:focus {\n outline: none;\n}\n\nh1:hover .header-anchor,\nh2:hover .header-anchor,\nh3:hover .header-anchor,\nh4:hover .header-anchor,\nh5:hover .header-anchor,\nh6:hover .header-anchor {\n opacity: 1;\n}\n\n.api-reference-menu {\n -moz-column-count: 2;\n -webkit-column-count: 2;\n columns: 2;\n margin-bottom: 50px;\n}\n\n.post-info {\n float: right;\n}\n\n.info-box {\n margin-top: 20px;\n color: #8a6d3b;\n background-color: #fcf8e3;\n border-color: #faebcc;\n padding: 15px;\n margin-bottom: 20px;\n border: 1px dashed #8a6d3b;\n border-radius: 4px;\n}\n\n.supporter.reaktor {\n width: 200px;\n margin: 0px auto;\n}\n"
},
{
"path": "docs/css/mono-blue.css",
"content": ".highlight {\n display: block;\n overflow-x: auto;\n padding: 0.5em;\n margin: 15px 0px;\n background: #eaeef3;\n -webkit-text-size-adjust: none;\n color: #00193a;\n}\n\ncode {\n color: #00193a;\n background: #eaeef3;\n}\n\na code {\n color: #337AB7;\n}\n\n.highlight .hll { background-color: #ffffcc }\n.highlight .c { color: #738191; font-style: italic } /* Comment */\n.highlight .err { border: 1px solid #FF0000 } /* Error */\n.highlight .k { color: #4c81c9; font-weight: bold } /* Keyword */\n.highlight .o { color: #666666 } /* Operator */\n.highlight .cm { color: #738191; font-style: italic } /* Comment.Multiline */\n.highlight .cp { color: #BC7A00 } /* Comment.Preproc */\n.highlight .c1 { color: #738191; font-style: italic } /* Comment.Single */\n.highlight .cs { color: #738191; font-style: italic } /* Comment.Special */\n.highlight .gd { color: #A00000 } /* Generic.Deleted */\n.highlight .ge { font-style: italic } /* Generic.Emph */\n.highlight .gr { color: #FF0000 } /* Generic.Error */\n.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n.highlight .gi { color: #00A000 } /* Generic.Inserted */\n.highlight .go { color: #808080 } /* Generic.Output */\n.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n.highlight .gs { font-weight: bold } /* Generic.Strong */\n.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n.highlight .gt { color: #0040D0 } /* Generic.Traceback */\n.highlight .kc { color: #4c81c9; font-weight: bold } /* Keyword.Constant */\n.highlight .kd { color: #4c81c9; font-weight: bold } /* Keyword.Declaration */\n.highlight .kn { color: #4c81c9; font-weight: bold } /* Keyword.Namespace */\n.highlight .kp { color: #4c81c9 } /* Keyword.Pseudo */\n.highlight .kr { color: #4c81c9; font-weight: bold } /* Keyword.Reserved */\n.highlight .kt { color: #B00040 } /* Keyword.Type */\n.highlight .m { color: #666666 } /* Literal.Number */\n.highlight .s { color: #BE7306;} /* Literal.String */\n.highlight .na { color: #7D9029 } /* Name.Attribute */\n.highlight .nb { color: #4c81c9 } /* Name.Builtin */\n.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n.highlight .no { color: #880000 } /* Name.Constant */\n.highlight .nd { color: #AA22FF } /* Name.Decorator */\n.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */\n.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n.highlight .nf { color: #0000FF } /* Name.Function */\n.highlight .nl { color: #A0A000 } /* Name.Label */\n.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n.highlight .nt { color: #4c81c9; font-weight: bold } /* Name.Tag */\n.highlight .nv { color: #19177C } /* Name.Variable */\n.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n.highlight .w { color: #bbbbbb } /* Text.Whitespace */\n.highlight .mf { color: #666666 } /* Literal.Number.Float */\n.highlight .mh { color: #666666 } /* Literal.Number.Hex */\n.highlight .mi { color: #666666 } /* Literal.Number.Integer */\n.highlight .mo { color: #666666 } /* Literal.Number.Oct */\n.highlight .sb { color: #BE7306 } /* Literal.String.Backtick */\n.highlight .sc { color: #BE7306 } /* Literal.String.Char */\n.highlight .sd { color: #BE7306; font-style: italic } /* Literal.String.Doc */\n.highlight .s2 { color: #BE7306 } /* Literal.String.Double */\n.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n.highlight .sh { color: #BE7306 } /* Literal.String.Heredoc */\n.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n.highlight .sx { color: #BE7306 } /* Literal.String.Other */\n.highlight .sr { color: #BB6688 } /* Literal.String.Regex */\n.highlight .s1 { color: #BE7306 } /* Literal.String.Single */\n.highlight .ss { color: #19177C } /* Literal.String.Symbol */\n.highlight .bp { color: #4c81c9 } /* Name.Builtin.Pseudo */\n.highlight .vc { color: #19177C } /* Name.Variable.Class */\n.highlight .vg { color: #19177C } /* Name.Variable.Global */\n.highlight .vi { color: #19177C } /* Name.Variable.Instance */\n.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */\n"
},
{
"path": "docs/docs/anti-patterns.md",
"content": "---\nid: anti-patterns\ntitle: Anti-patterns\n---\n\nThis page will contain common promise anti-patterns that are exercised in the wild.\n\n\n- [The explicit construction anti-pattern](#the-explicit-construction-anti-pattern)\n- [The `.then(success, fail)` anti-pattern](#the-.then)\n\n##The Explicit Construction Anti-Pattern\n\nThis is the most common anti-pattern. It is easy to fall into this when you don't really understand promises and think of them as glorified event emitters or callback utility. It's also sometimes called the promise constructor anti-pattern. Let's recap: promises are about making asynchronous code retain most of the lost properties of synchronous code such as flat indentation and one exception channel. This pattern is also called the deferred anti-pattern.\n\nIn the explicit construction anti-pattern, promise objects are created for no reason, complicating code.\n\nFirst example is creating deferred object when you already have a promise or thenable:\n\n```js\n//Code copyright by Twisternha http://stackoverflow.com/a/19486699/995876 CC BY-SA 2.5\nmyApp.factory('Configurations', function (Restangular, MotorRestangular, $q) {\n var getConfigurations = function () {\n var deferred = $q.defer();\n\n MotorRestangular.all('Motors').getList().then(function (Motors) {\n //Group by Config\n var g = _.groupBy(Motors, 'configuration');\n //Map values\n var mapped = _.map(g, function (m) {\n return {\n id: m[0].configuration,\n configuration: m[0].configuration,\n sizes: _.map(m, function (a) {\n return a.sizeMm\n })\n }\n });\n deferred.resolve(mapped);\n });\n return deferred.promise;\n };\n\n return {\n config: getConfigurations()\n }\n\n});\n```\n\nThis superfluous wrapping is also dangerous, any kind of errors and rejections are swallowed and not propagated to the caller of this function.\n\nInstead of using the Deferred anti-pattern, the code should simply return the promise it already has and propagate values using `return`:\n\n```js\nmyApp.factory('Configurations', function (Restangular, MotorRestangular, $q) {\n var getConfigurations = function () {\n //Just return the promise we already have!\n return MotorRestangular.all('Motors').getList().then(function (Motors) {\n //Group by Cofig\n var g = _.groupBy(Motors, 'configuration');\n //Return the mapped array as the value of this promise\n return _.map(g, function (m) {\n return {\n id: m[0].configuration,\n configuration: m[0].configuration,\n sizes: _.map(m, function (a) {\n return a.sizeMm\n })\n }\n });\n });\n };\n\n return {\n config: getConfigurations()\n }\n\n});\n```\n\nNot only is the code shorter but more importantly, if there is any error it will propagate properly to the final consumer.\n\nSecond example is creating a function that does nothing but manually wrap a callback API and doing a poor job at that:\n\n```js\nfunction applicationFunction(arg1) {\n return new Promise(function(resolve, reject){ //Or Q.defer() in Q\n libraryFunction(arg1, function (err, value) {\n if (err) {\n reject(err);\n } else {\n resolve(value);\n }\n });\n}\n```\n\nThis is reinventing the square wheel because any callback API wrapping can and should be done immediately using the promise library's promisification methods:\n\n```js\nvar applicationFunction = Promise.promisify(libraryFunction);\n```\n\nThe generic promisification is likely to be faster because it can use internals directly but also handles edge cases like `libraryFunction` throwing synchronously or using multiple success values.\n\n\n**So when should deferred be used?**\n\nWell simply, when you have to.\n\nYou might have to use a deferred object when wrapping a callback API that doesn't follow the standard convention. Like `setTimeout`:\n\n```js\n//setTimeout that returns a promise\nfunction delay(ms) {\n var deferred = Promise.defer(); // warning, defer is deprecated, use the promise constructor\n setTimeout(function(){\n deferred.fulfill();\n }, ms);\n return deferred.promise;\n}\n```\n\nSuch wrappers should be rare, if they're common for the reason that the promise library cannot generically promisify them, you should file an issue.\n\nIf you cannot do static promisification (promisify and promisifyAll perform too slowly to use at runtime), you may use [Promise.fromCallback](.).\n\nAlso see [this StackOverflow question](http://stackoverflow.com/questions/23803743/what-is-the-deferred-antipattern-and-how-do-i-avoid-it) for more examples and a debate around it.\n\n##The `.then(success, fail)` anti-pattern\n\n*Almost* a sure sign of using promises as glorified callbacks. Instead of `doThat(function(err, success))` you do `doThat().then(success, err)` and rationalize to yourself that at least the code is \"less coupled\" or something.\n\nThe `.then` signature is mostly about interop, there is *almost* never a reason to use `.then(success, fail)` in application code. It is even awkward to express it in the sync parallel:\n\n```js\nvar t0;\ntry {\n t0 = doThat();\n}\ncatch(e) {\n\n}\n//deal with t0 here and waste the try-catch\nvar stuff = JSON.parse(t0);\n```\n\nIt is more likely that you would write this instead in the sync world:\n\n```js\ntry {\n var stuff = JSON.parse(doThat());\n}\ncatch(e) {\n\n}\n```\n\nSo please write the same when using promises too:\n\n```js\ndoThat()\n.then(function(v) {\n return JSON.parse(v);\n})\n.catch(function(e) {\n\n});\n```\n\n`.catch` is specified for built-in Javascript promises and is \"sugar\" for `.then(null, function(){})`. Since the way errors work in promises is almost the entire point (and the only thing jQuery never got right, even if it used `.pipe` as a `.then`), I really hope the implementation you are using provides this method for readability.\n"
},
{
"path": "docs/docs/api/aggregateerror.md",
"content": "---\nlayout: api\nid: aggregateerror\ntitle: AggregateError\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##AggregateError\n\n```js\nnew AggregateError() extends Array -> AggregateError\n```\n\n\nA collection of errors. `AggregateError` is an array-like object, with numeric indices and a `.length` property. It supports all generic array methods such as `.forEach` directly.\n\n`AggregateError`s are caught in [`.error`](.) handlers, even if the contained errors are not operational.\n\n[Promise.some](.) and [Promise.any](.) use `AggregateError` as rejection reason when they fail.\n\n\nExample:\n\n```js\n//Assumes AggregateError has been made global\nvar err = new AggregateError();\nerr.push(new Error(\"first error\"));\nerr.push(new Error(\"second error\"));\nthrow err;\n```\n\n\n
\n\n\n\n"
},
{
"path": "docs/docs/api/all.md",
"content": "---\nlayout: api\nid: all\ntitle: .all\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.all\n\n```js\n.all() -> Promise\n```\n\nConsume the resolved [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) and wait for all items to fulfill similar to [Promise.all()](.).\n\n[Promise.resolve(iterable).all()](.) is the same as [Promise.all(iterable)](.).\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/any.md",
"content": "---\nlayout: api\nid: any\ntitle: .any\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.any\n\n```js\n.any() -> Promise\n```\n\nSame as [Promise.any(this)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/ascallback.md",
"content": "---\nlayout: api\nid: ascallback\ntitle: .asCallback\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.asCallback\n\n```js\n.asCallback(\n [function(any error, any value) callback],\n [Object {spread: boolean=false} options]\n) -> this\n```\n```js\n.nodeify(\n [function(any error, any value) callback],\n [Object {spread: boolean=false} options]\n) -> this\n```\n\nRegister a node-style callback on this promise. When this promise is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be `null` in case of success.\n\nReturns back this promise instead of creating a new one. If the `callback` argument is not a function, this method does not do anything.\n\nThis can be used to create APIs that both accept node-style callbacks and return promises:\n\n```js\nfunction getDataFor(input, callback) {\n return dataFromDataBase(input).asCallback(callback);\n}\n```\n\nThe above function can then make everyone happy.\n\nPromises:\n\n```js\ngetDataFor(\"me\").then(function(dataForMe) {\n console.log(dataForMe);\n});\n```\n\nNormal callbacks:\n\n```js\ngetDataFor(\"me\", function(err, dataForMe) {\n if( err ) {\n console.error( err );\n }\n console.log(dataForMe);\n});\n```\n\nPromises can be rejected with falsy values (or no value at all, equal to rejecting with `undefined`), however `.asCallback` will call the callback with an `Error` object if the promise's rejection reason is a falsy value. You can retrieve the original falsy value from the error's `.cause` property.\n\nExample:\n\n```js\nPromise.reject(null).asCallback(function(err, result) {\n // If is executed\n if (err) {\n // Logs 'null'\n console.log(err.cause);\n }\n});\n```\n\nThere is no effect on performance if the user doesn't actually pass a node-style callback function.\n\n####Option: spread\n\nSome nodebacks expect more than 1 success value but there is no mapping for this in the promise world. You may specify the option `spread` to call the nodeback with multiple values when the fulfillment value is an array:\n\n```js\nPromise.resolve([1,2,3]).asCallback(function(err, result) {\n // err == null\n // result is the array [1,2,3]\n});\n\nPromise.resolve([1,2,3]).asCallback(function(err, a, b, c) {\n // err == null\n // a == 1\n // b == 2\n // c == 3\n}, {spread: true});\n\nPromise.resolve(123).asCallback(function(err, a, b, c) {\n // err == null\n // a == 123\n // b == undefined\n // c == undefined\n}, {spread: true});\n```\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/bind.md",
"content": "---\nlayout: api\nid: bind\ntitle: .bind\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.bind\n\n```js\n.bind(any|Promise thisArg) -> BoundPromise\n```\n\nSame as calling [Promise.bind(thisArg, thisPromise)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/built-in-error-types.md",
"content": "---\nlayout: api\nid: built-in-error-types\ntitle: Built-in error types\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Built-in error types\n\nBluebird includes a few built-in error types for common usage. All error types have the same identity across different copies of bluebird\nmodule so that pattern matching works in [`.catch`](.). All error types have a constructor taking a message string as their first argument, with that message\nbecoming the `.message` property of the error object.\n\nBy default the error types need to be referenced from the Promise constructor, e.g. to get a reference to [TimeoutError](.), do `var TimeoutError = Promise.TimeoutError`. However, for convenience you will probably want to just make the references global.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/call.md",
"content": "---\nlayout: api\nid: call\ntitle: .call\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.call\n\n```js\n.call(\n String methodName,\n [any args...]\n)\n```\n\nThis is a convenience method for doing:\n\n```js\npromise.then(function(obj) {\n return obj[methodName].call(obj, arg...);\n});\n```\n\nFor example ([`some` is a built-in array method](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/some)):\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\nvar path = require(\"path\");\nvar thisPath = process.argv[2] || \".\";\nvar now = Date.now();\n\nfs.readdirAsync(thisPath)\n .map(function(fileName) {\n return fs.statAsync(path.join(thisPath, fileName));\n })\n .call(\"some\", function(stat) {\n return (now - new Date(stat.mtime)) < 10000;\n })\n .then(function(someFilesHaveBeenModifiedLessThanTenSecondsAgo) {\n console.log(someFilesHaveBeenModifiedLessThanTenSecondsAgo) ;\n });\n```\n\nChaining lo-dash or underscore methods (Copy-pasteable example):\n\n```js\nvar Promise = require(\"bluebird\");\nvar pmap = Promise.map;\nvar props = Promise.props;\nvar _ = require(\"lodash\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\nfunction getTotalSize(paths) {\n return pmap(paths, function(path) {\n return fs.statAsync(path).get(\"size\");\n }).reduce(function(a, b) {\n return a + b;\n }, 0);\n}\n\nfs.readdirAsync(\".\").then(_)\n .call(\"groupBy\", function(fileName) {\n return fileName.charAt(0);\n })\n .call(\"map\", function(fileNames, firstCh) {\n return props({\n firstCh: firstCh,\n count: fileNames.length,\n totalSize: getTotalSize(fileNames)\n });\n })\n // Since the currently wrapped array contains promises we need to unwrap it and call .all() before continuing the chain\n // If the currently wrapped thing was an object with properties that might be promises, we would call .props() instead\n .call(\"value\").all().then(_)\n .call(\"sortBy\", \"count\")\n .call(\"reverse\")\n .call(\"map\", function(data) {\n return data.count + \" total files beginning with \" + data.firstCh + \" with total size of \" + data.totalSize + \" bytes\";\n })\n .call(\"join\", \"\\n\")\n .then(console.log)\n```\n
\n\n\n\n"
},
{
"path": "docs/docs/api/cancel.md",
"content": "---\nlayout: api\nid: cancel\ntitle: .cancel\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.cancel\n\n```js\n.cancel() -> undefined\n```\n\nCancel this promise. Will not do anything if this promise is already settled or if the [Cancellation](.) feature has not been enabled. See [Cancellation](.) for how to use cancellation.\n\n\n
\n\n\n\n"
},
{
"path": "docs/docs/api/cancellation.md",
"content": "---\nlayout: api\nid: cancellation\ntitle: Cancellation\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Cancellation\n\nCancellation has been redesigned for bluebird 3.x, any code that relies on 2.x cancellation semantics won't work in 3.x.\n\nThe cancellation feature is **by default turned off**, you can enable it using [Promise.config](.).\n\nThe new cancellation has \"don't care\" semantics while the old cancellation had abort semantics. Cancelling a promise simply means that its handler callbacks will not be called.\n\nThe advantages of the new cancellation compared to the old cancellation are:\n\n- [.cancel()](.) is synchronous.\n- no setup code required to make cancellation work\n- composes with other bluebird features, like [Promise.all](.).\n- [reasonable semantics for multiple consumer cancellation](#what-about-promises-that-have-multiple-consumers)\n\nAs an optimization, the cancellation signal propagates upwards the promise chain so that an ongoing operation e.g. network request can be aborted. However, *not* aborting the network request still doesn't make any operational difference as the callbacks are still not called either way.\n\nYou may register an optional cancellation hook at a root promise by using the `onCancel` argument that is passed to the executor function when cancellation is enabled:\n\n```js\nfunction makeCancellableRequest(url) {\n return new Promise(function(resolve, reject, onCancel) {\n var xhr = new XMLHttpRequest();\n xhr.on(\"load\", resolve);\n xhr.on(\"error\", reject);\n xhr.open(\"GET\", url, true);\n xhr.send(null);\n // Note the onCancel argument only exists if cancellation has been enabled!\n onCancel(function() {\n xhr.abort();\n });\n });\n}\n```\n\nNote that the `onCancel` hook is really an optional disconnected optimization, there is no real requirement to register any cancellation hooks for cancellation to work. As such, any errors that may occur while inside the `onCancel` callback are not caught and turned into rejections.\n\nWhile `cancel().` is synchronous - `onCancel()` is called asynchronously (in the next turn) just like `then` handlers.\n\nExample:\n\n```js\nvar searchPromise = Promise.resolve(); // Dummy promise to avoid null check.\ndocument.querySelector(\"#search-input\").addEventListener(\"input\", function() {\n // The handlers of the previous request must not be called\n searchPromise.cancel();\n var url = \"/search?term=\" + encodeURIComponent(this.value.trim());\n showSpinner();\n searchPromise = makeCancellableRequest(url)\n .then(function(results) {\n return transformData(results);\n })\n .then(function(transformedData) {\n document.querySelector(\"#search-results\").innerHTML = transformedData;\n })\n .catch(function(e) {\n document.querySelector(\"#search-results\").innerHTML = renderErrorBox(e);\n })\n .finally(function() {\n // This check is necessary because `.finally` handlers are always called.\n if (!searchPromise.isCancelled()) {\n hideSpinner();\n }\n });\n});\n\n```\n\nAs shown in the example the handlers registered with `.finally` are called even if the promise is cancelled. Another such exception is [.reflect()](.). No other types of handlers will be called in case of cancellation. This means that in `.then(onSuccess, onFailure)` neither `onSuccess` or `onFailure` handler is called. This is similar to how [`Generator#return`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/return) works - only active `finally` blocks are executed and then the generator exits.\n\n###What about promises that have multiple consumers?\n\nIt is often said that promises cannot be cancellable because they can have multiple consumers.\n\nFor instance:\n\n```js\nvar result = makeCancellableRequest(...);\n\nvar firstConsumer = result.then(...);\nvar secondConsumer = result.then(...);\n```\n\nEven though in practice most users of promises will never have any need to take advantage of the fact that you can attach multiple consumers to a promise, it is nevertheless possible. The problem: \"what should happen if [.cancel()](.) is called on `firstConsumer`?\" Propagating the cancellation signal (and therefore making it abort the request) would be very bad as the second consumer might still be interested in the result despite the first consumer's disinterest.\n\nWhat actually happens is that `result` keeps track of how many consumers it has, in this case 2, and only if all the consumers signal cancel will the request be aborted. However, as far as `firstConsumer` can tell, the promise was successfully cancelled and its handlers will not be called.\n\nNote that it is an error to consume an already cancelled promise, doing such a thing will give you a promise that is rejected with `new CancellationError(\"late cancellation observer\")` as the rejection reason.\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/cancellationerror.md",
"content": "---\nlayout: api\nid: cancellationerror\ntitle: CancellationError\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##CancellationError\n\n```js\nnew CancellationError(String message) -> CancellationError\n```\n\n\nSignals that an operation has been aborted or cancelled. The default reason used by [`.cancel`](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/catch.md",
"content": "---\nlayout: api\nid: catch\ntitle: .catch\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.catch\n\n`.catch` is a convenience method for handling errors in promise chains. \nIt comes in two variants \n - A catch-all variant similar to the synchronous `catch(e) {` block. This variant is compatible with native promises. \n - A filtered variant (like other non-JS languages typically have) that lets you only handle specific errors. **This variant is usually preferable and is significantly safer**. \n\n### A note on promise exception handling.\n\nPromise exception handling mirrors native exception handling in JavaScript. A synchronous function `throw`ing is similar to a promise rejecting. Here is an example to illustrate it:\n\n```js\nfunction getItems(param) {\n try { \n var items = getItemsSync();\n if(!items) throw new InvalidItemsError(); \n } catch(e) { \n // can address the error here, either from getItemsSync returning a falsey value or throwing itself\n throw e; // need to re-throw the error unless I want it to be considered handled. \n }\n return process(items);\n}\n```\n\nSimilarly, with promises:\n\n```js\nfunction getItems(param) {\n return getItemsAsync().then(items => {\n if(!items) throw new InvalidItemsError(); \n return items;\n }).catch(e => {\n // can address the error here and recover from it, from getItemsAsync rejects or returns a falsey value\n throw e; // Need to rethrow unless we actually recovered, just like in the synchronous version\n }).then(process);\n}\n```\n\n### Catch-all\n\n```js\n.catch(function(any error) handler) -> Promise\n```\n```js\n.caught(function(any error) handler) -> Promise\n```\n\nThis is a catch-all exception handler, shortcut for calling [`.then(null, handler)`](.) on this promise. Any exception happening in a `.then`-chain will propagate to nearest `.catch` handler.\n\n*For compatibility with earlier ECMAScript versions, an alias `.caught` is provided for [`.catch`](.).*\n\n### Filtered Catch \n\n```js\n.catch(\n class ErrorClass|function(any error)|Object predicate...,\n function(any error) handler\n) -> Promise\n```\n```js\n.caught(\n class ErrorClass|function(any error)|Object predicate...,\n function(any error) handler\n) -> Promise\n```\nThis is an extension to [`.catch`](.) to work more like catch-clauses in languages like Java or C#. Instead of manually checking `instanceof` or `.name === \"SomeError\"`, you may specify a number of error constructors which are eligible for this catch handler. The catch handler that is first met that has eligible constructors specified, is the one that will be called.\n\nExample:\n\n```js\nsomePromise.then(function() {\n return a.b.c.d();\n}).catch(TypeError, function(e) {\n //If it is a TypeError, will end up here because\n //it is a type error to reference property of undefined\n}).catch(ReferenceError, function(e) {\n //Will end up here if a was never declared at all\n}).catch(function(e) {\n //Generic catch-the rest, error wasn't TypeError nor\n //ReferenceError\n});\n ```\n\nYou may also add multiple filters for a catch handler:\n\n```js\nsomePromise.then(function() {\n return a.b.c.d();\n}).catch(TypeError, ReferenceError, function(e) {\n //Will end up here on programmer error\n}).catch(NetworkError, TimeoutError, function(e) {\n //Will end up here on expected everyday network errors\n}).catch(function(e) {\n //Catch any unexpected errors\n});\n```\n\nFor a parameter to be considered a type of error that you want to filter, you need the constructor to have its `.prototype` property be `instanceof Error`.\n\nSuch a constructor can be minimally created like so:\n\n```js\nfunction MyCustomError() {}\nMyCustomError.prototype = Object.create(Error.prototype);\n```\n\nUsing it:\n\n```js\nPromise.resolve().then(function() {\n throw new MyCustomError();\n}).catch(MyCustomError, function(e) {\n //will end up here now\n});\n```\n\nHowever if you want stack traces and cleaner string output, then you should do:\n\n*in Node.js and other V8 environments, with support for `Error.captureStackTrace`*\n\n```js\nfunction MyCustomError(message) {\n this.message = message;\n this.name = \"MyCustomError\";\n Error.captureStackTrace(this, MyCustomError);\n}\nMyCustomError.prototype = Object.create(Error.prototype);\nMyCustomError.prototype.constructor = MyCustomError;\n```\n\nUsing CoffeeScript's `class` for the same:\n\n```coffee\nclass MyCustomError extends Error\n constructor: (@message) ->\n @name = \"MyCustomError\"\n Error.captureStackTrace(this, MyCustomError)\n```\n\nThis method also supports predicate-based filters. If you pass a\npredicate function instead of an error constructor, the predicate will receive\nthe error as an argument. The return result of the predicate will be used\ndetermine whether the error handler should be called.\n\nPredicates should allow for very fine grained control over caught errors:\npattern matching, error-type sets with set operations and many other techniques\ncan be implemented on top of them.\n\nExample of using a predicate-based filter:\n\n```js\nvar Promise = require(\"bluebird\");\nvar request = Promise.promisify(require(\"request\"));\n\nfunction ClientError(e) {\n return e.code >= 400 && e.code < 500;\n}\n\nrequest(\"http://www.google.com\").then(function(contents) {\n console.log(contents);\n}).catch(ClientError, function(e) {\n //A client error like 400 Bad Request happened\n});\n```\n\nPredicate functions that only check properties have a handy shorthand. In place of a predicate function, you can pass an object, and its properties will be checked against the error object for a match:\n\n```js\nfs.readFileAsync(...)\n .then(...)\n .catch({code: 'ENOENT'}, function(e) {\n console.log(\"file not found: \" + e.path);\n });\n```\n\nThe object predicate passed to `.catch` in the above code (`{code: 'ENOENT'}`) is shorthand for a predicate function `function predicate(e) { return isObject(e) && e.code == 'ENOENT' }`, I.E. loose equality is used.\n\n*For compatibility with earlier ECMAScript version, an alias `.caught` is provided for [`.catch`](.).*\n
\n\nBy not returning a rejected value or `throw`ing from a catch, you \"recover from failure\" and continue the chain:\n\n```js\nPromise.reject(Error('fail!'))\n .catch(function(e) {\n // fallback with \"recover from failure\"\n return Promise.resolve('success!'); // promise or value\n })\n .then(function(result) {\n console.log(result); // will print \"success!\"\n });\n```\n\nThis is exactly like the synchronous code:\n\n```js\nvar result;\ntry {\n throw Error('fail');\n} catch(e) {\n result = 'success!';\n}\nconsole.log(result);\n```\n\n\n\n\n"
},
{
"path": "docs/docs/api/catchreturn.md",
"content": "---\nlayout: api\nid: catchreturn\ntitle: .catchReturn\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.catchReturn\n\n```js\n.catchReturn(\n [class ErrorClass|function(any error) predicate],\n any value\n) -> Promise\n```\n\nConvenience method for:\n\n```js\n.catch(function() {\n return value;\n});\n```\nYou may optionally prepend one predicate function or ErrorClass to pattern match the error (the generic [.catch](.) methods accepts multiple)\n\nSame limitations regarding to the binding time of `value` to apply as with [`.return`](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/catchthrow.md",
"content": "---\nlayout: api\nid: catchthrow\ntitle: .catchThrow\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.catchThrow\n\n```js\n.catchThrow(\n [class ErrorClass|function(any error) predicate],\n any reason\n) -> Promise\n```\n\nConvenience method for:\n\n```js\n.catch(function() {\n throw reason;\n});\n```\nYou may optionally prepend one predicate function or ErrorClass to pattern match the error (the generic [.catch](.) methods accepts multiple)\n\nSame limitations regarding to the binding time of `reason` to apply as with [`.return`](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/collections.md",
"content": "---\nlayout: api\nid: collections\ntitle: Collections\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Collections\n\nMethods of `Promise` instances and core static methods of the Promise class to deal with collections of promises or mixed promises and values.\n\nAll collection methods have a static equivalent on the Promise object, e.g. `somePromise.map(...)...` is same as `Promise.map(somePromise, ...)...`,\n`somePromise.all` is same as [`Promise.all`](.) and so on.\n\nNone of the collection methods modify the original input. Holes in arrays are treated as if they were defined with the value `undefined`.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/core.md",
"content": "---\nlayout: api\nid: core\ntitle: Core\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Core\n\nCore methods of `Promise` instances and core static methods of the Promise class.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/deferred-migration.md",
"content": "---\nlayout: api\nid: deferred-migration\ntitle: Deferred migration\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Deferred migration\n\nDeferreds are deprecated in favor of the promise constructor. If you need deferreds for some reason, you can create them trivially using the constructor:\n\n```js\nfunction defer() {\n var resolve, reject;\n var promise = new Promise(function() {\n resolve = arguments[0];\n reject = arguments[1];\n });\n return {\n resolve: resolve,\n reject: reject,\n promise: promise\n };\n}\n```\n\nFor old code that still uses deferred objects, see [the deprecated API docs ](//bluebirdjs.com/docs/deprecated-apis.html#promise-resolution).\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/delay.md",
"content": "---\nlayout: api\nid: delay\ntitle: .delay\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.delay\n\n```js\n.delay(int ms) -> Promise\n```\n\nSame as calling [Promise.delay(ms, this)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/disposer.md",
"content": "---\nlayout: api\nid: disposer\ntitle: .disposer\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.disposer\n\n```js\n.disposer(function(any resource, Promise usingOutcomePromise) disposer) -> Disposer\n```\n\nA meta method used to specify the disposer method that cleans up a resource when using [`Promise.using`](/docs/api/promise.using.html).\n\nReturns a Disposer object which encapsulates both the resource as well as the method to clean it up. The user can pass this object to `Promise.using` to get access to the resource when it becomes available, as well as to ensure it's automatically cleaned up.\n\nThe second argument passed to a disposer is the result promise of the using block, which you can inspect synchronously.\n\nExample:\n\n```js\n// This function doesn't return a promise but a Disposer\n// so it's very hard to use it wrong (not passing it to `using`)\nfunction getConnection() {\n return db.connect().disposer(function(connection, promise) {\n connection.close();\n });\n}\n```\n\nIn the above example, the connection returned by `getConnection` can only be \nused via `Promise.using`, like so:\n\n```js\nfunction useConnection(query) {\n return Promise.using(getConnection(), function(connection) {\n return connection.sendQuery(query).then(function(results) {\n return process(results);\n })\n });\n}\n```\n\nThis will ensure that `connection.close()` will be called once the promise returned\nfrom the `Promise.using` closure is resolved or if an exception was thrown in the closure\nbody.\n\nReal example:\n\n```js\nvar pg = require(\"pg\");\n// Uncomment if pg has not been properly promisified yet\n//var Promise = require(\"bluebird\");\n//Promise.promisifyAll(pg, {\n// filter: function(methodName) {\n// return methodName === \"connect\"\n// },\n// multiArgs: true\n//});\n// Promisify rest of pg normally\n//Promise.promisifyAll(pg);\n\nfunction getSqlConnection(connectionString) {\n var close;\n return pg.connectAsync(connectionString).spread(function(client, done) {\n close = done;\n return client;\n }).disposer(function() {\n if (close) close();\n });\n}\n\nmodule.exports = getSqlConnection;\n```\n\nReal example 2:\n\n```js\nvar mysql = require(\"mysql\");\n// Uncomment if mysql has not been properly promisified yet\n// var Promise = require(\"bluebird\");\n// Promise.promisifyAll(mysql);\n// Promise.promisifyAll(require(\"mysql/lib/Connection\").prototype);\n// Promise.promisifyAll(require(\"mysql/lib/Pool\").prototype);\nvar pool = mysql.createPool({\n connectionLimit: 10,\n host: 'example.org',\n user: 'bob',\n password: 'secret'\n});\n\nfunction getSqlConnection() {\n return pool.getConnectionAsync().disposer(function(connection) {\n connection.release();\n });\n}\n\nmodule.exports = getSqlConnection;\n```\n\n#### Note about disposers in node\n\nIf a disposer method throws or returns a rejected promise, it's highly likely that it failed to dispose of the resource. In that case, Bluebird has two options - it can either ignore the error and continue with program execution or throw an exception (crashing the process in node.js).\n\nIn bluebird we've chosen to do the latter because resources are typically scarce. For example, if a database connection cannot be disposed of and Bluebird ignores that, the connection pool will be quickly depleted and the process will become unusable (all requests that query the database will wait forever). Since Bluebird doesn't know how to handle that, the only sensible default is to crash the process. That way, rather than getting a useless process that cannot fulfill more requests, we can swap the faulty worker with a new one letting the OS clean up the resources for us.\n\nAs a result, if you anticipate thrown errors or promise rejections while disposing of the resource you should use a `try..catch` block (or Promise.try) and write the appropriate catch code to handle the errors. If it's not possible to sensibly handle the error, letting the process crash is the next best option.\n\nThis also means that disposers should not contain code that does anything other than resource disposal. For example, you cannot write code inside a disposer to commit or rollback a transaction, because there is no mechanism for the disposer to signal a failure of the commit or rollback action without crashing the process.\n\nFor transactions, you can use the following similar pattern instead:\n\n```js\nfunction withTransaction(fn) {\n return Promise.using(pool.acquireConnection(), function(connection) {\n var tx = connection.beginTransaction()\n return Promise\n .try(fn, tx)\n .then(function(res) { return connection.commit().thenReturn(res) },\n function(err) {\n return connection.rollback()\n .catch(function(e) {/* maybe add the rollback error to err */})\n .thenThrow(err);\n });\n });\n}\n\n// If the withTransaction block completes successfully, the transaction is automatically committed\n// Any error or rejection will automatically roll it back\n\nwithTransaction(function(tx) {\n return tx.queryAsync(...).then(function() {\n return tx.queryAsync(...)\n }).then(function() {\n return tx.queryAsync(...)\n });\n});\n```\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/done.md",
"content": "---\nlayout: api\nid: done\ntitle: .done\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.done\n\n```js\n.done(\n [function(any value) fulfilledHandler],\n [function(any error) rejectedHandler]\n) -> undefined\n```\n\n\nLike [`.then`](.), but any unhandled rejection that ends up here will crash the process (in node) or be thrown as an error (in browsers). The use of this method is heavily discouraged and it only exists for historical reasons.\n\n\n
\n\n\n\n"
},
{
"path": "docs/docs/api/each.md",
"content": "---\nlayout: api\nid: each\ntitle: .each\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.each\n\n```js\n.each(function(any item, int index, int length) iterator) -> Promise\n```\n\nIterate over an array, or a promise of an array, which contains promises (or a mix of promises and values) with the given `iterator` function with the signature `(value, index, length)` where `value` is the resolved value of a respective promise in the input array. Iteration happens serially. If any promise in the input array is rejected the returned promise is rejected as well.\n\nResolves to the original array unmodified, this method is meant to be used for side effects. If the iterator function returns a promise or a thenable, then the result of the promise is awaited, before continuing with next iteration.\n\nExample where you might want to utilize `.each`:\n\n```js\n// Source: http://jakearchibald.com/2014/es7-async-functions/\nfunction loadStory() {\n return getJSON('story.json')\n .then(function(story) {\n addHtmlToPage(story.heading);\n return story.chapterURLs.map(getJSON);\n })\n .each(function(chapter) { addHtmlToPage(chapter.html); })\n .then(function() { addTextToPage(\"All done\"); })\n .catch(function(err) { addTextToPage(\"Argh, broken: \" + err.message); })\n .then(function() { document.querySelector('.spinner').style.display = 'none'; });\n}\n```\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/environment-variables.md",
"content": "---\nlayout: api\nid: environment-variables\ntitle: Environment variables\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Environment variables\n\nThis section only applies to node.js or io.js.\n\nYou can change bluebird behavior globally with various environment variables. These global variables affect all instances of bluebird that are running in your environment, rather than just the one you have `require`d in your application. The effect an environment variable has depends on the bluebird version.\n\nEnvironment variables supported by 2.x:\n\n- `BLUEBIRD_DEBUG` - Set to any truthy value this will enable long stack traces and warnings\n- `NODE_ENV` - If set exactly to `development` it will have the same effect as if the `BLUEBIRD_DEBUG` variable was set.\n\nEnvironment variables supported by 3.x:\n\n- `BLUEBIRD_DEBUG` - If set this will enable long stack traces and warnings, unless those are explicitly disabled. Setting this to exactly `0` can be used to override `NODE_ENV=development` enabling long stack traces and warnings.\n- `NODE_ENV` - If set exactly to `development` it will have the same effect as if the `BLUEBIRD_DEBUG` variable was set.\n- `BLUEBIRD_WARNINGS` - if set exactly to `0` it will explicitly disable warnings and this overrides any other setting that might enable warnings. If set to any truthy value, it will explicitly enable warnings.\n- `BLUEBIRD_LONG_STACK_TRACES` - if set exactly to `0` it will explicitly disable long stack traces and this overrides any other setting that might enable long stack traces. If set to any truthy value, it will explicitly enable long stack traces.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/error-management-configuration.md",
"content": "---\nlayout: api\nid: error-management-configuration\ntitle: Error management configuration\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Error management configuration\n\nThe default approach of bluebird is to immediately log the stack trace when there is an unhandled rejection. This is similar to how uncaught exceptions cause the stack trace to be logged so that you have something to work with when something is not working as expected.\n\nHowever because it is possible to handle a rejected promise at any time in the indeterminate future, some programming patterns will result in false positives. Because such programming patterns are not necessary and can always be refactored to never cause false positives, we recommend doing that to keep debugging as easy as possible . You may however feel differently so bluebird provides hooks to implement more complex failure policies.\n\nSuch policies could include:\n\n- Logging after the promise became GCd (requires a native node.js module)\n- Showing a live list of rejected promises\n- Using no hooks and using [`.done`](.) to manually to mark end points where rejections will not be handled\n- Swallowing all errors (challenge your debugging skills)\n- ...\n\n\n\n###Global rejection events\n\nStarting from 2.7.0 all bluebird instances also fire rejection events globally so that applications can register one universal hook for them.\n\nThe global events are:\n\n - `\"unhandledRejection\"` (corresponds to the local [`Promise.onPossiblyUnhandledRejection`](.))\n - `\"rejectionHandled\"` (corresponds to the local [`Promise.onUnhandledRejectionHandled`](.))\n\n\nAttaching global rejection event handlers in **node.js**:\n\n```js\n// NOTE: event name is camelCase as per node convention\nprocess.on(\"unhandledRejection\", function(reason, promise) {\n // See Promise.onPossiblyUnhandledRejection for parameter documentation\n});\n\n// NOTE: event name is camelCase as per node convention\nprocess.on(\"rejectionHandled\", function(promise) {\n // See Promise.onUnhandledRejectionHandled for parameter documentation\n});\n```\n\nAttaching global rejection event handlers in **browsers**:\n\nUsing DOM3 `addEventListener` APIs (support starting from IE9+):\n\n```js\n// NOTE: event name is all lower case as per DOM convention\nwindow.addEventListener(\"unhandledrejection\", function(e) {\n // NOTE: e.preventDefault() must be manually called to prevent the default\n // action which is currently to log the stack trace to console.warn\n e.preventDefault();\n // NOTE: parameters are properties of the event detail property\n var reason = e.detail.reason;\n var promise = e.detail.promise;\n // See Promise.onPossiblyUnhandledRejection for parameter documentation\n});\n\n// NOTE: event name is all lower case as per DOM convention\nwindow.addEventListener(\"rejectionhandled\", function(e) {\n // NOTE: e.preventDefault() must be manually called prevent the default\n // action which is currently unset (but might be set to something in the future)\n e.preventDefault();\n // NOTE: parameters are properties of the event detail property\n var promise = e.detail.promise;\n // See Promise.onUnhandledRejectionHandled for parameter documentation\n});\n```\n\nIn Web Workers you may use `self.addEventListener`.\n\nUsing legacy APIs (support starting from IE6+):\n\n```js\n// NOTE: event name is all lower case as per legacy convention\nwindow.onunhandledrejection = function(reason, promise) {\n // See Promise.onPossiblyUnhandledRejection for parameter documentation\n};\n\n// NOTE: event name is all lower case as per legacy convention\nwindow.onrejectionhandled = function(promise) {\n // See Promise.onUnhandledRejectionHandled for parameter documentation\n};\n```\n\n
\n\n\n\n"
},
{
"path": "docs/docs/api/error.md",
"content": "---\nlayout: api\nid: error\ntitle: .error\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.error\n\n```js\n.error([function(any error) rejectedHandler]) -> Promise\n```\n\n\nLike [`.catch`](.) but instead of catching all types of exceptions, it only catches operational errors.\n\n*Note, \"errors\" mean errors, as in objects that are `instanceof Error` - not strings, numbers and so on. See [a string is not an error](http://www.devthought.com/2011/12/22/a-string-is-not-an-error/).*\n\nIt is equivalent to the following [`.catch`](.) pattern:\n\n```js\n// Assumes OperationalError has been made global\nfunction isOperationalError(e) {\n if (e == null) return false;\n return (e instanceof OperationalError) || (e.isOperational === true);\n}\n\n// Now this bit:\n.catch(isOperationalError, function(e) {\n // ...\n})\n\n// Is equivalent to:\n\n.error(function(e) {\n // ...\n});\n```\n\nFor example, if a promisified function errbacks the node-style callback with an error, that could be caught with [`.error`](.). However if the node-style callback **throws** an error, only `.catch` would catch that.\n\nIn the following example you might want to handle just the `SyntaxError` from JSON.parse and Filesystem errors from `fs` but let programmer errors bubble as unhandled rejections:\n\n```js\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\nfs.readFileAsync(\"myfile.json\").then(JSON.parse).then(function (json) {\n console.log(\"Successful json\")\n}).catch(SyntaxError, function (e) {\n console.error(\"file contains invalid json\");\n}).error(function (e) {\n console.error(\"unable to read file, because: \", e.message);\n});\n```\n\nNow, because there is no catch-all handler, if you typed `console.lag` (causes an error you don't expect), you will see:\n\n```\nPossibly unhandled TypeError: Object # has no method 'lag'\n at application.js:8:13\nFrom previous event:\n at Object. (application.js:7:4)\n at Module._compile (module.js:449:26)\n at Object.Module._extensions..js (module.js:467:10)\n at Module.load (module.js:349:32)\n at Function.Module._load (module.js:305:12)\n at Function.Module.runMain (module.js:490:10)\n at startup (node.js:121:16)\n at node.js:761:3\n```\n\n*( If you don't get the above - you need to enable [long stack traces](/docs/api/promise.config.html) )*\n\nAnd if the file contains invalid JSON:\n\n```\nfile contains invalid json\n```\n\nAnd if the `fs` module causes an error like file not found:\n\n```\nunable to read file, because: ENOENT, open 'not_there.txt'\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/filter.md",
"content": "---\nlayout: api\nid: filter\ntitle: .filter\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.filter\n\n```js\n.filter(\n function(any item, int index, int length) filterer,\n [Object {concurrency: int=Infinity} options]\n) -> Promise\n```\n\nSame as [Promise.filter(this, filterer, options)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/finally.md",
"content": "---\nlayout: api\nid: finally\ntitle: .finally\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.finally\n\n```js\n.finally(function() handler) -> Promise\n```\n```js\n.lastly(function() handler) -> Promise\n```\n\n\nPass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for [`.finally`](.) in that the final value cannot be modified from the handler.\n\n*Note: using [`.finally`](.) for resource management has better alternatives, see [resource management](/docs/api/resource-management.html)*\n\nConsider the example:\n\n```js\nfunction anyway() {\n $(\"#ajax-loader-animation\").hide();\n}\n\nfunction ajaxGetAsync(url) {\n return new Promise(function (resolve, reject) {\n var xhr = new XMLHttpRequest;\n xhr.addEventListener(\"error\", reject);\n xhr.addEventListener(\"load\", resolve);\n xhr.open(\"GET\", url);\n xhr.send(null);\n }).then(anyway, anyway);\n}\n```\n\nThis example doesn't work as intended because the `then` handler actually swallows the exception and returns `undefined` for any further chainers.\n\nThe situation can be fixed with `.finally`:\n\n```js\nfunction ajaxGetAsync(url) {\n return new Promise(function (resolve, reject) {\n var xhr = new XMLHttpRequest;\n xhr.addEventListener(\"error\", reject);\n xhr.addEventListener(\"load\", resolve);\n xhr.open(\"GET\", url);\n xhr.send(null);\n }).finally(function() {\n $(\"#ajax-loader-animation\").hide();\n });\n}\n```\n\nNow the animation is hidden but, unless it throws an exception, the function has no effect on the fulfilled or rejected value of the returned promise. This is similar to how the synchronous `finally` keyword behaves.\n\nIf the handler function passed to `.finally` returns a promise, the promise returned by `.finally` will not be settled until the promise returned by the handler is settled. If the handler fulfills its promise, the returned promise will be fulfilled or rejected with the original value. If the handler rejects its promise, the returned promise will be rejected with the handler's value. This is similar to throwing an exception in a synchronous `finally` block, causing the original value or exception to be forgotten. This delay can be useful if the actions performed by the handler are done asynchronously. For example:\n\n```js\nfunction ajaxGetAsync(url) {\n return new Promise(function (resolve, reject) {\n var xhr = new XMLHttpRequest;\n xhr.addEventListener(\"error\", reject);\n xhr.addEventListener(\"load\", resolve);\n xhr.open(\"GET\", url);\n xhr.send(null);\n }).finally(function() {\n return Promise.fromCallback(function(callback) {\n $(\"#ajax-loader-animation\").fadeOut(1000, callback);\n });\n });\n}\n```\n\nIf the fade out completes successfully, the returned promise will be fulfilled or rejected with the value from `xhr`. If `.fadeOut` throws an exception or passes an error to the callback, the returned promise will be rejected with the error from `.fadeOut`.\n\n*For compatibility with earlier ECMAScript version, an alias `.lastly` is provided for [`.finally`](.).*\n
\n\n\n\n"
},
{
"path": "docs/docs/api/generators.md",
"content": "---\nlayout: api\nid: generators\ntitle: Generators\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Generators\n\nUsing ECMAScript6 generators feature to implement C# 5.0 `async/await` like syntax.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/get.md",
"content": "---\nlayout: api\nid: get\ntitle: .get\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.get\n\n```js\n.get(String propertyName|int index) -> Promise\n```\n\n\nThis is a convenience method for doing:\n\n```js\npromise.then(function(obj) {\n return obj[propertyName];\n});\n```\n\nFor example:\n\n```js\ndb.query(\"...\")\n .get(0)\n .then(function(firstRow) {\n\n });\n```\n\nIf `index` is negative, the indexed load will become `obj.length + index`. So that -1 can be used to read last item\nin the array, -2 to read the second last and so on. For example:\n\n```js\nPromise.resolve([1,2,3]).get(-1).then(function(value) {\n console.log(value); // 3\n});\n```\n\nIf the `index` is still negative after `obj.length + index`, it will be clamped to 0.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/iscancelled.md",
"content": "---\nlayout: api\nid: iscancelled\ntitle: .isCancelled\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.isCancelled\n\n```js\n.isCancelled() -> boolean\n```\n\nSee if this `promise` has been cancelled.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/isfulfilled.md",
"content": "---\nlayout: api\nid: isfulfilled\ntitle: .isFulfilled\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.isFulfilled\n\n```js\n.isFulfilled() -> boolean\n```\n\nSee if this promise has been fulfilled.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/ispending.md",
"content": "---\nlayout: api\nid: ispending\ntitle: .isPending\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.isPending\n\n```js\n.isPending() -> boolean\n```\n\n\nSee if this `promise` is pending (not fulfilled or rejected or cancelled).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/isrejected.md",
"content": "---\nlayout: api\nid: isrejected\ntitle: .isRejected\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.isRejected\n\n```js\n.isRejected() -> boolean\n```\n\nSee if this promise has been rejected.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/map.md",
"content": "---\nlayout: api\nid: map\ntitle: .map\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.map\n\n```js\n.map(\n function(any item, int index, int length) mapper,\n [Object {concurrency: int=Infinity} options]\n) -> Promise\n```\n\nSame as [Promise.map(this, mapper, options)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/mapseries.md",
"content": "---\nlayout: api\nid: mapseries\ntitle: .mapseries\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.mapSeries\n\n```js\n.mapSeries(function(any item, int index, int length) mapper) -> Promise\n```\n\nSame as [Promise.mapSeries(this, iterator)](.).\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/new-promise.md",
"content": "---\nlayout: api\nid: new-promise\ntitle: new Promise\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##new Promise\n\n```js\nnew Promise(function(function resolve, function reject) resolver) -> Promise\n```\n\n\nCreate a new promise. The passed in function will receive functions `resolve` and `reject` as its arguments which can be called to seal the fate of the created promise.\n\n*Note: See [explicit construction anti-pattern]({{ \"/docs/anti-patterns.html#the-explicit-construction-anti-pattern\" | prepend: site.baseurl }}) before creating promises yourself*\n\nExample:\n\n```js\nfunction ajaxGetAsync(url) {\n return new Promise(function (resolve, reject) {\n var xhr = new XMLHttpRequest;\n xhr.addEventListener(\"error\", reject);\n xhr.addEventListener(\"load\", resolve);\n xhr.open(\"GET\", url);\n xhr.send(null);\n });\n}\n```\n\nIf you pass a promise object to the `resolve` function, the created promise will follow the state of that promise.\n\n\n\nTo make sure a function that returns a promise is following the implicit but critically important contract of promises, you can start a function with `new Promise` if you cannot start a chain immediately:\n\n```js\nfunction getConnection(urlString) {\n return new Promise(function(resolve) {\n //Without new Promise, this throwing will throw an actual exception\n var params = parse(urlString);\n resolve(getAdapter(params).getConnection());\n });\n}\n```\n\nThe above ensures `getConnection` fulfills the contract of a promise-returning function of never throwing a synchronous exception. Also see [`Promise.try`](.) and [`Promise.method`](.)\n\nThe resolver is called synchronously (the following is for documentation purposes and not idiomatic code):\n\n```js\nfunction getPromiseResolveFn() {\n var res;\n new Promise(function (resolve) {\n res = resolve;\n });\n // res is guaranteed to be set\n return res;\n}\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/operationalerror.md",
"content": "---\nlayout: api\nid: operationalerror\ntitle: OperationalError\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##OperationalError\n\n```js\nnew OperationalError(String message) -> OperationalError\n```\n\n\nRepresents an error is an explicit promise rejection as opposed to a thrown error. For example, if an error is errbacked by a callback API promisified through [`Promise.promisify`](.) or [`Promise.promisifyAll`](.)\nand is not a typed error, it will be converted to a `OperationalError` which has the original error in the `.cause` property.\n\n`OperationalError`s are caught in [`.error`](.) handlers.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/progression-migration.md",
"content": "---\nlayout: api\nid: progression-migration\ntitle: Progression migration\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Progression migration\n\nProgression has been removed as there are composability and chaining issues with APIs that use promise progression handlers. Implementing the common use case of progress bars can be accomplished using a pattern similar to [IProgress](http://blogs.msdn.com/b/dotnet/archive/2012/06/06/async-in-4-5-enabling-progress-and-cancellation-in-async-apis.aspx) in C#.\n\nFor old code that still uses it, see [the progression docs in the deprecated API documentation](/docs/deprecated-apis.html#progression).\n\nUsing jQuery before:\n\n```js\nPromise.resolve($.get(...))\n .progressed(function() {\n // ...\n })\n .then(function() {\n // ...\n })\n .catch(function(e) {\n // ...\n })\n```\n\nUsing jQuery after:\n\n```js\nPromise.resolve($.get(...).progress(function() {\n // ...\n }))\n .then(function() {\n // ...\n })\n .catch(function(e) {\n // ...\n })\n```\n\nImplementing general progress interfaces like in C#:\n\n```js\nfunction returnsPromiseWithProgress(progressHandler) {\n return doFirstAction().tap(function() {\n progressHandler(0.33);\n }).then(doSecondAction).tap(function() {\n progressHandler(0.66);\n }).then(doThirdAction).tap(function() {\n progressHandler(1.00);\n });\n}\n\nreturnsPromiseWithProgress(function(progress) {\n ui.progressbar.setWidth((progress * 200) + \"px\"); // update width on client side\n}).then(function(value) { // action complete\n // entire chain is complete.\n}).catch(function(e) {\n // error\n});\n```\n\nAnother example using `coroutine`:\n\n```js\nvar doNothing = function() {};\nvar progressSupportingCoroutine = Promise.coroutine(function* (progress) {\n progress = typeof progress === \"function\" ? progress : doNothing;\n var first = yield getFirstValue();\n // 33% done\n progress(0.33);\n var second = yield getSecondValue();\n progress(0.67);\n var third = yield getThirdValue();\n progress(1);\n return [first, second, third];\n});\n\nvar progressConsumingCoroutine = Promise.coroutine(function* () {\n var allValues = yield progressSupportingCoroutine(function(p) {\n ui.progressbar.setWidth((p * 200) + \"px\");\n });\n var second = allValues[1];\n // ...\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.all.md",
"content": "---\nlayout: api\nid: promise.all\ntitle: Promise.all\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.all\n\n```js\nPromise.all(Iterable|Promise> input) -> Promise>\n```\n\nThis method is useful for when you want to wait for more than one promise to complete.\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)\\(arrays are `Iterable`\\), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and return a promise that is fulfilled when all the items in the array are fulfilled. The promise's fulfillment value is an array with fulfillment values at respective positions to the original array. If any promise in the array rejects, the returned promise is rejected with the rejection reason.\n\n\n```js\nvar files = [];\nfor (var i = 0; i < 100; ++i) {\n files.push(fs.writeFileAsync(\"file-\" + i + \".txt\", \"\", \"utf-8\"));\n}\nPromise.all(files).then(function() {\n console.log(\"all the files were created\");\n});\n```\n\n\nThis method is compatible with [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) from native promises.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.any.md",
"content": "---\nlayout: api\nid: promise.any\ntitle: Promise.any\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.any\n\n```js\nPromise.any(Iterable|Promise> input) -> Promise\n```\n\nLike [Promise.some](.), with 1 as `count`. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.bind.md",
"content": "---\nlayout: api\nid: promise.bind\ntitle: Promise.bind\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.bind\n\n```js\nPromise.bind(\n any|Promise thisArg,\n [any|Promise value=undefined]\n) -> BoundPromise\n```\n\nCreate a promise that follows this promise or in the static method is resolved with the given `value`, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise.\n\nIf `thisArg` is a promise or thenable, its resolution will be awaited for and the bound value will be the promise's fulfillment value. If `thisArg` rejects\nthen the returned promise is rejected with the `thisArg's` rejection reason. Note that this means you cannot use `this` without checking inside catch handlers for promises that bind to promise because in case of rejection of `thisArg`, `this` will be `undefined`.\n\n\n\nWithout arrow functions that provide lexical `this`, the correspondence between async and sync code breaks down when writing object-oriented code. [`.bind`](.) alleviates this.\n\nConsider:\n\n```js\nMyClass.prototype.method = function() {\n try {\n var contents = fs.readFileSync(this.file);\n var url = urlParse(contents);\n var result = this.httpGetSync(url);\n var refined = this.refine(result);\n return this.writeRefinedSync(refined);\n }\n catch (e) {\n this.error(e.stack);\n }\n};\n```\n\nThe above has a direct translation:\n\n```js\nMyClass.prototype.method = function() {\n return fs.readFileAsync(this.file).bind(this)\n .then(function(contents) {\n var url = urlParse(contents);\n return this.httpGetAsync(url);\n }).then(function(result) {\n var refined = this.refine(result);\n return this.writeRefinedAsync(refined);\n }).catch(function(e) {\n this.error(e.stack);\n });\n};\n```\n\n`.bind` is the most efficient way of utilizing `this` with promises. The handler functions in the above code are not closures and can therefore even be hoisted out if needed. There is literally no overhead when propagating the bound value from one promise to another.\n\n\n\n`.bind` also has a useful side purpose - promise handlers don't need to share a function to use shared state:\n\n```js\nsomethingAsync().bind({})\n.spread(function (aValue, bValue) {\n this.aValue = aValue;\n this.bValue = bValue;\n return somethingElseAsync(aValue, bValue);\n})\n.then(function (cValue) {\n return this.aValue + this.bValue + cValue;\n});\n```\n\nThe above without [`.bind`](.) could be achieved with:\n\n```js\nvar scope = {};\nsomethingAsync()\n.spread(function (aValue, bValue) {\n scope.aValue = aValue;\n scope.bValue = bValue;\n return somethingElseAsync(aValue, bValue);\n})\n.then(function (cValue) {\n return scope.aValue + scope.bValue + cValue;\n});\n```\n\nHowever, there are many differences when you look closer:\n\n- Requires a statement so cannot be used in an expression context\n- If not there already, an additional wrapper function is required to undefined leaking or sharing `scope`\n- The handler functions are now closures, thus less efficient and not reusable\n\n\n\nNote that bind is only propagated with promise transformation. If you create new promise chains inside a handler, those chains are not bound to the \"upper\" `this`:\n\n```js\nsomething().bind(var1).then(function() {\n //`this` is var1 here\n return Promise.all(getStuff()).then(function(results) {\n //`this` is undefined here\n //refine results here etc\n });\n}).then(function() {\n //`this` is var1 here\n});\n```\n\nHowever, if you are utilizing the full bluebird API offering, you will *almost never* need to resort to nesting promises in the first place. The above should be written more like:\n\n```js\nsomething().bind(var1).then(function() {\n //`this` is var1 here\n return getStuff();\n}).map(function(result) {\n //`this` is var1 here\n //refine result here\n}).then(function() {\n //`this` is var1 here\n});\n```\n\nAlso see this [Stackoverflow answer](http://stackoverflow.com/a/24412873/191693) as an additional example.\n\n\n\nIf you don't want to return a bound promise to the consumers of a promise, you can rebind the chain at the end:\n\n```js\nMyClass.prototype.method = function() {\n return fs.readFileAsync(this.file).bind(this)\n .then(function(contents) {\n var url = urlParse(contents);\n return this.httpGetAsync(url);\n }).then(function(result) {\n var refined = this.refine(result);\n return this.writeRefinedAsync(refined);\n }).catch(function(e) {\n this.error(e.stack);\n }).bind(); //The `thisArg` is implicitly undefined - I.E. the default promise `this` value\n};\n```\n\nRebinding can also be abused to do something gratuitous like this:\n\n```js\nPromise.resolve(\"my-element\")\n .bind(document)\n .then(document.getElementById)\n .bind(console)\n .then(console.log);\n```\n\nThe above does a `console.log` of `my-element`. Doing it this way is necessary because neither of the methods (`getElementById`, `console.log`) can be called as stand-alone methods.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.config.md",
"content": "---\nlayout: api\nid: promise.config\ntitle: Promise.config\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.config\n\n```js\nPromise.config(Object {\n warnings: boolean=false,\n longStackTraces: boolean=false,\n cancellation: boolean=false,\n monitoring: boolean=false,\n asyncHooks: boolean=false\n} options) -> Object;\n```\n\nConfigure long stack traces, warnings, monitoring, [async hooks](https://nodejs.org/api/async_hooks.html) and cancellation. Note that even though `false` is the default here, a development environment might be detected which automatically enables long stack traces and warnings. For **webpack** and **browserify** *development* environment is *always* enabled. See [installation](/docs/install.html#browserify-and-webpack) on how to configure webpack and browserify for production.\n\n```js\nPromise.config({\n // Enable warnings\n warnings: true,\n // Enable long stack traces\n longStackTraces: true,\n // Enable cancellation\n cancellation: true,\n // Enable monitoring\n monitoring: true,\n // Enable async hooks\n asyncHooks: true,\n});\n```\n\nYou can configure the warning for checking forgotten return statements with `wForgottenReturn`:\n\n```js\nPromise.config({\n // Enables all warnings except forgotten return statements.\n warnings: {\n wForgottenReturn: false\n }\n});\n```\n\n`wForgottenReturn` is the only warning type that can be separately configured. The corresponding environmental variable key is `BLUEBIRD_W_FORGOTTEN_RETURN`.\n\n\n\n\n\nIn Node.js you may configure warnings and long stack traces for the entire process using environment variables:\n\n```\nBLUEBIRD_LONG_STACK_TRACES=1 BLUEBIRD_WARNINGS=1 node app.js\n```\n\nBoth features are automatically enabled if the `BLUEBIRD_DEBUG` environment variable has been set or if the `NODE_ENV` environment variable is equal to `\"development\"`.\n\nUsing the value `0` will explicitly disable a feature despite debug environment otherwise activating it:\n\n```\n# Warnings are disabled despite being in development environment\nNODE_ENV=development BLUEBIRD_WARNINGS=0 node app.js\n```\n\nCancellation is always configured separately per bluebird instance.\n\n# Async hooks\n\nBluebird supports [async hooks](https://nodejs.org/api/async_hooks.html) in node versions 9.6.0 and later. After it is enabled promises from the bluebird instance are assigned unique asyncIds:\n\n```js\n// Async hooks disabled for bluebird\nconst ah = require('async_hooks');\nconst Promise = require(\"bluebird\");\nPromise.resolve().then(() => {\n console.log(`eid ${ah.executionAsyncId()} tid ${ah.triggerAsyncId()}`);\n //\n});\n```\n\n```js\n// Async hooks enabled for bluebird\nconst ah = require('async_hooks');\nconst Promise = require(\"bluebird\");\nPromise.config({asyncHooks: true});\nPromise.resolve().then(() => {\n console.log(`eid ${ah.executionAsyncId()} tid ${ah.triggerAsyncId()}`);\n //\n});\n```\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.coroutine.addyieldhandler.md",
"content": "---\nlayout: api\nid: promise.coroutine.addyieldhandler\ntitle: Promise.coroutine.addYieldHandler\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.coroutine.addYieldHandler\n\n```js\nPromise.coroutine.addYieldHandler(function handler) -> undefined\n```\n\n\nBy default you can only yield Promises and Thenables inside coroutines. You can use this function to add yielding support for arbitrary types.\n\nFor example, if you wanted `yield 500` to be same as `yield Promise.delay`:\n\n```js\nPromise.coroutine.addYieldHandler(function(value) {\n if (typeof value === \"number\") return Promise.delay(value);\n});\n```\n\nYield handlers are called when you yield something that is not supported by default. The first yield handler to return a promise or a thenable will be used.\nIf no yield handler returns a promise or a thenable then an error is raised.\n\nAn example of implementing callback support with `addYieldHandler`:\n\n*This is a demonstration of how powerful the feature is and not the recommended usage. For best performance you need to use `promisifyAll` and yield promises directly.*\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = require(\"fs\");\n\nvar _ = (function() {\n var promise = null;\n Promise.coroutine.addYieldHandler(function(v) {\n if (v === undefined && promise != null) {\n return promise;\n }\n promise = null;\n });\n return function() {\n var def = Promise.defer();\n promise = def.promise;\n return def.callback;\n };\n})();\n\n\nvar readFileJSON = Promise.coroutine(function* (fileName) {\n var contents = yield fs.readFile(fileName, \"utf8\", _());\n return JSON.parse(contents);\n});\n```\n\nAn example of implementing thunks support with `addYieldHandler`:\n\n*This is a demonstration of how powerful the feature is and not the recommended usage. For best performance you need to use `promisifyAll` and yield promises directly.*\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = require(\"fs\");\n\nPromise.coroutine.addYieldHandler(function(v) {\n if (typeof v === \"function\") {\n return Promise.fromCallback(function(cb) {\n v(cb);\n });\n }\n});\n\nvar readFileThunk = function(fileName, encoding) {\n return function(cb) {\n return fs.readFile(fileName, encoding, cb);\n };\n};\n\nvar readFileJSON = Promise.coroutine(function* (fileName) {\n var contents = yield readFileThunk(fileName, \"utf8\");\n return JSON.parse(contents);\n});\n```\n\nAn example of handling promises in parallel by adding an `addYieldHandler` for arrays :\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\nPromise.coroutine.addYieldHandler(function(yieldedValue) {\n if (Array.isArray(yieldedValue)) return Promise.all(yieldedValue);\n});\n\nvar readFiles = Promise.coroutine(function* (fileNames) {\n return yield fileNames.map(function (fileName) {\n return fs.readFileAsync(fileName, \"utf8\");\n });\n});\n```\n\nA custom yield handler can also be used just for a single call to `Promise.coroutine()`:\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\nvar readFiles = Promise.coroutine(function* (fileNames) {\n return yield fileNames.map(function (fileName) {\n return fs.readFileAsync(fileName, \"utf8\");\n });\n}, {\n yieldHandler: function(yieldedValue) {\n if (Array.isArray(yieldedValue)) return Promise.all(yieldedValue);\n }\n});\n```\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.coroutine.md",
"content": "---\nlayout: api\nid: promise.coroutine\ntitle: Promise.coroutine\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.coroutine\n\n```js\nPromise.coroutine(GeneratorFunction(...arguments) generatorFunction, Object options) -> function\n```\n\nReturns a function that can use `yield` to yield promises. Control is returned back to the generator when the yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+.\n\n```js\nvar Promise = require(\"bluebird\");\n\nfunction PingPong() {\n\n}\n\nPingPong.prototype.ping = Promise.coroutine(function* (val) {\n console.log(\"Ping?\", val);\n yield Promise.delay(500);\n this.pong(val+1);\n});\n\nPingPong.prototype.pong = Promise.coroutine(function* (val) {\n console.log(\"Pong!\", val);\n yield Promise.delay(500);\n this.ping(val+1);\n});\n\nvar a = new PingPong();\na.ping(0);\n```\n\nRunning the example:\n\n $ node test.js\n Ping? 0\n Pong! 1\n Ping? 2\n Pong! 3\n Ping? 4\n Pong! 5\n Ping? 6\n Pong! 7\n Ping? 8\n ...\n\nWhen called, the coroutine function will start an instance of the generator and returns a promise for its final value.\n\nDoing `Promise.coroutine` is almost like using the C# `async` keyword to mark the function, with `yield` working as the `await` keyword. Promises are somewhat like `Task`s.\n\n**Tip**\n\nYou are able to yield non-promise values by adding your own yield handler using [`Promise.coroutine.addYieldHandler`](.) or calling `Promise.coroutine()` with a yield handler function as `options.yieldHandler`.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.delay.md",
"content": "---\nlayout: api\nid: promise.delay\ntitle: Promise.delay\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.delay\n\n```js\nPromise.delay(\n int ms,\n [any|Promise value=undefined]\n) -> Promise\n```\n\n\nReturns a promise that will be resolved with `value` (or `undefined`) after given `ms` milliseconds. If `value` is a promise, the delay will start counting down when it is fulfilled and the returned promise will be fulfilled with the fulfillment value of the `value` promise. If `value` is a rejected promise, the resulting promise will be rejected immediately. \n\n```js\nPromise.delay(500).then(function() {\n console.log(\"500 ms passed\");\n return \"Hello world\";\n}).delay(500).then(function(helloWorldString) {\n console.log(helloWorldString);\n console.log(\"another 500 ms passed\") ;\n});\n```\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.each.md",
"content": "---\nlayout: api\nid: promise.each\ntitle: Promise.each\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.each\n\n```js\nPromise.each(\n Iterable|Promise> input,\n function(any value, int index, int arrayLength) iterator\n) -> Promise>\n```\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) (an array, for example), or a promise of an `Iterable`, iterates serially over all the values in it, executing the given `iterator` on each element. If an element is a promise, the iterator will wait for it before proceeding. The `iterator` function has signature `(value, index, arrayLength)` where `value` is the current element (or its resolved value if it is a promise).\n\nIf, at any step:\n\n* The iterator returns a promise or a thenable, it is awaited before continuing to the next iteration.\n\n* The current element of the iteration is a *pending* promise, that promise will be awaited before running the iterator.\n\n* The current element of the iteration is a *rejected* promise, the iteration will stop and be rejected as well (with the same reason).\n\nIf all iterations resolve successfully, the `Promise.each` call resolves to a new array containing the resolved values of the original input elements.\n\n`Promise.each` is very similar to [Promise.mapSeries](.). The difference between `Promise.each` and `Promise.mapSeries` is their resolution value. `Promise.each` resolves with an array as explained above, while `Promise.mapSeries` resolves with an array containing the *outputs* of the iterator function on each step. This way, `Promise.each` is meant to be mainly used for side-effect operations (since the outputs of the iterator are essentially discarded), just like the native `.forEach()` method of arrays, while `Promise.map` is meant to be used as an async version of the native `.map()` method of arrays.\n\nBasic example:\n\n```js\n// The array to be iterated over can be a mix of values and promises.\nvar fileNames = [\"1.txt\", Promise.resolve(\"2.txt\"), \"3.txt\", Promise.delay(3000, \"4.txt\"), \"5.txt\"];\n\nPromise.each(fileNames, function(fileName, index, arrayLength) {\n // The iteration will be performed sequentially, awaiting for any\n // promises in the process.\n return fs.readFileAsync(fileName).then(function(fileContents) {\n // ...\n\n // The final resolution value of the iterator is is irrelevant,\n // since the result of the `Promise.each` has nothing to do with\n // the outputs of the iterator.\n return \"anything\"; // Doesn't matter\n });\n}).then(function(result) {\n // This will run after the last step is done\n console.log(\"Done!\")\n console.log(result); // [\"1.txt\", \"2.txt\", \"3.txt\", \"4.txt\", \"5.txt\"]\n});\n```\n\n\n##Example\n```js\nlet stories = [ '8952', '8884'];\nPromise.each(stories, (item, idx, length) => {\n return request.getAsync(`https://hacker-news.firebaseio.com/v0/item/${item}.json?print=pretty`)\n .then(res => {\n // need to do explicit operations here\n })\n})\n.then(result => {\n console.log('ALL done', result);//['8952', '8884']\n})\n\n```\n\n[api/promise.each](unfinished-article)\n=======\nExample with a rejected promise in the array:\n\n\n```js\n// If one of the promises in the original array rejects,\n// the iteration will stop once it reaches it\nvar items = [\"A\", Promise.delay(8000, \"B\"), Promise.reject(\"C\"), \"D\"];\n\nPromise.each(items, function(item) {\n return Promise.delay(4000).then(function() {\n console.log(\"On iterator: \" + item);\n });\n}).then(function(result) {\n // This not run\n}).catch(function(rejection) {\n console.log(\"Catch: \" + rejection);\n});\n\n// The code above outputs the following after 12 seconds (not 16!):\n// On iterator: A\n// On iterator: B\n// Catch: C\n```\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.filter.md",
"content": "---\nlayout: api\nid: promise.filter\ntitle: Promise.filter\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.filter\n\n```js\nPromise.filter(\n Iterable|Promise> input,\n function(any item, int index, int length) filterer,\n [Object {concurrency: int=Infinity} options]\n) -> Promise\n```\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)\\(arrays are `Iterable`\\), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and [filter the array to another](http://en.wikipedia.org/wiki/Filter_\\(higher-order_function\\)) using the given `filterer` function.\n\n\nIt is essentially an efficient shortcut for doing a [.map](.) and then [`Array#filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter):\n\n```js\nPromise.map(valuesToBeFiltered, function(value, index, length) {\n return Promise.all([filterer(value, index, length), value]);\n}).then(function(values) {\n return values.filter(function(stuff) {\n return stuff[0] == true\n }).map(function(stuff) {\n return stuff[1];\n });\n});\n```\n\nExample for filtering files that are accessible directories in the current directory:\n\n```js\nvar Promise = require(\"bluebird\");\nvar E = require(\"core-error-predicates\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\nfs.readdirAsync(process.cwd()).filter(function(fileName) {\n return fs.statAsync(fileName)\n .then(function(stat) {\n return stat.isDirectory();\n })\n .catch(E.FileAccessError, function() {\n return false;\n });\n}).each(function(directoryName) {\n console.log(directoryName, \" is an accessible directory\");\n});\n```\n\n####Filter Option: concurrency\n\nSee [Map Option: concurrency](#map-option-concurrency)\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.fromcallback.md",
"content": "---\nlayout: api\nid: promise.fromcallback\ntitle: Promise.fromCallback\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.fromCallback\n\n```js\nPromise.fromCallback(\n function(function callback) resolver,\n [Object {multiArgs: boolean=false} options]\n) -> Promise\n```\n```js\nPromise.fromNode(\n function(function callback) resolver,\n [Object {multiArgs: boolean=false} options]\n) -> Promise\n```\n\nReturns a promise that is resolved by a node style callback function. This is the most fitting way to do on the fly promisification when libraries don't expose classes for automatic promisification by undefined.\n\nThe resolver function is passed a callback that expects to be called back according to error-first node conventions.\n\nSetting `multiArgs` to `true` means the resulting promise will always fulfill with an array of the callback's success value(s). This is needed because promises only support a single success value while\nsome callback API's have multiple success value. The default is to ignore all but the first success value of a callback function.\n\nUsing manual resolver:\n\n```js\nvar Promise = require(\"bluebird\");\n// \"email-templates\" doesn't expose prototypes for promisification\nvar emailTemplates = Promise.promisify(require('email-templates'));\nvar templatesDir = path.join(__dirname, 'templates');\n\n\nemailTemplates(templatesDir).then(function(template) {\n return Promise.fromCallback(function(callback) {\n return template(\"newsletter\", callback);\n }, {multiArgs: true}).spread(function(html, text) {\n console.log(html, text);\n });\n});\n```\n\nThe same can also be written more concisely with `Function.prototype.bind`:\n\n```js\nvar Promise = require(\"bluebird\");\n// \"email-templates\" doesn't expose prototypes for promisification\nvar emailTemplates = Promise.promisify(require('email-templates'));\nvar templatesDir = path.join(__dirname, 'templates');\n\n\nemailTemplates(templatesDir).then(function(template) {\n return Promise.fromCallback(template.bind(null, \"newsletter\"), {multiArgs: true})\n .spread(function(html, text) {\n console.log(html, text);\n });\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.getnewlibrarycopy.md",
"content": "---\nlayout: api\nid: promise.getnewlibrarycopy\ntitle: Promise.getNewLibraryCopy\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.getNewLibraryCopy\n\n```js\nPromise.getNewLibraryCopy() -> Object\n```\n\nReturns a new independent copy of the Bluebird library.\n\nThis method should be used before you use any of the methods which would otherwise alter the global `Bluebird` object - to avoid polluting global state.\n\nA basic example:\n\n```js\nvar Promise = require('bluebird');\nvar Promise2 = Promise.getNewLibraryCopy();\n\nPromise2.x = 123;\n\nconsole.log(Promise2 == Promise); // false\nconsole.log(Promise2.x); // 123\nconsole.log(Promise.x); // undefined\n```\n\n`Promise2` is independent to `Promise`. Any changes to `Promise2` do not affect the copy of Bluebird returned by `require('bluebird')`.\n\nIn practice:\n\n```js\nvar Promise = require('bluebird').getNewLibraryCopy();\n\nPromise.coroutine.addYieldHandler( function() { /* */ } ); // alters behavior of `Promise.coroutine()`\n\n// somewhere in another file or module in same app\nvar Promise = require('bluebird');\n\nPromise.coroutine(function*() {\n // this code is unaffected by the yieldHandler defined above\n // because it was defined on an independent copy of Bluebird\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.join.md",
"content": "---\nlayout: api\nid: promise.join\ntitle: Promise.join\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.join\n\n```js\nPromise.join(\n Promise|any values...,\n function handler\n) -> Promise\n```\n\n\nFor coordinating multiple concurrent discrete promises. While [`.all`](.) is good for handling a dynamically sized list of uniform promises, `Promise.join` is much easier (and more performant) to use when you have a fixed amount of discrete promises that you want to coordinate concurrently. The final parameter, handler function, will be invoked with the result values of all of the fulfilled promises. For example:\n\n```js\nvar Promise = require(\"bluebird\");\nvar join = Promise.join;\n\njoin(getPictures(), getComments(), getTweets(),\n function(pictures, comments, tweets) {\n console.log(\"in total: \" + pictures.length + comments.length + tweets.length);\n});\n```\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\nvar pg = require(\"pg\");\nPromise.promisifyAll(pg, {\n filter: function(methodName) {\n return methodName === \"connect\"\n },\n multiArgs: true\n});\n// Promisify rest of pg normally\nPromise.promisifyAll(pg);\nvar join = Promise.join;\nvar connectionString = \"postgres://username:password@localhost/database\";\n\nvar fContents = fs.readFileAsync(\"file.txt\", \"utf8\");\nvar fStat = fs.statAsync(\"file.txt\");\nvar fSqlClient = pg.connectAsync(connectionString).spread(function(client, done) {\n client.close = done;\n return client;\n});\n\njoin(fContents, fStat, fSqlClient, function(contents, stat, sqlClient) {\n var query = \" \\\n INSERT INTO files (byteSize, contents) \\\n VALUES ($1, $2) \\\n \";\n return sqlClient.queryAsync(query, [stat.size, contents]).thenReturn(query);\n})\n.then(function(query) {\n console.log(\"Successfully ran the Query: \" + query);\n})\n.finally(function() {\n // This is why you want to use Promise.using for resource management\n if (fSqlClient.isFulfilled()) {\n fSqlClient.value().close();\n }\n});\n```\n\n*Note: In 1.x and 0.x `Promise.join` used to be a `Promise.all` that took the values in as arguments instead of an array. This behavior has been deprecated but is still supported partially - when the last argument is an immediate function value the new semantics will apply*\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.longstacktraces.md",
"content": "---\nlayout: api\nid: promise.longstacktraces\ntitle: Promise.longStackTraces\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n## ~~Promise.longStackTraces~~\n\nThis method is deprecated. Use [Promise.config](/docs/api/promise.config.html) instead.\n\n```js\nPromise.config({\n longStackTraces: true\n})\n```\n\n---\n\n```js\nPromise.longStackTraces() -> undefined\n```\n\nCall this right after the library is loaded to enable long stack traces. Long stack traces cannot be disabled after being enabled, and cannot be enabled after promises have already been created. Long stack traces imply a substantial performance penalty, around 4-5x for throughput and 0.5x for latency.\n\nLong stack traces are enabled by default in the debug build.\n\nTo enable them in all instances of bluebird in node.js, use the environment variable `BLUEBIRD_DEBUG`:\n\n```\nBLUEBIRD_DEBUG=1 node server.js\n```\n\nSetting the environment variable `NODE_ENV` to `\"development\"` also automatically enables long stack traces.\n\nYou should enabled long stack traces if you want better debugging experience. For example:\n\n```js\nPromise.longStackTraces();\nPromise.resolve().then(function outer() {\n return Promise.resolve().then(function inner() {\n return Promise.resolve().then(function evenMoreInner() {\n a.b.c.d()\n }).catch(function catcher(e) {\n console.error(e.stack);\n });\n });\n});\n```\n\nGives\n\n ReferenceError: a is not defined\n at evenMoreInner (:6:13)\n From previous event:\n at inner (:5:24)\n From previous event:\n at outer (:4:20)\n From previous event:\n at :3:9\n at Object.InjectedScript._evaluateOn (:581:39)\n at Object.InjectedScript._evaluateAndWrap (:540:52)\n at Object.InjectedScript.evaluate (:459:21)\n\nWhile with long stack traces disabled, you would get:\n\n ReferenceError: a is not defined\n at evenMoreInner (:6:13)\n at tryCatch1 (:41:19)\n at Promise$_resolvePromise [as _resolvePromise] (:1739:13)\n at Promise$_resolveLast [as _resolveLast] (:1520:14)\n at Async$_consumeFunctionBuffer [as _consumeFunctionBuffer] (:560:33)\n at Async$consumeFunctionBuffer (:515:14)\n at MutationObserver.Promise$_Deferred (:433:17)\n\nOn client side, long stack traces currently only work in recent Firefoxes, Chrome and Internet Explorer 10+.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.map.md",
"content": "---\nlayout: api\nid: promise.map\ntitle: Promise.map\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.map\n\n```js\nPromise.map(\n Iterable|Promise> input,\n function(any item, int index, int length) mapper,\n [Object {concurrency: int=Infinity} options]\n) -> Promise\n```\n\nGiven a finite [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)\\(arrays are `Iterable`\\), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and [map the array to another](http://en.wikipedia.org/wiki/Map_\\(higher-order_function\\)) using the given `mapper` function.\n\nPromises returned by the `mapper` function are awaited for and the returned promise doesn't fulfill until all mapped promises have fulfilled as well. If any promise in the array is rejected, or any promise returned by the `mapper` function is rejected, the returned promise is rejected as well.\n\nThe mapper function for a given item is called as soon as possible, that is, when the promise for that item's index in the input array is fulfilled. This doesn't mean that the result array has items in random order, it means that `.map` can be used for concurrency coordination unlike `.all`.\n\nA common use of `Promise.map` is to replace the `.push`+`Promise.all` boilerplate:\n\n```js\nvar promises = [];\nfor (var i = 0; i < fileNames.length; ++i) {\n promises.push(fs.readFileAsync(fileNames[i]));\n}\nPromise.all(promises).then(function() {\n console.log(\"done\");\n});\n\n// Using Promise.map:\nPromise.map(fileNames, function(fileName) {\n // Promise.map awaits for returned promises as well.\n return fs.readFileAsync(fileName);\n}).then(function() {\n console.log(\"done\");\n});\n\n// Using Promise.map and async/await:\nawait Promise.map(fileNames, function(fileName) {\n // Promise.map awaits for returned promises as well.\n return fs.readFileAsync(fileName);\n});\nconsole.log(\"done\");\n\n```\n\nA more involved example:\n\n```js\nvar Promise = require(\"bluebird\");\nvar join = Promise.join;\nvar fs = Promise.promisifyAll(require(\"fs\"));\nfs.readdirAsync(\".\").map(function(fileName) {\n var stat = fs.statAsync(fileName);\n var contents = fs.readFileAsync(fileName).catch(function ignore() {});\n return join(stat, contents, function(stat, contents) {\n return {\n stat: stat,\n fileName: fileName,\n contents: contents\n }\n });\n// The return value of .map is a promise that is fulfilled with an array of the mapped values\n// That means we only get here after all the files have been statted and their contents read\n// into memory. If you need to do more operations per file, they should be chained in the map\n// callback for concurrency.\n}).call(\"sort\", function(a, b) {\n return a.fileName.localeCompare(b.fileName);\n}).each(function(file) {\n var contentLength = file.stat.isDirectory() ? \"(directory)\" : file.contents.length + \" bytes\";\n console.log(file.fileName + \" last modified \" + file.stat.mtime + \" \" + contentLength)\n});\n```\n\n####Map Option: concurrency\n\nYou may optionally specify a concurrency limit:\n\n```js\n...map(..., {concurrency: 3});\n```\n\nThe concurrency limit applies to Promises returned by the mapper function and it basically limits the number of Promises created. For example, if `concurrency` is `3` and the mapper callback has been called enough so that there are three returned Promises currently pending, no further callbacks are called until one of the pending Promises resolves. So the mapper function will be called three times and it will be called again only after at least one of the Promises resolves.\n\nPlaying with the first example with and without limits, and seeing how it affects the duration when reading 20 files:\n\n```js\nvar Promise = require(\"bluebird\");\nvar join = Promise.join;\nvar fs = Promise.promisifyAll(require(\"fs\"));\nvar concurrency = parseFloat(process.argv[2] || \"Infinity\");\nconsole.time(\"reading files\");\nfs.readdirAsync(\".\").map(function(fileName) {\n var stat = fs.statAsync(fileName);\n var contents = fs.readFileAsync(fileName).catch(function ignore() {});\n return join(stat, contents, function(stat, contents) {\n return {\n stat: stat,\n fileName: fileName,\n contents: contents\n }\n });\n// The return value of .map is a promise that is fulfilled with an array of the mapped values\n// That means we only get here after all the files have been statted and their contents read\n// into memory. If you need to do more operations per file, they should be chained in the map\n// callback for concurrency.\n}, {concurrency: concurrency}).call(\"sort\", function(a, b) {\n return a.fileName.localeCompare(b.fileName);\n}).then(function() {\n console.timeEnd(\"reading files\");\n});\n```\n\n```bash\n$ sync && echo 3 > /proc/sys/vm/drop_caches\n$ node test.js 1\nreading files 35ms\n$ sync && echo 3 > /proc/sys/vm/drop_caches\n$ node test.js Infinity\nreading files: 9ms\n```\n\nThe order `map` calls the mapper function on the array elements is not specified, there is no guarantee on the order in which it'll execute the `map`er on the elements. For order guarantee in sequential execution - see [Promise.mapSeries](.).\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.mapseries.md",
"content": "---\nlayout: api\nid: promise.mapseries\ntitle: Promise.mapSeries\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.mapSeries\n\n```js\nPromise.mapSeries(\n Iterable|Promise> input,\n function(any value, int index, int arrayLength) mapper\n) -> Promise>\n```\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) (an array, for example), or a promise of an `Iterable`, iterates serially over all the values in it, executing the given `mapper` on each element. If an element is a promise, the mapper will wait for it before proceeding. The `mapper` function has signature `(value, index, arrayLength)` where `value` is the current element (or its resolved value if it is a promise).\n\nIf, at any step:\n\n* The mapper returns a promise or a thenable, it is awaited before continuing to the next iteration.\n\n* The current element of the iteration is a *pending* promise, that promise will be awaited before running the mapper.\n\n* The current element of the iteration is a *rejected* promise, the iteration will stop and be rejected as well (with the same reason).\n\nIf all iterations resolve successfully, the `Promise.mapSeries` call resolves to a new array containing the results of each `mapper` execution, in order.\n\n`Promise.mapSeries` is very similar to [Promise.each](.). The difference between `Promise.each` and `Promise.mapSeries` is their resolution value. `Promise.mapSeries` resolves with an array as explained above, while `Promise.each` resolves with an array containing the *resolved values of the input elements* (ignoring the outputs of the iteration steps). This way, `Promise.each` is meant to be mainly used for side-effect operations (since the outputs of the iterator are essentially discarded), just like the native `.forEach()` method of arrays, while `Promise.map` is meant to be used as an async version of the native `.map()` method of arrays.\n\nBasic example:\n\n```js\n// The array to be mapped over can be a mix of values and promises.\nvar fileNames = [\"1.txt\", Promise.resolve(\"2.txt\"), \"3.txt\", Promise.delay(3000, \"4.txt\"), \"5.txt\"];\n\nPromise.mapSeries(fileNames, function(fileName, index, arrayLength) {\n // The iteration will be performed sequentially, awaiting for any\n // promises in the process.\n return fs.readFileAsync(fileName).then(function(fileContents) {\n // ...\n return fileName + \"!\";\n });\n}).then(function(result) {\n // This will run after the last step is done\n console.log(\"Done!\")\n console.log(result); // [\"1.txt!\", \"2.txt!\", \"3.txt!\", \"4.txt!\", \"5.txt!\"]\n});\n```\n\nExample with a rejected promise in the array:\n\n```js\n// If one of the promises in the original array rejects,\n// the iteration will stop once it reaches it\nvar items = [\"A\", Promise.delay(8000, \"B\"), Promise.reject(\"C\"), \"D\"];\n\nPromise.each(items, function(item) {\n return Promise.delay(4000).then(function() {\n console.log(\"On mapper: \" + item);\n });\n}).then(function(result) {\n // This not run\n}).catch(function(rejection) {\n console.log(\"Catch: \" + rejection);\n});\n\n// The code above outputs the following after 12 seconds (not 16!):\n// On mapper: A\n// On mapper: B\n// Catch: C\n```\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.method.md",
"content": "---\nlayout: api\nid: promise.method\ntitle: Promise.method\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.method\n\n```js\nPromise.method(function(...arguments) fn) -> function\n```\n\n\nReturns a new function that wraps the given function `fn`. The new function will always return a promise that is fulfilled with the original functions return values or rejected with thrown exceptions from the original function.\n\nThis method is convenient when a function can sometimes return synchronously or throw synchronously.\n\nExample without using `Promise.method`:\n\n```js\nMyClass.prototype.method = function(input) {\n if (!this.isValid(input)) {\n return Promise.reject(new TypeError(\"input is not valid\"));\n }\n\n if (this.cache(input)) {\n return Promise.resolve(this.someCachedValue);\n }\n\n return db.queryAsync(input).bind(this).then(function(value) {\n this.someCachedValue = value;\n return value;\n });\n};\n```\n\nUsing the same function `Promise.method`, there is no need to manually wrap direct return or throw values into a promise:\n\n```js\nMyClass.prototype.method = Promise.method(function(input) {\n if (!this.isValid(input)) {\n throw new TypeError(\"input is not valid\");\n }\n\n if (this.cache(input)) {\n return this.someCachedValue;\n }\n\n return db.queryAsync(input).bind(this).then(function(value) {\n this.someCachedValue = value;\n return value;\n });\n});\n```\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.noconflict.md",
"content": "---\nlayout: api\nid: promise.noconflict\ntitle: Promise.noConflict\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.noConflict\n\n```js\nPromise.noConflict() -> Object\n```\n\n\nThis is relevant to browser environments with no module loader.\n\nRelease control of the `Promise` namespace to whatever it was before this library was loaded. Returns a reference to the library namespace so you can attach it to something else.\n\n```html\n\n\n\n\n```\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.onpossiblyunhandledrejection.md",
"content": "---\nlayout: api\nid: promise.onpossiblyunhandledrejection\ntitle: Promise.onPossiblyUnhandledRejection\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.onPossiblyUnhandledRejection\n\n```js\nPromise.onPossiblyUnhandledRejection(function(any error, Promise promise) handler) -> undefined\n```\n\n\n*Note: this hook is specific to the bluebird instance it's called on, application developers should use [global rejection events](/docs/api/error-management-configuration.html#global-rejection-events)*\n\nAdd `handler` as the handler to call when there is a possibly unhandled rejection. The default handler logs the error stack to stderr or `console.error` in browsers.\n\n```js\nPromise.onPossiblyUnhandledRejection(function(e, promise) {\n throw e;\n});\n```\n\nPassing no value or a non-function will have the effect of removing any kind of handling for possibly unhandled rejections.\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.onunhandledrejectionhandled.md",
"content": "---\nlayout: api\nid: promise.onunhandledrejectionhandled\ntitle: Promise.onUnhandledRejectionHandled\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.onUnhandledRejectionHandled\n\n```js\nPromise.onUnhandledRejectionHandled(function(Promise promise) handler) -> undefined\n```\n\n\n*Note: this hook is specific to the bluebird instance its called on, application developers should use [global rejection events](/docs/api/error-management-configuration.html#global-rejection-events)*\n\nAdd `handler` as the handler to call when a rejected promise that was reported as \"possibly unhandled rejection\" became handled.\n\nTogether with `onPossiblyUnhandledRejection` these hooks can be used to implement a debugger that will show a list\nof unhandled promise rejections updated in real time as promises become handled.\n\nFor example:\n\n```js\nvar unhandledPromises = [];\nPromise.onPossiblyUnhandledRejection(function(reason, promise) {\n unhandledPromises.push(promise);\n //Update some debugger UI\n});\n\nPromise.onUnhandledRejectionHandled(function(promise) {\n var index = unhandledPromises.indexOf(promise);\n unhandledPromises.splice(index, 1);\n //Update the debugger UI\n});\n```\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.promisify.md",
"content": "---\nlayout: api\nid: promise.promisify\ntitle: Promise.promisify\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.promisify\n\n```js\nPromise.promisify(\n function(any arguments..., function callback) nodeFunction,\n [Object {\n multiArgs: boolean=false,\n context: any=this\n } options]\n) -> function\n```\n\nReturns a function that will wrap the given `nodeFunction`. Instead of taking a callback, the returned function will return a promise whose fate is decided by the callback behavior of the given node function. The node function should conform to node.js convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument.\n\nIf the `nodeFunction` calls its callback with multiple success values, the fulfillment value will be the first fulfillment item.\n\nSetting `multiArgs` to `true` means the resulting promise will always fulfill with an array of the callback's success value(s). This is needed because promises only support a single success value while some callback API's have multiple success value. The default is to ignore all but the first success value of a callback function.\n\nIf you pass a `context`, the `nodeFunction` will be called as a method on the `context`.\n\nExample of promisifying the asynchronous `readFile` of node.js `fs`-module:\n\n```js\nvar readFile = Promise.promisify(require(\"fs\").readFile);\n\nreadFile(\"myfile.js\", \"utf8\").then(function(contents) {\n return eval(contents);\n}).then(function(result) {\n console.log(\"The result of evaluating myfile.js\", result);\n}).catch(SyntaxError, function(e) {\n console.log(\"File had syntax error\", e);\n//Catch any other error\n}).catch(function(e) {\n console.log(\"Error reading file\", e);\n});\n```\n\nNote that if the node function is a method of some object, you can pass the object as the second argument like so:\n\n```js\nvar redisGet = Promise.promisify(redisClient.get, {context: redisClient});\nredisGet('foo').then(function() {\n //...\n});\n```\n\nBut this will also work:\n\n```js\nvar getAsync = Promise.promisify(redisClient.get);\ngetAsync.call(redisClient, 'foo').then(function() {\n //...\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.promisifyall.md",
"content": "---\nlayout: api\nid: promise.promisifyall\ntitle: Promise.promisifyAll\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.promisifyAll\n\n```js\nPromise.promisifyAll(\n Object target,\n [Object {\n suffix: String=\"Async\",\n multiArgs: boolean=false,\n filter: boolean function(String name, function func, Object target, boolean passesDefaultFilter),\n promisifier: function(function originalFunction, function defaultPromisifier)\n } options]\n) -> Object\n```\n\nPromisifies the entire object by going through the object's properties and creating an async equivalent of each function on the object and its prototype chain. The promisified method name will be the original method name suffixed with `suffix` (default is `\"Async\"`). Any class properties of the object (which is the case for the main export of many modules) are also promisified, both static and instance methods. Class property is a property with a function value that has a non-empty `.prototype` object. Returns the input object.\n\nNote that the original methods on the object are not overwritten but new methods are created with the `Async`-suffix. For example, if you `promisifyAll` the node.js `fs` object use `fs.statAsync` to call the promisified `stat` method.\n\nExample:\n\n```js\nPromise.promisifyAll(require(\"redis\"));\n\n//Later on, all redis client instances have promise returning functions:\n\nredisClient.hexistsAsync(\"myhash\", \"field\").then(function(v) {\n\n}).catch(function(e) {\n\n});\n```\n\nIt also works on singletons or specific instances:\n\n```js\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\nfs.readFileAsync(\"myfile.js\", \"utf8\").then(function(contents) {\n console.log(contents);\n}).catch(function(e) {\n console.error(e.stack);\n});\n```\n\nSee [promisification](#promisification) for more examples.\n\nThe entire prototype chain of the object is promisified on the object. Only enumerable are considered. If the object already has a promisified version of the method, it will be skipped. The target methods are assumed to conform to node.js callback convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument. If the node method calls its callback with multiple success values, the fulfillment value will be an array of them.\n\nIf a method name already has an `\"Async\"`-suffix, an exception will be thrown.\n\n####Option: suffix\n\nOptionally, you can define a custom suffix through the options object:\n\n```js\nvar fs = Promise.promisifyAll(require(\"fs\"), {suffix: \"MySuffix\"});\nfs.readFileMySuffix(...).then(...);\n```\n\nAll the above limitations apply to custom suffices:\n\n- Choose the suffix carefully, it must not collide with anything\n- PascalCase the suffix\n- The suffix must be a valid JavaScript identifier using ASCII letters\n- Always use the same suffix everywhere in your application, you could create a wrapper to make this easier:\n\n```js\nmodule.exports = function myPromisifyAll(target) {\n return Promise.promisifyAll(target, {suffix: \"MySuffix\"});\n};\n```\n\n####Option: multiArgs\n\nSetting `multiArgs` to `true` means the resulting promise will always fulfill with an array of the callback's success value(s). This is needed because promises only support a single success value while some callback API's have multiple success value. The default is to ignore all but the first success value of a callback function.\n\nIf a module has multiple argument callbacks as an exception rather than the rule, you can filter out the multiple argument methods in first go and then promisify rest of the module in second go:\n\n```js\nPromise.promisifyAll(something, {\n filter: function(name) {\n return name === \"theMultiArgMethodIwant\";\n },\n multiArgs: true\n});\n// Rest of the methods\nPromise.promisifyAll(something);\n```\n\n####Option: filter\n\nOptionally, you can define a custom filter through the options object:\n\n```js\nPromise.promisifyAll(..., {\n filter: function(name, func, target, passesDefaultFilter) {\n // name = the property name to be promisified without suffix\n // func = the function\n // target = the target object where the promisified func will be put with name + suffix\n // passesDefaultFilter = whether the default filter would be passed\n // return boolean (return value is coerced, so not returning anything is same as returning false)\n\n return passesDefaultFilter && ...\n }\n})\n```\n\nThe default filter function will ignore properties that start with a leading underscore, properties that are not valid JavaScript identifiers and constructor functions (function which have enumerable properties in their `.prototype`).\n\n\n####Option: promisifier\n\nOptionally, you can define a custom promisifier, so you could promisifyAll e.g. the chrome APIs used in Chrome extensions.\n\nThe promisifier gets a reference to the original method and should return a function which returns a promise.\n\n```js\nfunction DOMPromisifier(originalMethod) {\n // return a function\n return function promisified() {\n var args = [].slice.call(arguments);\n // Needed so that the original method can be called with the correct receiver\n var self = this;\n // which returns a promise\n return new Promise(function(resolve, reject) {\n args.push(resolve, reject);\n originalMethod.apply(self, args);\n });\n };\n}\n\n// Promisify e.g. chrome.browserAction\nPromise.promisifyAll(chrome.browserAction, {promisifier: DOMPromisifier});\n\n// Later\nchrome.browserAction.getTitleAsync({tabId: 1})\n .then(function(result) {\n\n });\n```\n\nCombining `filter` with `promisifier` for the restler module to promisify event emitter:\n\n```js\nvar Promise = require(\"bluebird\");\nvar restler = require(\"restler\");\nvar methodNamesToPromisify = \"get post put del head patch json postJson putJson\".split(\" \");\n\nfunction EventEmitterPromisifier(originalMethod) {\n // return a function\n return function promisified() {\n var args = [].slice.call(arguments);\n // Needed so that the original method can be called with the correct receiver\n var self = this;\n // which returns a promise\n return new Promise(function(resolve, reject) {\n // We call the originalMethod here because if it throws,\n // it will reject the returned promise with the thrown error\n var emitter = originalMethod.apply(self, args);\n\n emitter\n .on(\"success\", function(data, response) {\n resolve([data, response]);\n })\n .on(\"fail\", function(data, response) {\n // Erroneous response like 400\n resolve([data, response]);\n })\n .on(\"error\", function(err) {\n reject(err);\n })\n .on(\"abort\", function() {\n reject(new Promise.CancellationError());\n })\n .on(\"timeout\", function() {\n reject(new Promise.TimeoutError());\n });\n });\n };\n};\n\nPromise.promisifyAll(restler, {\n filter: function(name) {\n return methodNamesToPromisify.indexOf(name) > -1;\n },\n promisifier: EventEmitterPromisifier\n});\n\n// ...\n\n// Later in some other file\n\nvar restler = require(\"restler\");\nrestler.getAsync(\"http://...\", ...,).spread(function(data, response) {\n\n})\n```\n\nUsing `defaultPromisifier` parameter to add enhancements on top of normal node\npromisification:\n\n```js\nvar fs = Promise.promisifyAll(require(\"fs\"), {\n promisifier: function(originalFunction, defaultPromisifer) {\n var promisified = defaultPromisifier(originalFunction);\n\n return function() {\n // Enhance normal promisification by supporting promises as\n // arguments\n\n var args = [].slice.call(arguments);\n var self = this;\n return Promise.all(args).then(function(awaitedArgs) {\n return promisified.apply(self, awaitedArgs);\n });\n };\n }\n});\n\n// All promisified fs functions now await their arguments if they are promises\nvar version = fs.readFileAsync(\"package.json\", \"utf8\").then(JSON.parse).get(\"version\");\nfs.writeFileAsync(\"the-version.txt\", version, \"utf8\");\n```\n\n####Promisifying multiple classes in one go\n\nYou can promisify multiple classes in one go by constructing an array out of the classes and passing it to `promisifyAll`:\n\n```js\nvar Pool = require(\"mysql/lib/Pool\");\nvar Connection = require(\"mysql/lib/Connection\");\nPromise.promisifyAll([Pool, Connection]);\n```\n\nThis works because the array acts as a \"module\" where the indices are the \"module\"'s properties for classes.\n\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.props.md",
"content": "---\nlayout: api\nid: promise.props\ntitle: Promise.props\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.props\n\n```js\nPromise.props(Object|Map|Promise input) -> Promise\n```\n\nLike [`.all`](.) but for object properties or `Map`s\\* entries instead of iterated values. Returns a promise that is fulfilled when all the properties of the object or the `Map`'s' values\\*\\* are fulfilled. The promise's fulfillment value is an object or a `Map` with fulfillment values at respective keys to the original object or a `Map`. If any promise in the object or `Map` rejects, the returned promise is rejected with the rejection reason.\n\nIf `object` is a trusted `Promise`, then it will be treated as a promise for object rather than for its properties. All other objects (except `Map`s) are treated for their properties as is returned by `Object.keys` - the object's own enumerable properties.\n\n*\\*Only the native [ECMAScript 6 `Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) implementation that is provided by the environment as is is supported*\n\n*\\*\\*If the map's keys happen to be `Promise`s, they are not awaited for and the resulting `Map` will still have those same `Promise` instances as keys*\n\n\n```js\nPromise.props({\n pictures: getPictures(),\n comments: getComments(),\n tweets: getTweets()\n}).then(function(result) {\n console.log(result.tweets, result.pictures, result.comments);\n});\n```\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\nvar _ = require(\"lodash\");\nvar path = require(\"path\");\nvar util = require(\"util\");\n\nfunction directorySizeInfo(root) {\n var counts = {dirs: 0, files: 0};\n var stats = (function reader(root) {\n return fs.readdirAsync(root).map(function(fileName) {\n var filePath = path.join(root, fileName);\n return fs.statAsync(filePath).then(function(stat) {\n stat.filePath = filePath;\n if (stat.isDirectory()) {\n counts.dirs++;\n return reader(filePath)\n }\n counts.files++;\n return stat;\n });\n }).then(_.flatten);\n })(root).then(_.chain);\n\n var smallest = stats.call(\"min\", \"size\").call(\"pick\", \"size\", \"filePath\").call(\"value\");\n var largest = stats.call(\"max\", \"size\").call(\"pick\", \"size\", \"filePath\").call(\"value\");\n var totalSize = stats.call(\"pluck\", \"size\").call(\"reduce\", function(a, b) {\n return a + b;\n }, 0);\n\n return Promise.props({\n counts: counts,\n smallest: smallest,\n largest: largest,\n totalSize: totalSize\n });\n}\n\n\ndirectorySizeInfo(process.argv[2] || \".\").then(function(sizeInfo) {\n console.log(util.format(\" \\n\\\n %d directories, %d files \\n\\\n Total size: %d bytes \\n\\\n Smallest file: %s with %d bytes \\n\\\n Largest file: %s with %d bytes \\n\\\n \", sizeInfo.counts.dirs, sizeInfo.counts.files, sizeInfo.totalSize,\n sizeInfo.smallest.filePath, sizeInfo.smallest.size,\n sizeInfo.largest.filePath, sizeInfo.largest.size));\n});\n```\n\nNote that if you have no use for the result object other than retrieving the properties, it is more convenient to use [`Promise.join`](.):\n\n```js\nPromise.join(getPictures(), getComments(), getTweets(),\n function(pictures, comments, tweets) {\n console.log(pictures, comments, tweets);\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.race.md",
"content": "---\nlayout: api\nid: promise.race\ntitle: Promise.race\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.race\n\n```js\nPromise.race(Iterable|Promise> input) -> Promise\n```\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)\\(arrays are `Iterable`\\), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and return a promise that is fulfilled or rejected as soon as a promise in the array is fulfilled or rejected with the respective rejection reason or fulfillment value.\n\nThis method is only implemented because it's in the ES6 standard. If you want to race promises to fulfillment the [`.any`](.) method is more appropriate as it doesn't qualify a rejected promise as the winner. It also has less surprises: `.race` must become infinitely pending if an empty array is passed but passing an empty array to [`.any`](.) is more usefully a `RangeError`\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.reduce.md",
"content": "---\nlayout: api\nid: promise.reduce\ntitle: Promise.reduce\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.reduce\n\n```js\nPromise.reduce(\n Iterable|Promise> input,\n function(any accumulator, any item, int index, int length) reducer,\n [any initialValue]\n) -> Promise\n```\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)\\(arrays are `Iterable`\\), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and [reduce the array to a value](http://en.wikipedia.org/wiki/Fold_\\(higher-order_function\\)) using the given `reducer` function.\n\nIf the reducer function returns a promise, then the result of the promise is awaited, before continuing with next iteration. If any promise in the array is rejected or a promise returned by the reducer function is rejected, the result is rejected as well.\n\nRead given files sequentially while summing their contents as an integer. Each file contains just the text `10`.\n\n```js\nPromise.reduce([\"file1.txt\", \"file2.txt\", \"file3.txt\"], function(total, fileName) {\n return fs.readFileAsync(fileName, \"utf8\").then(function(contents) {\n return total + parseInt(contents, 10);\n });\n}, 0).then(function(total) {\n //Total is 30\n});\n```\n\n*If `initialValue` is `undefined` (or a promise that resolves to `undefined`) and the iterable contains only 1 item, the callback will not be called and the iterable's single item is returned. If the iterable is empty, the callback will not be called and `initialValue` is returned (which may be `undefined`).*\n\n`Promise.reduce` will start calling the reducer as soon as possible, this is why you might want to use it over `Promise.all` (which awaits for the entire array before you can call [`Array#reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) on it).\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.reject.md",
"content": "---\nlayout: api\nid: promise.reject\ntitle: Promise.reject\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.reject\n\n```js\nPromise.reject(any error) -> Promise\n```\n\n\nCreate a promise that is rejected with the given `error`.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.resolve.md",
"content": "---\nlayout: api\nid: promise.resolve\ntitle: Promise.resolve\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n \n## Promise.resolve\n\n```js\nPromise.resolve(Promise|any value) -> Promise\n```\n\n\nCreate a promise that is resolved with the given value. If `value` is already a trusted `Promise`, it is returned as is. If `value` is not a thenable, a fulfilled Promise is returned with `value` as its fulfillment value. If `value` is a thenable (Promise-like object, like those returned by jQuery's `$.ajax`), returns a trusted Promise that assimilates the state of the thenable.\n\nThis can be useful if a function returns a promise (say into a chain) but can optionally return a static value. Say, for a lazy-loaded value. Example:\n\n```js\nvar someCachedValue;\n\nvar getValue = function() {\n if (someCachedValue) {\n return Promise.resolve(someCachedValue);\n }\n\n return db.queryAsync().then(function(value) {\n someCachedValue = value;\n return value;\n });\n};\n```\n\nAnother example with handling jQuery castable objects (`$` is jQuery)\n\n```js\nPromise.resolve($.get(\"http://www.google.com\")).then(function() {\n //Returning a thenable from a handler is automatically\n //cast to a trusted Promise as per Promises/A+ specification\n return $.post(\"http://www.yahoo.com\");\n}).then(function() {\n\n}).catch(function(e) {\n //jQuery doesn't throw real errors so use catch-all\n console.log(e.statusText);\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.setscheduler.md",
"content": "---\nlayout: api\nid: promise.setscheduler\ntitle: Promise.setScheduler\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.setScheduler\n\n```js\nPromise.setScheduler(function(function fn) scheduler) -> function\n```\n\n\nScheduler should be a function that asynchronously schedules the calling of the passed in function:\n\n```js\n// This is just an example of how to use the api, there is no reason to do this\nPromise.setScheduler(function(fn) {\n setTimeout(fn, 0);\n});\n```\n\nSetting a custom scheduler could be necessary when you need a faster way to schedule functions than bluebird does by default. It also makes bluebird possible to use in platforms where normal timing constructs like `setTimeout` and `process.nextTick` are not available (like Nashhorn).\n\nYou can also use it as a hook:\n\n```js\n// This will synchronize bluebird promise queue flushing with angulars queue flushing\n// Angular is also now responsible for choosing the actual scheduler\nPromise.setScheduler(function(fn) {\n $rootScope.$evalAsync(fn);\n});\n```\n\n> **Danger** - in order to keep bluebird promises [Promises/A+](https://promisesaplus.com/) compliant a scheduler that executes the function asynchronously (like the examples in this page) must be used. \n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.some.md",
"content": "---\nlayout: api\nid: promise.some\ntitle: Promise.some\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.some\n\n```js\nPromise.some(\n Iterable|Promise> input,\n int count\n) -> Promise\n```\n\nGiven an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols)\\(arrays are `Iterable`\\), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and return a promise that is fulfilled as soon as `count` promises are fulfilled in the array. The fulfillment value is an array with `count` values in the order they were fulfilled.\n\nThis example pings 4 nameservers, and logs the fastest 2 on console:\n\n```js\nPromise.some([\n ping(\"ns1.example.com\"),\n ping(\"ns2.example.com\"),\n ping(\"ns3.example.com\"),\n ping(\"ns4.example.com\")\n], 2).spread(function(first, second) {\n console.log(first, second);\n});\n```\n\nIf too many promises are rejected so that the promise can never become fulfilled, it will be immediately rejected with an [AggregateError](.) of the rejection reasons in the order they were thrown in.\n\nYou can get a reference to [AggregateError](.) from `Promise.AggregateError`.\n\n```js\nPromise.some(...)\n .then(...)\n .then(...)\n .catch(Promise.AggregateError, function(err) {\n err.forEach(function(e) {\n console.error(e.stack);\n });\n });\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promise.try.md",
"content": "---\nlayout: api\nid: promise.try\ntitle: Promise.try\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.try\n\n```js\nPromise.try(function() fn) -> Promise\n```\n```js\nPromise.attempt(function() fn) -> Promise\n```\n\n\nStart the chain of promises with `Promise.try`. Any synchronous exceptions will be turned into rejections on the returned promise.\n\n```js\nfunction getUserById(id) {\n return Promise.try(function() {\n if (typeof id !== \"number\") {\n throw new Error(\"id must be a number\");\n }\n return db.getUserById(id);\n });\n}\n```\n\nNow if someone uses this function, they will catch all errors in their Promise `.catch` handlers instead of having to handle both synchronous and asynchronous exception flows.\n\n*For compatibility with earlier ECMAScript version, an alias `Promise.attempt` is provided for [`Promise.try`](.).*\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promise.using.md",
"content": "---\nlayout: api\nid: promise.using\ntitle: Promise.using\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promise.using\n\n```js\nPromise.using(\n Promise|Disposer|any resource,\n Promise|Disposer|any resource...,\n function(any resources...) handler\n) -> Promise\n```\n```js\nPromise.using(\n Array resources,\n function(Array resources) handler\n) -> Promise\n```\n\n\nIn conjunction with [`.disposer`](.), `using` will make sure that no matter what, the specified disposer will be called when the promise returned by the callback passed to `using` has settled. The disposer is necessary because there is no standard interface in node for disposing resources.\n\nHere is a simple example (where `getConnection()` has been defined to return a proper Disposer object)\n\n```js\nusing(getConnection(), function(connection) {\n // Don't leak the `connection` variable anywhere from here\n // it is only guaranteed to be open while the promise returned from\n // this callback is still pending\n return connection.queryAsync(\"SELECT * FROM TABLE\");\n // Code that is chained from the promise created in the line above\n // still has access to `connection`\n}).then(function(rows) {\n // The connection has been closed by now\n console.log(rows);\n});\n```\n\nUsing multiple resources:\n\n```js\nusing(getConnection(), function(conn1) {\n return using(getConnection(), function(conn2) {\n // use conn1 and conn 2 here\n });\n}).then(function() {\n // Both connections closed by now\n})\n```\n\nThe above can also be written as (with a caveat, see below)\n\n```js\nusing(getConnection(), getConnection(), function(conn1, conn2) {\n // use conn1 and conn2\n}).then(function() {\n // Both connections closed by now\n})\n```\n\nHowever, if the second `getConnection` throws **synchronously**, the first connection is leaked. This will not happen\nwhen using APIs through bluebird promisified methods though. You can wrap functions that could throw in [`Promise.method`](.) which will turn synchronous rejections into rejected promises.\n\nNote that you can mix promises and disposers, so that you can acquire all the things you need in parallel instead of sequentially\n\n```js\n// The files don't need resource management but you should\n// still start the process of reading them even before you have the connection\n// instead of waiting for the connection\n\n// The connection is always closed, no matter what fails at what point\nusing(readFile(\"1.txt\"), readFile(\"2.txt\"), getConnection(), function(txt1, txt2, conn) {\n // use conn and have access to txt1 and txt2\n});\n```\n\n\n\n\nYou can also pass the resources in an array in the first argument. In this case the handler function will only be called with one argument that is the array containing the resolved resources in respective positions in the array. Example:\n\n```js\nvar connectionPromises = [getConnection(), getConnection()];\n\nusing(connectionPromises, function(connections) {\n var conn1 = connections[0];\n var conn2 = connections[1];\n // use conn1 and conn2\n}).then(function() {\n // Both connections closed by now\n})\n\n```\n\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/promiseinspection.md",
"content": "---\nlayout: api\nid: promiseinspection\ntitle: PromiseInspection\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##PromiseInspection\n\n```js\ninterface PromiseInspection {\n any reason()\n any value()\n boolean isPending()\n boolean isRejected()\n boolean isFulfilled()\n boolean isCancelled()\n}\n```\n\nThis interface is implemented by `Promise` instances as well as the `PromiseInspection` result given by [.reflect()](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/promisification.md",
"content": "---\nlayout: api\nid: promisification\ntitle: Promisification\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Promisification\n\nPromisification means converting an existing promise-unaware API to a promise-returning API.\n\nThe usual way to use promises in node is to [Promise.promisifyAll](.) some API and start exclusively calling promise returning versions of the APIs methods. E.g.\n\n```js\nvar fs = require(\"fs\");\nPromise.promisifyAll(fs);\n// Now you can use fs as if it was designed to use bluebird promises from the beginning\n\nfs.readFileAsync(\"file.js\", \"utf8\").then(...)\n```\n\nNote that the above is an exceptional case because `fs` is a singleton instance. Most libraries can be promisified by requiring the library's classes (constructor functions) and calling promisifyAll on the `.prototype`. This only needs to be done once in the entire application's lifetime and after that you may use the library's methods exactly as they are documented, except by appending the `\"Async\"`-suffix to method calls and using the promise interface instead of the callback interface.\n\nAs a notable exception in `fs`, `fs.existsAsync` doesn't work as expected, because Node's `fs.exists` doesn't call back with error as first argument. More at [#418](.). One possible workaround is using `fs.statAsync`.\n\nSome examples of the above practice applied to some popular libraries:\n\n```js\n// The most popular redis module\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"redis\"));\n```\n\n```js\n// The most popular mongodb module\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mongodb\"));\n```\n\n```js\n// The most popular mysql module\nvar Promise = require(\"bluebird\");\n// Note that the library's classes are not properties of the main export\n// so we require and promisifyAll them manually\nPromise.promisifyAll(require(\"mysql/lib/Connection\").prototype);\nPromise.promisifyAll(require(\"mysql/lib/Pool\").prototype);\n```\n\n```js\n// Mongoose\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mongoose\"));\n```\n\n```js\n// Request\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"request\"));\n// Use request.getAsync(...) not request(..), it will not return a promise\n```\n\n```js\n// mkdir\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mkdirp\"));\n// Use mkdirp.mkdirpAsync not mkdirp(..), it will not return a promise\n```\n\n```js\n// winston\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"winston\"));\n```\n\n```js\n// rimraf\nvar Promise = require(\"bluebird\");\n// The module isn't promisified but the function returned is\nvar rimrafAsync = Promise.promisify(require(\"rimraf\"));\n```\n\n```js\n// xml2js\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"xml2js\"));\n```\n\n```js\n// jsdom\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"jsdom\"));\n```\n\n```js\n// fs-extra\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"fs-extra\"));\n```\n\n```js\n// prompt\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"prompt\"));\n```\n\n```js\n// Nodemailer\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"nodemailer\"));\n```\n\n```js\n// ncp\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"ncp\"));\n```\n\n```js\n// pg\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"pg\"));\n```\n\nIn all of the above cases the library made its classes available in one way or another. If this is not the case, you can still promisify by creating a throwaway instance:\n\n```js\nvar ParanoidLib = require(\"...\");\nvar throwAwayInstance = ParanoidLib.createInstance();\nPromise.promisifyAll(Object.getPrototypeOf(throwAwayInstance));\n// Like before, from this point on, all new instances + even the throwAwayInstance suddenly support promises\n```\n\nSee also [`Promise.promisifyAll`](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/props.md",
"content": "---\nlayout: api\nid: props\ntitle: .props\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.props\n\n```js\n.props() -> Promise\n```\n\nSame as [Promise.props(this)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/race.md",
"content": "---\nlayout: api\nid: race\ntitle: .race\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.race\n\n```js\n.race() -> Promise\n```\n\nSame as [Promise.race(this)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/reason.md",
"content": "---\nlayout: api\nid: reason\ntitle: .reason\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.reason\n\n```js\n.reason() -> any\n```\n\n\nGet the rejection reason of this promise. Throws an error if the promise isn't rejected - it is a bug to call this method on an unrejected promise.\n\nYou should check if this promise is [.isRejected()](.) in code paths where it's guaranteed that this promise is rejected.\n\n\n
\n\n\n\n"
},
{
"path": "docs/docs/api/reduce.md",
"content": "---\nlayout: api\nid: reduce\ntitle: .reduce\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.reduce\n\n```js\n.reduce(\n function(any accumulator, any item, int index, int length) reducer,\n [any initialValue]\n) -> Promise\n```\n\nSame as [Promise.reduce(this, reducer, initialValue)](.).\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/reflect.md",
"content": "---\nlayout: api\nid: reflect\ntitle: .reflect\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.reflect\n\n```js\n.reflect() -> Promise\n```\n\n\nThe [`.reflect`](.) method returns a promise that is always successful when this promise is settled. Its fulfillment value is an object that implements the [PromiseInspection](.) interface and reflects the resolution of this promise.\n\nUsing `.reflect()` to implement `settleAll` (wait until all promises in an array are either rejected or fulfilled) functionality\n\n```js\nvar promises = [getPromise(), getPromise(), getPromise()];\nPromise.all(promises.map(function(promise) {\n return promise.reflect();\n})).each(function(inspection) {\n if (inspection.isFulfilled()) {\n console.log(\"A promise in the array was fulfilled with\", inspection.value());\n } else {\n console.error(\"A promise in the array was rejected with\", inspection.reason());\n }\n});\n```\n\nUsing `.reflect()` to implement `settleProps` (like settleAll for an object's properties) functionality\n\n```js\nvar object = {\n first: getPromise1(),\n second: getPromise2()\n};\nPromise.props(Object.keys(object).reduce(function(newObject, key) {\n newObject[key] = object[key].reflect();\n return newObject;\n}, {})).then(function(object) {\n if (object.first.isFulfilled()) {\n console.log(\"first was fulfilled with\", object.first.value());\n } else {\n console.error(\"first was rejected with\", object.first.reason());\n }\n})\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/resource-management.md",
"content": "---\nlayout: api\nid: resource-management\ntitle: Resource management\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Resource management\n\nManaging resources properly without leaks can be challenging. Simply using `.finally` is not enough as the following example demonstrates:\n\n```js\nfunction doStuff() {\n return Promise.all([\n connectionPool.getConnectionAsync(),\n fs.readFileAsync(\"file.sql\", \"utf8\")\n ]).spread(function(connection, fileContents) {\n return connection.query(fileContents).finally(function() {\n connection.close();\n });\n }).then(function() {\n console.log(\"query successful and connection closed\");\n });\n}\n```\n\nIt is very subtle but over time this code will exhaust the entire connection pool and the server needs to be restarted. This is because\nreading the file may fail and then of course `.spread` is not called at all and thus the connection is not closed.\n\nOne could solve this by either reading the file first or connecting first, and only proceeding if the first step succeeds. However,\nthis would lose a lot of the benefits of using asynchronity and we might almost as well go back to using simple synchronous code.\n\nWe can do better, retaining concurrency and not leaking resources, by using:\n\n* [disposers](disposer.html), objects that wrap a resource and a method to release that resource, together with \n* [`Promise.using`](promise.using.html), a function to safely use disposers in a way that automatically calls their release method\n\n```js\nvar using = Promise.using;\n\nusing(getConnection(),\n fs.readFileAsync(\"file.sql\", \"utf8\"), function(connection, fileContents) {\n return connection.query(fileContents);\n}).then(function() {\n console.log(\"query successful and connection closed\");\n});\n```\n\nContinue by reading about [disposers](disposer.html) and [`Promise.using`](promise.using.html)\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/return.md",
"content": "---\nlayout: api\nid: return\ntitle: .return\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.return\n\n```js\n.return(any value) -> Promise\n```\n```js\n.thenReturn(any value) -> Promise\n```\n\nConvenience method for:\n\n```js\n.then(function() {\n return value;\n});\n```\n\nin the case where `value` doesn't change its value because its binding time is different than when using a closure.\n\nThat means `value` is bound at the time of calling [`.return`](.) so this will not work as expected:\n\n```js\nfunction getData() {\n var data;\n\n return query().then(function(result) {\n data = result;\n }).return(data);\n}\n```\n\nbecause `data` is `undefined` at the time `.return` is called.\n\nFunction that returns the full path of the written file:\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require(\"fs\"));\nvar baseDir = process.argv[2] || \".\";\n\nfunction writeFile(path, contents) {\n var fullpath = require(\"path\").join(baseDir, path);\n return fs.writeFileAsync(fullpath, contents).return(fullpath);\n}\n\nwriteFile(\"test.txt\", \"this is text\").then(function(fullPath) {\n console.log(\"Successfully file at: \" + fullPath);\n});\n```\n\n*For compatibility with earlier ECMAScript version, an alias `.thenReturn` is provided for [`.return`](.).*\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/some.md",
"content": "---\nlayout: api\nid: some\ntitle: .some\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.some\n\n```js\n.some(int count) -> Promise\n```\n\nSame as [Promise.some(this, count)](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/spread.md",
"content": "---\nlayout: api\nid: spread\ntitle: .spread\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.spread\n\n```js\n.spread(\n [function(any values...) fulfilledHandler]\n) -> Promise\n```\n\n\nLike calling `.then`, but the fulfillment value _must be_ an array, which is flattened to the formal parameters of the fulfillment handler.\n\n```js\nPromise.all([\n fs.readFileAsync(\"file1.txt\"),\n fs.readFileAsync(\"file2.txt\")\n]).spread(function(file1text, file2text) {\n if (file1text === file2text) {\n console.log(\"files are equal\");\n }\n else {\n console.log(\"files are not equal\");\n }\n});\n```\n\nWhen chaining `.spread`, returning an array of promises also works:\n\n```js\nPromise.delay(500).then(function() {\n return [fs.readFileAsync(\"file1.txt\"),\n fs.readFileAsync(\"file2.txt\")] ;\n}).spread(function(file1text, file2text) {\n if (file1text === file2text) {\n console.log(\"files are equal\");\n }\n else {\n console.log(\"files are not equal\");\n }\n});\n```\n\nNote that if using ES6, the above can be replaced with [.then()](.) and destructuring:\n\n```js\nPromise.delay(500).then(function() {\n return [fs.readFileAsync(\"file1.txt\"),\n fs.readFileAsync(\"file2.txt\")] ;\n}).all().then(function([file1text, file2text]) {\n if (file1text === file2text) {\n console.log(\"files are equal\");\n }\n else {\n console.log(\"files are not equal\");\n }\n});\n```\n\nNote that [.spread()](.) implicitly does [.all()](.) but the ES6 destructuring syntax doesn't, hence the manual `.all()` call in the above code.\n\nIf you want to coordinate several discrete concurrent promises, use [`Promise.join`](.)\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/suppressunhandledrejections.md",
"content": "---\nlayout: api\nid: suppressunhandledrejections\ntitle: .suppressUnhandledRejections\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.suppressUnhandledRejections\n\n```js\n.suppressUnhandledRejections() -> undefined\n```\n\nBasically sugar for doing:\n\n```js\nsomePromise.catch(function(){});\n```\n\nWhich is needed in case error handlers are attached asynchronously to the promise later, which would otherwise result in premature unhandled rejection reporting.\n\nExample:\n\n```js\nvar tweets = fetchTweets();\n$(document).on(\"ready\", function() {\n tweets.then(function() {\n // Render tweets\n }).catch(function(e) {\n alert(\"failed to fetch tweets because: \" + e);\n });\n});\n```\n\nIf fetching tweets fails before the document is ready the rejection is reported as unhandled even though it will be eventually handled when the document is ready. This is of course impossible to determine automatically, but you can explicitly do so using `.suppressUnhandledRejections()`:\n\n```js\nvar tweets = fetchTweets();\ntweets.suppressUnhandledRejections();\n$(document).on(\"ready\", function() {\n tweets.then(function() {\n // Render tweets\n }).catch(function(e) {\n alert(\"failed to fetch tweets because: \" + e);\n });\n});\n```\n\nIt should be noted that there is no real need to attach the handlers asynchronously. Exactly the same effect can be achieved with:\n\n```js\nfetchTweets()\n .finally(function() {\n return $.ready.promise();\n })\n // DOM guaranteed to be ready after this point\n .then(function() {\n // Render tweets\n })\n .catch(function(e) {\n alert(\"failed to fetch tweets because: \" + e);\n });\n```\n\nThe advantage of using `.suppressUnhandledRejections()` over `.catch(function(){})` is that it doesn't increment the branch count of the promise. Branch counts matter when using cancellation because a promise will only be cancelled if all of its branches want to cancel it.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/synchronous-inspection.md",
"content": "---\nlayout: api\nid: synchronous-inspection\ntitle: Synchronous inspection\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Synchronous inspection\n\nOften it is known in certain code paths that a promise is guaranteed to be fulfilled at that point - it would then be extremely inconvenient to use [`.then`](.) to get at the promise's value as the callback is always called asynchronously.\n\n\n**Note**: In recent versions of Bluebird a design choice was made to expose [.reason()](.) and [.value()](.) as well as other inspection methods on promises directly in order to make the below use case easier to work with. Every promise implements the [PromiseInspection](.) interface.\n\nFor example, if you need to use values of earlier promises in the chain, you could nest:\n\n\n```js\n// From Q Docs https://github.com/kriskowal/q/#chaining\n// MIT License Copyright 2009–2014 Kristopher Michael Kowal.\nfunction authenticate() {\n return getUsername().then(function (username) {\n return getUser(username);\n // chained because we will not need the user name in the next event\n }).then(function (user) {\n // nested because we need both user and password next\n return getPassword().then(function (password) {\n if (user.passwordHash !== hash(password)) {\n throw new Error(\"Can't authenticate\");\n }\n });\n });\n}\n```\n\nOr you could take advantage of the fact that if we reach password validation, then the user promise must be fulfilled:\n\n```js\nfunction authenticate() {\n var user = getUsername().then(function(username) {\n return getUser(username);\n });\n\n return user.then(function(user) {\n return getPassword();\n }).then(function(password) {\n // Guaranteed that user promise is fulfilled, so .value() can be called here\n if (user.value().passwordHash !== hash(password)) {\n throw new Error(\"Can't authenticate\");\n }\n });\n}\n```\n\nIn the latter the indentation stays flat no matter how many previous variables you need, whereas with the former each additional previous value would require an additional nesting level.\n
\n\n\n\n"
},
{
"path": "docs/docs/api/tap.md",
"content": "---\nlayout: api\nid: tap\ntitle: .tap\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.tap\n\n```js\n.tap(function(any value) handler) -> Promise\n```\nEssentially like `.then()`, except that the value passed in is the value returned.\n\nThis means you can insert `.tap()` into a `.then()` chain without affecting what is passed through the chain. (See example below).\n\nUnlike [`.finally`](.) this is not called for rejections.\n\n```js\ngetUser().tap(function(user) {\n //Like in finally, if you return a promise from the handler\n //the promise is awaited for before passing the original value through\n return recordStatsAsync();\n}).then(function(user) {\n //user is the user from getUser(), not recordStatsAsync()\n});\n```\n\nCommon case includes adding logging to an existing promise chain:\n\n```js\ndoSomething()\n .then(...)\n .then(...)\n .then(...)\n .then(...)\n```\n\n```js\ndoSomething()\n .then(...)\n .then(...)\n .tap(console.log)\n .then(...)\n .then(...)\n```\n\n*Note: in browsers it is necessary to call `.tap` with `console.log.bind(console)` because console methods can not be called as stand-alone functions.*\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/tapcatch.md",
"content": "---\nlayout: api\nid: tapCatch\ntitle: .tapCatch\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.tapCatch\n\n\n`.tapCatch` is a convenience method for reacting to errors without handling them with promises - similar to `finally` but only called on rejections. Useful for logging errors.\n\nIt comes in two variants.\n- A tapCatch-all variant similar to [`.catch`](.) block. This variant is compatible with native promises.\n- A filtered variant (like other non-JS languages typically have) that lets you only handle specific errors. **This variant is usually preferable**.\n\n\n### `tapCatch` all\n```js\n.tapCatch(function(any value) handler) -> Promise\n```\n\n\nLike [`.finally`](.) that is not called for fulfillments.\n\n```js\ngetUser().tapCatch(function(err) {\n return logErrorToDatabase(err);\n}).then(function(user) {\n //user is the user from getUser(), not logErrorToDatabase()\n});\n```\n\nCommon case includes adding logging to an existing promise chain:\n\n#### Rate Limiting\n\n```js\nPromise.\n try(logIn).\n then(respondWithSuccess).\n tapCatch(countFailuresForRateLimitingPurposes).\n catch(respondWithError);\n```\n\n#### Circuit Breakers\n\n```js\nPromise.\n try(makeRequest).\n then(respondWithSuccess).\n tapCatch(adjustCircuitBreakerState).\n catch(respondWithError);\n```\n\n#### Logging\n\n```js\nPromise.\n try(doAThing).\n tapCatch(logErrorsRelatedToThatThing).\n then(respondWithSuccess).\n catch(respondWithError);\n```\n\n*Note: in browsers it is necessary to call `.tapCatch` with `console.log.bind(console)` because console methods can not be called as stand-alone functions.*\n\n### Filtered `tapCatch`\n\n\n```js\n.tapCatch(\n class ErrorClass|function(any error),\n function(any error) handler\n) -> Promise\n```\n```js\n.tapCatch(\n class ErrorClass|function(any error),\n function(any error) handler\n) -> Promise\n\n\n```\nThis is an extension to [`.tapCatch`](.) to filter exceptions similarly to languages like Java or C#. Instead of manually checking `instanceof` or `.name === \"SomeError\"`, you may specify a number of error constructors which are eligible for this tapCatch handler. The tapCatch handler that is first met that has eligible constructors specified, is the one that will be called.\n\nUsage examples include:\n\n#### Rate Limiting\n\n```js\nPromise.\n try(logIn).\n then(respondWithSuccess).\n tapCatch(InvalidCredentialsError, countFailuresForRateLimitingPurposes).\n catch(respondWithError);\n```\n\n#### Circuit Breakers\n\n```js\nPromise.\n try(makeRequest).\n then(respondWithSuccess).\n tapCatch(RequestError, adjustCircuitBreakerState).\n catch(respondWithError);\n```\n\n#### Logging\n\n```js\nPromise.\n try(doAThing).\n tapCatch(logErrorsRelatedToThatThing).\n then(respondWithSuccess).\n catch(respondWithError);\n```\n\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/then.md",
"content": "---\nlayout: api\nid: then\ntitle: .then\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.then\n\n```js\n.then(\n [function(any value) fulfilledHandler],\n [function(any error) rejectedHandler]\n) -> Promise\n```\n\n\n[Promises/A+ `.then`](http://promises-aplus.github.io/promises-spec/). If you are new to promises, see the [Beginner's Guide]({{ \"/docs/beginners-guide.html\" | prepend: site.baseurl }}).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/throw.md",
"content": "---\nlayout: api\nid: throw\ntitle: .throw\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.throw\n\n```js\n.throw(any reason) -> Promise\n```\n```js\n.thenThrow(any reason) -> Promise\n```\n\n\nConvenience method for:\n\n```js\n.then(function() {\n throw reason;\n});\n```\n\nSame limitations regarding to the binding time of `reason` to apply as with [`.return`](.).\n\n*For compatibility with earlier ECMAScript version, an alias `.thenThrow` is provided for [`.throw`](.).*\n
\n\n\n\n"
},
{
"path": "docs/docs/api/timeout.md",
"content": "---\nlayout: api\nid: timeout\ntitle: .timeout\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.timeout\n\n```js\n.timeout(\n int ms,\n [String message=\"operation timed out\"]\n) -> Promise\n```\n```js\n.timeout(\n int ms,\n [Error error]\n) -> Promise\n```\n\n\nReturns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within `ms` milliseconds, the returned promise is rejected with a [`TimeoutError`](.) or the `error` as the reason.\n\nWhen using the first signature, you may specify a custom error message with the `message` parameter.\n\n\n```js\nvar Promise = require(\"bluebird\");\nvar fs = Promise.promisifyAll(require('fs'));\nfs.readFileAsync(\"huge-file.txt\").timeout(100).then(function(fileContents) {\n\n}).catch(Promise.TimeoutError, function(e) {\n console.log(\"could not read file within 100ms\");\n});\n```\n
\n\n\n\n\n"
},
{
"path": "docs/docs/api/timeouterror.md",
"content": "---\nlayout: api\nid: timeouterror\ntitle: TimeoutError\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##TimeoutError\n\n```js\nnew TimeoutError(String message) -> TimeoutError\n```\n\n\nSignals that an operation has timed out. Used as a custom cancellation reason in [`.timeout`](.).\n
\n\n\n\n"
},
{
"path": "docs/docs/api/timers.md",
"content": "---\nlayout: api\nid: timers\ntitle: Timers\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Timers\n\nMethods to delay and time promises out.\n\n
\n
\n\n\n\n"
},
{
"path": "docs/docs/api/utility.md",
"content": "---\nlayout: api\nid: utility\ntitle: Utility\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##Utility\n\nFunctions that could potentially be handy in some situations.\n\n\n
\n\n\n\n"
},
{
"path": "docs/docs/api/value.md",
"content": "---\nlayout: api\nid: value\ntitle: .value\n---\n\n\n[← Back To API Reference](/docs/api-reference.html)\n
\n##.value\n\n```js\n.value() -> any\n```\n\n\nGet the fulfillment value of this promise. Throws an error if the promise isn't fulfilled - it is a bug to call this method on an unfulfilled promise.\n\nYou should check if this promise is [.isFulfilled()](.) in code paths where it's not guaranteed that this promise is fulfilled.\n
\n"
},
{
"path": "docs/docs/async-dialogs.md",
"content": "---\nid: async-dialogs\ntitle: Async Dialogs\n---\n\n[async-dialogs](unfinished-article)\n\nTypically *promises* are used in conjunction with asynchronous tasks such as a\nnetwork request or a `setTimeout`; a lesser explored use is dealing with user\ninput. Since a program has to wait for a user to continue some actions it makes\nsense to consider it an asynchronous event.\n\nFor comparison I'll start with an example of a *synchronous* user interaction\nusing `window.prompt` and then move to an *asynchronous* interaction by making\nour own DOM based prompt. To begin, here is a template for a simple HTML page:\n\n```html\n\n\n\n \n Async Dislogs Example\n \n \n\n\n
The current time is .
\n
Your name is .
\n \n\n\n```\n\n`window.prompt` blocks the web page from processing while it waits for the user\nto enter in data. It has to block because the input is returned and the next\nline of code needs that result. But for sake of this tutorial we are going to\nconvert the typical conditional code into a promise API using a [promise\nconstructor](api/new-promise.html).\n\n```javascript\nfunction promptPromise(message) {\n return new Promise(function(resolve, reject) {\n var result = window.prompt(message);\n if (result != null) {\n resolve(result);\n } else {\n reject(new Error('User cancelled'));\n }\n });\n}\n\nvar button = document.getElementById('action');\nvar output = document.getElementById('prompt');\n\nbutton.addEventListener('click', function() {\n promptPromise('What is your name?')\n .then(function(name) {\n output.innerHTML = String(name);\n })\n .catch(function() {\n output.innerHTML = '¯\\\\_(ツ)_/¯';\n });\n});\n```\n\n[Run example on JSBin][Example1]\n\nThis doesn't add much much using `window.prompt`; however, one advantage is the\nAPI that promises provide. In the case where we call `promptPromise(…)` we can\neasily react to the result of the dialog without having to worry about how it is\nimplemented. In our example we've implemented the `window.prompt` but our call\nto `promptPromise()` doesn't care. This makes a change to an *asynchronous*\ndialog a little more future proof.\n\nTo drive home the synchronous nature of the `window.prompt` notice that the time\nstops ticking when the prompt dialog is displayed. Let's fix that by making our\nown prompt. Since our dialog is just DOM manipulation the page won't be blocked\nwhile waiting for user input.\n\nFirst add the prompt dialog to the HTML:\n\n```html\n\n
\n
foobar
\n \n
\n \n \n
\n
\n```\n\nWe will want to keep the same API so our change will be only to the\n`promisePrompt`. It will find the dialog DOM elements, attach events to the\nelements, show the dialog box, return a promise that is resolved based on the\nattached events, and finally detaches the events and cleans up after itself\n(hiding the dialog box for another use later).\n\n```javascript\nfunction promptPromise(message) {\n var dialog = document.getElementById('dialog');\n var input = dialog.querySelector('input');\n var okButton = dialog.querySelector('button.ok');\n var cancelButton = dialog.querySelector('button.cancel');\n\n dialog.querySelector('.message').innerHTML = String(message);\n dialog.className = '';\n\n return new Promise(function(resolve, reject) {\n dialog.addEventListener('click', function handleButtonClicks(e) {\n if (e.target.tagName !== 'BUTTON') { return; }\n dialog.removeEventListener('click', handleButtonClicks);\n dialog.className = 'hidden';\n if (e.target === okButton) {\n resolve(input.value);\n } else {\n reject(new Error('User cancelled'));\n }\n });\n });\n}\n```\n\n[Run example on JSBin][Example2]\n\nNow when the user presses the **Set Name** button the clock continues to update\nwhile the dialog is visible.\n\nBecause the `removeEventListener` requires a reference to the original function\nthat was used with the `addEventListener` it makes it difficult to clean up\nafter itself without storing the references in a scope higher then the handler\nitself. Using a named function we can reference it when a user clicks the\nbutton. To help with performance and to avoid duplicating code the example uses\n[event delegation][1] to capture both buttons in one *click* handler.\n\n[1]: https://davidwalsh.name/event-delegate\n\nThe same thing can be done with less code using jQuery's [event\nnamespacing](https://api.jquery.com/on/#event-names).\n\n```javascript\nreturn new Promise(function(resolve, reject) {\n $('#okButton').on('click.promptDialog', function() {\n resolve(input.value);\n });\n $('#cancelButton').on('click.promptDialog', reject);\n})\n.finally(function() {\n $('#okButton').off('click.promptDialog');\n $('#cancelButton').off('click.promptDialog');\n});\n```\n\nThere are still a few problems with the earlier code example. It feels like it\nis doing too much. A *squint* test reveals behavior for showing the dialog, set\nthe dialog's message, attach two DOM events, construct a promise, event\ndelegation, hide the dialog, and finally detach DOM events. That is a lot for\none little function. A refactoring can help.\n\nAbstraction is the key here. We will make an *object* (or class) that is\nresponsible for managing the dialog box. Its interface will manage only two\nfunction references (callbacks): when the user clicks ok and when user clicks\ncancel. And it will offer the value when asked.\n\nUsing an abstraction like this the `promisePrompt` no longer needs to know\nanything about the DOM and concentrates on just providing a promise. This will\nalso make things easier to create a promised version of a progress bar or\nconfirmation dialog or any other type of UI that we want to have a value for.\nAll we will need to do is write a class for that dialog type with the same\ninterface and just pass that class into our promise making method.\n\nThe dialog interface might look like this:\n\n```javascript\nvar noop = function() {\n return this;\n};\n\nfunction Dialog() {\n this.setCallbacks(noop, noop);\n}\nDialog.prototype.setCallbacks = function(okCallback, cancelCallback) {\n this._okCallback = okCallback;\n this._cancelCallback = cancelCallback;\n return this;\n};\nDialog.prototype.waitForUser = function() {\n var _this = this;\n return new Promise(function(resolve, reject) {\n _this.setCallbacks(resolve, reject);\n });\n};\nDialog.prototype.show = noop;\nDialog.prototype.hide = noop;\n```\n\nInitially the Dialog class sets the two callbacks to *noop* functions. It is up\nto the child class to call them when necessary. We break down the promise\ncreation to one function `waitForUser()` that sets the callbacks and returns a\npromise. At this level the `show()` and `hide()` are just *noop* functions as\nwell and will be implemented by the child classes.\n\nOur `PromptDialog` class is responsible for inheriting from `Dialog` and setting\nup the required DOM scaffolding and eventually call `this._okCallback` or\n`this._cancelCallback` as appropriate.\n\nIt might look like this:\n\n```javascript\nfunction PromptDialog() {\n Dialog.call(this);\n this.el = document.getElementById('dialog');\n this.inputEl = this.el.querySelector('input');\n this.messageEl = this.el.querySelector('.message');\n this.okButton = this.el.querySelector('button.ok');\n this.cancelButton = this.el.querySelector('button.cancel');\n this.attachDomEvents();\n}\nPromptDialog.prototype = Object.create(Dialog.prototype);\nPromptDialog.prototype.attachDomEvents = function() {\n var _this = this;\n this.okButton.addEventListener('click', function() {\n _this._okCallback(_this.inputEl.value);\n });\n this.cancelButton.addEventListener('click', function() {\n _this._cancelCallback();\n });\n};\nPromptDialog.prototype.show = function(message) {\n this.messageEl.innerHTML = String(message);\n this.el.className = '';\n return this;\n};\nPromptDialog.prototype.hide = function() {\n this.el.className = 'hidden';\n return this;\n};\n```\n\nNotice that use of `return this;` in most of the functions? That pattern will\nallow method chaining as you'll see shortly.\n\nThis inherits from `Dialog` and stores references to the required DOM elements\nthat this dialog uses. It then attaches the require DOM events\n(`attachDomEvents()`) which eventually call the callbacks. Then it implements\nthe `show()` and `hide()` methods. Its usage is more flexible and verbose:\n\n```javascript\nvar output = document.getElementById('prompt');\nvar prompt = new PromptDialog();\n\nprompt.show('What is your name?')\n .waitForUser()\n .then(function(name) {\n output.innerHTML = String(name);\n })\n .catch(function() {\n output.innerHTML = '¯\\\\_(ツ)_/¯';\n })\n .finally(function() {\n prompt.hide();\n });\n```\n\n[Run example on JSBin][Example3]\n\nThis abstraction can be expanded on in other ways. For example a notification\ndialog:\n\n```javascript\nfunction NotifyDialog() {\n Dialog.call(this);\n var _this = this;\n this.el = document.getElementById('notify-dialog');\n this.messageEl = this.el.querySelector('.message');\n this.okButton = this.el.querySelector('button.ok');\n this.okButton.addEventListener('click', function() {\n _this._okCallback();\n });\n}\nNotifyDialog.prototype = Object.create(Dialog.prototype);\nNotifyDialog.prototype.show = function(message) {\n this.messageEl.innerHTML = String(message);\n this.el.className = '';\n return this;\n};\nNotifyDialog.prototype.show = function() {\n this.el.className = 'hidden';\n return this;\n};\n```\n\n#### Exercises for the student\n\n1. Write a function that takes a `Dialog` instance and a default value. Have it\n return a promise that resolves to the default value if the user clicks\n cancel.\n2. With the use of abstract classes can the similarities between `PromptDialog`\n and `NotifyDialog` be abstracted? Make a sub class of `Dialog` that\n abstracts the common DOM code (`DOMDialog`). Then refactor the\n `PromptDialog` and `NotifyDialog` to inherate from `DOMDialog` but\n references the correct DOM selectors.\n\n## Cancellation\n\nSomething missing from the above example is proper error handling. When it comes\nto promises it is a best practise to always *reject a promise with an Error* and\nnot with plain data such as an object, string, number, or null/undefined. The\nreasoning for this is promises are best used as a way to regain some of the\nsyntax you have with the standard `try {} catch() {}` blocks with asynchronous\ncode.\n\nAn advantage of using `Error`s is the ability to test why a promise was rejected\nand make decisions on that. This ability is also baked into how Bluebird works.\nYou can pass in a predicate to the `catch()` block allowing you to have more\nthan one block based on what `Error` it was rejected with. For example:\n\n```javascript\ndoSomething().then(function(value) {\n // Do something with value or fail with an error.\n throw new Error('testing errors');\n})\n.catch(ArgumentError, function(e) {\n console.log('You buggered up something with the arguments.', e);\n})\n.catch(SyntaxError, function(e) {\n console.log('Check your syntax!', e);\n})\n.catch(function(e) {\n // e is an Error object.\n console.log('Well something genaric happened.', e);\n});\n```\n\nIn our dialog example perhaps we want to differentiate between a rejected\npromise because of some problem (bad AJAX, programming error, etc.) or because\nthe user pressed the cancel button.\n\nTo do this we will have two `catch()` functions one for `UserCanceledError` and\none for any other `Error`. We can make a custom error like so:\n\n```javascript\nfunction UserCanceledError() {\n this.name = 'UserCanceledError';\n this.message = 'Dialog cancelled';\n}\nUserCanceledError.prototype = Object.create(Error.prototype);\n```\n\nSee [this StackOverflow answer](http://stackoverflow.com/a/17891099/227176) for\na more detailed and feature complete way to make custom errors.\n\nNow we can add a `cancel()` reject with this in our event listener:\n\n```javascript\nDialog.prototype.cancel = function() {\n this._cancelCallback(new UserCanceledError());\n};\n\n…\n\nPromptDialog.prototype.attachDomEvents = function() {\n var _this = this;\n this.okButton.addEventListener('click', function() {\n _this._okCallback(_this.inputEl.value);\n });\n this.cancelButton.addEventListener('click', function() {\n _this.cancel();\n });\n};\n```\n\nAnd in our usage case we can test for it:\n\n```javascript\n// Timeout the dialog in five seconds.\nsetTimeout(function() { prompt.cancel(); }, 5000);\n\nprompt.show('What is your name?')\n .waitForUser()\n .then(function(name) {\n output.innerHTML = String(name);\n })\n .catch(UserCanceledError, function() {\n output.innerHTML = '¯\\\\_(ツ)_/¯';\n })\n .catch(function(e) {\n console.log('Something bad happened!', e);\n })\n .finally(function() {\n prompt.hide();\n });\n```\n\n[Run example on JSBin][Example4]\n\n**NOTE:** Bluebird supports [cancellation](api/cancellation.html) as an optional\nfeature that is turned off by default. However, its implementation (since\nversion 3.0) is meant to stop the then and catch callbacks from firing. It is\nnot helpful in the example of a user cancellation as described here.\n\n## Progress bar\n\nWhen there are asynchronous tasks that have the ability to notify progress as\nthey complete it can be tempting to want that in the promise that represents\nthat task. Unfortunately this is a bit of an anti-pattern. That is because the\npoint of promises is to represent a value as if it was natural (like it is in\nnormal synchronous code) and not to be over glorified callback management.\n\nSo how then could we represent a progress bar like dialog? Well the answer is to\nmanage the progress through callbacks outside the promise API. Bluebird has\nsince [deprecated the progression feature](deprecated-apis.html#progression) and\noffers an alternative which I hope to illustrate here.\n\nAnother key difference between a *progress bar* dialog and any other dialog\nwe've discussed here is that a progress bar represents information on another\ntask and *not* user import. Instead of the program waiting for the user to\nprovide a value the dialog box is waiting on the program to provide a value\n(resolved: 100% complete, rejected: aborted half way through). Because of this\nthe *progress bar* dialog would have a different interface then the previous\ndialogs we've covered. However, there can still be some user interaction so in\nessence we are dealing with two promises.\n\nBluebird has a way to manage more than one promise simultaneously. When you want\nto know if more then one promise completes there is a `Promise.all()` function\nthat takes an array of promises and returns a new promise waiting for them all\nto resolve. But if any one is rejected the returned promise is immediately\nrejected.\n\nBluebird also has a `Promise.race()` function which does the same thing but\ndoesn't wait for all of them to finish. That is what we want. An example how\nthis might look:\n\n```javascript\nfunction showProgress(otherPromise) {\n var progress = new ProgressbarDialog().show('Uploading…');\n return Promise.race([otherPromise, promise.waitForUser()])\n .finally(function() {\n progress.hide();\n });\n}\n```\n\nHere is some example HTML for the Progress Dialog:\n\n```html\n\n
\n \n
\n
\n \n
\n
\n```\n\nThe JavaScript is the same as the `PromptDialog` only we will add a\n`setProgress()` method:\n\n```javascript\nfunction ProgressDialog() {\n Dialog.call(this);\n this.el = document.getElementById('progress-dialog');\n this.messageEl = this.el.querySelector('.message');\n this.progressBar = this.el.querySelector('.progress-bar>div');\n this.cancelButton = this.el.querySelector('button.cancel');\n this.attachDomEvents();\n}\nProgressDialog.prototype = Object.create(Dialog.prototype);\nProgressDialog.prototype.attachDomEvents = function() {\n var _this = this;\n this.cancelButton.addEventListener('click', function() {\n _this.cancel();\n });\n\n};\nProgressDialog.prototype.show = function(message) {\n this.messageEl.innerHTML = String(message);\n this.el.className = '';\n return this;\n};\nProgressDialog.prototype.hide = function() {\n this.el.className = 'hidden';\n return this;\n};\nProgressDialog.prototype.setProgress = function(percent) {\n this.progressBar.style.width = percent + '%';\n};\n```\n\nA common misconception is that promises are a form of callback management. This\nis not the case and is why the idea of having a progress callback is not part of\nthe Promise spec. However, much like the Promise library passes in a `resolve`\nand `reject` callback when you create a new promise (`new Promise(…)`) we can do\nthe same patter for a progress callback.\n\nNow to the fun part. For this tutorial we will *fake* a lengthy file upload by\nusing `setTimeout`. The intent is to provide a promise and to allow a progress\nto be periodically ticked away. We will expect a function to be passed which\nis called whenever the progress needs updating. And it returns a promise.\n\n```javascript\nfunction delayedPromise(progressCallback) {\n var step = 10;\n return new Promise(function(resolve, reject) {\n var progress = 0 - step; // So first run of nextTick will set progress to 0\n function nextTick() {\n if (progress >= 100 ) {\n resolve('done');\n } else {\n progress += step;\n progressCallback(progress);\n setTimeout(nextTick, 500);\n }\n }\n nextTick();\n });\n}\n```\n\nWhen we construct our `ProgressDialog` we use the `waitForUser()` method to\ncapture the user interaction promise and then use `delayedPromise()` to capture\nthe fake network promise and finally `Promise.reace()` to manage the two\nsimultaneously and end with a single promise as usual.\n\n```javascript\ndocument.addEventListener('DOMContentLoaded', function() {\n var button = document.getElementById('action');\n var output = document.getElementById('output');\n\n var prompt = new ProgressDialog();\n\n button.addEventListener('click', function() {\n var pendingProgress = true;\n var waitForPromise = delayedPromise(function(progress) {\n if (pendingProgress) {\n prompt.setProgress(progress);\n }\n });\n\n // Prevent user from pressing button while dialog is visible.\n button.disabled = true;\n\n prompt.show('Simulating a file upload.');\n\n Promise.race([waitForPromise, prompt.waitForUser()])\n .then(function() {\n output.innerHTML = 'Progress completed';\n })\n .catch(UserCanceledError, function() {\n output.innerHTML = 'Progress canceled by user';\n })\n .catch(function(e) {\n console.log('Error', e);\n })\n .finally(function() {\n pendingProgress = false;\n button.disabled = false;\n prompt.hide();\n });\n });\n});\n```\n\n[Run example on JSBin][Example5]\n\nI hope this helps illustrate some concepts available with Promises and a\ndifferent perspective on how promises can represent more then just AJAX data.\n\nAlthough the code may look verbose it does provide the benefit that it is\nmodular and can be easily changed. A trait difficult to achieve with a more\nprocedural style.\n\nHappy coding, [@sukima](https://github.com/sukima).\n\n[Example1]: http://jsbin.com/kowama/edit?js,output\n[Example2]: http://jsbin.com/fucofu/edit?js,output\n[Example3]: http://jsbin.com/wupixi/edit?js,output\n[Example4]: http://jsbin.com/yaropo/edit?js,output\n[Example5]: http://jsbin.com/bipeve/edit?js,output\n"
},
{
"path": "docs/docs/beginners-guide.md",
"content": "---\nid: beginners-guide\ntitle: Beginner's Guide\n---\n\n[beginners-guide](unfinished-article)\n"
},
{
"path": "docs/docs/benchmarks.md",
"content": "---\nid: benchmarks\ntitle: Benchmarks\n---\n\nBenchmarks have been ran with the following versions of modules.\n\n```\n├── async@1.5.2\n├── babel@5.8.35\n├── davy@1.1.0\n├── deferred@0.7.5\n├── kew@0.7.0\n├── lie@3.0.2\n├── neo-async@1.7.3\n├── optimist@0.6.1\n├── promise@7.1.1\n├── q@1.4.1\n├── rsvp@3.2.1\n├── streamline@2.0.16\n├── streamline-runtime@1.0.38\n├── text-table@0.2.0\n├── vow@0.4.12\n└── when@3.7.7\n```\n\n###1\\. DoxBee sequential\n\nThis is Gorki Kosev's benchmark used in the article [Analysis of generators and other async patterns in node](http://spion.github.io/posts/analysis-generators-and-other-async-patterns-node.html). The benchmark emulates a situation where N=10000 requests are being made concurrently to execute some mixed async/sync action with fast I/O response times.\n\nThis is a throughput benchmark.\n\nEvery implementation runs in a freshly created isolated process which is warmed up to the benchmark code before timing it. The memory column represents the highest snapshotted RSS memory (as reported by `process.memoryUsage().rss`) during processing.\n\nCommand: `./bench doxbee` (needs cloned repository)\n\nThe implementations for this benchmark are found in [`benchmark/doxbee-sequential`](https://github.com/petkaantonov/bluebird/tree/master/benchmark/doxbee-sequential) directory.\n\n\n```\nresults for 10000 parallel executions, 1 ms per I/O op\n\nfile time(ms) memory(MB)\ncallbacks-baseline.js 116 33.98\ncallbacks-suguru03-neo-async-waterfall.js 145 43.81\npromises-bluebird-generator.js 183 42.35\npromises-bluebird.js 214 43.41\npromises-cujojs-when.js 312 64.37\npromises-then-promise.js 396 74.33\npromises-tildeio-rsvp.js 414 84.80\npromises-native-async-await.js 422 104.23\npromises-ecmascript6-native.js 424 92.12\ngenerators-tj-co.js 444 90.98\npromises-lvivski-davy.js 480 114.46\ncallbacks-caolan-async-waterfall.js 520 109.01\npromises-dfilatov-vow.js 612 134.38\npromises-obvious-kew.js 725 208.63\npromises-calvinmetcalf-lie.js 730 164.96\nstreamline-generators.js 809 154.36\npromises-medikoo-deferred.js 913 178.51\nobservables-pozadi-kefir.js 991 194.00\nstreamline-callbacks.js 1127 196.54\nobservables-Reactive-Extensions-RxJS.js 1906 268.41\nobservables-caolan-highland.js 6887 662.08\npromises-kriskowal-q.js 8533 435.51\nobservables-baconjs-bacon.js.js 21282 882.61\n\nPlatform info:\nLinux 4.4.0-79-generic x64\nNode.JS 8.6.0\nV8 6.0.287.53\nIntel(R) Core(TM) i5-6600K CPU @ 3.50GHz × 4\n\n```\n\n###2\\. Parallel\n\nThis made-up scenario runs 25 shimmed queries in parallel per each request (N=10000) with fast I/O response times.\n\nThis is a throughput benchmark.\n\nEvery implementation runs in a freshly created isolated process which is warmed up to the benchmark code before timing it. The memory column represents the highest snapshotted RSS memory (as reported by `process.memoryUsage().rss`) during processing.\n\nCommand: `./bench parallel` (needs cloned repository)\n\nThe implementations for this benchmark are found in [`benchmark/madeup-parallel`](https://github.com/petkaantonov/bluebird/tree/master/benchmark/madeup-parallel) directory.\n\n```\nresults for 10000 parallel executions, 1 ms per I/O op\n\nfile time(ms) memory(MB)\ncallbacks-baseline.js 274 75.11\ncallbacks-suguru03-neo-async-parallel.js 320 88.84\npromises-bluebird.js 407 107.25\npromises-bluebird-generator.js 432 113.19\ncallbacks-caolan-async-parallel.js 550 154.27\npromises-cujojs-when.js 648 168.65\npromises-ecmascript6-native.js 1145 308.87\npromises-lvivski-davy.js 1153 257.36\npromises-native-async-await.js 1260 323.68\npromises-then-promise.js 1372 313.24\npromises-tildeio-rsvp.js 1435 398.73\npromises-medikoo-deferred.js 1626 306.02\npromises-calvinmetcalf-lie.js 1805 351.21\npromises-dfilatov-vow.js 2492 558.25\npromises-obvious-kew.js 3403 784.61\nstreamline-generators.js 13068 919.24\nstreamline-callbacks.js 25509 1141.57\n\nPlatform info:\nLinux 4.4.0-79-generic x64\nNode.JS 8.6.0\nV8 6.0.287.53\nIntel(R) Core(TM) i5-6600K CPU @ 3.50GHz × 4\n```\n\n###3\\. Latency benchmarks\n\nFor reasonably fast promise implementations latency is going to be fully determined by the scheduler being used and is therefore not interesting to benchmark. [JSPerfs](https://jsperf.com/) that benchmark promises tend to benchmark latency.\n"
},
{
"path": "docs/docs/changelog.md",
"content": "---\nid: changelog\ntitle: Changelog\n---\n\n## 3.7.2 (2019-11-28)\n\nBugfixes:\n\n - Fixes firefox settimeout not initialized error \\([#1623](.)\\)\n\n\n## 3.7.1 (2019-10-15)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - Fix \\([#1614](.)\\)\n - Fix \\([#1613](.)\\)\n - Fix \\([#1616](.)\\)\n\n## 3.7.0 (2019-10-01)\n\nFeatures:\n\n - Add [Promise.allSettled](.) method \\([#1606](.)\\)\n\n## 3.6.0 (2019-10-01)\n\nFeatures:\n\n - Add support for AsyncResource \\([#1403](.)\\)\n\nBugfixes:\n\n - Fix [.reduce](.) generating unhandled rejection events \\([#1501](.)\\)\n - Fix [Promise.reduce](.) generating unhandled rejction events \\([#1502](.)\\)\n - Fix [.map](.) and [.filter](.) generating unhandled rejection events \\([#1487](.)\\)\n - Fix [Promise.map](.) unhandled rejection events \\([#1489](.)\\)\n - Fix cancel skipping upward propagation \\([#1459](.)\\)\n - Fix loadTimes deprecation \\([#1505](.)\\)\n - Fix [Promise.each](.) maximum stack exceeded error \\([#1326](.)\\)\n - Make PromiseRejectionEvent confrom to spec \\([#1509](.)\\)\n - Fix false unhandled rejection events \\([#1468](.)\\)\n\n## 3.5.5 (2019-05-24)\n\nFeatures:\n\n - Added Symbol.toStringTag support to Promise \\([#1421](.)\\)\n\nBugfixes:\n\n - Fix error in IE9 \\([#1591](.), [#1592](.)\\)\n - Fix error with undefined stack trace \\([#1537](.)\\)\n - Fix [.catch](.) throwing an error later rather than immediately when passed non-function handler \\([#1517](.)\\)\n\n## 3.5.4 (2019-04-03)\n\n- Proper version check supporting VSCode\\([#1576](.)\\)\n\n## 3.5.3 (2018-11-06)\n\nBugfixes:\n\n - Update acorn dependency\n\n## 3.5.2 (2018-09-03)\n\nBugfixes:\n\n - Fix `PromiseRejectionEvent` to contain `.reason` and `.promise` properties. \\([#1509](.), [#1464](.)\\)\n - Fix promise chain retaining memory until the entire chain is resolved \\([#1544](.), [#1529](.)\\)\n\n\n## 3.5.1 (2017-10-04)\n\nBugfixes:\n\n - Fix false positive unhandled rejection when using async await \\([#1404](.)\\)\n - Fix false positive when reporting error as non-error \\([#990](.)\\)\n\n## 3.5.0 (2017-03-03)\n\nFeatures:\n\n - Added new method: [.tapCatch](.) \\([#1220](.)\\)\n\nBugfixes:\n\n - Fixed streamline benchmarks \\([#1233](.)\\)\n - Fixed yielding a function calling the function \\([#1314](.), [#1315](.)\\)\n - Fixed confusing error message when calling [.catch](.) with non function predicate \\([#1350](.)\\)\n - Fixed [.props](.) resolving to empty object when called with empty `Map` \\([#1338](.)\\)\n - Fixed confusing error message when invoking `Promise` directly without `new` \\([#1320](.)\\)\n - Added dedicated webpack entry point \\([#1318](.)\\)\n\n## 3.4.7 (2016-12-22)\n\n- Promise config returns reference to Bluebird library\n- Updated logo\n- Benchmark fix\n- Don't drop syntaxerror context from stack traces\n- Fix environment variables sometimes causing long stack traces to be enabled\n\n## 3.4.6 (2016-09-01)\n\nBugfixes:\n\n- Fix [Promise.map](.) and [.map](.) not always calling the callback asynchronously \\([#1148](.)\\)\n\n## 3.4.5 (2016-08-31)\n\nBugfixes:\n\n - Fix unhandled error regression introduced in 3.4.3 [#1217](.)\n\n## 3.4.4 (2016-08-30)\n\nBugfixes:\n\n - Fix benchmark parallel in node 6 [#1165](.)\n - Fix memory leak with Promise.each [#1057](.)\n - Fix thenable passed to .return being evaluated too early [#1210](.)\n - Fix \"unhandledrejection\" event not having .detail field when using DOM3 event listener api [#1209](.)\n - Fix [Promise.join](.) not ensuring asynchronous callback [#1153](.)\n - Fix domains leaking when synchronous error is thrown while a domain is active [#1125](.)\n\n\n\n## 3.4.3 (2016-08-25)\n\nBugfixes:\n\n - The \"a promise was created in a handler but not returned from it\" warning now highlights the file, line and column where the return statement is missing.\n - The \"a promise was created in a handler but not returned from it\" warning now adds the bluebird API method used to create the non-returned promise at the top of the warning stack\n\n## 3.4.2 (2016-08-24)\n\n\nBugfixes:\n\n - Add missing link to unhandled warning docs \\([#1205](.)\\)\n - Fix [Promise.delay](.) not having a long stack trace \\([#1182](.)\\)\n - Fix false unhandled rejection when a rejected promise originating from one copy of bluebird is passed to another copy's [.return](.) or [.catchReturn](.) \\([#1186](.)\\)\n - Fix Promise.resolve is not a function error \\([#1192](.)\\)\n - Fix global events not being fired through DOM 3 API inside a worker \\([#1190](.)\\)\n - Fix .cancel() not immediately marking a promise as being cancelled if it has cancellable parent \\([#1187](.)\\)\n - Fix maximum callstack exceeded with [Promise.coroutine](.) \\([#1170](.)\\)\n\n## 3.4.1 (2016-06-17)\n\nFeatures:\n\n - Added [Promise.getNewLibraryCopy](.)\n\n## 3.4.0 (2016-05-17)\n\nFeatures:\n\n - Add `Promise.version` which tells the bluebird version as a string e.g. `\"3.4.0\"` ([#1042](.)).\n - [.map](.), [Promise.map](.), [.filter](.) and [Promise.filter](.) now return rejected promise when inappropriate options argument is passed ([#1097](.)).\n\nBugfixes:\n\n- Fix bug where callback to [.disposer](.) is not called if the resource is `null` ([#1099](.)).\n- Fix bug where assimilating thenable throws unexpectedly when using hostile host objects as thenables ([#1104](.)).\n\n## 3.3.5 (2016-04-12)\n\nBugfixes:\n\n - Fix then sometimes not being called on iOS/Firefox ([#1022](.)).\n - Fix custom schedulers not being called when using promisified functions ([#1023](.)).\n - Fix unexpected error being thrown when promisifed function is called with no arguments ([#1063](.)).\n\n## 3.3.4 (2016-03-07)\n\nFeatures:\n\n - Warnings about created promises that are not returned are no longer given if the handler promise has not been chained. This should reduce the amount of false positives with this warning.\n\n## 3.3.3 (2016-02-25)\n\nBugfixes:\n\n - Fix stack overflow error when a promise returned by promisified function rejects early in a huge array when using [Promise.mapSeries](.) or [Promise.each](.)\n\n\n## 3.3.2 (2016-02-25)\n\nBugfixes:\n\n - Fix missing newline in stack trace reported by [.done()](.) ([#1020](.)).\n - Detect deep circular resolutions\n\n## 3.3.1 (2016-02-13)\n\nBugfixes:\n\n - Fix crash when cancelling a [.tap()](.) handler promise ([#1006](.)).\n\n## 3.3.0 (2016-02-12)\n\nFeatures:\n\n - Cancelling Promise returned from [Promise.delay()](.) and [.delay()](.) now calls `clearTimeout` ([#1000](.))\n - Add [monitoring and lifecycle hooks](http://bluebirdjs.com/docs/features.html#promise-monitoring)\n - Add `'warning'` hook for warnings ([#980](.))\n\nBugfixes:\n\n - Fix warnings for \"promise was rejected with non-error\" being output when promises are rejected with errors from different realm ([#990](.))\n\n\n## 3.2.2 (2016-02-05)\n\nBugfixes:\n\n - Make build script's output work without TTY\n\n## 3.2.1 (2016-02-01)\n\nBugfixes:\n\n - Revert monitoring feature due to crash in browser\n\n\n## 3.2.0 (2016-02-01)\n\n- Broken build\n\n## 3.1.5 (2016-01-26)\n\nDummy release to trigger CDN update.\n\n## 3.1.4 (2016-01-25)\n\nBugfixes:\n\n - Fix broken npm prepublish script release\n\n\n## 3.1.3 (2016-01-25)\n\nBugfixes:\n\n - Fix generators crashing in node 0.12 ([#978](.))\n - Add minimal build files to build ([#976](.), [#757](.))\n\n## 3.1.2 (2016-01-23)\n\nFeatures:\n\n - [.timeout()](.) now `clearTimeout`s the timer if the resulting promise is cancelled ([#926](.))\n - [Promise.coroutine](.) now returns function with same `.length` as the original function ([#927](.), [#933](.))\n\nBugfixes:\n\n - Fix long stack traces not working when promise is created from [Promise.fromCallback](.) ([#971](.))\n - Fix [.finally()](.) handlers not being called when promise is cancelled while a domain is active ([#963](.))\n - Fix [.timeout()](.) trying to cancel a promise even if cancellation is disabled ([#970](.))\n\n## 3.1.1 (2015-12-16)\n\nBugfixes:\n\n - Disable wForgottenWarning when all warnings are disabled\n\n\n## 3.1.0 (2015-12-16)\n\nFeatures:\n\n - Added ability to configure the [forgotten return statement](http://bluebirdjs.com/docs/warning-explanations.html#warning-a-promise-was-created-in-a-handler-but-none-were-returned-from-it) warning separately \\([#920](.)\\).\n\nBugfixes:\n\n- Fixed the bug where returning a value from [.finally](.) or [.tap](.) handler did not make a warning about a forgotten return go away \\([#846](.)\\).\n- Fixed the bug where setTimeout is used in Chrome instead of MutationObserver \\([#915](.)\\)\n- Fixed the bug where using [.bind](.) suppressed unhandled rejections \\([#841](.)\\)\n\n## 3.0.6 (2015-12-01)\n\nBugfixes:\n\n - Fix [.timeout()](.) not cancelling parent \\([#891](.)\\)\n - Fix long stack traces when using [Promise.resolve()](.) \\([#861](.)\\)\n - Fix [Promise.config()](.) not disabling long stack traces when passing `longStackTraces: false` \\([#897](.)\\)\n\n## 3.0.5 (2015-11-01)\n\nBugfixes:\n\n - Added [forgotten return warnings](http://bluebirdjs.com/docs/warning-explanations.html#warning-a-promise-was-created-in-a-handler-but-none-were-returned-from-it) to [Promise.try](.) and [Promise.method](.)\n\n## 3.0.4 (2015-11-01)\n\nBugfixes:\n\n - The stack trace for [forgotten return warnings](http://bluebirdjs.com/docs/warning-explanations.html#warning-a-promise-was-created-in-a-handler-but-none-were-returned-from-it) is more useful now.\n\n\n## 3.0.3 (2015-11-01)\n\nBugfixes:\n\n - 3rd party libraries rejecting promises with non-errors no longer causes warnings\n - When `NODE_ENV` environment variable is `\"development\"` setting `BLUEBIRD_DEBUG` environment variable to `0` can now be used to disable debug mode\n\n## 3.0.2 (2015-10-29)\n\nBugfixes:\n\n - Fix crash when using node.js domains [#829](.)\n\n## 3.0.1 (2015-10-28)\n\nSee [New in 3.0](new-in-bluebird-3.html).\n\n## 3.0.0 (2015-10-27)\n\nSee [New in 3.0](new-in-bluebird-3.html).\n\n## 2.11.0 (2016-08-30)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 2.10.2 (2015-10-01)\n\nFeatures:\n\n - [.timeout()](.) now takes a custom error object as second argument\n\n## 2.10.1 (2015-09-21)\n\n - Fix error \"Cannot promisify an API that has normal methods with 'Async'-suffix\" when promisifying certain objects with a custom promisifier\n\n## 2.10.0 (2015-09-08)\n\nFeatures:\n\n - `Promise.using` can now take the promises-for-resources as an array ([#733](.)).\n - Browser builds for minimal core are now hosted on CDN ([#724](.)).\n\nBugfixes:\n\n - Disabling debug mode with `BLUEBIRD_DEBUG=0` environment variable now works ([#719](.)).\n - Fix unhandled rejection reporting when passing rejected promise to `.return()` ([#721](.)).\n - Fix unbound promise's then handlers being called with wrong `this` value ([#738](.)).\n\n## 2.9.34 (2015-07-15)\n\nBugfixes:\n\n- Correct domain for .map, .each, .filter, .reduce callbacks ([#701](.)).\n - Preserve bound-with-promise promises across the entire chain ([#702](.)).\n\n## 2.9.33 (2015-07-09)\n\nBugfixes:\n\n - Methods on `Function.prototype` are no longer promisified ([#680](.)).\n\n## 2.9.32 (2015-07-03)\n\nBugfixes:\n\n - Fix `.return(primitiveValue)` returning a wrapped version of the primitive value when a Node.js domain is active ([#689](.)).\n\n## 2.9.31 (2015-07-03)\n\nBugfixes:\n\n - Fix Promises/A+ compliance issue regarding circular thenables: the correct behavior is to go into an infinite loop instead of warning with an error (Fixes [#682](.)).\n - Fix \"(node) warning: possible EventEmitter memory leak detected\" ([#661](.)).\n - Fix callbacks sometimes being called with a wrong node.js domain ([#664](.)).\n - Fix callbacks sometimes not being called at all in iOS 8.1 WebApp mode ([#666](.), [#687](.)).\n\n## 2.9.30 (2015-06-14)\n\nBugfixes:\n\n - Fix regression with `promisifyAll` not promisifying certain methods\n\n## 2.9.29 (2015-06-14)\n\nBugfixes:\n\n - Improve `promisifyAll` detection of functions that are class constructors. Fixes mongodb 2.x promisification.\n\n## 2.9.28 (2015-06-14)\n\nBugfixes:\n\n - Fix handled rejection being reported as unhandled in certain scenarios when using [.all](.) or [Promise.join](.) ([#645](.))\n - Fix custom scheduler not being called in Google Chrome when long stack traces are enabled ([#650](.))\n\n## 2.9.27 (2015-05-30)\n\nBugfixes:\n\n - Fix `sinon.useFakeTimers()` breaking scheduler ([#631](.))\n\nMisc:\n\n - Add nw testing facilities (`node tools/test --nw`)\n\n## 2.9.26 (2015-05-25)\n\nBugfixes:\n\n - Fix crash in NW [#624](.)\n - Fix [`.return()`](.) not supporting `undefined` as return value [#627](.)\n\n## 2.9.25 (2015-04-28)\n\nBugfixes:\n\n - Fix crash in node 0.8\n\n## 2.9.24 (2015-04-02)\n\nBugfixes:\n\n - Fix not being able to load multiple bluebird copies introduced in 2.9.22 ([#559](.), [#561](.), [#560](.)).\n\n## 2.9.23 (2015-04-02)\n\nBugfixes:\n\n - Fix node.js domain propagation ([#521](.)).\n\n## 2.9.22 (2015-04-02)\n\n - Fix `.promisify` crashing in phantom JS ([#556](.))\n\n## 2.9.21 (2015-03-30)\n\n - Fix error object's `'stack'`' overwriting causing an error when its defined to be a setter that throws an error ([#552](.)).\n\n## 2.9.20 (2015-03-29)\n\nBugfixes:\n\n - Fix regression where there is a long delay between calling `.cancel()` and promise actually getting cancelled in Chrome when long stack traces are enabled\n\n## 2.9.19 (2015-03-29)\n\nBugfixes:\n\n - Fix crashing in Chrome when long stack traces are disabled\n\n## 2.9.18 (2015-03-29)\n\nBugfixes:\n\n - Fix settlePromises using trampoline\n\n## 2.9.17 (2015-03-29)\n\n\nBugfixes:\n\n - Fix Chrome DevTools async stack traceability ([#542](.)).\n\n## 2.9.16 (2015-03-28)\n\nFeatures:\n\n - Use setImmediate if available\n\n## 2.9.15 (2015-03-26)\n\nFeatures:\n\n - Added `.asCallback` alias for `.nodeify`.\n\nBugfixes:\n\n - Don't always use nextTick, but try to pick up setImmediate or setTimeout in NW. Fixes [#534](.), [#525](.)\n - Make progress a core feature. Fixes [#535](.) Note that progress has been removed in 3.x - this is only a fix necessary for 2.x custom builds.\n\n## 2.9.14 (2015-03-12)\n\nBugfixes:\n\n - Always use process.nextTick. Fixes [#525](.)\n\n## 2.9.13 (2015-02-27)\n\nBugfixes:\n\n - Fix .each, .filter, .reduce and .map callbacks being called synchornously if the input is immediate. ([#513](.))\n\n## 2.9.12 (2015-02-19)\n\nBugfixes:\n\n - Fix memory leak introduced in 2.9.0 ([#502](.))\n\n## 2.9.11 (2015-02-19)\n\nBugfixes:\n\n - Fix [#503](.)\n\n## 2.9.10 (2015-02-18)\n\nBugfixes:\n\n - Fix [#501](.)\n\n## 2.9.9 (2015-02-12)\n\nBugfixes:\n\n - Fix `TypeError: Cannot assign to read only property 'length'` when jsdom has declared a read-only length for all objects to inherit.\n\n## 2.9.8 (2015-02-10)\n\nBugfixes:\n\n - Fix regression introduced in 2.9.7 where promisify didn't properly dynamically look up methods on `this`\n\n## 2.9.7 (2015-02-08)\n\nBugfixes:\n\n - Fix `promisify` not retaining custom properties of the function. This enables promisifying the `\"request\"` module's export function and its methods at the same time.\n - Fix `promisifyAll` methods being dependent on `this` when they are not originally dependent on `this`. This enables e.g. passing promisified `fs` functions directly as callbacks without having to bind them to `fs`.\n - Fix `process.nextTick` being used over `setImmediate` in node.\n\n## 2.9.6 (2015-02-02)\n\nBugfixes:\n\n - Node environment detection can no longer be fooled\n\n## 2.9.5 (2015-02-02)\n\nMisc:\n\n - Warn when [`.then()`](.) is passed non-functions\n\n## 2.9.4 (2015-01-30)\n\nBugfixes:\n\n - Fix [.timeout()](.) not calling `clearTimeout` with the proper handle in node causing the process to wait for unneeded timeout. This was a regression introduced in 2.9.1.\n\n## 2.9.3 (2015-01-27)\n\nBugfixes:\n\n - Fix node-webkit compatibility issue ([#467](https://github.com/petkaantonov/bluebird/pull/467))\n - Fix long stack trace support in recent firefox versions\n\n## 2.9.2 (2015-01-26)\n\nBugfixes:\n\n - Fix critical bug regarding to using promisifyAll in browser that was introduced in 2.9.0 ([#466](https://github.com/petkaantonov/bluebird/issues/466)).\n\nMisc:\n\n - Add `\"browser\"` entry point to package.json\n\n## 2.9.1 (2015-01-24)\n\nFeatures:\n\n - If a bound promise is returned by the callback to [`Promise.method`](.) and [`Promise.try`](.), the returned promise will be bound to the same value\n\n## 2.9.0 (2015-01-24)\n\nFeatures:\n\n - Add [`Promise.fromNode`](.)\n - Add new paramter `value` for [`Promise.bind`](.)\n\nBugfixes:\n\n - Fix several issues with [`cancellation`](.) and [`.bind()`](.) interoperation when `thisArg` is a promise or thenable\n - Fix promises created in [`disposers`](.) not having proper long stack trace context\n - Fix [`Promise.join`](.) sometimes passing the passed in callback function as the last argument to itself.\n\nMisc:\n\n - Reduce minified full browser build file size by not including unused code generation functionality.\n - Major internal refactoring related to testing code and source code file layout\n\n## 2.8.2 (2015-01-20)\n\nFeatures:\n\n - [Global rejection events](https://github.com/petkaantonov/bluebird/blob/master/API.md#global-rejection-events) are now fired both as DOM3 events and as legacy events in browsers\n\n## 2.8.1 (2015-01-20)\n\nBugfixes:\n\n - Fix long stack trace stiching consistency when rejected from thenables\n\n## 2.8.0 (2015-01-19)\n\nFeatures:\n\n - Major debuggability improvements:\n - Long stack traces have been re-designed. They are now much more readable,\n succint, relevant and consistent across bluebird features.\n - Long stack traces are supported now in IE10+\n\n## 2.7.1 (2015-01-15)\n\nBugfixes:\n\n - Fix [#447](.)\n\n## 2.7.0 (2015-01-15)\n\nFeatures:\n\n - Added more context to stack traces originating from coroutines ([#421](https://github.com/petkaantonov/bluebird/issues/421))\n - Implemented [global rejection events](https://github.com/petkaantonov/bluebird/blob/master/API.md#global-rejection-events) ([#428](https://github.com/petkaantonov/bluebird/issues/428), [#357](https://github.com/petkaantonov/bluebird/issues/357))\n - [Custom promisifiers](https://github.com/petkaantonov/bluebird/blob/master/API.md#option-promisifier) are now passed the default promisifier which can be used to add enhancements on top of normal node promisification\n - [Promisification filters](https://github.com/petkaantonov/bluebird/blob/master/API.md#option-filter) are now passed `passesDefaultFilter` boolean\n\nBugfixes:\n\n - Fix `.noConflict()` call signature ([#446]())\n - Fix `Promise.method`ified functions being called with `undefined` when they were called with no arguments\n\n## 2.6.4 (2015-01-12)\n\nBugfixes:\n\n - `OperationalErrors` thrown by promisified functions retain custom properties, such as `.code` and `.path`.\n\n## 2.6.3 (2015-01-12)\n\nBugfixes:\n\n - Fix [#429](https://github.com/petkaantonov/bluebird/issues/429)\n - Fix [#432](https://github.com/petkaantonov/bluebird/issues/432)\n - Fix [#433](https://github.com/petkaantonov/bluebird/issues/433)\n\n## 2.6.2 (2015-01-07)\n\nBugfixes:\n\n - Fix [#426](https://github.com/petkaantonov/bluebird/issues/426)\n\n## 2.6.1 (2015-01-07)\n\nBugfixes:\n\n - Fixed built browser files not being included in the git tag release for bower\n\n## 2.6.0 (2015-01-06)\n\nFeatures:\n\n - Significantly improve parallel promise performance and memory usage (+50% faster, -50% less memory)\n\n\n## 2.5.3 (2014-12-30)\n\n## 2.5.2 (2014-12-29)\n\nBugfixes:\n\n - Fix bug where already resolved promise gets attached more handlers while calling its handlers resulting in some handlers not being called\n - Fix bug where then handlers are not called in the same order as they would run if Promises/A+ 2.3.2 was implemented as adoption\n - Fix bug where using `Object.create(null)` as a rejection reason would crash bluebird\n\n## 2.5.1 (2014-12-29)\n\nBugfixes:\n\n - Fix `.finally` throwing null error when it is derived from a promise that is resolved with a promise that is resolved with a promise\n\n## 2.5.0 (2014-12-28)\n\nFeatures:\n\n - [`.get`](.) now supports negative indexing.\n\nBugfixes:\n\n - Fix bug with `Promise.method` wrapped function returning a promise that never resolves if the function returns a promise that is resolved with another promise\n - Fix bug with `Promise.delay` never resolving if the value is a promise that is resolved with another promise\n\n## 2.4.3 (2014-12-28)\n\nBugfixes:\n\n - Fix memory leak as described in [this Promises/A+ spec issue](https://github.com/promises-aplus/promises-spec/issues/179).\n\n## 2.4.2 (2014-12-21)\n\nBugfixes:\n\n - Fix bug where spread rejected handler is ignored in case of rejection\n - Fix synchronous scheduler passed to `setScheduler` causing infinite loop\n\n## 2.4.1 (2014-12-20)\n\nFeatures:\n\n - Error messages now have links to wiki pages for additional information\n - Promises now clean up all references (to handlers, child promises etc) as soon as possible.\n\n## 2.4.0 (2014-12-18)\n\nFeatures:\n\n - Better filtering of bluebird internal calls in long stack traces, especially when using minified file in browsers\n - Small performance improvements for all collection methods\n - Promises now delete references to handlers attached to them as soon as possible\n - Additional stack traces are now output on stderr/`console.warn` for errors that are thrown in the process/window from rejected `.done()` promises. See [#411](https://github.com/petkaantonov/bluebird/issues/411)\n\n## 2.3.11 (2014-10-31)\n\nBugfixes:\n\n - Fix [#371](https://github.com/petkaantonov/bluebird/issues/371), [#373](https://github.com/petkaantonov/bluebird/issues/373)\n\n\n## 2.3.10 (2014-10-28)\n\nFeatures:\n\n - `Promise.method` no longer wraps primitive errors\n - `Promise.try` no longer wraps primitive errors\n\n## 2.3.7 (2014-10-25)\n\nBugfixes:\n\n - Fix [#359](https://github.com/petkaantonov/bluebird/issues/359), [#362](https://github.com/petkaantonov/bluebird/issues/362) and [#364](https://github.com/petkaantonov/bluebird/issues/364)\n\n## 2.3.6 (2014-10-15)\n\nFeatures:\n\n - Implement [`.reflect()`](.)\n\n## 2.3.5 (2014-10-06)\n\nBugfixes:\n\n - Fix issue when promisifying methods whose names contain the string 'args'\n\n## 2.3.4 (2014-09-27)\n\n - `P` alias was not declared inside WebWorkers\n\n## 2.3.3 (2014-09-27)\n\nBugfixes:\n\n - Fix [#318](https://github.com/petkaantonov/bluebird/issues/318), [#314](https://github.com/petkaantonov/bluebird/issues/#314)\n\n## 2.3.2 (2014-08-25)\n\nBugfixes:\n\n - `P` alias for `Promise` now exists in global scope when using browser builds without a module loader, fixing an issue with firefox extensions\n\n## 2.3.1 (2014-08-23)\n\nFeatures:\n\n - `.using` can now be used with disposers created from different bluebird copy\n\n## 2.3.0 (2014-08-13)\n\nFeatures:\n\n - [`.bind()`](.) and [`Promise.bind()`](.) now await for the resolution of the `thisArg` if it's a promise or a thenable\n\nBugfixes:\n\n - Fix [#276](https://github.com/petkaantonov/bluebird/issues/276)\n\n## 2.2.2 (2014-07-14)\n\n - Fix [#259](https://github.com/petkaantonov/bluebird/issues/259)\n\n## 2.2.1 (2014-07-07)\n\n - Fix multiline error messages only showing the first line\n\n## 2.2.0 (2014-07-07)\n\nBugfixes:\n\n - `.any` and `.some` now consistently reject with RangeError when input array contains too few promises\n - Fix iteration bug with `.reduce` when input array contains already fulfilled promises\n\n## 2.1.3 (2014-06-18)\n\nBugfixes:\n\n - Fix [#235](https://github.com/petkaantonov/bluebird/issues/235)\n\n## 2.1.2 (2014-06-15)\n\nBugfixes:\n\n - Fix [#232](https://github.com/petkaantonov/bluebird/issues/232)\n\n## 2.1.1 (2014-06-11)\n\n## 2.1.0 (2014-06-11)\n\nFeatures:\n\n - Add [`promisifier`](.) option to `Promise.promisifyAll()`\n - Improve performance of `.props()` and collection methods when used with immediate values\n\n\nBugfixes:\n\n - Fix a bug where .reduce calls the callback for an already visited item\n - Fix a bug where stack trace limit is calculated to be too small, which resulted in too short stack traces\n\nAdd undocumented experimental `yieldHandler` option to `Promise.coroutine`\n\n## 2.0.7 (2014-06-08)\n## 2.0.6 (2014-06-07)\n## 2.0.5 (2014-06-05)\n## 2.0.4 (2014-06-05)\n## 2.0.3 (2014-06-05)\n## 2.0.2 (2014-06-04)\n## 2.0.1 (2014-06-04)\n\n## 2.0.0 (2014-06-04)\n\n#What's new in 2.0\n\n- [Resource management](api-reference.html#resource-management) - never leak resources again\n- [Promisification](api-reference.html#promisification) on steroids - entire modules can now be promisified with one line of code\n- [`.map()`](.), [`.each()`](.), [`.filter()`](.), [`.reduce()`](.) reimagined from simple sugar to powerful concurrency coordination tools\n- [API Documentation](api-reference.html) has been reorganized and more elaborate examples added\n- Deprecated [progression](#progression-migration) and [deferreds](#deferred-migration)\n- Improved performance and readability\n\nFeatures:\n\n- Added [`using()`](.) and [`disposer()`](.)\n- [`.map()`](.) now calls the handler as soon as items in the input array become fulfilled\n- Added a concurrency option to [`.map()`](.)\n- [`.filter()`](.) now calls the handler as soon as items in the input array become fulfilled\n- Added a concurrency option to [`.filter()`](.)\n- [`.reduce()`](.) now calls the handler as soon as items in the input array become fulfilled, but in-order\n- Added [`.each()`](.)\n- [`Promise.resolve()`](.) behaves like `Promise.cast`. `Promise.cast` deprecated.\n- [Synchronous inspection](api-reference.html#synchronous-inspection): Removed `.inspect()`, added [`.value()`](.) and [`.reason()`](.)\n- [`Promise.join()`](.) now takes a function as the last argument\n- Added [`Promise.setScheduler()`](.)\n- [`.cancel()`](.) supports a custom cancellation reason\n- [`.timeout()`](.) now cancels the promise instead of rejecting it\n- [`.nodeify()`](.) now supports passing multiple success results when mapping promises to nodebacks\n- Added `suffix` and `filter` options to [`Promise.promisifyAll()`](.)\n\nBreaking changes:\n\n- Sparse array holes are not skipped by collection methods but treated as existing elements with `undefined` value\n- `.map()` and `.filter()` do not call the given mapper or filterer function in any specific order\n- Removed the `.inspect()` method\n- Yielding an array from a coroutine is not supported by default. You can use [`coroutine.addYieldHandler()`](.) to configure the old behavior (or any behavior you want).\n- [`.any()`](.) and [`.some()`](.) no longer use an array as the rejection reason. [`AggregateError`](.) is used instead.\n\n\n## 1.2.4 (2014-04-27)\n\nBugfixes:\n\n - Fix promisifyAll causing a syntax error when a method name is not a valid identifier\n - Fix syntax error when es5.js is used in strict mode\n\n## 1.2.3 (2014-04-17)\n\nBugfixes:\n\n - Fix [#179](https://github.com/petkaantonov/bluebird/issues/179)\n\n## 1.2.2 (2014-04-09)\n\nBugfixes:\n\n - Promisified methods from promisifyAll no longer call the original method when it is overriden\n - Nodeify doesn't pass second argument to the callback if the promise is fulfilled with `undefined`\n\n## 1.2.1 (2014-03-31)\n\nBugfixes:\n\n - Fix [#168](https://github.com/petkaantonov/bluebird/issues/168)\n\n## 1.2.0 (2014-03-29)\n\nFeatures:\n\n - New method: [`.value()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#value---dynamic)\n - New method: [`.reason()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#reason---dynamic)\n - New method: [`Promise.onUnhandledRejectionHandled()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#promiseonunhandledrejectionhandledfunction-handler---undefined)\n - `Promise.map()`, `.map()`, `Promise.filter()` and `.filter()` start calling their callbacks as soon as possible while retaining a correct order. See [`8085922f`](https://github.com/petkaantonov/bluebird/commit/8085922fb95a9987fda0cf2337598ab4a98dc315).\n\nBugfixes:\n\n - Fix [#165](https://github.com/petkaantonov/bluebird/issues/165)\n - Fix [#166](https://github.com/petkaantonov/bluebird/issues/166)\n\n## 1.1.1 (2014-03-18)\n\nBugfixes:\n\n - [#138](https://github.com/petkaantonov/bluebird/issues/138)\n - [#144](https://github.com/petkaantonov/bluebird/issues/144)\n - [#148](https://github.com/petkaantonov/bluebird/issues/148)\n - [#151](https://github.com/petkaantonov/bluebird/issues/151)\n\n## 1.1.0 (2014-03-08)\n\nFeatures:\n\n - Implement [`Promise.prototype.tap()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#tapfunction-handler---promise)\n - Implement [`Promise.coroutine.addYieldHandler()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#promisecoroutineaddyieldhandlerfunction-handler---void)\n - Deprecate `Promise.prototype.spawn`\n\nBugfixes:\n\n - Fix already rejected promises being reported as unhandled when handled through collection methods\n - Fix browserisfy crashing from checking `process.version.indexOf`\n\n## 1.0.8 (2014-03-03)\n\nBugfixes:\n\n - Fix active domain being lost across asynchronous boundaries in Node.JS 10.xx\n\n## 1.0.7 (2014-02-25)\n\nBugfixes:\n\n - Fix handled errors being reported\n\n## 1.0.6 (2014-02-17)\n\nBugfixes:\n\n - Fix bug with unhandled rejections not being reported\n when using `Promise.try` or `Promise.method` without\n attaching further handlers\n\n## 1.0.5 (2014-02-15)\n\nFeatures:\n\n - Node.js performance: promisified functions try to check amount of passed arguments in most optimal order\n - Node.js promisified functions will have same `.length` as the original function minus one (for the callback parameter)\n\n## 1.0.4 (2014-02-09)\n\nFeatures:\n\n - Possibly unhandled rejection handler will always get a stack trace, even if the rejection or thrown error was not an error\n - Unhandled rejections are tracked per promise, not per error. So if you create multiple branches from a single ancestor and that ancestor gets rejected, each branch with no error handler with the end will cause a possibly unhandled rejection handler invocation\n\nBugfixes:\n\n - Fix unhandled non-writable objects or primitives not reported by possibly unhandled rejection handler\n\n## 1.0.3 (2014-02-05)\n\nBugfixes:\n\n - [#93](https://github.com/petkaantonov/bluebird/issues/88)\n\n## 1.0.2 (2014-02-04)\n\nFeatures:\n\n - Significantly improve performance of foreign bluebird thenables\n\nBugfixes:\n\n - [#88](https://github.com/petkaantonov/bluebird/issues/88)\n\n## 1.0.1 (2014-01-28)\n\nFeatures:\n\n - Error objects that have property `.isAsync = true` will now be caught by `.error()`\n\nBugfixes:\n\n - Fix TypeError and RangeError shims not working without `new` operator\n\n## 1.0.0 (2014-01-12)\n\nFeatures:\n\n - `.filter`, `.map`, and `.reduce` no longer skip sparse array holes. This is a backwards incompatible change.\n - Like `.map` and `.filter`, `.reduce` now allows returning promises and thenables from the iteration function.\n\nBugfixes:\n\n - [#58](https://github.com/petkaantonov/bluebird/issues/58)\n - [#61](https://github.com/petkaantonov/bluebird/issues/61)\n - [#64](https://github.com/petkaantonov/bluebird/issues/64)\n - [#60](https://github.com/petkaantonov/bluebird/issues/60)\n\n## 0.11.6-1 (2013-12-29)\n\n## 0.11.6-0 (2013-12-29)\n\nFeatures:\n\n - You may now return promises and thenables from the filterer function used in `Promise.filter` and `Promise.prototype.filter`.\n\n - `.error()` now catches additional sources of rejections:\n\n - Rejections originating from `Promise.reject`\n\n - Rejections originating from thenables using\n the `reject` callback\n\n - Rejections originating from promisified callbacks\n which use the `errback` argument\n\n - Rejections originating from `new Promise` constructor\n where the `reject` callback is called explicitly\n\n - Rejections originating from `PromiseResolver` where\n `.reject()` method is called explicitly\n\nBugfixes:\n\n - Fix `captureStackTrace` being called when it was `null`\n - Fix `Promise.map` not unwrapping thenables\n\n## 0.11.5-1 (2013-12-15)\n\n## 0.11.5-0 (2013-12-03)\n\nFeatures:\n\n - Improve performance of collection methods\n - Improve performance of promise chains\n\n## 0.11.4-1 (2013-12-02)\n\n## 0.11.4-0 (2013-12-02)\n\nBugfixes:\n\n - Fix `Promise.some` behavior with arguments like negative integers, 0...\n - Fix stack traces of synchronously throwing promisified functions'\n\n## 0.11.3-0 (2013-12-02)\n\nFeatures:\n\n - Improve performance of generators\n\nBugfixes:\n\n - Fix critical bug with collection methods.\n\n## 0.11.2-0 (2013-12-02)\n\nFeatures:\n\n - Improve performance of all collection methods\n\n## 0.11.1-0 (2013-12-02)\n\nFeatures:\n\n- Improve overall performance.\n- Improve performance of promisified functions.\n- Improve performance of catch filters.\n- Improve performance of .finally.\n\nBugfixes:\n\n- Fix `.finally()` rejecting if passed non-function. It will now ignore non-functions like `.then`.\n- Fix `.finally()` not converting thenables returned from the handler to promises.\n- `.spread()` now rejects if the ultimate value given to it is not spreadable.\n\n## 0.11.0-0 (2013-12-02)\n\nFeatures:\n\n - Improve overall performance when not using `.bind()` or cancellation.\n - Promises are now not cancellable by default. This is backwards incompatible change - see [`.cancellable()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#cancellable---promise)\n - [`Promise.delay`](https://github.com/petkaantonov/bluebird/blob/master/API.md#promisedelaydynamic-value-int-ms---promise)\n - [`.delay()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#delayint-ms---promise)\n - [`.timeout()`](https://github.com/petkaantonov/bluebird/blob/master/API.md#timeoutint-ms--string-message---promise)\n\n## 0.10.14-0 (2013-12-01)\n\nBugfixes:\n\n - Fix race condition when mixing 3rd party asynchrony.\n\n## 0.10.13-1 (2013-11-30)\n\n## 0.10.13-0 (2013-11-30)\n\nBugfixes:\n\n - Fix another bug with progression.\n\n## 0.10.12-0 (2013-11-30)\n\nBugfixes:\n\n - Fix bug with progression.\n\n## 0.10.11-4 (2013-11-29)\n\n## 0.10.11-2 (2013-11-29)\n\nBugfixes:\n\n - Fix `.race()` not propagating bound values.\n\n## 0.10.11-1 (2013-11-29)\n\nFeatures:\n\n - Improve performance of `Promise.race`\n\n## 0.10.11-0 (2013-11-29)\n\nBugfixes:\n\n - Fixed `Promise.promisifyAll` invoking property accessors. Only data properties with function values are considered.\n\n## 0.10.10-0 (2013-11-28)\n\nFeatures:\n\n - Disable long stack traces in browsers by default. Call `Promise.longStackTraces()` to enable them.\n\n## 0.10.9-1 (2013-11-27)\n\nBugfixes:\n\n - Fail early when `new Promise` is constructed incorrectly\n\n## 0.10.9-0 (2013-11-27)\n\nBugfixes:\n\n - Promise.props now takes a [thenable-for-collection](https://github.com/petkaantonov/bluebird/blob/f41edac61b7c421608ff439bb5a09b7cffeadcf9/test/mocha/props.js#L197-L217)\n - All promise collection methods now reject when a promise-or-thenable-for-collection turns out not to give a collection\n\n## 0.10.8-0 (2013-11-25)\n\nFeatures:\n\n - All static collection methods take thenable-for-collection\n\n## 0.10.7-0 (2013-11-25)\n\nFeatures:\n\n - throw TypeError when thenable resolves with itself\n - Make .race() and Promise.race() forever pending on empty collections\n\n## 0.10.6-0 (2013-11-25)\n\nBugfixes:\n\n - Promise.resolve and PromiseResolver.resolve follow thenables too.\n\n## 0.10.5-0 (2013-11-24)\n\nBugfixes:\n\n - Fix infinite loop when thenable resolves with itself\n\n## 0.10.4-1 (2013-11-24)\n\nBugfixes:\n\n - Fix a file missing from build. (Critical fix)\n\n## 0.10.4-0 (2013-11-24)\n\nFeatures:\n\n - Remove dependency of es5-shim and es5-sham when using ES3.\n\n## 0.10.3-0 (2013-11-24)\n\nFeatures:\n\n - Improve performance of `Promise.method`\n\n## 0.10.2-1 (2013-11-24)\n\nFeatures:\n\n - Rename PromiseResolver#asCallback to PromiseResolver#callback\n\n## 0.10.2-0 (2013-11-24)\n\nFeatures:\n\n - Remove memoization of thenables\n\n## 0.10.1-0 (2013-11-21)\n\nFeatures:\n\n - Add methods `Promise.resolve()`, `Promise.reject()`, `Promise.defer()` and `.resolve()`.\n\n## 0.10.0-1 (2013-11-17)\n\n## 0.10.0-0 (2013-11-17)\n\nFeatures:\n\n - Implement `Promise.method()`\n - Implement `.return()`\n - Implement `.throw()`\n\nBugfixes:\n\n - Fix promises being able to use themselves as resolution or follower value\n\n## 0.9.11-1 (2013-11-14)\n\nFeatures:\n\n - Implicit `Promise.all()` when yielding an array from generators\n\n## 0.9.11-0 (2013-11-13)\n\nBugfixes:\n\n - Fix `.spread` not unwrapping thenables\n\n## 0.9.10-2 (2013-11-13)\n\nFeatures:\n\n - Improve performance of promisified functions on V8\n\nBugfixes:\n\n - Report unhandled rejections even when long stack traces are disabled\n - Fix `.error()` showing up in stack traces\n\n## 0.9.10-1 (2013-11-05)\n\nBugfixes:\n\n - Catch filter method calls showing in stack traces\n\n## 0.9.10-0 (2013-11-05)\n\nBugfixes:\n\n - Support primitives in catch filters\n\n## 0.9.9-0 (2013-11-05)\n\nFeatures:\n\n - Add `Promise.race()` and `.race()`\n\n## 0.9.8-0 (2013-11-01)\n\nBugfixes:\n\n - Fix bug with `Promise.try` not unwrapping returned promises and thenables\n\n## 0.9.7-0 (2013-10-29)\n\nBugfixes:\n\n - Fix bug with build files containing duplicated code for promise.js\n\n## 0.9.6-0 (2013-10-28)\n\nFeatures:\n\n - Improve output of reporting unhandled non-errors\n - Implement RejectionError wrapping and `.error()` method\n\n## 0.9.5-0 (2013-10-27)\n\nFeatures:\n\n - Allow fresh copies of the library to be made\n\n## 0.9.4-1 (2013-10-27)\n\n## 0.9.4-0 (2013-10-27)\n\nBugfixes:\n\n - Rollback non-working multiple fresh copies feature\n\n## 0.9.3-0 (2013-10-27)\n\nFeatures:\n\n - Allow fresh copies of the library to be made\n - Add more components to customized builds\n\n## 0.9.2-1 (2013-10-25)\n\n## 0.9.2-0 (2013-10-25)\n\nFeatures:\n\n - Allow custom builds\n\n## 0.9.1-1 (2013-10-22)\n\nBugfixes:\n\n - Fix unhandled rethrown exceptions not reported\n\n## 0.9.1-0 (2013-10-22)\n\nFeatures:\n\n - Improve performance of `Promise.try`\n - Extend `Promise.try` to accept arguments and ctx to make it more usable in promisification of synchronous functions.\n\n## 0.9.0-0 (2013-10-18)\n\nFeatures:\n\n - Implement `.bind` and `Promise.bind`\n\nBugfixes:\n\n - Fix `.some()` when argument is a pending promise that later resolves to an array\n\n## 0.8.5-1 (2013-10-17)\n\nFeatures:\n\n - Enable process wide long stack traces through BLUEBIRD_DEBUG environment variable\n\n## 0.8.5-0 (2013-10-16)\n\nFeatures:\n\n - Improve performance of all collection methods\n\nBugfixes:\n\n - Fix .finally passing the value to handlers\n - Remove kew from benchmarks due to bugs in the library breaking the benchmark\n - Fix some bluebird library calls potentially appearing in stack traces\n\n## 0.8.4-1 (2013-10-15)\n\nBugfixes:\n\n - Fix .pending() call showing in long stack traces\n\n## 0.8.4-0 (2013-10-15)\n\nBugfixes:\n\n - Fix PromiseArray and its sub-classes swallowing possibly unhandled rejections\n\n## 0.8.3-3 (2013-10-14)\n\nBugfixes:\n\n - Fix AMD-declaration using named module.\n\n## 0.8.3-2 (2013-10-14)\n\nFeatures:\n\n - The mortals that can handle it may now release Zalgo by `require(\"bluebird/zalgo\");`\n\n## 0.8.3-1 (2013-10-14)\n\nBugfixes:\n\n - Fix memory leak when using the same promise to attach handlers over and over again\n\n## 0.8.3-0 (2013-10-13)\n\nFeatures:\n\n - Add `Promise.props()` and `Promise.prototype.props()`. They work like `.all()` for object properties.\n\nBugfixes:\n\n - Fix bug with .some returning garbage when sparse arrays have rejections\n\n## 0.8.2-2 (2013-10-13)\n\nFeatures:\n\n - Improve performance of `.reduce()` when `initialValue` can be synchronously cast to a value\n\n## 0.8.2-1 (2013-10-12)\n\nBugfixes:\n\n - Fix .npmignore having irrelevant files\n\n## 0.8.2-0 (2013-10-12)\n\nFeatures:\n\n - Improve performance of `.some()`\n\n## 0.8.1-0 (2013-10-11)\n\nBugfixes:\n\n - Remove uses of dynamic evaluation (`new Function`, `eval` etc) when strictly not necessary. Use feature detection to use static evaluation to avoid errors when dynamic evaluation is prohibited.\n\n## 0.8.0-3 (2013-10-10)\n\nFeatures:\n\n - Add `.asCallback` property to `PromiseResolver`s\n\n## 0.8.0-2 (2013-10-10)\n\n## 0.8.0-1 (2013-10-09)\n\nFeatures:\n\n - Improve overall performance. Be able to sustain infinite recursion when using promises.\n\n## 0.8.0-0 (2013-10-09)\n\nBugfixes:\n\n - Fix stackoverflow error when function calls itself \"synchronously\" from a promise handler\n\n## 0.7.12-2 (2013-10-09)\n\nBugfixes:\n\n - Fix safari 6 not using `MutationObserver` as a scheduler\n - Fix process exceptions interfering with internal queue flushing\n\n## 0.7.12-1 (2013-10-09)\n\nBugfixes:\n\n - Don't try to detect if generators are available to allow shims to be used\n\n## 0.7.12-0 (2013-10-08)\n\nFeatures:\n\n - Promisification now consider all functions on the object and its prototype chain\n - Individual promisifcation uses current `this` if no explicit receiver is given\n - Give better stack traces when promisified callbacks throw or errback primitives such as strings by wrapping them in an `Error` object.\n\nBugfixes:\n\n - Fix runtime APIs throwing synchronous errors\n\n## 0.7.11-0 (2013-10-08)\n\nFeatures:\n\n - Deprecate `Promise.promisify(Object target)` in favor of `Promise.promisifyAll(Object target)` to avoid confusion with function objects\n - Coroutines now throw error when a non-promise is `yielded`\n\n## 0.7.10-1 (2013-10-05)\n\nFeatures:\n\n - Make tests pass Internet Explorer 8\n\n## 0.7.10-0 (2013-10-05)\n\nFeatures:\n\n - Create browser tests\n\n## 0.7.9-1 (2013-10-03)\n\nBugfixes:\n\n - Fix promise cast bug when thenable fulfills using itself as the fulfillment value\n\n## 0.7.9-0 (2013-10-03)\n\nFeatures:\n\n - More performance improvements when long stack traces are enabled\n\n## 0.7.8-1 (2013-10-02)\n\nFeatures:\n\n - Performance improvements when long stack traces are enabled\n\n## 0.7.8-0 (2013-10-02)\n\nBugfixes:\n\n - Fix promisified methods not turning synchronous exceptions into rejections\n\n## 0.7.7-1 (2013-10-02)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.7-0 (2013-10-01)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.6-0 (2013-09-29)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.5-0 (2013-09-28)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.4-1 (2013-09-28)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.4-0 (2013-09-28)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.3-1 (2013-09-28)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.3-0 (2013-09-27)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.2-0 (2013-09-27)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.1-5 (2013-09-26)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.1-4 (2013-09-25)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.1-3 (2013-09-25)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.1-2 (2013-09-24)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.1-1 (2013-09-24)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.1-0 (2013-09-24)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.0-1 (2013-09-23)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.7.0-0 (2013-09-23)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.5-2 (2013-09-20)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.5-1 (2013-09-18)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.5-0 (2013-09-18)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.4-1 (2013-09-18)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.4-0 (2013-09-18)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.3-4 (2013-09-18)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.3-3 (2013-09-18)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.3-2 (2013-09-16)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.3-1 (2013-09-16)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.3-0 (2013-09-15)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.2-1 (2013-09-14)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.2-0 (2013-09-14)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.1-0 (2013-09-14)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.6.0-0 (2013-09-13)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-6 (2013-09-12)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-5 (2013-09-12)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-4 (2013-09-12)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-3 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-2 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-1 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.9-0 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.8-1 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.8-0 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.7-0 (2013-09-11)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.6-1 (2013-09-10)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.6-0 (2013-09-10)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.5-1 (2013-09-10)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.5-0 (2013-09-09)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.4-1 (2013-09-08)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.4-0 (2013-09-08)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.3-0 (2013-09-07)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.2-0 (2013-09-07)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.1-0 (2013-09-07)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.5.0-0 (2013-09-07)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.4.0-0 (2013-09-06)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.3.0-1 (2013-09-06)\n\nFeatures:\n\n - feature\n\nBugfixes:\n\n - bugfix\n\n## 0.3.0 (2013-09-06)\n"
},
{
"path": "docs/docs/coming-from-other-languages.md",
"content": "---\nid: coming-from-other-languages\ntitle: Coming from Other Languages\n---\n\nThis page describes parallels of using promises in other languages. Promises as a pattern are very common in other languages and knowing what they map to in other languages might help you with grasping them conceptually\n\n - [C#](#c)\n - [Scala](#scala)\n - [Python](#python)\n - [C++](#c)\n - [Haskell](#haskell)\n - [Java](#java)\n - [Android Java](#android-java)\n - [Objective-C](#objective-c)\n\n\n## C#\n\nA promise is similar to a C# `Task`. They both represent the result of an operation.\n\nA promise's `then` method is similar to a Task's `ContinueWith` method in that both allow attaching a continuation to the promise. Bluebird's [Promise.coroutine](.) is analogous to C#'s `async/await` syntax.\n\nA `TaskCompletionSource` is analogous to the promise constructor. Although usually promisification is preferred (see the API reference or working with callbacks section).\n\n`Task.FromResult` is analogous to [Promise.resolve](.).\n\nThe difference between a `Task` and a promise are that a task might not be started and might require a `.Start` call where a promise always represents an already started operation.\n\nIn addition promises are always unwrapped. A promise implicitly has `Task.Unwrap` called on it - that is, promises perform recursive assimilation of promises within them.\n\nSee [this question on StackOverflow](http://stackoverflow.com/questions/26136389/how-can-i-realize-pattern-promise-deffered) for more differences.\n\n## Scala\n\nA bluebird promise is similar to a Scala `Future`. A scala `Promise` is similar to how the promise constructor can be used (previously, to a bluebird Deferred).\n\nJust like a future, a promise represents a value over time. The value can resolve to either a fulfilled (ok completion) or rejected (error completion) state.\n\nWhere blocking on a Future in scala is discouraged, in JavaScript it's downright impossible.\n\nIn addition promises are always unwrapped. That is, promises perform recursive assimilation of promises within them. You can't have a `Promise>` where a `Future[Future[T]]` is valid in Scala.\n\nSee [this question on StackOverflow](http://stackoverflow.com/questions/22724883/js-deferred-promise-future-compared-to-functional-languages-like-scala) for more differences.\n\n## Python\n\nA promise is similar to a Twisted Deferred object. In fact the first JavaScript implementations of promises were based on it. However, the APIs have diverged since. The mental model is still very similar.\n\nA promise is _not_ similar to a Python `concurrent.Future` which does not chain actions.\n\nAsyncio coroutines are similar to bluebird coroutines in what they let you do, however bluebird coroutines also enable functional-style chaining.\n\n## C++\n\nA bluebird promise is similar to a `std::future` and the promise constructor is similar to an `std::promise` although it should rarely be used in practice (see the promisification section).\n\nHowever, a bluebird promise is more powerful than the current implementation of `std::future` since while chaining has been discussed it is not yet implemented. Promises can be chained together.\n\nBoost futures expose a `.then` method similar to promises and allow this functionality.\n\n## Haskell\n\nA promise is a monadic construct with `.then` filling the role of `>>=` (bind). The major difference is that `.then` performs recursive assimilation which acts like a `flatMap` or a map. The type signature of `then` is quote complicated. If we omit the error argument and not throw - it's similar to:\n\n```hs\nthen::Promise a -> (a -> (Either (Promise b) b)) -> Promise b\n```\n\nThat is, you can return either a promise _or a plain value_ from a `then` without wrapping it.\n\nPromises perform a role similar to `IO` in that they allow for easy chaining of asynchronous non-blocking operations. `Promise.coroutine` can be seen as similar to `do` notation although in practice it's not an accurate comparison.\n\n## Java\n\nA promise is similar to a guava `Future` with `chain` being similar to `then`.\n\nIf your'e familiar with Java 8 lambdas, you can think of a promise as a `Future` you can `map` to another future.\n\n## Android Java\n\nSeveral popular Android libraries use promises - for example the Parse Java API returns `Task`s which are similar to JavaScript promises.\n\n## Objective-C\n\nIf you're familiar with PromiseKit, it is based on a same specification bluebird is based on so the API should feel familiar right away.\n"
},
{
"path": "docs/docs/coming-from-other-libraries.md",
"content": "---\nid: coming-from-other-libraries\ntitle: Coming from Other Libraries\n---\n\nThis page is a reference for migrating to bluebird from other flow control or promise libraries. See [installation](install.html) on how to use bluebird in your environment.\n\n - [Coming from native promises](#coming-from-native-promises)\n - [Coming from jQuery deferreds](#coming-from-jquery-deferreds)\n - [Coming from `async` module](#coming-from-async-module)\n - [Coming from Q](#coming-from-q)\n - [Coming from co/koa](#coming-from-co)\n - [Coming from highland, RxJS or BaconJS](#coming-from-highland)\n\n##Coming from native promises\n\nBluebird promises are a drop-in replacement for native promises except for subclassing. Additionally you might want to replace usages of the often incorrectly used [Promise.race](.) with bluebird's [Promise.any](.) which does what is usually mistakenly expected from [Promise.race](.). For maximum compatibility, bluebird does provide [Promise.race](.) with ES6 semantics.\n\nYou can also refactor some looping patterns to a more natural form that would [leak memory when using native promises](https://github.com/promises-aplus/promises-spec/issues/179).\n\n##Coming from jQuery deferreds\n\nBluebird treats jQuery deferreds and promises interchangeably. Wherever you can take a promise or return a promise, you can take or return a jQuery deferred instead and it works the same.\n\nFor instance, there is no need to write something like this:\n\n```js\nvar firstRequest = new Promise(function(resolve, reject) {\n $.ajax({...}).done(resolve).fail(reject);\n});\nvar secondRequest = new Promise(function(resolve, reject) {\n $.ajax({...}).done(resolve).fail(reject);\n});\n\nPromise.all([firstRequest, secondRequest]).then(function() {\n // ...\n});\n```\n\nSince [Promise.all](.) takes promises, it must also take jQuery deferreds, so the above can be shortened to:\n\n```js\nvar firstRequest = $.ajax({...});\nvar secondRequest = $.ajax({...});\n\nPromise.all([firstRequest, secondRequest]).then(function() {\n // ...\n});\n```\n\nThat said, if you have code written using jQuery deferred methods, such as `.then`, `.done` and so on, you cannot drop-in replace the jQuery deferred with a bluebird promise in that code. Despite having the same names, jQuery deferred methods have different semantics than bluebird promise methods. These differences are due to the completely different goals of the implementations. Bluebird is [an internal DSL](http://en.wikipedia.org/wiki/Domain-specific_language) for the domain of asynchronous control flow while jQuery deferreds are a callback aggregator utility (\"glorified event emitters\").\n\nIf you do have some code using jQuery deferred methods extensively try to see if some of these jQuery deferred patterns and their replacements can be applied:\n\n```js\n// jQuery\n$.when.apply($, someArray).then(...)\n// bluebird\nPromise.all(someArray).then(...)\n```\n\n```js\n// jQuery\nvar data = [1,2,3,4];\nvar processItemsDeferred = [];\n\nfor(var i = 0; i < data.length; i++) {\n processItemsDeferred.push(processItem(data[i]));\n}\n\n$.when.apply($, processItemsDeferred).then(everythingDone);\n\n// bluebird\nvar data = [1,2,3,4];\nPromise.map(data, function(item) {\n return processItem(item);\n}).then(everythingDone);\n```\n\n```js\n// jQuery\nvar d = $.Deferred();\nd.resolve(\"value\");\n// bluebird\nvar d = Promise.resolve(\"value\");\n```\n\n```js\n// jQuery\nvar d = $.Deferred();\nd.reject(new Error(\"error\"));\n// bluebird\nvar d = Promise.reject(new Error(\"error\"));\n```\n\n```js\n// jQuery\nvar clicked = $.Deferred();\n$(\"body\").one(\"click\", function(e) {\n clicked.resolve(e);\n});\n// bluebird\nvar clicked = new Promise(function(resolve) {\n $(\"body\").one(\"click\", resolve);\n});\n```\n\n```js\n// jQuery\n.always(removeSpinner);\n// bluebird\n.finally(removeSpinner);\n```\n\n##Coming from `async` module\n\nWhen working with promises the philosophy is basically a complete opposite than when using `async`. Async provides a huge bag of uncomposable helper functions that work at a very low level of abstraction. When using promises you can get the utility otherwise provided by uncountable amount of inflexible helper functions by just combining and composing a few existing functions and concepts.\n\nThat means when you have a problem there probably isn't an existing function tailored exactly to that problem but instead you can just combine the existing utilities to arrive at a solution. The upside of this is that you don't need to come up with all these different functions to solve problems that are not that different from each other. The most important thing to do when migrating from async to bluebird is this profound shift in philosophy.\n\nThis section lists the most common async module replacements.\n\n###`async.waterfall`\n\nIf the waterfall elements are static, you can just replace it with a normal promise chain. For waterfalls with dynamic steps, use [Promise.each](.). Multiple arguments can be ferried in an array.\n\nImplementing the example from [async homepage](https://github.com/caolan/async#waterfalltasks-callback)\n\n```js\nasync.waterfall([\n function(callback) {\n callback(null, 'one', 'two');\n },\n function(arg1, arg2, callback) {\n // arg1 now equals 'one' and arg2 now equals 'two'\n callback(null, 'three');\n },\n function(arg1, callback) {\n // arg1 now equals 'three'\n callback(null, 'done');\n }\n], function (err, result) {\n // result now equals 'done'\n});\n```\n\nSince the array passed to waterfall is static (always the same 3 functions) a plain old promise chain is used:\n\n```js\nPromise.resolve(['one', 'two']).spread(function(arg1, arg2) {\n // arg1 now equals 'one' and arg2 now equals 'two'\n return 'three';\n}).then(function(arg1) {\n // arg1 now equals 'three'\n return 'done';\n}).then(function(result) {\n // result now equals 'done'\n});\n```\n\nIf destructuring parameters are supported, `.spread(function(arg1, arg2) {})` can be replaced with `.then(function([arg1, arg2]){})`.\n\n###`async.series`\n\nUsing [Promise.mapSeries](.) to implement the example from [async homepage](https://github.com/caolan/async#seriestasks-callback):\n\n```js\nasync.series([\n function(callback){\n setTimeout(function(){\n callback(null, 1);\n }, 200);\n },\n function(callback){\n setTimeout(function(){\n callback(null, 2);\n }, 100);\n }\n],\n// optional callback\nfunction(err, results){\n // results is now equal to [1, 2]\n});\n```\n\n```js\nPromise.mapSeries([{timeout: 200, value: 1},\n {timeout: 100, value: 2}], function(item) {\n return Promise.delay(item.timeout, item.value);\n}).then(function(results) {\n // results is now equal to [1, 2]\n});\n```\n\n\n###`async.parallel`\n\nUsing [Promise.all](.) to implement the example from [async homepage](https://github.com/caolan/async#parallel):\n\n```js\nasync.parallel([\n function(callback){\n setTimeout(function(){\n callback(null, 'one');\n }, 200);\n },\n function(callback){\n setTimeout(function(){\n callback(null, 'two');\n }, 100);\n }\n],\n// optional callback\nfunction(err, results){\n // the results array will equal ['one','two'] even though\n // the second function had a shorter timeout.\n});\n```\n\n```js\nPromise.all([Promise.delay(200, 'one'),\n Promise.delay(100, 'two')]).then(function(results) {\n // the results array will equal ['one','two'] even though\n // the second function had a shorter timeout.\n});\n```\n\n###`async.mapSeries`\n\nUsing [Promise.each](.) to implement the example from [async homepage](https://github.com/caolan/async#maparr-iterator-callback):\n\n```js\nvar fs = require('fs');\nasync.mapSeries(['file1','file2','file3'], fs.stat, function(err, results){\n // results is now an array of stats for each file\n});\n```\n\n```js\nvar fs = Promise.promisifyAll(require('fs'));\nPromise.each(['file1','file2','file3'], function(fileName, index, length) {\n return fs.statAsync(fileName);\n}).then(function(results) {\n // results is now an array of stats for each file\n});\n```\n\n###`async.map`\n\nUsing [Promise.map](.) to implement the example from [async homepage](https://github.com/caolan/async#maparr-iterator-callback):\n\n```js\nvar fs = require('fs');\nasync.map(['file1','file2','file3'], fs.stat, function(err, results){\n // results is now an array of stats for each file\n});\n```\n\n```js\nvar fs = Promise.promisifyAll(require('fs'));\nPromise.map(['file1','file2','file3'], function(fileName, index, length) {\n return fs.statAsync(fileName);\n}).then(function(results) {\n // results is now an array of stats for each file\n});\n```\n\n###`async.whilst`\n\nUsing recursion to implement the example from [async homepage](https://github.com/caolan/async#whilsttest-fn-callback):\n\n```js\nvar count = 0;\nasync.whilst(\n function () { return count < 5; },\n function (callback) {\n count++;\n setTimeout(callback, 1000);\n },\n function (err) {\n // 5 seconds have passed\n }\n);\n```\n```js\n(function loop() {\n if (count < 5) {\n count++;\n return Promise.delay(1000).then(loop);\n }\n return Promise.resolve();\n})().then(function() {\n // 5 seconds have passed\n});\n```\n\nBe warned that the above example implementations are only superficially equivalent. Callbacks, even with the help of async, require too much boilerplate code to provide the same guarantees as promises.\n\n##Coming from Q\n\nQ and bluebird share a lot of common methods that nevertheless have different names:\n\n- `Q(...)` -> [Promise.resolve()](.)\n- `.fail()` -> [.catch()](.) or `.caught()`\n- `.fin()` -> [.finally()](.) or `.lastly()`\n- `Q.fcall()` -> [Promise.try](.) or `Promise.attempt()`\n- `.thenResolve()` -> [.return()](.) or `.thenReturn()`\n- `.thenReject()` -> [.throw()](.) or `thenThrow()`\n\n##Coming from co/koa\n\nIn recent versions generator libraries started abandoning old ideas of special tokens passed to callbacks and started using promises for what's being yielded.\n\nBluebird's [Promise.coroutine](.) is a superset of the `co` library, being more extensible as well as supporting cancellation (in environments where [`Generator#return`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/return) is implemented).\n\n##Coming from highland, RxJS or BaconJS\n\nStream libraries tend to serve a different purpose than promise libraries. Unlike promise libraries streams can represent multiple values.\n\nCheck out the benchmarks section for examples of transitioning an API from Bacon/Rx to promises.\n"
},
{
"path": "docs/docs/contribute.md",
"content": "---\nid: contribute\ntitle: Contribute\n---\n\nFor development tasks such as contributing, running benchmarks or testing, you need to clone the repository and install dev-dependencies.\n\nInstall [node](http://nodejs.org/)\n\n git clone git@github.com:petkaantonov/bluebird.git\n cd bluebird\n npm install\n\n- [Directory structure](#directory-structure)\n- [Style guide](#style-guide)\n- [Building](#building)\n - [Supported options by the build tool](#supported-options-by-the-build-tool)\n- [Testing](#testing)\n - [Testing in browsers](#testing-in-browsers)\n - [Supported options by the test tool](#supported-options-by-the-test-tool)\n- [Benchmarking](#benchmarking)\n\n## Directory structure\n\n- `/benchmark` contains benchmark scripts and stats of benchmarks\n\n- `/tools` contains building and testing tools and scripts\n\n- `/src` contains the source code\n\n- `/test` contains test code\n\n - `/test/mocha` contains tests using the mocha testing framework\n - `/test/browser` a directory that can be statically served using a webserver to run tests in browsers. See [testing in browsers](README.md#testing-in-browsers).\n\n\n## Style guide\n\nUse the same style as is used in the surrounding code.\n\n###Whitespace\n\n- No more than 80 columns per line\n- 4 space indentation\n- No trailing whitespace\n- LF at end of files\n- Curly braces can be left out of single statement `if/else/else if`s when it is obvious there will never be multiple statements such as null check at the top of a function for an early return.\n- Add an additional new line between logical sections of code.\n\n###Variables\n\n- Use multiple `var` statements instead of a single one with comma separator. Do not declare variables until you need them.\n\n###Equality and type checks\n\n- Always use `===` except when checking for null or undefined. To check for null or undefined, use `x == null`.\n- For checks that can be done with `typeof`: do not make helper functions, save results of `typeof` to a variable or make the type string a non-constant. Always write the check in the form `typeof expression === \"constant string\"` even if it feels like repeating yourself.\n\n##Building\n\n```\nnode tools/build --debug --release --zalgo --browser --minify\n```\n\n###Supported options by the build tool\n\nThe value of boolean flags is determined by presence, if you want to pass false value for a boolean flag, use the `no-`-prefix e.g. `--no-debug`.\n\n - `--release` - Whether to build the release build. The release build is placed at `js/release` directory. Default `false`.\n - `--debug` - Whether to build the debug build. The debug build is placed at `js/debug` directory. Default `false`.\n - `--zalgo` - Whether to build the zalgo build. The zalgo build is placed at `js/zalgo` directory. Default `false`.\n - `--browser` - Whether to compile the browser build. The browser build file is placed at `js/browser/bluebird.js` Default `false`.\n - `--minify` - Whether to minify the compiled browser build. The minified browser build file is placed at `js/browser/bluebird.min.js` Default `true`.\n\n##Testing\n\nTo run all tests, run\n\n node --expose-gc tools/test\n\nIf you need to run generator tests in older versions of NodeJS run the `tool/test.js` script with `--harmony` argument and 0.11+:\n\n node-dev --harmony tools/test\n\nIn recent versions of NodeJS where generators are enabled by default:\n\n node tools/test\n\nYou may specify an individual test file to run with the `--run` script flag:\n\n node tools/test --run=cancel.js\n\n\nThis enables output from the test and may give a better idea where the test is failing. The paramter to `--run` can be any file name located in `test/mocha` folder.\n\n###Testing in browsers\n\nTo run the test in a browser instead of node, pass the flag `--browser` to the test tool\n\n node tools/test --run=cancel.js --browser\n\nThis will automatically create a server (default port 9999) and open it in your default browser once the tests have been compiled.\n\nKeep the test tab active because some tests are timing-sensitive and will fail if the browser is throttling timeouts. Chrome will do this for example when the tab is not active.\n\n###Supported options by the test tool\n\nThe value of boolean flags is determined by presence, if you want to pass false value for a boolean flag, use the `no-`-prefix e.g. `--no-browser`.\n\n - `--run=String`. Which tests to run (or compile when testing in browser). Default `\"all\"`. Can also be a glob string (relative to ./test/mocha folder)\n - `--cover=String`. Create code coverage using the String as istanbul reporter. Coverage is created in the ./coverage folder. No coverage is created by default, default reporter is `\"html\"` (use `--cover` to use default reporter).\n - `--browser` - Whether to compile tests for browsers. Default `false`.\n - `--port=Number` - Whe port where local server is hosted when testing in browser. Default `9999`\n - `--execute-browser-tests` - Whether to execute the compiled tests for browser when using `--browser`. Default `true`.\n - `--open-browser` - Whether to open the default browser when executing browser tests. Default `true`.\n - `--fake-timers` - Whether to use fake timers (`setTimeout` etc) when running tests in node. Default `true`.\n - `--js-hint` - Whether to run JSHint on source files. Default `true`.\n - `--saucelabs` Wheter to create a tunnel to sauce labs and run tests in their VMs instead of your browser when compiling tests for browser.Default `false`.\n\n##Benchmarking\n\nTo run a benchmark, run the given command for a benchmark while on the project root. Requires bash (on windows the mingw32 that comes with git works fine too).\n\nEach benchmark must\n\n - Have implementations that do the same thing\n - Run each implementation of a benchmark in a separate freshly created process\n - Warmup each implementation before timing\n\n###1\\. DoxBee sequential\n\nCurrently the most relevant benchmark is @gorkikosev's benchmark in the article [Analysis of generators and other async patterns in node](http://spion.github.io/posts/analysis-generators-and-other-async-patterns-node.html). The benchmark emulates a situation where n amount of users are making a request in parallel to execute some mixed async/sync action.\n\nCommand: `bench doxbee`\n\nThe implementations for this benchmark are found in `benchmark/doxbee-sequential` directory.\n\n###2\\. Parallel\n\nThis made-up scenario runs 25 shimmed queries in parallel.\n\nCommand: `bench parallel`\n\nThe implementations for this benchmark are found in `benchmark/madeup-parallel` directory.\n"
},
{
"path": "docs/docs/deprecated-apis.md",
"content": "---\nid: deprecated-apis\ntitle: Deprecated APIs\n---\n\n[deprecated-apis](unfinished-article)\n\nThis file contains documentation for APIs that are no longer supported by Bluebird.\nThese APIs still work in Bluebird but will be removed at a future version of the library.\n\nFor every use case that the methods below solve there exists a better alternative in [the API reference](/docs/api-reference.html).\n\n- [Progression](#progression)\n - [`.progressed(Function handler)`](#progressedfunction-handler---promise)\n - [`.then([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])`](#thenfunction-fulfilledhandler--function-rejectedhandler---function-progresshandler----promise)\n - [`.done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])`](#donefunction-fulfilledhandler--function-rejectedhandler---function-progresshandler----promise)\n\n- [Promise resolution](#promise-resolution)\n - [`.resolve(dynamic value)`](#resolvedynamic-value---undefined)\n - [`.reject(dynamic reason)`](#rejectdynamic-reason---undefined)\n - [`.progress(dynamic value)`](#progressdynamic-value---undefined)\n - [`.callback`](#callback---function)\n\n - [Old Promise Cancellation](#old-promise-cancellation)\n \n\n##Progression\n\nThe old progression API was meant to be used for tracking the progress of promise resolution. In retrospect, it did not work or compose very well. We understand that problem better now and the use case could be better solved without it.\n\nSee [Progression Migration](./api/progression-migration.html) for migration assistance and examples of how to convert APIs that use progression to ones that do not.\n\n#####`.progressed(Function handler)` -> `Promise`\n\n\nShorthand for `.then(null, null, handler);`. Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise.\n\n\n\n#####`.then([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])` -> `Promise`\n\nThe standard [Promises/A+ `.then()`](http://promises-aplus.github.io/promises-spec/) is still supported by Bluebird and support for it will continue indefinitely . However, the variant accepting a third `progressHandler` argument is no longer supported.\n\n\n\n\n#####`.done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])` -> `void`\n\nLike `.then()`, but any unhandled rejection that ends up here will be thrown as an error. Again, only the variant with the progression handler is deprecated here. `.done` is still fully supported.\n\n\n\n\n\n##Promise resolution\n\nA `PromiseResolver` can be used to control the fate of a promise. It is like \"Deferred\" in jQuery or `$q.defer` in $q. The `PromiseResolver` objects have a `.promise` property which returns a reference to the controlled promise that can be passed to clients. `.promise` of a `PromiseResolver` is not a getter function to match other implementations.\n\nThe methods of a `PromiseResolver` have no effect if the fate of the underlying promise is already decided (follow, reject, fulfill).\n\n**The use of `Promise.defer` and deferred objects is discouraged - it is much more awkward and error-prone than using `new Promise`.**\n\n\n\n#####`.resolve(dynamic value)` -> `undefined`\n\nResolve the underlying promise with `value` as the resolution value. If `value` is a thenable or a promise, the underlying promise will assume its state.\n\n\n\n#####`.reject(dynamic reason)` -> `undefined`\n\nReject the underlying promise with `reason` as the rejection reason.\n\n\n\n#####`.progress(dynamic value)` -> `undefined`\n\nProgress the underlying promise with `value` as the progression value.\n\nExample\n\n```js\nfunction delay(ms) {\n var resolver = Promise.defer();\n var now = Date.now();\n setTimeout(function(){\n resolver.resolve(Date.now() - now);\n }, ms);\n return resolver.promise;\n}\n\ndelay(500).then(function(ms){\n console.log(ms + \" ms passed\");\n});\n```\n\n\n\n##Old Promise Cancellation\n\nIn 2.x, promise cancellation looked very differently. Promise cancellation received a major overhaul for version 3 in order to create a sound variant of cancellable promises. You can still use 2.x cancellation with bluebird 2.x (which is still supported - but not recommended). See [Cancellation](/cancellation.html) for more details. The 2.x docs are [still accessible under the 2.x branch](https://github.com/petkaantonov/bluebird/blob/2.x/API.md).\n\n"
},
{
"path": "docs/docs/deprecated_apis.md",
"content": "---\nid: deprecated_apis\ntitle: Deprecated APIs\n---\n\nThis file contains documentation for APIs that are no longer supported by Bluebird.\nThese APIs still work in Bluebird but will be removed at a future version of the library.\n\nFor every use case that the methods below solve there exists a better alternative in [the API reference](./API.md).\n\n- [Progression](#progression)\n - [`.progressed(Function handler)`](#.progressed)\n - [`.then([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])`](#.then)\n - [`.done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])`](#.done)\n - [`.fork([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])`](#.fork)\n\n- [Promise resolution](#promise-resolution)\n - [`.resolve(dynamic value)`](#.resolve)\n - [`.reject(dynamic reason)`](#.reject)\n - [`.progress(dynamic value)`](#.progress)\n - [`.callback`](#.callback)\n\n\n\n##Progression\n\nThe old progression API was meant to be used for tracking the progress of promise resolution. In retrospect, it did not work or compose very well. We understand that problem better now and the use case could be better solved without it.\n\nSee [Progression Migration](./API.md#progression-migration) for migration assistance and examples of how to convert APIs that use progression to ones that do not.\n\n#####`.progressed(Function handler)` -> `Promise`\n\n\nShorthand for [`.then(null, null, handler);`](.). Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise.\n\n\n\n#####`.then([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])` -> `Promise`\n\nThe standard [Promises/A+ `.then()`](http://promises-aplus.github.io/promises-spec/) is still supported by Bluebird and support for it will continue indefinitely. However, the variant accepting a third `progressHandler` argument is no longer supported.\n\n\n\n\n#####`.done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])` -> `void`\n\nLike [`.then()`](.), but any unhandled rejection that ends up here will be thrown as an error. Again, only the variant with the progression handler is deprecated here. `.done` is still fully supported.\n\n\n\n\n#####`.fork([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])` -> `Promise`\n\nLike [`.then()`](.), but cancellation of the returned promise or any of its descendant will not propagate cancellation to this promise or this promise's ancestors. Again, only the variant with the progression handler is deprecated here. `.fork` is still fully supported.\n\n\n\n\n##Promise resolution\n\nA `PromiseResolver` can be used to control the fate of a promise. It is like \"Deferred\" in jQuery or `$q.defer` in $q. The `PromiseResolver` objects have a `.promise` property which is a reference to the controlled promise that can be passed to clients. `.promise` of a `PromiseResolver` is not a getter function to match other implementations.\n\nThe methods of a `PromiseResolver` have no effect if the fate of the underlying promise is already decided (follow, reject, fulfill).\n\n**The use of `Promise.defer` and deferred objects is discouraged - it is much more awkward and error-prone than using `new Promise`.**\n\n\n\n#####`.resolve(dynamic value)` -> `undefined`\n\nResolve the underlying promise with `value` as the resolution value. If `value` is a thenable or a promise, the underlying promise will assume its state.\n\n\n\n#####`.reject(dynamic reason)` -> `undefined`\n\nReject the underlying promise with `reason` as the rejection reason.\n\n\n\n#####`.progress(dynamic value)` -> `undefined`\n\nProgress the underlying promise with `value` as the progression value.\n\nExample\n\n```js\nfunction delay(ms) {\n var resolver = Promise.defer();\n var now = Date.now();\n setTimeout(function() {\n resolver.resolve(Date.now() - now);\n }, ms);\n return resolver.promise;\n}\n\ndelay(500).then(function(ms) {\n console.log(ms + \" ms passed\");\n});\n```\n\n\n"
},
{
"path": "docs/docs/download-api-reference.md",
"content": "---\nid: download-api-reference\ntitle: Download API Reference\n---\n\nIn order to use the documentation offline (without a stable internet connection).\n\n - Go to [the GitHub Pages Branch `gh-pages`](https://github.com/petkaantonov/bluebird/tree/gh-pages).\n - Click \"Clone Or Download\".\n - Click \"Download Zip\".\n - Extract the contents of the zip and open the \"docs\" folder.\n - Open `api-reference.html` which is the documentation root.\n"
},
{
"path": "docs/docs/error-explanations.md",
"content": "---\nid: error-explanations\ntitle: Error Explanations\n---\n\n - [Error: Promise.promisify called on an object](#error-promise.promisify-called-on-an-object)\n - [Error: the promise constructor requires a resolver function](#error-the-promise-constructor-requires-a-resolver-function)\n - [Error: the promise constructor cannot be invoked directly](#error-the-promise-constructor-cannot-be-invoked-directly)\n - [Error: expecting an array, a promise or a thenable](#error-expecting-an-array-a-promise-or-a-thenable)\n - [Error: generatorFunction must be a function](#error-generatorfunction-must-be-a-function)\n - [Error: fn must be a function](#error-fn-must-be-a-function)\n - [Error: cannot enable long stack traces after promises have been created](#error-cannot-enable-long-stack-traces-after-promises-have-been-created)\n - [Error: cannot get fulfillment value of a non-fulfilled promise](#error-cannot-get-fulfillment-value-of-a-non-fulfilled-promise)\n - [Error: cannot get rejection reason of a non-rejected promise](#error-cannot-get-rejection-reason-of-a-non-rejected-promise)\n - [Error: the target of promisifyAll must be an object or a function](#error-the-target-of-promisifyall-must-be-an-object-or-a-function)\n - [Error: circular promise resolution chain](#error-circular-promise-resolution-chain)\n - [Error: cannot await properties of a non-object](#error-cannot-await-properties-of-a-non-object)\n - [Error: expecting a positive integer](#error-expecting-a-positive-integer)\n - [Error: A value was yielded that could not be treated as a promise](#error-a-value-was-yielded-that-could-not-be-treated-as-a-promise)\n - [Error: cannot await properties of a non object](#error-cannot-await-properties-of-a-non-object)\n - [Error: Cannot promisify an API that has normal methods](#error-cannot-promisify-an-api-that-has-normal-methods)\n - [Error: Catch filter must inherit from Error or be a simple predicate function](#error-catch-filter-must-inherit-from-error-or-be-a-simple-predicate-function)\n - [Error: No async scheduler available](#error-no-async-scheduler-available)\n\n\n## Error: Promise.promisify called on an object\n\n\nYou got this this error because you've used `Promise.promisify` on an object, for example:\n\n```js\nvar fs = Promise.promisify(require(\"fs\"));\n```\n\nInstead, use [`Promise.promisifyAll`](.) :\n\n```js\nvar fs = Promise.promisifyAll(require(\"fs\"));\n```\n\n## Error: the promise constructor requires a resolver function\n\nYou got this error because you used `new Promise()` or `new Promise(something)` without passing a function as the parameter.\n\nIf you want to wrap an API with a promise manually, the correct syntax is:\n\n```js\nfunction wrapWithPromise(parameter) {\n return new Promise(function (resolve, reject) {\n doSomethingAsync({\n error:reject,\n success:resolve\n });\n });\n}\n```\n\nPlease consider reading about [new Promise](.) and also consider checking out automatic [promisification](.) as well as [Promise.method](.)\n\n## Error: the promise constructor cannot be invoked directly\n\nYou can get this error for several reasons:\n\n#### 1. You forgot to use `new` when creating a new promise using `new Promise(resolver)` syntax.\n\nThis can happen when you tried to do something like:\n\n return Promise(function(resolve,reject){\n //...\n })\n\nYou can correct this by doing:\n\n return new Promise(function(resolve,reject){\n //...\n })\n\nPlease consider reading about [new Promise](.) and also consider checking out automatic [promisification](.) as well as [Promise.method](.)\n\n#### 2. You are trying to subclass `Promise`\n\nBluebird does not support extending promises this way. Instead, see [scoped prototypes](features.html#scoped-prototypes).\n\n## Error: expecting an array, a promise or a thenable\n\nThe function being called expects a Promise, but is given something different. There are two main reasons why this may occur.\n\n**1. Working with collections (like arrays) but pass a single, non-collection element instead**\n\nExample:\n\n```js\nfunction returnThree(){ return 3;}\n\nPromise.resolve(5).map(returnThree).then(function(val){\n console.log(\"Hello Value!\",val); \n});\n```\n\nThe `map` operation is expecting an array here (or a promise on one) and instead gets the number `5`.\n\n```js\nfunction returnThree(){ return 3;}\n\nPromise.resolve([5]).map(returnThree).then(function(val){\n console.log(\"Hello Value!\",val); \n});\n```\n```map``` is given an array with a single element (see ```[5]``` instead of ```5```), so this statement will work (but is bad practice).\n\n---\n\n**2.```return``` is forgotten in a 'fat' arrow / anonymous function call ```=>```:**\n\nWhen debugging or performing a one-time operation on a variable before passing it to a function, a return variable is forgotten.\n\nExample:\n\n```js\nfunction nextFunction(something){ return Promise.resolve(something*3); }\n\nmyFunction()\n .then(result => nextFunction(result)); // We are implicitly returning a Promise\n```\n\nDebugging, we want to see the value of result, so we add a ```console.log()``` line:\n\n```js\nfunction nextFunction(something){ return Promise.resolve(something*3); }\n\nmyFunction().then(result => {\n console.log(\"Debug:\", result);\n nextFunction(result)); // The chain is broken! We don't return anything to the .then() call\n});\n```\n\nAs this is an anonymous function call, we need to **return** something, which is not currently happening.\n\nTo fix, simply remember to add ```return``` in front of your promise-complying function:\n\n```js\nfunction nextFunction(something){ return Promise.resolve(something*3); }\n\nmyFunction().then(result => {\n console.log(\"Debug:\", result);\n return nextFunction(result)); // The anonymous function returns the function which returns the promise .then() needs\n});\n```\n\n\n## Error: generatorFunction must be a function\n\nYou are getting this error when trying to use [Promise.coroutine](.) and not passing it a generator function as a parameter. For example:\n\n```js\nPromise.coroutine(function* () { // Note the *\n var data = yield $.get(\"http://www.example.com\");\n var moreUrls = data.split(\"\\n\");\n var contents = [];\n for( var i = 0, len = moreUrls.length; i < len; ++i ) {\n contents.push(yield $.get(moreUrls[i]));\n }\n return contents;\n});\n```\n\nPlease refer to the relevant section in the documentation about [Generators](.) in order to get usage instructions:\n\n**Note**: Bluebird used to eagerly check for generators which caused problems with transpilers. Because of this, you might get an error similar to `TypeError: Cannot read property 'next' of undefined` if you pass a function instead of a generator function to Bluebird.\n\n[Promise.coroutine](.) is built to work with generators to form C# like `async/await`\n\n## Error: fn must be a function\n\nYou passed a non-function where a function was expected.\n\n## Error: cannot enable long stack traces after promises have been created\n\nYou are getting this error because you are enabling long stack traces after a promise has already been created.\n\nWhen using `longStackTraces` the first line in your code after requiring Bluebird should be:\n\n```js\nPromise.config({\n longStackTraces: true\n});\n```\n\nSee the API page about [Promise.longStackTraces](.)\n\n## Error: cannot get fulfillment value of a non-fulfilled promise\n\nYou can get this error when you're trying to call `.value` or `.error` when inspecting a promise where the promise has not been fulfilled or rejected yet.\n\nFor example:\n\n```js\nvar p = Promise.delay(1000);\np.inspect().value();\n```\n\nConsider using [.isPending()](.) [.isFulfilled()](.) and [.isRejected()](.) in order to inspect the promise for status.\n\nPlease consider reading more about [synchronous inspection](.)\n\n## Error: cannot get rejection reason of a non-rejected promise\n\nYou can get this error when you're trying to call `.value` or `.error` when inspecting a promise where the promise has not been fulfilled or rejected yet.\n\nFor example:\n\n```js\nvar p = Promise.delay(1000);\np.inspect().value();\n```\n\nConsider using [.isPending()](.) [.isFulfilled()](.) and [.isRejected()](.) in order to inspect the promise for status.\n\nPlease consider reading more about [synchronous inspection](.)\n\n\n##Error: the target of promisifyAll must be an object or a function\n\nThis can happen when you are calling [Promise.promisifyAll](.) on a function and invoking it instead of passing it.\n\nIn general, the usage of [Promise.promisifyAll](.) is along the lines of `var fs = Promise.promisifyAll(require(\"fs\"))`.\n\nConsider reading the section about [promisification](.)\n\n## Error: circular promise resolution chain\n\nThis usually happens when you have a promise that resolves or rejects with itself.\n\nFor example: `var p = Promise.delay(100).then(function(){ return p});` .\n\nIn this case, the promise resolves with itself which was is not intended.\n\nThis also happens when implementing live-updating models with a `.then` method that indicates when the model is \"ready\". A promise is a process, it starts and it ends.\n\nPromises do not aim to solve such live updating problems directly. One option would be to use an intermediate promise - for example a `.loaded` property on the model that fulfills with nothing.\n\nresolving it with itself tells it \"it is done when it is done\"\n\n## Error: cannot await properties of a non-object\n\nThe `.props` method expects to receive an object.\n\nFor example:\n\n```js\nPromise.props({\n pictures: getPictures(),\n comments: getComments(),\n tweets: getTweets()\n}).then(function(result){\n console.log(result.tweets, result.pictures, result.comments);\n});\n```\n\nThis happens when a non object value or a promise that resolves with something that is not an object is being passed instead.\n\n## Error: expecting a positive integer\n\nThis happens when you call `.some` passing it a negative value or a non-integer.\n\nOne possible cause is using `.indexOf` which returns `-1` when it doesn't find the value being searched for.\n\nPlease consider reading the API docs for [`.some`](.)\n\n## Error: A value was yielded that could not be treated as a promise\n\nYou are getting this error because you have tried to `yield` something in a coroutine without a yield handler, for example:\n\n```js\nvar coroutine = Promise.coroutine(function*(){\n var bar = yield \"Foo\";\n console.log(bar);\n});\n```\n\nThe solution is to either convert it to a promise by calling `Promise.resolve` on it or `Promise.promisify` if it's a callback:\n\n```js\nvar coroutine = Promise.coroutine(function*(){\n var bar = yield Promise.resolve(\"Foo\");\n console.log(bar);\n});\n```\n\nOr to use [Promise.coroutine.addYieldHandler`](.) to teach [Promise.coroutine](.) to accept these sort of values.\n\n## Error: cannot await properties of a non object\n\nThe `.props` method expects to receive an object.\n\nFor example:\n\n```js\nPromise.props({\n pictures: getPictures(),\n comments: getComments(),\n tweets: getTweets()\n}).then(function(result){\n console.log(result.tweets, result.pictures, result.comments);\n});\n```\n\nThis happens when a non object value or a promise that resolves with something that is not an object is being passed instead.\n\n\n## Error: Cannot promisify an API that has normal methods\n\nThis error indicates you have tried to call [Promise.promisifyAll](.) on an object that already has a property with the `Async` suffix:\n\n```js\nvar myApi = { foo: function(cb){ ... }, fooAsync(cb) { ... }\n```\n\nThis is because Bluebird adds the `Async` suffix to distinguish the original method from the promisified one, so `fooAsync` would have been overridden. In order to avoid this - either rename `fooAsync` before promisifying the API, or call [Promise.promisify](.) manually on select properties.\n\nYou may also use the custom suffix option to choose another suffix that doesn't result in conflicts.\n\nIf you find this issue in a common library please [open an issue](https://github.com/petkaantonov/bluebird/issues/new).\n\n## Error: Catch filter must inherit from Error or be a simple predicate function\n\nBluebird supports typed and predicate [.catch()](.) calls]. However in order to use the typed/predicate catch syntax for error handling you must do one of two things.\n\nPass it a constructor that inherits from `Error`:\n\n }).catch(ReferenceError, function(e) { // this is fine\n }).catch(Array, function(e) { // arrays don't capture stack traces\n\nThis is to enable better stack trace support and to have more consistent and logical code.\n\nAlternatively, if you provide it a predicate be sure it's a simple function:\n\n }).catch(function(e){ return false; }, function(e) { // this catches nothing\n }).catch(function(e){ return e.someProp = 5; }, function(e) { // this is fine\n\nPlease see the API docs of [.catch()](.) on how to use predicate catches.\n\n## Error: No async scheduler available\n\nAsync scheduler is a function that takes a callback function and calls the callback function as soon as possible, but asynchronously. For example `setTimeout`.\n\nBy default bluebird only tries a few common async schedulers, such as `setTimeout`, `process.nextTick` and `MutationObserver`. However if your JavaScript runtime environment doesn't expose any of these, you will see this error.\n\nYou may use [Promise.setScheduler](.) to pass a custom scheduler that your environment supports. For example in DukTape:\n\n```js\nPromise.setScheduler(function(fn){ // fn is what to execute\n var timer = uv.new_timer.call({});\n uv.timer_start(timer, 0, 0, fn); // add the function as a callback to the timer\n});\n```\n\n\n\n\n"
},
{
"path": "docs/docs/features.md",
"content": "---\nid: features\ntitle: Features\n---\n\n[features](unfinished-article)\n\n\n- [Synchronous inspection](#synchronous-inspection)\n- [Concurrency coordination](#concurrency-coordination)\n- [Promisification on steroids](#promisification-on-steroids)\n- [Debuggability and error handling](#debuggability-and-error-handling)\n- [Resource management](#resource-management)\n- [Cancellation and timeouts](#cancellation-and-timeouts)\n- [Scoped prototypes](#scoped-prototypes)\n- [Promise monitoring](#promise-monitoring)\n- [Async/Await](#async-await)\n\n##Synchronous inspection\n\nSynchronous inspection allows you to retrieve the fulfillment value of an already fulfilled promise or the rejection reason of an already rejected promise synchronously.\n\nOften it is known in certain code paths that a promise is guaranteed to be fulfilled at that point - it would then be extremely inconvenient to use [`.then`](.) to get at the promise's value as the callback is always called asynchronously.\n\nSee the API on [synchronous inspection](.) for more information.\n\n##Concurrency coordination\n\nThrough the use of [.each](.) and [.map](.) doing things just at the right concurrency level becomes a breeze.\n\n##Promisification on steroids\n\nPromisification means converting an existing promise-unaware API to a promise-returning API.\n\nThe usual way to use promises in node is to [Promise.promisifyAll](.) some API and start exclusively calling promise returning versions of the APIs methods. E.g.\n\n```js\nvar fs = require(\"fs\");\nPromise.promisifyAll(fs);\n// Now you can use fs as if it was designed to use bluebird promises from the beginning\n\nfs.readFileAsync(\"file.js\", \"utf8\").then(...)\n```\n\nNote that the above is an exceptional case because `fs` is a singleton instance. Most libraries can be promisified by requiring the library's classes (constructor functions) and calling promisifyAll on the `.prototype`. This only needs to be done once in the entire application's lifetime and after that you may use the library's methods exactly as they are documented, except by appending the `\"Async\"`-suffix to method calls and using the promise interface instead of the callback interface.\n\nAs a notable exception in `fs`, `fs.existsAsync` doesn't work as expected, because Node's `fs.exists` doesn't call back with error as first argument. More at [#418](.). One possible workaround is using `fs.statAsync`.\n\nSome examples of the above practice applied to some popular libraries:\n\n```js\n// The most popular redis module\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"redis\"));\n```\n\n```js\n// The most popular mongodb module\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mongodb\"));\n```\n\n```js\n// The most popular mysql module\nvar Promise = require(\"bluebird\");\n// Note that the library's classes are not properties of the main export\n// so we require and promisifyAll them manually\nPromise.promisifyAll(require(\"mysql/lib/Connection\").prototype);\nPromise.promisifyAll(require(\"mysql/lib/Pool\").prototype);\n```\n\n```js\n// Mongoose\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mongoose\"));\n```\n\n```js\n// Request\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"request\"));\n// Use request.getAsync(...) not request(..), it will not return a promise\n```\n\n```js\n// mkdir\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mkdirp\"));\n// Use mkdirp.mkdirpAsync not mkdirp(..), it will not return a promise\n```\n\n```js\n// winston\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"winston\"));\n```\n\n```js\n// rimraf\nvar Promise = require(\"bluebird\");\n// The module isn't promisified but the function returned is\nvar rimrafAsync = Promise.promisify(require(\"rimraf\"));\n```\n\n```js\n// xml2js\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"xml2js\"));\n```\n\n```js\n// jsdom\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"jsdom\"));\n```\n\n```js\n// fs-extra\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"fs-extra\"));\n```\n\n```js\n// prompt\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"prompt\"));\n```\n\n```js\n// Nodemailer\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"nodemailer\"));\n```\n\n```js\n// ncp\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"ncp\"));\n```\n\n```js\n// pg\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"pg\"));\n```\n\nIn all of the above cases the library made its classes available in one way or another. If this is not the case, you can still promisify by creating a throwaway instance:\n\n```js\nvar ParanoidLib = require(\"...\");\nvar throwAwayInstance = ParanoidLib.createInstance();\nPromise.promisifyAll(Object.getPrototypeOf(throwAwayInstance));\n// Like before, from this point on, all new instances + even the throwAwayInstance suddenly support promises\n```\n\nSee also [`Promise.promisifyAll`](.).\n\n##Debuggability and error handling\n\n - [Surfacing unhandled errors](#surfacing-unhandled-errors)\n - [Long stack traces](#long-stack-traces)\n - [Error pattern matching](#error-pattern-matching)\n - [Warnings](#warnings)\n\n###Surfacing unhandled errors\n\nThe default approach of bluebird is to immediately log the stack trace when there is an unhandled rejection. This is similar to how uncaught exceptions cause the stack trace to be logged so that you have something to work with when something is not working as expected.\n\nHowever because it is possible to handle a rejected promise at any time in the indeterminate future, some programming patterns will result in false positives. Because such programming patterns are not necessary and can always be refactored to never cause false positives, we recommend doing that to keep debugging as easy as possible . You may however feel differently so bluebird provides hooks to implement more complex failure policies.\n\nSuch policies could include:\n\n- Logging after the promise became GCd (requires a native node.js module)\n- Showing a live list of rejected promises\n- Using no hooks and using [`.done`](.) to manually to mark end points where rejections will not be handled\n- Swallowing all errors (challenge your debugging skills)\n- ...\n\nSee [global rejection events](http://bluebirdjs.com/docs/api/error-management-configuration.html#global-rejection-events) to learn more about the hooks.\n\n###Long stack traces\n\nNormally stack traces don't go beyond asynchronous boundaries so their utility is greatly reduced in asynchronous code:\n\n```js\nsetTimeout(function() {\n setTimeout(function() {\n setTimeout(function() {\n a.b.c;\n }, 1);\n }, 1)\n}, 1)\n```\n\n```\nReferenceError: a is not defined\n at null._onTimeout file.js:4:13\n at Timer.listOnTimeout (timers.js:90:15)\n```\n\nOf course you could use hacks like monkey patching or domains but these break down when something can't be monkey patched or new apis are introduced.\n\nSince in bluebird [promisification](.) is made trivial, you can get long stack traces all the time:\n\n```js\nvar Promise = require(\"bluebird\");\n\nPromise.delay(1)\n .delay(1)\n .delay(1).then(function() {\n a.b.c;\n });\n```\n\n```\nUnhandled rejection ReferenceError: a is not defined\n at file.js:6:9\n at processImmediate [as _immediateCallback] (timers.js:321:17)\nFrom previous event:\n at Object. (file.js:5:15)\n at Module._compile (module.js:446:26)\n at Object.Module._extensions..js (module.js:464:10)\n at Module.load (module.js:341:32)\n at Function.Module._load (module.js:296:12)\n at Function.Module.runMain (module.js:487:10)\n at startup (node.js:111:16)\n at node.js:799:3\n```\n\nAnd there is more. Bluebird's long stack traces additionally eliminate cycles, don't leak memory, are not limited to a certain amount of asynchronous boundaries and are fast enough for most applications to be used in production. All these are non-trivial problems that haunt straight-forward long stack trace implementations.\n\nSee [installation](install.html) on how to enable long stack traces in your environment.\n\n###Error pattern matching\n\nPerhaps the greatest thing about promises is that it unifies all error handling into one mechanism where errors propagate automatically and have to be explicitly ignored.\n\n###Warnings\n\nPromises can have a steep learning curve and it doesn't help that promise standards go out of their way to make it even harder. Bluebird works around the limitations by providing warnings where the standards disallow throwing errors when incorrect usage is detected. See [Warning Explanations](warning-explanations.html) for the possible warnings that bluebird covers.\n\nSee [installation](install.html) on how to enable warnings in your environment.\n\nNote - in order to get full stack traces with warnings in Node 6.x+ you need to enable to `--trace-warnings` flag which will give you a full stack trace of where the warning is coming from.\n\n###Promise monitoring\n\nThis feature enables subscription to promise lifecycle events via standard global events mechanisms in browsers and Node.js.\n\nThe following lifecycle events are available: \n\n - `\"promiseCreated\"` - Fired when a promise is created through the constructor.\n - `\"promiseChained\"` - Fired when a promise is created through chaining (e.g. [.then](.)).\n - `\"promiseFulfilled\"` - Fired when a promise is fulfilled.\n - `\"promiseRejected\"` - Fired when a promise is rejected.\n - `\"promiseResolved\"` - Fired when a promise adopts another's state.\n - `\"promiseCancelled\"` - Fired when a promise is cancelled.\n\nThis feature has to be explicitly enabled by calling [Promise.config](.) with `monitoring: true`.\n\nThe actual subscription API depends on the environment.\n\n1\\. In Node.js, use `process.on`:\n\n```js\n// Note the event name is in camelCase, as per Node.js convention.\nprocess.on(\"promiseChained\", function(promise, child) {\n // promise - The parent promise the child was chained from\n // child - The created child promise.\n});\n```\n\n2\\. In modern browsers use `window.addEventListener` (window context) or `self.addEventListener()` (web worker or window context) method:\n\n```js\n// Note the event names are in mashedtogetherlowercase, as per DOM convention.\nself.addEventListener(\"promisechained\", function(event) {\n // event.details.promise - The parent promise the child was chained from\n // event.details.child - The created child promise.\n});\n```\n\n3\\. In legacy browsers use `window.oneventname = handlerFunction;`.\n\n```js\n// Note the event names are in mashedtogetherlowercase, as per legacy convention.\nwindow.onpromisechained = function(promise, child) {\n // event.details.promise - The parent promise the child was chained from\n // event.details.child - The created child promise.\n};\n```\n\n##Resource management\n\n##Cancellation and timeouts\n\nSee [`Cancellation`](.) for how to use cancellation.\n\n```js\n// Enable cancellation\nPromise.config({cancellation: true});\n\nvar fs = Promise.promisifyAll(require(\"fs\"));\n\n// In 2000ms or less, load & parse a file 'config.json'\nvar p = Promise.resolve('./config.json')\n .timeout(2000)\n .catch(console.error.bind(console, 'Failed to load config!'))\n .then(fs.readFileAsync)\n .then(JSON.parse);\n// Listen for exception event to trigger promise cancellation\nprocess.on('unhandledException', function(event) {\n // cancel config loading\n p.cancel();\n});\n```\n\n##Scoped prototypes\n\nBuilding a library that depends on bluebird? You should know about the \"scoped prototype\" feature.\n\nIf your library needs to do something obtrusive like adding or modifying methods on the `Promise` prototype, uses long stack traces or uses a custom unhandled rejection handler then... that's totally ok as long as you don't use `require(\"bluebird\")`. Instead you should create a file\nthat creates an isolated copy. For example, creating a file called `bluebird-extended.js` that contains:\n\n```js\n //NOTE the function call right after\nmodule.exports = require(\"bluebird/js/main/promise\")();\n```\n\nYour library can then use `var Promise = require(\"bluebird-extended\");` and do whatever it wants with it. Then if the application or other library uses their own bluebird promises they will all play well together because of Promises/A+ thenable assimilation magic.\n\n\n##Async/Await\n\n"
},
{
"path": "docs/docs/getting-started.md",
"content": "---\nid: getting-started\ntitle: Getting Started\nredirect_from: \"/index.html\"\nredirect_from: \"/docs/index.html\"\n---\n\n[getting-started](unfinished-article)\n\n## Node.js\n\n npm install bluebird\n\nThen:\n\n```js\nvar Promise = require(\"bluebird\");\n```\n\nAlternatively in ES6 \n\n```js\nimport * as Promise from \"bluebird\";\n```\n\nIf that ES6 import [doesn't work](https://github.com/petkaantonov/bluebird/pull/1594)\n\n```js\nimport {Promise} from \"bluebird\";\n```\n\n## Browsers\n\n(See also [Installation](install.html).)\n\nThere are many ways to use bluebird in browsers:\n\n- Direct downloads\n - Full build [bluebird.js](https://cdn.jsdelivr.net/bluebird/latest/bluebird.js)\n - Full build minified [bluebird.min.js](https://cdn.jsdelivr.net/bluebird/latest/bluebird.min.js)\n - Core build [bluebird.core.js](https://cdn.jsdelivr.net/bluebird/latest/bluebird.core.js)\n - Core build minified [bluebird.core.min.js](https://cdn.jsdelivr.net/bluebird/latest/bluebird.core.min.js)\n- You may use browserify on the main export\n- You may use the [bower](http://bower.io) package.\n\nWhen using script tags the global variables `Promise` and `P` (alias for `Promise`) become available. Bluebird runs on a wide variety of browsers including older versions. We'd like to thank BrowserStack for giving us a free account which helps us test that. \n"
},
{
"path": "docs/docs/install.md",
"content": "---\nid: install\ntitle: Installation\n---\n\n- [Browser installation](#browser-installation)\n- [Node installation](#node-installation)\n- [Supported platforms](#supported-platforms)\n\n##Browser installation\n\nDownload bluebird {{ site.version }} (development)\n\nUnminified source file meant to be used in development. Warnings and long stack traces are enabled which are taxing on performance.\n\n```html\n\n```\n\nDownload bluebird {{ site.version }} (production)\n\nMinified source file meant to be used in production. Warnings and long straces are disabled. The gzipped size is 17.76KB.\n\n```html\n\n```\n\nUnless an AMD loader is installed, the script tag installation exposes the library in the `Promise` and `P` namespaces. If you want to restore the `Promise` namespace, use `var Bluebird = Promise.noConflict()`.\n\n###Bower\n\n```\n$ bower install --save bluebird\n```\n\n###Browserify and Webpack\n\n```\n$ npm install bluebird\n```\n\nUsing webpack for development/debugging:\n\n```js\nvar Promise = require(\"bluebird\");\n// Configure webpack and browserify for development/debugging\nPromise.config({\n longStackTraces: true,\n warnings: true // note, run node with --trace-warnings to see full stack traces for warnings\n})\n```\n\nUsing webpack for production/performance:\n\n\n```js\nvar Promise = require(\"bluebird\");\n// Configure webpack and browserify for production/performance\nPromise.config({\n longStackTraces: false,\n warnings: false\n})\n```\n\n##Node installation\n\n```\n$ npm install bluebird\n```\n\n```js\nvar Promise = require(\"bluebird\");\n```\n\nTo enable long stack traces and warnings in node development:\n\n```\n$ NODE_ENV=development node server.js\n```\n\nTo enable long stack traces and warnings in node production:\n\n```\n$ BLUEBIRD_DEBUG=1 node server.js\n```\n\nSee [Environment Variables](.).\n\n##Supported platforms\n\nBluebird officially supports and is tested on node.js, iojs and browsers starting from IE7. Unofficial platforms are supported with best effort only.\n\nIE7 and IE8 do not support using keywords as property names, so if supporting these browsers is required you need to use the compatibility aliases:\n\n\n- [`Promise.try()`](.) -> `Promise.attempt()`\n- [`.catch()`](.) -> `.caught()`\n- [`.finally()`](.) -> `.lastly()`\n- [`.return()`](.) -> `.thenReturn()`\n- [`.throw()`](.) -> `.thenThrow()`\n\nLong stack traces are only supported in Chrome, recent Firefoxes and Internet Explorer 10+\n\n[](https://saucelabs.com/u/petka_antonov)\n"
},
{
"path": "docs/docs/new-in-bluebird-3.md",
"content": "---\nid: new-in-bluebird-3\ntitle: New in bluebird 3.0\n---\n\n##Cancellation overhaul\n\nCancellation has been redesigned for bluebird 3.0. Any code that relies on 2.x cancellation semantics won't work in 3.0 or later. See [Cancellation](.) for more information.\n\n##Promisification API changes\n\nBoth promisification \\([Promise.promisify](.) and [Promise.promisifyAll](.)\\) methods and [Promise.fromCallback](.) now by default ignore multiple arguments passed to the callback adapter and instead only the first argument is used to resolve the promise. The behavior in 2.x is to construct an array of the arguments and resolve the promise with it when more than one argument is passed to the callback adapter. The problems with this approach and reasons for the change are discussed in [#307](.).\n\n[Promise.promisify](.)'s second argument is now an options object, so any code using the second argument needs to change:\n\n```js\n// 2.x\nPromise.promisify(fn, ctx);\n// 3.0\nPromise.promisify(fn, {context: ctx});\n```\n\nBoth promisification \\([Promise.promisify](.) and [Promise.promisifyAll](.)\\) methods and [Promise.fromCallback](.) all take a new boolean option `multiArgs` which defaults to `false`. Enabling this option will make the adapter callback *always* construct an array of the passed arguments regardless of amount of arguments. This can be used to reliably get access to all arguments rather than just the first one.\n\n##Collection method changes\n\nAll collection methods now support objects that implement [ES6's *iterable*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) protocol along with regular arrays.\n\n[Promise.props](.) and [.props](.) now support [ES6 `Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) objects along with normal objects. Actual `Map` objects are only considered for their entries in the map instead of both entries and properties.\n\n\n##Warnings\n\nWarnings have been added to report usages which are very likely to be programmer errors. See [Promise.config](.) for how to enable warnings. See [Warning Explanations](warning-explanations.html) for list of the warnings and their explanations.\n\n##Feature additions\n\n- [.catch\\(\\)](.) now supports an object predicate as a filter: `.catch({code: 'ENOENT'}, e => ...)`.\n- Added [.suppressUnhandledRejections\\(\\)](.).\n- Added [.catchThrow\\(\\)](.).\n- Added [.catchReturn\\(\\)](.).\n- Added [Promise.mapSeries\\(\\)](.) and [.mapSeries\\(\\)](.)\n\n##Deprecations\n\n- `Promise.settle` has been deprecated. Use [.reflect](.) instead.\n- `Promise.spawn` has been deprecated. Use [Promise.coroutine](.) instead.\n- [Promise.try](.)'s `ctx` and `arg` arguments have been deprecated.\n- `.nodeify` is now better known as [.asCallback](.)\n- `.fromNode` is now better known as [Promise.fromCallback](.)\n\n\n##Summary of breaking changes\n\n- Promisifier APIs.\n- Cancellation redesign.\n- Promise progression has been completely removed.\n- [.spread](.)'s second argument has been removed.\n- [.done](.) causes an irrecoverable fatal error in Node.js environments now. See [#471](.) for rationale.\n- Errors created with [Promise.reject](.) or `reject` callback of [new Promise](.) are no longer marked as [OperationalError](.)s.\n\n##3.0.1 update\n\nNote that the 3.0.1 update is strictly speaking backward-incompatible with 3.0.0. Version 3.0.0 changed the previous behavior of the `.each` method and made it work the same as the new `.mapSeries` - 3.0.1 unrolls this change by reverting to the `.tap`-like behavior found in 2.x However, this would only affect users who updated to 3.0.0 during the short time that it wasn't deprecated and started relying on the new `.each` behavior. This seems unlikely, and therefore the major version was not changed.\n"
},
{
"path": "docs/docs/support.md",
"content": "---\nid: support\ntitle: Support\n---\n\nDepending on the nature of your problem there are a few possible ways of getting help with your problem.\n\n###Stack Overflow\n\nStack Overflow has an active community answering questions on both the [bluebird](http://stackoverflow.com/questions/tagged/bluebird) and [promise](http://stackoverflow.com/questions/tagged/promise) tags. If you are unfamiliar with Stack Overflow, do review [the asking guidelines](http://stackoverflow.com/help/asking) before asking a new question there.\n\n###Google Groups mailing list\n\nThe [bluebird-js@googlegroups.com](https://groups.google.com/forum/#!forum/bluebird-js) mailing list is the best place to ask any question that cannot be easily fit in the stack overflow question format.\n\n###IRC\n\nYou can usually get fast answers on the freenode.net channels [#bluebird](irc://chat.freenode.net/bluebird) and [#promises](irc://chat.freenode.net/promises).\n\n###Gitter\n\nIf you are not comfortable using IRC you can also join the [bluebird gitter chat](https://gitter.im/petkaantonov/bluebird)\n\n###Github issue tracker\n\nIf you feel that your problem is caused by a bug or a missing feature that should be added, you should use the [Github issue tracker](https://github.com/petkaantonov/bluebird/issues/) to report it. However in any other case the issue tracker is not the appropriate channel.\n"
},
{
"path": "docs/docs/warning-explanations.md",
"content": "---\nid: warning-explanations\ntitle: Warning Explanations\n---\n\n[warning-explanations](unfinished-article)\n\n - [Warning: .then() only accepts functions](#warning-then-only-accepts-functions)\n - [Warning: a promise was rejected with a non-error](#warning-a-promise-was-rejected-with-a-non-error)\n - [Warning: a promise was created in a handler but was not returned from it](#warning-a-promise-was-created-in-a-handler-but-was-not-returned-from-it)\n\nNote - in order to get full stack traces with warnings in Node 6.x+ you need to enable to `--trace-warnings` flag which will give you a full stack trace of where the warning is coming from.\n\n## Warning: .then() only accepts functions\n\nIf you see this warning your code is probably not doing what you expect it to, the most common reason is passing the *result* of calling a function to [.then()](.) instead of the function *itself*:\n\n```js\nfunction processImage(image) {\n // Code that processes image\n}\n\ngetImage().then(processImage());\n```\n\nThe above calls the function `processImage()` *immediately* and passes the result to [.then()](.) (which is most likely `undefined` - the default return value when a function doesn't return anything).\n\nTo fix it, simply pass the function reference to [.then()](.) as is:\n\n```js\ngetImage().then(processImage)\n```\n\n*If you are wondering why this is a warning and not a simple TypeError it is because the due to historic reasons Promises/A+ specification requires that incorrect usage is silently ignored.*\n\n## Warning: a promise was rejected with a non-error\n\nDue to a historic mistake in JavaScript, the `throw` statement is allowed to be used with any value, not just errors, and Promises/A+ choosing to inherit this mistake, it is possible to reject a promise with a value that is not an error.\n\nAn error is an object that is a `instanceof Error`. It will at minimum have the properties `.stack` and `.message`, which are an absolute *must* have for any value that is being used in an automatic propagation mechanism, such as exceptions and rejections. This is because errors are usually handled many levels above where they actually originate - the error object must have sufficient metadata about it so that its ultimate handler (possibly many levels above) will have all the information needed for creating a useful high level error report.\n\nSince all objects support having properties you might still wonder why exactly does it have to be an error object and not just any object. In addition to supporting properties, an equally important feature necessary for values that are automatically propagated is the stack trace property (`.stack`). A stack trace allows you easily find where an error originated from as it gives the code's call stack - along with line numbers for reference in code files.\n\nYou should heed this warning because rejecting a promise with a non-error makes debugging extremely hard and costly. Additionally, if you reject with simple primitives such as `undefined` (commonly caused by simply calling `reject()`) you cannot handle errors at all because it's impossible to tell from `undefined` what exactly went wrong. All you can tell the user is that \"something went wrong\" and lose them forever.\n\n\n## Warning: a promise was created in a handler but was not returned from it\n\nThis usually means that you simply forgot a `return` statement somewhere, which will cause a runaway promise that is not connected to any promise chain.\n\nFor example:\n\n```js\ngetUser().then(function(user) {\n getUserData(user);\n}).then(function(userData) {\n // userData is undefined\n});\n```\n\nBecause the result of `getUserData()` is not returned from the first then handler, it becomes a runaway promise that is not awaited for by the second then. The second [.then()](.) simply gets immediately called with `undefined` (because `undefined` is the default return value when you don't return anything).\n\nTo fix it, you need to `return` the promise:\n\n```js\ngetUser().then(function(user) {\n return getUserData(user);\n}).then(function(userData) {\n // userData is the user's data\n});\n```\n\n\n\nIf you know what you're doing and don't want to silence all warnings, you can create runaway promises without causing this warning by returning e.g. `null`:\n\n```js\ngetUser().then(function(user) {\n // Perform this in the \"background\" and don't care about its result at all\n saveAnalytics(user);\n // return a non-undefined value to signal that we didn't forget to return\n return null;\n});\n```\n\n\n"
},
{
"path": "docs/docs/what-about-generators.md",
"content": "---\nid: what-about-generators\ntitle: What About Generators?\n---\n\nThere is an [excellent article](https://www.promisejs.org/generators/) on promisejs.org detailing how to combine promises with generators to achieve much cleaner code. Instead of the `async` function the article proposes, you can use [Promise.coroutine](.).\n\n[what-about-generators](unfinished-article)\n"
},
{
"path": "docs/docs/why-bluebird.md",
"content": "---\nid: why-bluebird\ntitle: Why bluebird?\n---\n\nThere are many third party promise libraries available for JavaScript and even the standard library contains a promise implementation in newer versions of browsers and node/io.js. This page will explore why one might use bluebird promises over other third party or the standard library implementations. For reasons to use promises in general, see the [Why Promises?](why-promises.html) article.\n\n###Bluebird design principles\n\nBluebird is built with the following design principles in mind:\n\n - **Pragmatic and not theoretical** - Bluebird will always pick the pragmatic route vs the theoretically elegant one when there is a conflict. The library's API was created based on real-life use cases and after a lot of consideration.\n - **Fully featured without bloat** - Bluebird provides all the tools and utilities needed to realize a highly expressive and fluent DSL for asynchronous JavaScript without suffering from bloat by avoiding incorporating features that are solely motivated by theoretical arguments, have extremely narrow applicability, or have limited synergy and composability with existing features.\n - **Easy to debug** - A major consequence of choosing pragmatism over theoretical elegance, a property that is unique to bluebird among promise libraries taken to this extent.\n - Bluebird ships with the best cross-platform long stack traces out there and a warning system. This helps you recognize common and devastating promise usage mistakes early before they lead to hard to debug code later.\n - Unhandled errors are not silently swallowed by default but reported along with helpful stack traces where applicable. All of this is of course configurable.\n - **Zero overhead abstraction** - In server-side applications the performance of a promise implementation matters. Bluebird's server-side performance is measured with highly relevant and realistic end-to-end macro [benchmarks](benchmarks.html), and consistently comes out on top. We understand that if bluebird is as close to a zero cost abstraction as possible, developers won't be tempted to short-circuit and absorb complexity themselves.\n - **Runs everywhere** - Bluebird runs on pretty much every platform. This makes bluebird ideal for projects who care about providing consistent cross-platform and cross-version experience. It runs on old IE, it has even been known to run on Netscape 7.\n - **Spec compatible** - Bluebird can work as a drop-in replacement for native promises for an instant performance boost. It passes the Promises/A+ test suite and is fully spec compliant.\n\n\n\n"
},
{
"path": "docs/docs/why-performance.md",
"content": "---\nid: why-performance\ntitle: Why Performance?\n---\n\n[why-performance](unfinished-article)\n"
},
{
"path": "docs/docs/why-promises.md",
"content": "---\nid: why-promises\ntitle: Why Promises?\n---\n\nPromises are a concurrency primitive with a proven track record and language integration in most modern programming languages. They have been extensively studied since the 80s and will make your life much easier.\n\nYou should use promises to turn this:\n\n```js\nfs.readFile(\"file.json\", function (err, val) {\n if (err) {\n console.error(\"unable to read file\");\n }\n else {\n try {\n val = JSON.parse(val);\n console.log(val.success);\n }\n catch (e) {\n console.error(\"invalid json in file\");\n }\n }\n});\n```\n\nInto this:\n\n```js\nfs.readFileAsync(\"file.json\").then(JSON.parse).then(function (val) {\n console.log(val.success);\n})\n.catch(SyntaxError, function (e) {\n console.error(\"invalid json in file\");\n})\n.catch(function (e) {\n console.error(\"unable to read file\");\n});\n```\n\n*If you're thinking, \"There's no `readFileAsync` method on `fs` that returns a promise!\" see [promisification](api/promisification.html)*\n\nYou might notice that the promise approach looks very similar to using synchronous I/O:\n\n```js\ntry {\n var val = JSON.parse(fs.readFileSync(\"file.json\"));\n console.log(val.success);\n}\n// Gecko-only syntax; used for illustrative purposes\ncatch (e if e instanceof SyntaxError) {\n console.error(\"invalid json in file\");\n}\ncatch (e) {\n console.error(\"unable to read file\");\n}\n```\n\nThis is the point—to have something that works like `return` and `throw` in synchronous code.\n\nYou can also use promises to improve code that was written with callbacks:\n\n```js\n//Copyright Plato http://stackoverflow.com/a/19385911/995876\n//CC BY-SA 2.5\nmapSeries(URLs, function (URL, done) {\n var options = {};\n needle.get(URL, options, function (error, response, body) {\n if (error) {\n return done(error);\n }\n try {\n var ret = JSON.parse(body);\n return done(null, ret);\n }\n catch (e) {\n done(e);\n }\n });\n}, function (err, results) {\n if (err) {\n console.log(err);\n } else {\n console.log('All Needle requests successful');\n // results is a 1 to 1 mapping in order of URLs > needle.body\n processAndSaveAllInDB(results, function (err) {\n if (err) {\n return done(err);\n }\n console.log('All Needle requests saved');\n done(null);\n });\n }\n});\n```\n\nThis is far more readable when done with promises:\n\n```js\nPromise.promisifyAll(needle);\nvar options = {};\n\nvar current = Promise.resolve();\nPromise.map(URLs, function (URL) {\n current = current.then(function () {\n return needle.getAsync(URL, options);\n });\n return current;\n}).map(function (responseAndBody) {\n return JSON.parse(responseAndBody[1]);\n}).then(function (results) {\n return processAndSaveAllInDB(results);\n}).then(function () {\n console.log('All Needle requests saved');\n}).catch(function (e) {\n console.log(e);\n});\n```\n\nAlso, promises don't just give you correspondences for synchronous features; they can also be used as limited event emitters or callback aggregators.\n\nMore reading:\n\n - [Promise nuggets](https://promise-nuggets.github.io/)\n - [Why I am switching to promises](http://spion.github.io/posts/why-i-am-switching-to-promises.html)\n - [What is the the point of promises](http://domenic.me/2012/10/14/youre-missing-the-point-of-promises/#toc_1)\n - [Aren't Promises Just Callbacks?](http://stackoverflow.com/questions/22539815/arent-promises-just-callbacks)\n"
},
{
"path": "docs/docs/working-with-callbacks.md",
"content": "---\nid: working-with-callbacks\ntitle: Working with Callbacks\n---\n\nThis page explains how to interface your code with existing callback APIs and libraries you're using. We'll see that making bluebird work with callback APIs is not only easy - it's also fast.\n\nWe'll cover several subjects. If you want to get the tl;dr what you need is likely the [Working with callback APIs using the Node convention](#working-with-callback-apis-using-the-node-convention) section.\n\nFirst to make sure we're on the same page:\n\nPromises have state, they start as pending and can settle to:\n\n - __fulfilled__ meaning that the computation completed successfully.\n - __rejected__ meaning that the computation failed.\n\nPromise returning functions _should never throw_, they should always successfully return a promise which is rejected in the case of an error. Throwing from a promise returning function will force you to use both a `} catch { ` _and_ a `.catch`. People using promisified APIs do not expect promises to throw. If you're not sure how async APIs work in JS - please [see this answer](http://stackoverflow.com/questions/14220321/how-to-return-the-response-from-an-asynchronous-call/16825593#16825593) first.\n\n * [Automatic vs. Manual conversion](#automatic-vs.-manual-conversion)\n * [Working with callback APIs using the Node convention](#working-with-callback-apis-using-the-node-convention)\n * [Working with one time events.](#working-with-one-time-events)\n * [Working with delays](#working-with-delays/setTimeout)\n * [Working with browser APIs](#working-with-browser-apis)\n * [Working with databases](#working-with-databases)\n * [More Common Examples](#more-common-examples)\n * [Working with any other APIs](#working-with-any-other-apis)\n\nThere is also [this more general StackOverflow question](http://stackoverflow.com/questions/22519784/how-do-i-convert-an-existing-callback-api-to-promises) about conversion of callback APIs to promises. If you find anything missing in this guide however, please do open an issue or pull request.\n\n###Automatic vs. Manual conversion\n\nThere are two primary methods of converting callback based APIs into promise based ones. You can either manually map the API calls to promise returning functions or you can let the bluebird do it for you. We **strongly** recommend the latter.\n\nPromises provide a lot of really cool and powerful guarantees like throw safety which are hard to provide when manually converting APIs to use promises. Thus, whenever it is possible to use the `Promise.promisify` and `Promise.promisifyAll` methods - we recommend you use them. Not only are they the safest form of conversion - they also use techniques of dynamic recompilation to introduce very little overhead.\n\n###Working with callback APIs using the Node convention\n\nIn Node/io.js most APIs follow a convention of ['error-first, single-parameter'](https://gist.github.com/CrabDude/10907185) as such:\n\n```js\nfunction getStuff(data, callback) {\n ...\n}\n\ngetStuff(\"dataParam\", function(err, data) {\n if (!err) {\n\n }\n});\n```\n\nThis APIs are what most core modules in Node/io use and bluebird comes with a fast and efficient way to convert them to promise based APIs through the `Promise.promisify` and `Promise.promisifyAll` function calls.\n\n - [Promise.promisify](.) - converts a _single_ callback taking function into a promise returning function. It does not alter the original function and returns the modified version.\n - [Promise.promisifyAll](.) - takes an _object_ full of functions and _converts each function_ into the new one with the `Async` suffix (by default). It does not change the original functions but instead adds new ones.\n\n> **Note** - please check the linked docs for more parameters and usage examples.\n\nHere's an example of `fs.readFile` with or without promises:\n\n```js\n// callbacks\nvar fs = require(\"fs\");\nfs.readFile(\"name\", \"utf8\", function(err, data) {\n\n});\n```\n\nPromises:\n\n```js\nvar fs = Promise.promisifyAll(require(\"fs\"));\nfs.readFileAsync(\"name\", \"utf8\").then(function(data) {\n\n});\n```\n\nNote the new method is suffixed with `Async`, as in `fs.readFileAsync`. It did not replace the `fs.readFile` function. Single functions can also be promisified for example:\n\n```js\nvar request = Promise.promisify(require(\"request\"));\nrequest(\"foo.bar\").then(function(result) {\n\n});\n```\n\n> **Note** `Promise.promisify` and `Promise.promisifyAll` use dynamic recompilation for really fast wrappers and thus calling them should be done only once. [Promise.fromCallback](.) exists for cases where this is not possible.\n\n###Working with one time events\n\nSometimes, we want to find out when a single one time event has finished. For example - a stream is done. For this we can use [new Promise](.). Note that this option should be considered only if [automatic conversion](#working-with-callback-apis-using-the-node-convention) isn't possible.\n\nNote that promises model a _single value through time_, they only resolve _once_ - so while they're a good fit for a single event, they are not recommended for multiple event APIs.\n\nFor example, let's say you have a window `onload` event you want to bind to. We can use the promise construction and resolve when the window has loaded as such:\n\n```js\n// onload example, the promise constructor takes a\n// 'resolver' function that tells the promise when\n// to resolve and fire off its `then` handlers.\nvar loaded = new Promise(function(resolve, reject) {\n window.addEventListener(\"load\", resolve);\n});\n\nloaded.then(function() {\n // window is loaded here\n});\n```\n\nHere is another example with an API that lets us know when a connection is ready. The attempt here is imperfect and we'll describe why soon:\n\n```js\nfunction connect() {\n var connection = myConnector.getConnection(); // Synchronous.\n return new Promise(function(resolve, reject) {\n connection.on(\"ready\", function() {\n // When a connection has been established\n // mark the promise as fulfilled.\n resolve(connection);\n });\n connection.on(\"error\", function(e) {\n // If it failed connecting, mark it\n // as rejected.\n reject(e); // e is preferably an `Error`.\n });\n });\n}\n```\n\nThe problem with the above is that `getConnection` itself might throw for some reason and if it does we'll get a synchronous rejection. An asynchronous operation should always be asynchronous to prevent double guarding and race conditions so it's best to always put the sync parts inside the promise constructor as such:\n\n```js\nfunction connect() {\n return new Promise(function(resolve, reject) {\n // If getConnection throws here instead of getting\n // an exception we're getting a rejection thus\n // producing a much more consistent API.\n var connection = myConnector.getConnection();\n connection.on(\"ready\", function() {\n // When a connection has been established\n // mark the promise as fulfilled.\n resolve(connection);\n });\n connection.on(\"error\", function(e) {\n // If it failed connecting, mark it\n // as rejected.\n reject(e); // e is preferably an `Error`\n });\n });\n}\n```\n###Working with delays/setTimeout\n\nThere is no need to convert timeouts/delays to a bluebird API, bluebird already ships with the [Promise.delay](.) function for this use case. Please consult the [timers](.) section of the docs on usage and examples.\n\n###Working with browser APIs\n\nOften browser APIs are nonstandard and automatic promisification will fail for them. If you're running into an API that you can't promisify with [promisify](.) and [promisifyAll](.) - please consult the [working with other APIs section](#working-with-any-other-apis)\n\n###Working with databases\n\nFor resource management in general and databases in particular, bluebird includes the powerful [Promise.using](.) and disposers system. This is similar to `with` in Python, `using` in C#, try/resource in Java or RAII in C++ in that it lets you handle resource management in an automatic way.\n\nSeveral examples of databases follow.\n\n> **Note** for more examples please see the [Promise.using](.) section.\n\n####Mongoose/MongoDB\n\nMongoose works with persistent connections and the driver takes care of reconnections/disposals. For this reason using `using` with it isn't required - instead connect on server startup and use promisification to expose promises.\n\nNote that Mongoose already ships with promise support but the promises it offers are significantly slower and don't report unhandled rejections so it is recommended to use automatic promisification with it anyway:\n\n```js\nvar Mongoose = Promise.promisifyAll(require(\"mongoose\"));\n```\n\n####Sequelize\n\nSequelize already uses Bluebird promises internally and has promise returning APIs. Use those.\n\n####RethinkDB\n\nRethink already uses Bluebird promises internally and has promise returning APIs. Use those.\n\n####Bookshelf\n\nBookshelf already uses Bluebird promises internally and has promise returning APIs. Use those.\n\n\n####PostgreSQL\n\nHere is how to create a disposer for the PostgreSQL driver:\n\n```js\nvar pg = require(\"pg\");\n// Uncomment if pg has not been properly promisified yet.\n//var Promise = require(\"bluebird\");\n//Promise.promisifyAll(pg, {\n// filter: function(methodName) {\n// return methodName === \"connect\"\n// },\n// multiArgs: true\n//});\n// Promisify rest of pg normally.\n//Promise.promisifyAll(pg);\n\nfunction getSqlConnection(connectionString) {\n var close;\n return pg.connectAsync(connectionString).spread(function(client, done) {\n close = done;\n return client;\n }).disposer(function() {\n if (close) close();\n });\n}\n\nmodule.exports = getSqlConnection;\n```\n\nWhich would allow you to use:\n\n```js\nvar using = Promise.using;\n\nusing(getSqlConnection(), function(conn) {\n // use connection here and _return the promise_\n\n}).then(function(result) {\n // connection already disposed here\n\n});\n```\n\nIt's also possible to use a disposer pattern (but not actual disposers) for transaction management:\n\n```js\n\nfunction withTransaction(fn) {\n return Promise.using(pool.acquireConnection(), function(connection) {\n var tx = connection.beginTransaction()\n return Promise\n .try(fn, tx)\n .then(function(res) { return connection.commit().thenReturn(res) },\n function(err) {\n return connection.rollback()\n .catch(function(e) {/* maybe add the rollback error to err */})\n .thenThrow(err);\n });\n });\n}\nexports.withTransaction = withTransaction;\n```\n\nWhich would let you do:\n\n```js\nwithTransaction(tx => {\n return tx.queryAsync(...).then(function() {\n return tx.queryAsync(...)\n }).then(function() {\n return tx.queryAsync(...)\n });\n});\n```\n\n####MySQL\n\nHere is how to create a disposer for the MySQL driver:\n\n```js\nvar mysql = require(\"mysql\");\n// Uncomment if mysql has not been properly promisified yet\n// var Promise = require(\"bluebird\");\n// Promise.promisifyAll(mysql);\n// Promise.promisifyAll(require(\"mysql/lib/Connection\").prototype);\n// Promise.promisifyAll(require(\"mysql/lib/Pool\").prototype);\nvar pool = mysql.createPool({\n connectionLimit: 10,\n host: 'example.org',\n user: 'bob',\n password: 'secret'\n});\n\nfunction getSqlConnection() {\n return pool.getConnectionAsync().disposer(function(connection) {\n connection.release();\n });\n}\n\nmodule.exports = getSqlConnection;\n```\n\nThe usage pattern is similar to the PostgreSQL example above. You can also use a disposer pattern (but not an actual .disposer). See the PostgreSQL example above for instructions.\n\n###More common examples\n\n\nSome examples of the above practice applied to some popular libraries:\n\n```js\n// The most popular redis module\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"redis\"));\n```\n\n```js\n// The most popular mongodb module\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mongodb\"));\n```\n\n```js\n// The most popular mysql module\nvar Promise = require(\"bluebird\");\n// Note that the library's classes are not properties of the main export\n// so we require and promisifyAll them manually\nPromise.promisifyAll(require(\"mysql/lib/Connection\").prototype);\nPromise.promisifyAll(require(\"mysql/lib/Pool\").prototype);\n```\n\n```js\n// Mongoose\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mongoose\"));\n```\n\n```js\n// Request\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"request\"));\n// Use request.getAsync(...) not request(..), it will not return a promise\n```\n\n```js\n// mkdir\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"mkdirp\"));\n// Use mkdirp.mkdirpAsync not mkdirp(..), it will not return a promise\n```\n\n```js\n// winston\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"winston\"));\n```\n\n```js\n// rimraf\nvar Promise = require(\"bluebird\");\n// The module isn't promisified but the function returned is\nvar rimrafAsync = Promise.promisify(require(\"rimraf\"));\n```\n\n```js\n// xml2js\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"xml2js\"));\n```\n\n```js\n// jsdom\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"jsdom\"));\n```\n\n```js\n// fs-extra\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"fs-extra\"));\n```\n\n```js\n// prompt\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"prompt\"));\n```\n\n```js\n// Nodemailer\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"nodemailer\"));\n```\n\n```js\n// ncp\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"ncp\"));\n```\n\n```js\n// pg\nvar Promise = require(\"bluebird\");\nPromise.promisifyAll(require(\"pg\"));\n```\n\nIn all of the above cases the library made its classes available in one way or another. If this is not the case, you can still promisify by creating a throwaway instance:\n\n```js\nvar ParanoidLib = require(\"...\");\nvar throwAwayInstance = ParanoidLib.createInstance();\nPromise.promisifyAll(Object.getPrototypeOf(throwAwayInstance));\n// Like before, from this point on, all new instances + even the throwAwayInstance suddenly support promises\n```\n\n###Working with any other APIs\n\nSometimes you have to work with APIs that are inconsistent and do not follow a common convention.\n\n> **Note** Promise returning function should never throw\n\nFor example, something like:\n\n```js\nfunction getUserData(userId, onLoad, onFail) { ...\n```\n\nWe can use the promise constructor to convert it to a promise returning function:\n\n```js\nfunction getUserDataAsync(userId) {\n return new Promise(function(resolve, reject) {\n // Put all your code here, this section is throw-safe.\n getUserData(userId, resolve, reject);\n });\n}\n```\n"
},
{
"path": "docs/helpers.rb",
"content": "require \"sanitize\"\n\nclass Helpers\n def self.clean(input)\n return Sanitize.fragment(input)\n .downcase\n .gsub(/\\s+/, \"-\")\n .gsub(/^([A-Za-z0-9\\-_.:]+).*?$/, \"\\\\1\")\n .gsub(/^\\./, \"\")\n .gsub(/\\.$/, \"\")\n .gsub(/[^A-Za-z0-9\\-_.]/, \"\")\n .sub(/^-+/, \"\")\n .sub(/-+$/, \"\")\n\n end\nend\n"
},
{
"path": "docs/img/README.txt",
"content": "SVG available upon request.\n"
},
{
"path": "docs/index.html",
"content": "\n\nRedirecting...\n\n\n
Redirecting...
\nClick here if you are not redirected.\n\n"
},
{
"path": "issue_template.md",
"content": "(This issue tracker is only for bug reports or feature requests, if this is neither, please choose appropriate channel from http://bluebirdjs.com/docs/support.html)\n\nPlease answer the questions the best you can:\n\n1) What version of bluebird is the issue happening on?\n\n2) What platform and version? (For example Node.js 0.12 or Google Chrome 32)\n\n3) Did this issue happen with earlier version of bluebird?\n\n(Write description of your issue here, stack traces from errors and code that reproduces the issue are helpful)\n\n"
},
{
"path": "package.json",
"content": "{\n \"name\": \"bluebird\",\n \"description\": \"Full featured Promises/A+ implementation with exceptionally good performance\",\n \"version\": \"3.7.2\",\n \"keywords\": [\n \"promise\",\n \"performance\",\n \"promises\",\n \"promises-a\",\n \"promises-aplus\",\n \"async\",\n \"await\",\n \"deferred\",\n \"deferreds\",\n \"future\",\n \"flow control\",\n \"dsl\",\n \"fluent interface\"\n ],\n \"scripts\": {\n \"lint\": \"node scripts/jshint.js\",\n \"test\": \"node --expose-gc tools/test.js\",\n \"istanbul\": \"istanbul\",\n \"prepublish\": \"npm run generate-browser-core && npm run generate-browser-full\",\n \"generate-browser-full\": \"node tools/build.js --no-clean --no-debug --release --browser --minify\",\n \"generate-browser-core\": \"node tools/build.js --features=core --no-debug --release --zalgo --browser --minify && mv js/browser/bluebird.js js/browser/bluebird.core.js && mv js/browser/bluebird.min.js js/browser/bluebird.core.min.js\"\n },\n \"homepage\": \"https://github.com/petkaantonov/bluebird\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git://github.com/petkaantonov/bluebird.git\"\n },\n \"bugs\": {\n \"url\": \"http://github.com/petkaantonov/bluebird/issues\"\n },\n \"license\": \"MIT\",\n \"author\": {\n \"name\": \"Petka Antonov\",\n \"email\": \"petka_antonov@hotmail.com\",\n \"url\": \"http://github.com/petkaantonov/\"\n },\n \"devDependencies\": {\n \"acorn\": \"^6.0.2\",\n \"acorn-walk\": \"^6.1.0\",\n \"baconjs\": \"^0.7.43\",\n \"bluebird\": \"^2.9.2\",\n \"body-parser\": \"^1.10.2\",\n \"browserify\": \"^8.1.1\",\n \"cli-table\": \"~0.3.1\",\n \"co\": \"^4.2.0\",\n \"cross-spawn\": \"^0.2.3\",\n \"glob\": \"^4.3.2\",\n \"grunt-saucelabs\": \"~8.6.3\",\n \"highland\": \"^2.3.0\",\n \"istanbul\": \"^0.3.5\",\n \"jshint\": \"^2.6.0\",\n \"jshint-stylish\": \"~0.2.0\",\n \"kefir\": \"^2.4.1\",\n \"mkdirp\": \"~0.5.0\",\n \"mocha\": \"~10.2\",\n \"open\": \"~0.0.5\",\n \"optimist\": \"~0.6.1\",\n \"rimraf\": \"~2.2.6\",\n \"rx\": \"^2.3.25\",\n \"serve-static\": \"^1.7.1\",\n \"sinon\": \"~1.7.3\",\n \"uglify-js\": \"~2.4.16\"\n },\n \"readmeFilename\": \"README.md\",\n \"main\": \"./js/release/bluebird.js\",\n \"webpack\": \"./js/release/bluebird.js\",\n \"browser\": \"./js/browser/bluebird.js\",\n \"files\": [\n \"js/browser\",\n \"js/release\",\n \"LICENSE\"\n ]\n}\n"
},
{
"path": "src/any.js",
"content": "\"use strict\";\nmodule.exports = function(Promise) {\nvar SomePromiseArray = Promise._SomePromiseArray;\nvar ASSERT = require(\"./assert\");\n\nfunction any(promises) {\n var ret = new SomePromiseArray(promises);\n var promise = ret.promise();\n ASSERT(promise.isPending());\n ASSERT(ret instanceof SomePromiseArray);\n ret.setHowMany(1);\n ret.setUnwrap();\n ret.init();\n return promise;\n}\n\nPromise.any = function (promises) {\n return any(promises);\n};\n\nPromise.prototype.any = function () {\n return any(this);\n};\n\n};\n"
},
{
"path": "src/assert.js",
"content": "\"use strict\";\nmodule.exports = (function(){\nvar AssertionError = (function() {\n function AssertionError(a) {\n this.constructor$(a);\n this.message = a;\n this.name = \"AssertionError\";\n }\n AssertionError.prototype = new Error();\n AssertionError.prototype.constructor = AssertionError;\n AssertionError.prototype.constructor$ = Error;\n return AssertionError;\n})();\n\nfunction getParams(args) {\n var params = [];\n for (var i = 0; i < args.length; ++i) params.push(\"arg\" + i);\n return params;\n}\n\nfunction nativeAssert(callName, args, expect) {\n try {\n var params = getParams(args);\n var constructorArgs = params;\n constructorArgs.push(\"return \" +\n callName + \"(\"+ params.join(\",\") + \");\");\n var fn = Function.apply(null, constructorArgs);\n return fn.apply(null, args);\n } catch (e) {\n if (!(e instanceof SyntaxError)) {\n throw e;\n } else {\n return expect;\n }\n }\n}\n\nreturn function assert(boolExpr, message) {\n if (boolExpr === true) return;\n\n if (typeof boolExpr === \"string\" &&\n boolExpr.charAt(0) === \"%\") {\n var nativeCallName = boolExpr;\n INLINE_SLICE(args, arguments, 2);\n if (nativeAssert(nativeCallName, args, message) === message) return;\n message = (nativeCallName + \" !== \" + message);\n }\n\n var ret = new AssertionError(message);\n if (Error.captureStackTrace) {\n Error.captureStackTrace(ret, assert);\n }\n throw ret;\n};\n})();\n"
},
{
"path": "src/async.js",
"content": "\"use strict\";\nvar firstLineError;\ntry {throw new Error(); } catch (e) {firstLineError = e;}\nvar ASSERT = require(\"./assert\");\nvar schedule = require(\"./schedule\");\nvar Queue = require(\"./queue\");\n\nfunction Async() {\n this._customScheduler = false;\n this._isTickUsed = false;\n this._lateQueue = new Queue(LATE_QUEUE_CAPACITY);\n this._normalQueue = new Queue(NORMAL_QUEUE_CAPACITY);\n this._haveDrainedQueues = false;\n var self = this;\n this.drainQueues = function () {\n self._drainQueues();\n };\n this._schedule = schedule;\n}\n\nAsync.prototype.setScheduler = function(fn) {\n var prev = this._schedule;\n this._schedule = fn;\n this._customScheduler = true;\n return prev;\n};\n\nAsync.prototype.hasCustomScheduler = function() {\n return this._customScheduler;\n};\n\nAsync.prototype.haveItemsQueued = function () {\n return this._isTickUsed || this._haveDrainedQueues;\n};\n\n\nAsync.prototype.fatalError = function(e, isNode) {\n if (isNode) {\n process.stderr.write(\"Fatal \" + (e instanceof Error ? e.stack : e) +\n \"\\n\");\n process.exit(2);\n } else {\n this.throwLater(e);\n }\n};\n\n// Must be used if fn can throw\nAsync.prototype.throwLater = function(fn, arg) {\n if (arguments.length === 1) {\n arg = fn;\n fn = function () { throw arg; };\n }\n if (typeof setTimeout !== \"undefined\") {\n setTimeout(function() {\n fn(arg);\n }, 0);\n } else try {\n this._schedule(function() {\n fn(arg);\n });\n } catch (e) {\n throw new Error(NO_ASYNC_SCHEDULER);\n }\n};\n\n//When the fn absolutely needs to be called after\n//the queue has been completely flushed\nfunction AsyncInvokeLater(fn, receiver, arg) {\n ASSERT(arguments.length === 3);\n this._lateQueue.push(fn, receiver, arg);\n this._queueTick();\n}\n\nfunction AsyncInvoke(fn, receiver, arg) {\n ASSERT(arguments.length === 3);\n this._normalQueue.push(fn, receiver, arg);\n this._queueTick();\n}\n\nfunction AsyncSettlePromises(promise) {\n this._normalQueue._pushOne(promise);\n this._queueTick();\n}\n\nAsync.prototype.invokeLater = AsyncInvokeLater;\nAsync.prototype.invoke = AsyncInvoke;\nAsync.prototype.settlePromises = AsyncSettlePromises;\n\n\nfunction _drainQueue(queue) {\n while (queue.length() > 0) {\n _drainQueueStep(queue);\n }\n}\n\n// Shift the queue in a separate function to allow\n// garbage collection after each step\nfunction _drainQueueStep(queue) {\n var fn = queue.shift();\n if (typeof fn !== \"function\") {\n fn._settlePromises();\n } else {\n var receiver = queue.shift();\n var arg = queue.shift();\n fn.call(receiver, arg);\n }\n}\n\nAsync.prototype._drainQueues = function () {\n ASSERT(this._isTickUsed);\n _drainQueue(this._normalQueue);\n this._reset();\n this._haveDrainedQueues = true;\n _drainQueue(this._lateQueue);\n};\n\nAsync.prototype._queueTick = function () {\n if (!this._isTickUsed) {\n this._isTickUsed = true;\n this._schedule(this.drainQueues);\n }\n};\n\nAsync.prototype._reset = function () {\n this._isTickUsed = false;\n};\n\nmodule.exports = Async;\nmodule.exports.firstLineError = firstLineError;\n"
},
{
"path": "src/bind.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL, tryConvertToPromise, debug) {\nvar calledBind = false;\nvar rejectThis = function(_, e) {\n this._reject(e);\n};\n\nvar targetRejected = function(e, context) {\n context.promiseRejectionQueued = true;\n context.bindingPromise._then(rejectThis, rejectThis, null, this, e);\n};\n\nvar bindingResolved = function(thisArg, context) {\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG, this._bitField)) {\n this._resolveCallback(context.target);\n }\n};\n\nvar bindingRejected = function(e, context) {\n if (!context.promiseRejectionQueued) this._reject(e);\n};\n\nPromise.prototype.bind = function (thisArg) {\n if (!calledBind) {\n calledBind = true;\n Promise.prototype._propagateFrom = debug.propagateFromFunction();\n Promise.prototype._boundValue = debug.boundValueFunction();\n }\n var maybePromise = tryConvertToPromise(thisArg);\n var ret = new Promise(INTERNAL);\n ret._propagateFrom(this, PROPAGATE_CANCEL);\n var target = this._target();\n ret._setBoundTo(maybePromise);\n if (maybePromise instanceof Promise) {\n var context = {\n promiseRejectionQueued: false,\n promise: ret,\n target: target,\n bindingPromise: maybePromise\n };\n target._then(INTERNAL, targetRejected, undefined, ret, context);\n maybePromise._then(\n bindingResolved, bindingRejected, undefined, ret, context);\n ret._setOnCancel(maybePromise);\n } else {\n ret._resolveCallback(target);\n }\n return ret;\n};\n\nPromise.prototype._setBoundTo = function (obj) {\n if (obj !== undefined) {\n this._bitField = this._bitField | IS_BOUND;\n this._boundTo = obj;\n } else {\n this._bitField = this._bitField & (~IS_BOUND);\n }\n};\n\nPromise.prototype._isBound = function () {\n return (this._bitField & IS_BOUND) === IS_BOUND;\n};\n\nPromise.bind = function (thisArg, value) {\n return Promise.resolve(value).bind(thisArg);\n};\n};\n"
},
{
"path": "src/bluebird.js",
"content": "\"use strict\";\nvar old;\nif (typeof Promise !== \"undefined\") old = Promise;\nfunction noConflict() {\n try { if (Promise === bluebird) Promise = old; }\n catch (e) {}\n return bluebird;\n}\nvar bluebird = require(\"./promise\")();\nbluebird.noConflict = noConflict;\nmodule.exports = bluebird;\n"
},
{
"path": "src/call_get.js",
"content": "\"use strict\";\nvar cr = Object.create;\nif (cr) {\n var callerCache = cr(null);\n var getterCache = cr(null);\n callerCache[\" size\"] = getterCache[\" size\"] = 0;\n}\n\nmodule.exports = function(Promise) {\nvar util = require(\"./util\");\nvar canEvaluate = util.canEvaluate;\nvar isIdentifier = util.isIdentifier;\n\nvar getMethodCaller;\nvar getGetter;\nif (!__BROWSER__) {\nvar makeMethodCaller = function (methodName) {\n return new Function(\"ensureMethod\", \" \\n\\\n return function(obj) { \\n\\\n 'use strict' \\n\\\n var len = this.length; \\n\\\n ensureMethod(obj, 'methodName'); \\n\\\n switch(len) { \\n\\\n case 1: return obj.methodName(this[0]); \\n\\\n case 2: return obj.methodName(this[0], this[1]); \\n\\\n case 3: return obj.methodName(this[0], this[1], this[2]); \\n\\\n case 0: return obj.methodName(); \\n\\\n default: \\n\\\n return obj.methodName.apply(obj, this); \\n\\\n } \\n\\\n }; \\n\\\n \".replace(/methodName/g, methodName))(ensureMethod);\n};\n\nvar makeGetter = function (propertyName) {\n return new Function(\"obj\", \" \\n\\\n 'use strict'; \\n\\\n return obj.propertyName; \\n\\\n \".replace(\"propertyName\", propertyName));\n};\n\nvar getCompiled = function(name, compiler, cache) {\n var ret = cache[name];\n if (typeof ret !== \"function\") {\n if (!isIdentifier(name)) {\n return null;\n }\n ret = compiler(name);\n cache[name] = ret;\n cache[\" size\"]++;\n if (cache[\" size\"] > 512) {\n var keys = Object.keys(cache);\n for (var i = 0; i < 256; ++i) delete cache[keys[i]];\n cache[\" size\"] = keys.length - 256;\n }\n }\n return ret;\n};\n\ngetMethodCaller = function(name) {\n return getCompiled(name, makeMethodCaller, callerCache);\n};\n\ngetGetter = function(name) {\n return getCompiled(name, makeGetter, getterCache);\n};\n}\n\nfunction ensureMethod(obj, methodName) {\n var fn;\n if (obj != null) fn = obj[methodName];\n if (typeof fn !== \"function\") {\n var message = \"Object \" + util.classString(obj) + \" has no method '\" +\n util.toString(methodName) + \"'\";\n throw new Promise.TypeError(message);\n }\n return fn;\n}\n\nfunction caller(obj) {\n var methodName = this.pop();\n var fn = ensureMethod(obj, methodName);\n return fn.apply(obj, this);\n}\nPromise.prototype.call = function (methodName) {\n INLINE_SLICE(args, arguments, 1);\n if (!__BROWSER__) {\n if (canEvaluate) {\n var maybeCaller = getMethodCaller(methodName);\n if (maybeCaller !== null) {\n return this._then(\n maybeCaller, undefined, undefined, args, undefined);\n }\n }\n }\n args.push(methodName);\n return this._then(caller, undefined, undefined, args, undefined);\n};\n\nfunction namedGetter(obj) {\n return obj[this];\n}\nfunction indexedGetter(obj) {\n var index = +this;\n if (index < 0) index = Math.max(0, index + obj.length);\n return obj[index];\n}\nPromise.prototype.get = function (propertyName) {\n var isIndex = (typeof propertyName === \"number\");\n var getter;\n if (!isIndex) {\n if (canEvaluate) {\n var maybeGetter = getGetter(propertyName);\n getter = maybeGetter !== null ? maybeGetter : namedGetter;\n } else {\n getter = namedGetter;\n }\n } else {\n getter = indexedGetter;\n }\n return this._then(getter, undefined, undefined, propertyName, undefined);\n};\n};\n"
},
{
"path": "src/cancel.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, PromiseArray, apiRejection, debug) {\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar tryCatch = util.tryCatch;\nvar errorObj = util.errorObj;\nvar async = Promise._async;\n\nPromise.prototype[\"break\"] = Promise.prototype.cancel = function() {\n if (!debug.cancellation()) return this._warn(\"cancellation is disabled\");\n\n var promise = this;\n var child = promise;\n while (promise._isCancellable()) {\n if (!promise._cancelBy(child)) {\n if (child._isFollowing()) {\n child._followee().cancel();\n } else {\n child._cancelBranched();\n }\n break;\n }\n\n var parent = promise._cancellationParent;\n if (parent == null || !parent._isCancellable()) {\n if (promise._isFollowing()) {\n promise._followee().cancel();\n } else {\n promise._cancelBranched();\n }\n break;\n } else {\n if (promise._isFollowing()) promise._followee().cancel();\n promise._setWillBeCancelled();\n child = promise;\n promise = parent;\n }\n }\n};\n\nPromise.prototype._branchHasCancelled = function() {\n ASSERT(typeof this._branchesRemainingToCancel === \"number\");\n this._branchesRemainingToCancel--;\n};\n\nPromise.prototype._enoughBranchesHaveCancelled = function() {\n return this._branchesRemainingToCancel === undefined ||\n this._branchesRemainingToCancel <= 0;\n};\n\nPromise.prototype._cancelBy = function(canceller) {\n if (canceller === this) {\n this._branchesRemainingToCancel = 0;\n this._invokeOnCancel();\n return true;\n } else {\n ASSERT(canceller._cancellationParent === this);\n this._branchHasCancelled();\n if (this._enoughBranchesHaveCancelled()) {\n this._invokeOnCancel();\n return true;\n }\n }\n return false;\n};\n\nPromise.prototype._cancelBranched = function() {\n if (this._enoughBranchesHaveCancelled()) {\n this._cancel();\n }\n};\n\nPromise.prototype._cancel = function() {\n if (!this._isCancellable()) return;\n ASSERT(!this._isFollowing());\n this._setCancelled();\n async.invoke(this._cancelPromises, this, undefined);\n};\n\nPromise.prototype._cancelPromises = function() {\n if (this._length() > 0) this._settlePromises();\n};\n\nPromise.prototype._unsetOnCancel = function() {\n ASSERT(this._isCancellable() || this._isCancelled());\n this._onCancelField = undefined;\n};\n\nPromise.prototype._isCancellable = function() {\n return this.isPending() && !this._isCancelled();\n};\n\nPromise.prototype.isCancellable = function() {\n return this.isPending() && !this.isCancelled();\n};\n\nPromise.prototype._doInvokeOnCancel = function(onCancelCallback, internalOnly) {\n if (util.isArray(onCancelCallback)) {\n for (var i = 0; i < onCancelCallback.length; ++i) {\n this._doInvokeOnCancel(onCancelCallback[i], internalOnly);\n }\n } else if (onCancelCallback !== undefined) {\n if (typeof onCancelCallback === \"function\") {\n if (!internalOnly) {\n var e = tryCatch(onCancelCallback).call(this._boundValue());\n if (e === errorObj) {\n this._attachExtraTrace(e.e);\n async.throwLater(e.e);\n }\n }\n } else {\n onCancelCallback._resultCancelled(this);\n }\n }\n};\n\nPromise.prototype._invokeOnCancel = function() {\n var onCancelCallback = this._onCancel();\n // The existence of onCancel handler on a promise signals that the handler\n // has not been queued for invocation yet.\n this._unsetOnCancel();\n async.invoke(this._doInvokeOnCancel, this, onCancelCallback);\n};\n\nPromise.prototype._invokeInternalOnCancel = function() {\n if (this._isCancellable()) {\n this._doInvokeOnCancel(this._onCancel(), true);\n this._unsetOnCancel();\n }\n};\n\nPromise.prototype._resultCancelled = function() {\n this.cancel();\n};\n\n};\n"
},
{
"path": "src/catch_filter.js",
"content": "\"use strict\";\nmodule.exports = function(NEXT_FILTER) {\nvar util = require(\"./util\");\nvar getKeys = require(\"./es5\").keys;\nvar tryCatch = util.tryCatch;\nvar errorObj = util.errorObj;\n\nfunction catchFilter(instances, cb, promise) {\n return function(e) {\n var boundTo = promise._boundValue();\n predicateLoop: for (var i = 0; i < instances.length; ++i) {\n var item = instances[i];\n\n if (item === Error ||\n (item != null && item.prototype instanceof Error)) {\n if (e instanceof item) {\n return tryCatch(cb).call(boundTo, e);\n }\n } else if (typeof item === \"function\") {\n var matchesPredicate = tryCatch(item).call(boundTo, e);\n if (matchesPredicate === errorObj) {\n return matchesPredicate;\n } else if (matchesPredicate) {\n return tryCatch(cb).call(boundTo, e);\n }\n } else if (util.isObject(e)) {\n var keys = getKeys(item);\n for (var j = 0; j < keys.length; ++j) {\n var key = keys[j];\n if (item[key] != e[key]) {\n continue predicateLoop;\n }\n }\n return tryCatch(cb).call(boundTo, e);\n }\n }\n return NEXT_FILTER;\n };\n}\n\nreturn catchFilter;\n};\n"
},
{
"path": "src/constants.js",
"content": "//This is pretty lame but what you gonna do\n\n//async.js\nCONSTANT(LATE_QUEUE_CAPACITY, 16);\nCONSTANT(NORMAL_QUEUE_CAPACITY, 16);\n\n//errors.js\nCONSTANT(ERROR_HANDLED_KEY, \"__promiseHandled__\");\nCONSTANT(OPERATIONAL_ERROR_KEY, \"isOperational\");\nCONSTANT(DEFAULT_STATE, 0);\nCONSTANT(STACK_ATTACHED, 1);\nCONSTANT(ERROR_HANDLED, 2);\n\n//join.js\nCONSTANT(GENERATED_CLASS_COUNT, 8);\n\n//promise.js\nCONSTANT(USE_BOUND, true);\nCONSTANT(DONT_USE_BOUND, false);\n\nCONSTANT(PROPAGATE_CANCEL, 1);\nCONSTANT(PROPAGATE_BIND, 2);\nCONSTANT(PROPAGATE_ALL, PROPAGATE_CANCEL | PROPAGATE_BIND);\n\nCONSTANT(CALLBACK_FULFILL_OFFSET, 0);\nCONSTANT(CALLBACK_REJECT_OFFSET, 1);\nCONSTANT(CALLBACK_PROMISE_OFFSET, 2);\nCONSTANT(CALLBACK_RECEIVER_OFFSET, 3);\nCONSTANT(CALLBACK_SIZE, 4);\n//Layout for ._bitField\n//[RR]XO GWFN CTBH IUDE LLLL LLLL LLLL LLLL\n//[RR] = [Reserved] (Both bits are either on or off to represent\n// 1 bit due to 31-bit integers in 32-bit v8)\n//R = [Reserved]\n//X = noAsyncGuarantee\n//O = returnedNonUndefined\n//G = isAsyncGuaranteed\n//W = isFollowing (The promise that is being followed is not stored explicitly)\n//F = isFulfilled\n//N = isRejected\n//C = willBeCancelled\n//T = isFinal (used for .done() implementation)\n//B = isBound\n//I = isRejectionIgnored\n//H = isRejectionUnhandled\n//U = isUnhanldedRejectionNotified\n//D = isDisposable\n//E = isCancelled\n//L = Length, 16 bit unsigned\nCONSTANT(ASYNC_GUARANTEE_SHIFT, 2)\nCONSTANT(NO_STATE, 0x0|0);\nCONSTANT(NO_ASYNC_GUARANTEE, 0x20000000|0);\nCONSTANT(RETURNED_NON_UNDEFINED, 0x10000000|0);\nCONSTANT(IS_ASYNC_GUARANTEED, 0x8000000|0);\nCONSTANT(IS_FOLLOWING, 0x4000000|0);\nCONSTANT(IS_FULFILLED, 0x2000000|0);\nCONSTANT(IS_REJECTED, 0x1000000|0);\nCONSTANT(WILL_BE_CANCELLED, 0x800000|0);\nCONSTANT(IS_FINAL, 0x400000|0);\nCONSTANT(IS_BOUND, 0x200000|0);\nCONSTANT(IS_REJECTION_UNHANDLED, 0x100000|0);\nCONSTANT(IS_REJECTION_IGNORED, 0x80000|0);\nCONSTANT(IS_UNHANDLED_REJECTION_NOTIFIED, 0x40000|0);\nCONSTANT(IS_DISPOSABLE, 0x20000|0);\nCONSTANT(IS_CANCELLED, 0x10000|0);\nCONSTANT(IS_CANCELLED_OR_WILL_BE_CANCELLED, IS_CANCELLED | WILL_BE_CANCELLED)\nCONSTANT(LENGTH_MASK, 0xFFFF|0);\nCONSTANT(LENGTH_CLEAR_MASK, ~LENGTH_MASK);\nCONSTANT(MAX_LENGTH, LENGTH_MASK);\nCONSTANT(IS_REJECTED_OR_CANCELLED, IS_REJECTED | IS_CANCELLED);\nCONSTANT(IS_REJECTED_OR_FULFILLED, IS_REJECTED | IS_FULFILLED);\nCONSTANT(IS_REJECTED_OR_FULFILLED_OR_CANCELLED, IS_REJECTED | IS_FULFILLED| IS_CANCELLED);\nCONSTANT(IS_PENDING_AND_WAITING_NEG, IS_REJECTED_OR_FULFILLED_OR_CANCELLED);\n\nCONSTANT(IS_FATE_SEALED, IS_REJECTED | IS_FULFILLED | IS_FOLLOWING | IS_CANCELLED);\n\nCONSTANT(AFTER_PROMISIFIED_SUFFIX, \"Async\");\nCONSTANT(UNHANDLED_REJECTION_EVENT, \"unhandledRejection\");\nCONSTANT(REJECTION_HANDLED_EVENT, \"rejectionHandled\");\n\n//promise_array.js\n//MUST BE NEGATIVE NUMBERS\nCONSTANT(RESOLVE_UNDEFINED, -1);\nCONSTANT(RESOLVE_ARRAY, -2);\nCONSTANT(RESOLVE_OBJECT, -3);\nCONSTANT(RESOLVE_FOREVER_PENDING, -4);\nCONSTANT(RESOLVE_CALL_METHOD, -5);\nCONSTANT(RESOLVE_MAP, -6);\n\n//queue.js\nCONSTANT(QUEUE_MAX_CAPACITY, (1 << 30) | 0);\nCONSTANT(QUEUE_MIN_CAPACITY, 16);\n\n//captured_trace.js\nCONSTANT(FROM_PREVIOUS_EVENT, \"From previous event:\");\nCONSTANT(NO_STACK_TRACE, \" (No stack trace)\");\nCONSTANT(ADDITIONAL_STACK_TRACE, \"^--- With additional stack trace: \");\nCONSTANT(UNHANDLED_REJECTION_HEADER, \"Unhandled rejection \");\n\n//finally.js\nCONSTANT(FINALLY_TYPE, 0);\nCONSTANT(TAP_TYPE, 1);\n\n//direct_resolve.js\nCONSTANT(THROW, 1);\nCONSTANT(RETURN, 2);\n\n//promisify.js\nCONSTANT(MAX_PARAM_COUNT, 1023);\nCONSTANT(PARAM_COUNTS_TO_TRY, 3);\n\n//error.js\nCONSTANT(BLUEBIRD_ERRORS, \"__BluebirdErrorTypes__\");\n\n//deprecated\nCONSTANT(OBJECT_PROMISIFY_DEPRECATED, \"Promise.promisify for promisifying entire objects is deprecated. Use Promise.promisifyAll instead.\\n\\n\\\n See http://goo.gl/MqrFmX\");\nCONSTANT(SPAWN_DEPRECATED, \"Promise.spawn is deprecated. Use Promise.coroutine instead.\");\n\n//errors\nCONSTANT(LATE_CANCELLATION_OBSERVER, \"late cancellation observer\");\nCONSTANT(TIMEOUT_ERROR, \"operation timed out\");\nCONSTANT(COLLECTION_ERROR, \"expecting an array or an iterable object but got \");\nCONSTANT(OBJECT_ERROR, \"expecting an object but got \");\nCONSTANT(FUNCTION_ERROR, \"expecting a function but got \");\nCONSTANT(CONSTRUCT_ERROR_INVOCATION, \"the promise constructor cannot be invoked directly\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(NOT_GENERATOR_ERROR, \"generatorFunction must be a function\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(LONG_STACK_TRACES_ERROR, \"cannot enable long stack traces after promises have been created\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(INSPECTION_VALUE_ERROR, \"cannot get fulfillment value of a non-fulfilled promise\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(INSPECTION_REASON_ERROR, \"cannot get rejection reason of a non-rejected promise\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(PROMISIFY_TYPE_ERROR, \"the target of promisifyAll must be an object or a function\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(CIRCULAR_RESOLUTION_ERROR, \"circular promise resolution chain\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(PROPS_TYPE_ERROR, \"cannot await properties of a non-object\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(POSITIVE_INTEGER_ERROR, \"expecting a positive integer\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(YIELDED_NON_PROMISE_ERROR, \"A value %s was yielded that could not be treated as a promise\\n\\n\\\n See http://goo.gl/MqrFmX\\n\\n\");\nCONSTANT(FROM_COROUTINE_CREATED_AT, \"From coroutine:\\n\");\nCONSTANT(UNBOUND_RESOLVER_INVOCATION, \"Illegal invocation, resolver resolve/reject must be called within a resolver context. Consider using the promise constructor instead.\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(PROMISIFICATION_NORMAL_METHODS_ERROR, \"Cannot promisify an API that has normal methods with '%s'-suffix\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(SUFFIX_NOT_IDENTIFIER, \"suffix must be a valid identifier\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\nCONSTANT(NO_ASYNC_SCHEDULER, \"No async scheduler available\\n\\n\\\n See http://goo.gl/MqrFmX\\n\");\n"
},
{
"path": "src/context.js",
"content": "\"use strict\";\nmodule.exports = function(Promise) {\nvar longStackTraces = false;\nvar contextStack = [];\n\nPromise.prototype._promiseCreated = function() {};\nPromise.prototype._pushContext = function() {};\nPromise.prototype._popContext = function() {return null;};\nPromise._peekContext = Promise.prototype._peekContext = function() {};\n\nfunction Context() {\n this._trace = new Context.CapturedTrace(peekContext());\n}\nContext.prototype._pushContext = function () {\n if (this._trace !== undefined) {\n this._trace._promiseCreated = null;\n contextStack.push(this._trace);\n }\n};\n\nContext.prototype._popContext = function () {\n if (this._trace !== undefined) {\n var trace = contextStack.pop();\n var ret = trace._promiseCreated;\n trace._promiseCreated = null;\n return ret;\n }\n return null;\n};\n\nfunction createContext() {\n if (longStackTraces) return new Context();\n}\n\nfunction peekContext() {\n var lastIndex = contextStack.length - 1;\n if (lastIndex >= 0) {\n return contextStack[lastIndex];\n }\n return undefined;\n}\nContext.CapturedTrace = null;\nContext.create = createContext;\nContext.deactivateLongStackTraces = function() {};\nContext.activateLongStackTraces = function() {\n var Promise_pushContext = Promise.prototype._pushContext;\n var Promise_popContext = Promise.prototype._popContext;\n var Promise_PeekContext = Promise._peekContext;\n var Promise_peekContext = Promise.prototype._peekContext;\n var Promise_promiseCreated = Promise.prototype._promiseCreated;\n Context.deactivateLongStackTraces = function() {\n Promise.prototype._pushContext = Promise_pushContext;\n Promise.prototype._popContext = Promise_popContext;\n Promise._peekContext = Promise_PeekContext;\n Promise.prototype._peekContext = Promise_peekContext;\n Promise.prototype._promiseCreated = Promise_promiseCreated;\n longStackTraces = false;\n };\n longStackTraces = true;\n Promise.prototype._pushContext = Context.prototype._pushContext;\n Promise.prototype._popContext = Context.prototype._popContext;\n Promise._peekContext = Promise.prototype._peekContext = peekContext;\n Promise.prototype._promiseCreated = function() {\n var ctx = this._peekContext();\n if (ctx && ctx._promiseCreated == null) ctx._promiseCreated = this;\n };\n};\nreturn Context;\n};\n"
},
{
"path": "src/debuggability.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, Context,\n enableAsyncHooks, disableAsyncHooks) {\nvar async = Promise._async;\nvar Warning = require(\"./errors\").Warning;\nvar util = require(\"./util\");\nvar es5 = require(\"./es5\");\nvar ASSERT = require(\"./assert\");\nvar canAttachTrace = util.canAttachTrace;\nvar unhandledRejectionHandled;\nvar possiblyUnhandledRejection;\nvar bluebirdFramePattern =\n /[\\\\\\/]bluebird[\\\\\\/]js[\\\\\\/](release|debug|instrumented)/;\nvar nodeFramePattern = /\\((?:timers\\.js):\\d+:\\d+\\)/;\nvar parseLinePattern = /[\\/<\\(](.+?):(\\d+):(\\d+)\\)?\\s*$/;\nvar stackFramePattern = null;\nvar formatStack = null;\nvar indentStackFrames = false;\nvar printWarning;\nvar debugging = !!(util.env(\"BLUEBIRD_DEBUG\") != 0 &&\n (__DEBUG__ ||\n util.env(\"BLUEBIRD_DEBUG\") ||\n util.env(\"NODE_ENV\") === \"development\"));\n\nvar warnings = !!(util.env(\"BLUEBIRD_WARNINGS\") != 0 &&\n (debugging || util.env(\"BLUEBIRD_WARNINGS\")));\n\nvar longStackTraces = !!(util.env(\"BLUEBIRD_LONG_STACK_TRACES\") != 0 &&\n (debugging || util.env(\"BLUEBIRD_LONG_STACK_TRACES\")));\n\nvar wForgottenReturn = util.env(\"BLUEBIRD_W_FORGOTTEN_RETURN\") != 0 &&\n (warnings || !!util.env(\"BLUEBIRD_W_FORGOTTEN_RETURN\"));\n\nvar deferUnhandledRejectionCheck;\n(function() {\n var promises = [];\n\n function unhandledRejectionCheck() {\n for (var i = 0; i < promises.length; ++i) {\n promises[i]._notifyUnhandledRejection();\n }\n unhandledRejectionClear();\n }\n\n function unhandledRejectionClear() {\n promises.length = 0;\n }\n\n deferUnhandledRejectionCheck = function(promise) {\n promises.push(promise);\n setTimeout(unhandledRejectionCheck, 1);\n };\n\n es5.defineProperty(Promise, \"_unhandledRejectionCheck\", {\n value: unhandledRejectionCheck\n });\n es5.defineProperty(Promise, \"_unhandledRejectionClear\", {\n value: unhandledRejectionClear\n });\n})();\n\nPromise.prototype.suppressUnhandledRejections = function() {\n var target = this._target();\n target._bitField = ((target._bitField & (~IS_REJECTION_UNHANDLED)) |\n IS_REJECTION_IGNORED);\n};\n\nPromise.prototype._ensurePossibleRejectionHandled = function () {\n if ((this._bitField & IS_REJECTION_IGNORED) !== 0) return;\n this._setRejectionIsUnhandled();\n deferUnhandledRejectionCheck(this);\n};\n\nPromise.prototype._notifyUnhandledRejectionIsHandled = function () {\n fireRejectionEvent(REJECTION_HANDLED_EVENT,\n unhandledRejectionHandled, undefined, this);\n};\n\nPromise.prototype._setReturnedNonUndefined = function() {\n this._bitField = this._bitField | RETURNED_NON_UNDEFINED;\n};\n\nPromise.prototype._returnedNonUndefined = function() {\n return (this._bitField & RETURNED_NON_UNDEFINED) !== 0;\n};\n\nPromise.prototype._notifyUnhandledRejection = function () {\n if (this._isRejectionUnhandled()) {\n var reason = this._settledValue();\n this._setUnhandledRejectionIsNotified();\n fireRejectionEvent(UNHANDLED_REJECTION_EVENT,\n possiblyUnhandledRejection, reason, this);\n }\n};\n\nPromise.prototype._setUnhandledRejectionIsNotified = function () {\n this._bitField = this._bitField | IS_UNHANDLED_REJECTION_NOTIFIED;\n};\n\nPromise.prototype._unsetUnhandledRejectionIsNotified = function () {\n this._bitField = this._bitField & (~IS_UNHANDLED_REJECTION_NOTIFIED);\n};\n\nPromise.prototype._isUnhandledRejectionNotified = function () {\n return (this._bitField & IS_UNHANDLED_REJECTION_NOTIFIED) > 0;\n};\n\nPromise.prototype._setRejectionIsUnhandled = function () {\n ASSERT(!this._isFollowing());\n this._bitField = this._bitField | IS_REJECTION_UNHANDLED;\n};\n\nPromise.prototype._unsetRejectionIsUnhandled = function () {\n ASSERT(!this._isFollowing());\n this._bitField = this._bitField & (~IS_REJECTION_UNHANDLED);\n if (this._isUnhandledRejectionNotified()) {\n this._unsetUnhandledRejectionIsNotified();\n this._notifyUnhandledRejectionIsHandled();\n }\n};\n\nPromise.prototype._isRejectionUnhandled = function () {\n ASSERT(!this._isFollowing());\n return (this._bitField & IS_REJECTION_UNHANDLED) > 0;\n};\n\nPromise.prototype._warn = function(message, shouldUseOwnTrace, promise) {\n return warn(message, shouldUseOwnTrace, promise || this);\n};\n\nPromise.onPossiblyUnhandledRejection = function (fn) {\n var context = Promise._getContext();\n possiblyUnhandledRejection = util.contextBind(context, fn);\n};\n\nPromise.onUnhandledRejectionHandled = function (fn) {\n var context = Promise._getContext();\n unhandledRejectionHandled = util.contextBind(context, fn);\n};\n\nvar disableLongStackTraces = function() {};\nPromise.longStackTraces = function () {\n if (async.haveItemsQueued() && !config.longStackTraces) {\n throw new Error(LONG_STACK_TRACES_ERROR);\n }\n if (!config.longStackTraces && longStackTracesIsSupported()) {\n var Promise_captureStackTrace = Promise.prototype._captureStackTrace;\n var Promise_attachExtraTrace = Promise.prototype._attachExtraTrace;\n var Promise_dereferenceTrace = Promise.prototype._dereferenceTrace;\n config.longStackTraces = true;\n disableLongStackTraces = function() {\n if (async.haveItemsQueued() && !config.longStackTraces) {\n throw new Error(LONG_STACK_TRACES_ERROR);\n }\n Promise.prototype._captureStackTrace = Promise_captureStackTrace;\n Promise.prototype._attachExtraTrace = Promise_attachExtraTrace;\n Promise.prototype._dereferenceTrace = Promise_dereferenceTrace;\n Context.deactivateLongStackTraces();\n config.longStackTraces = false;\n };\n Promise.prototype._captureStackTrace = longStackTracesCaptureStackTrace;\n Promise.prototype._attachExtraTrace = longStackTracesAttachExtraTrace;\n Promise.prototype._dereferenceTrace = longStackTracesDereferenceTrace;\n Context.activateLongStackTraces();\n }\n};\n\nPromise.hasLongStackTraces = function () {\n return config.longStackTraces && longStackTracesIsSupported();\n};\n\n\nvar legacyHandlers = {\n unhandledrejection: {\n before: function() {\n var ret = util.global.onunhandledrejection;\n util.global.onunhandledrejection = null;\n return ret;\n },\n after: function(fn) {\n util.global.onunhandledrejection = fn;\n }\n },\n rejectionhandled: {\n before: function() {\n var ret = util.global.onrejectionhandled;\n util.global.onrejectionhandled = null;\n return ret;\n },\n after: function(fn) {\n util.global.onrejectionhandled = fn;\n }\n }\n};\n\nvar fireDomEvent = (function() {\n var dispatch = function(legacy, e) {\n if (legacy) {\n var fn;\n try {\n fn = legacy.before();\n return !util.global.dispatchEvent(e);\n } finally {\n legacy.after(fn);\n }\n } else {\n return !util.global.dispatchEvent(e);\n }\n };\n try {\n if (typeof CustomEvent === \"function\") {\n var event = new CustomEvent(\"CustomEvent\");\n util.global.dispatchEvent(event);\n return function(name, event) {\n name = name.toLowerCase();\n var eventData = {\n detail: event,\n cancelable: true\n };\n var domEvent = new CustomEvent(name, eventData);\n es5.defineProperty(\n domEvent, \"promise\", {value: event.promise});\n es5.defineProperty(\n domEvent, \"reason\", {value: event.reason});\n\n return dispatch(legacyHandlers[name], domEvent);\n };\n // In Firefox < 48 CustomEvent is not available in workers but\n // Event is.\n } else if (typeof Event === \"function\") {\n var event = new Event(\"CustomEvent\");\n util.global.dispatchEvent(event);\n return function(name, event) {\n name = name.toLowerCase();\n var domEvent = new Event(name, {\n cancelable: true\n });\n domEvent.detail = event;\n es5.defineProperty(domEvent, \"promise\", {value: event.promise});\n es5.defineProperty(domEvent, \"reason\", {value: event.reason});\n return dispatch(legacyHandlers[name], domEvent);\n };\n } else {\n var event = document.createEvent(\"CustomEvent\");\n event.initCustomEvent(\"testingtheevent\", false, true, {});\n util.global.dispatchEvent(event);\n return function(name, event) {\n name = name.toLowerCase();\n var domEvent = document.createEvent(\"CustomEvent\");\n domEvent.initCustomEvent(name, false, true,\n event);\n return dispatch(legacyHandlers[name], domEvent);\n };\n }\n } catch (e) {}\n return function() {\n return false;\n };\n})();\n\nvar fireGlobalEvent = (function() {\n if (util.isNode) {\n return function() {\n return process.emit.apply(process, arguments);\n };\n } else {\n if (!util.global) {\n return function() {\n return false;\n };\n }\n return function(name) {\n var methodName = \"on\" + name.toLowerCase();\n var method = util.global[methodName];\n if (!method) return false;\n method.apply(util.global, [].slice.call(arguments, 1));\n return true;\n };\n }\n})();\n\nfunction generatePromiseLifecycleEventObject(name, promise) {\n return {promise: promise};\n}\n\nvar eventToObjectGenerator = {\n promiseCreated: generatePromiseLifecycleEventObject,\n promiseFulfilled: generatePromiseLifecycleEventObject,\n promiseRejected: generatePromiseLifecycleEventObject,\n promiseResolved: generatePromiseLifecycleEventObject,\n promiseCancelled: generatePromiseLifecycleEventObject,\n promiseChained: function(name, promise, child) {\n return {promise: promise, child: child};\n },\n warning: function(name, warning) {\n return {warning: warning};\n },\n unhandledRejection: function (name, reason, promise) {\n return {reason: reason, promise: promise};\n },\n rejectionHandled: generatePromiseLifecycleEventObject\n};\n\nvar activeFireEvent = function (name) {\n var globalEventFired = false;\n try {\n globalEventFired = fireGlobalEvent.apply(null, arguments);\n } catch (e) {\n async.throwLater(e);\n globalEventFired = true;\n }\n\n var domEventFired = false;\n try {\n domEventFired = fireDomEvent(name,\n eventToObjectGenerator[name].apply(null, arguments));\n } catch (e) {\n async.throwLater(e);\n domEventFired = true;\n }\n\n return domEventFired || globalEventFired;\n};\n\nPromise.config = function(opts) {\n opts = Object(opts);\n if (\"longStackTraces\" in opts) {\n if (opts.longStackTraces) {\n Promise.longStackTraces();\n } else if (!opts.longStackTraces && Promise.hasLongStackTraces()) {\n disableLongStackTraces();\n }\n }\n if (\"warnings\" in opts) {\n var warningsOption = opts.warnings;\n config.warnings = !!warningsOption;\n wForgottenReturn = config.warnings;\n\n if (util.isObject(warningsOption)) {\n if (\"wForgottenReturn\" in warningsOption) {\n wForgottenReturn = !!warningsOption.wForgottenReturn;\n }\n }\n }\n if (\"cancellation\" in opts && opts.cancellation && !config.cancellation) {\n if (async.haveItemsQueued()) {\n throw new Error(\n \"cannot enable cancellation after promises are in use\");\n }\n Promise.prototype._clearCancellationData =\n cancellationClearCancellationData;\n Promise.prototype._propagateFrom = cancellationPropagateFrom;\n Promise.prototype._onCancel = cancellationOnCancel;\n Promise.prototype._setOnCancel = cancellationSetOnCancel;\n Promise.prototype._attachCancellationCallback =\n cancellationAttachCancellationCallback;\n Promise.prototype._execute = cancellationExecute;\n propagateFromFunction = cancellationPropagateFrom;\n config.cancellation = true;\n }\n if (\"monitoring\" in opts) {\n if (opts.monitoring && !config.monitoring) {\n config.monitoring = true;\n Promise.prototype._fireEvent = activeFireEvent;\n } else if (!opts.monitoring && config.monitoring) {\n config.monitoring = false;\n Promise.prototype._fireEvent = defaultFireEvent;\n }\n }\n if (\"asyncHooks\" in opts && util.nodeSupportsAsyncResource) {\n var prev = config.asyncHooks;\n var cur = !!opts.asyncHooks;\n if (prev !== cur) {\n config.asyncHooks = cur;\n if (cur) {\n enableAsyncHooks();\n } else {\n disableAsyncHooks();\n }\n }\n }\n return Promise;\n};\n\nfunction defaultFireEvent() { return false; }\n\nPromise.prototype._fireEvent = defaultFireEvent;\nPromise.prototype._execute = function(executor, resolve, reject) {\n try {\n executor(resolve, reject);\n } catch (e) {\n return e;\n }\n};\nPromise.prototype._onCancel = function () {};\nPromise.prototype._setOnCancel = function (handler) { USE(handler); };\nPromise.prototype._attachCancellationCallback = function(onCancel) {\n USE(onCancel);\n};\nPromise.prototype._captureStackTrace = function () {};\nPromise.prototype._attachExtraTrace = function () {};\nPromise.prototype._dereferenceTrace = function () {};\nPromise.prototype._clearCancellationData = function() {};\nPromise.prototype._propagateFrom = function (parent, flags) {\n USE(parent);\n USE(flags);\n};\n\nfunction cancellationExecute(executor, resolve, reject) {\n var promise = this;\n try {\n executor(resolve, reject, function(onCancel) {\n if (typeof onCancel !== \"function\") {\n throw new TypeError(\"onCancel must be a function, got: \" +\n util.toString(onCancel));\n }\n promise._attachCancellationCallback(onCancel);\n });\n } catch (e) {\n return e;\n }\n}\n\nfunction cancellationAttachCancellationCallback(onCancel) {\n if (!this._isCancellable()) return this;\n\n var previousOnCancel = this._onCancel();\n if (previousOnCancel !== undefined) {\n if (util.isArray(previousOnCancel)) {\n previousOnCancel.push(onCancel);\n } else {\n this._setOnCancel([previousOnCancel, onCancel]);\n }\n } else {\n this._setOnCancel(onCancel);\n }\n}\n\nfunction cancellationOnCancel() {\n ASSERT(this._isCancellable());\n return this._onCancelField;\n}\n\nfunction cancellationSetOnCancel(onCancel) {\n ASSERT(this._isCancellable());\n this._onCancelField = onCancel;\n}\n\nfunction cancellationClearCancellationData() {\n this._cancellationParent = undefined;\n this._onCancelField = undefined;\n}\n\nfunction cancellationPropagateFrom(parent, flags) {\n ASSERT(flags !== 0);\n if ((flags & PROPAGATE_CANCEL) !== 0) {\n this._cancellationParent = parent;\n var branchesRemainingToCancel = parent._branchesRemainingToCancel;\n if (branchesRemainingToCancel === undefined) {\n branchesRemainingToCancel = 0;\n }\n parent._branchesRemainingToCancel = branchesRemainingToCancel + 1;\n }\n if ((flags & PROPAGATE_BIND) !== 0 && parent._isBound()) {\n this._setBoundTo(parent._boundTo);\n }\n}\n\nfunction bindingPropagateFrom(parent, flags) {\n ASSERT(flags !== 0);\n if ((flags & PROPAGATE_BIND) !== 0 && parent._isBound()) {\n this._setBoundTo(parent._boundTo);\n }\n}\nvar propagateFromFunction = bindingPropagateFrom;\n\nfunction boundValueFunction() {\n var ret = this._boundTo;\n if (ret !== undefined) {\n if (ret instanceof Promise) {\n if (ret.isFulfilled()) {\n return ret.value();\n } else {\n return undefined;\n }\n }\n }\n return ret;\n}\n\nfunction longStackTracesCaptureStackTrace() {\n ASSERT(this._trace == null);\n this._trace = new CapturedTrace(this._peekContext());\n}\n\nfunction longStackTracesAttachExtraTrace(error, ignoreSelf) {\n if (canAttachTrace(error)) {\n var trace = this._trace;\n if (trace !== undefined) {\n if (ignoreSelf) trace = trace._parent;\n }\n if (trace !== undefined) {\n trace.attachExtraTrace(error);\n } else if (!error.__stackCleaned__) {\n var parsed = parseStackAndMessage(error);\n util.notEnumerableProp(error, \"stack\",\n parsed.message + \"\\n\" + parsed.stack.join(\"\\n\"));\n util.notEnumerableProp(error, \"__stackCleaned__\", true);\n }\n }\n}\n\nfunction longStackTracesDereferenceTrace() {\n this._trace = undefined;\n}\n\nfunction checkForgottenReturns(returnValue, promiseCreated, name, promise,\n parent) {\n if (returnValue === undefined && promiseCreated !== null &&\n wForgottenReturn) {\n if (parent !== undefined && parent._returnedNonUndefined()) return;\n if (BIT_FIELD_READ(LENGTH_MASK, promise._bitField) === 0) return;\n\n if (name) name = name + \" \";\n var handlerLine = \"\";\n var creatorLine = \"\";\n if (promiseCreated._trace) {\n var traceLines = promiseCreated._trace.stack.split(\"\\n\");\n var stack = cleanStack(traceLines);\n for (var i = stack.length - 1; i >= 0; --i) {\n var line = stack[i];\n if (!nodeFramePattern.test(line)) {\n var lineMatches = line.match(parseLinePattern);\n if (lineMatches) {\n handlerLine = \"at \" + lineMatches[1] +\n \":\" + lineMatches[2] + \":\" + lineMatches[3] + \" \";\n }\n break;\n }\n }\n\n if (stack.length > 0) {\n var firstUserLine = stack[0];\n for (var i = 0; i < traceLines.length; ++i) {\n\n if (traceLines[i] === firstUserLine) {\n if (i > 0) {\n creatorLine = \"\\n\" + traceLines[i - 1];\n }\n break;\n }\n }\n\n }\n }\n var msg = \"a promise was created in a \" + name +\n \"handler \" + handlerLine + \"but was not returned from it, \" +\n \"see http://goo.gl/rRqMUw\" +\n creatorLine;\n promise._warn(msg, true, promiseCreated);\n }\n}\n\nfunction deprecated(name, replacement) {\n var message = name +\n \" is deprecated and will be removed in a future version.\";\n if (replacement) message += \" Use \" + replacement + \" instead.\";\n return warn(message);\n}\n\nfunction warn(message, shouldUseOwnTrace, promise) {\n if (!config.warnings) return;\n var warning = new Warning(message);\n var ctx;\n if (shouldUseOwnTrace) {\n promise._attachExtraTrace(warning);\n } else if (config.longStackTraces && (ctx = Promise._peekContext())) {\n ctx.attachExtraTrace(warning);\n } else {\n var parsed = parseStackAndMessage(warning);\n warning.stack = parsed.message + \"\\n\" + parsed.stack.join(\"\\n\");\n }\n\n if (!activeFireEvent(\"warning\", warning)) {\n formatAndLogError(warning, \"\", true);\n }\n}\n\nfunction reconstructStack(message, stacks) {\n for (var i = 0; i < stacks.length - 1; ++i) {\n stacks[i].push(FROM_PREVIOUS_EVENT);\n stacks[i] = stacks[i].join(\"\\n\");\n }\n if (i < stacks.length) {\n stacks[i] = stacks[i].join(\"\\n\");\n }\n return message + \"\\n\" + stacks.join(\"\\n\");\n}\n\nfunction removeDuplicateOrEmptyJumps(stacks) {\n for (var i = 0; i < stacks.length; ++i) {\n if (stacks[i].length === 0 ||\n ((i + 1 < stacks.length) && stacks[i][0] === stacks[i+1][0])) {\n stacks.splice(i, 1);\n i--;\n }\n }\n}\n\nfunction removeCommonRoots(stacks) {\n var current = stacks[0];\n for (var i = 1; i < stacks.length; ++i) {\n var prev = stacks[i];\n var currentLastIndex = current.length - 1;\n var currentLastLine = current[currentLastIndex];\n var commonRootMeetPoint = -1;\n\n for (var j = prev.length - 1; j >= 0; --j) {\n if (prev[j] === currentLastLine) {\n commonRootMeetPoint = j;\n break;\n }\n }\n\n for (var j = commonRootMeetPoint; j >= 0; --j) {\n var line = prev[j];\n if (current[currentLastIndex] === line) {\n current.pop();\n currentLastIndex--;\n } else {\n break;\n }\n }\n current = prev;\n }\n}\n\nfunction cleanStack(stack) {\n var ret = [];\n for (var i = 0; i < stack.length; ++i) {\n var line = stack[i];\n var isTraceLine = NO_STACK_TRACE === line ||\n stackFramePattern.test(line);\n var isInternalFrame = isTraceLine && shouldIgnore(line);\n if (isTraceLine && !isInternalFrame) {\n if (indentStackFrames && line.charAt(0) !== \" \") {\n // Make Firefox stack traces readable...it is almost\n // impossible to see the event boundaries without\n // indentation.\n line = \" \" + line;\n }\n ret.push(line);\n }\n }\n return ret;\n}\n\nfunction stackFramesAsArray(error) {\n var stack = error.stack.replace(/\\s+$/g, \"\").split(\"\\n\");\n for (var i = 0; i < stack.length; ++i) {\n var line = stack[i];\n if (NO_STACK_TRACE === line || stackFramePattern.test(line)) {\n break;\n }\n }\n // Chrome and IE include the error message in the stack\n if (i > 0 && error.name != \"SyntaxError\") {\n stack = stack.slice(i);\n }\n return stack;\n}\n\nfunction parseStackAndMessage(error) {\n var stack = error.stack;\n var message = error.toString();\n stack = typeof stack === \"string\" && stack.length > 0\n ? stackFramesAsArray(error) : [NO_STACK_TRACE];\n return {\n message: message,\n stack: error.name == \"SyntaxError\" ? stack : cleanStack(stack)\n };\n}\n\nfunction formatAndLogError(error, title, isSoft) {\n if (typeof console !== \"undefined\") {\n var message;\n if (util.isObject(error)) {\n var stack = error.stack;\n message = title + formatStack(stack, error);\n } else {\n message = title + String(error);\n }\n if (typeof printWarning === \"function\") {\n printWarning(message, isSoft);\n } else if (typeof console.log === \"function\" ||\n typeof console.log === \"object\") {\n console.log(message);\n }\n }\n}\n\nfunction fireRejectionEvent(name, localHandler, reason, promise) {\n var localEventFired = false;\n try {\n if (typeof localHandler === \"function\") {\n localEventFired = true;\n if (name === REJECTION_HANDLED_EVENT) {\n localHandler(promise);\n } else {\n localHandler(reason, promise);\n }\n }\n } catch (e) {\n async.throwLater(e);\n }\n\n if (name === UNHANDLED_REJECTION_EVENT) {\n if (!activeFireEvent(name, reason, promise) && !localEventFired) {\n formatAndLogError(reason, UNHANDLED_REJECTION_HEADER);\n }\n } else {\n activeFireEvent(name, promise);\n }\n}\n\nfunction formatNonError(obj) {\n var str;\n if (typeof obj === \"function\") {\n str = \"[function \" +\n (obj.name || \"anonymous\") +\n \"]\";\n } else {\n str = obj && typeof obj.toString === \"function\"\n ? obj.toString() : util.toString(obj);\n var ruselessToString = /\\[object [a-zA-Z0-9$_]+\\]/;\n if (ruselessToString.test(str)) {\n try {\n var newStr = JSON.stringify(obj);\n str = newStr;\n }\n catch(e) {\n\n }\n }\n if (str.length === 0) {\n str = \"(empty array)\";\n }\n }\n return (\"(<\" + snip(str) + \">, no stack trace)\");\n}\n\nfunction snip(str) {\n var maxChars = 41;\n if (str.length < maxChars) {\n return str;\n }\n return str.substr(0, maxChars - 3) + \"...\";\n}\n\nfunction longStackTracesIsSupported() {\n return typeof captureStackTrace === \"function\";\n}\n\n// For filtering out internal calls from stack traces\nvar shouldIgnore = function() { return false; };\nvar parseLineInfoRegex = /[\\/<\\(]([^:\\/]+):(\\d+):(?:\\d+)\\)?\\s*$/;\nfunction parseLineInfo(line) {\n var matches = line.match(parseLineInfoRegex);\n if (matches) {\n return {\n fileName: matches[1],\n line: parseInt(matches[2], 10)\n };\n }\n}\n\nfunction setBounds(firstLineError, lastLineError) {\n if (!longStackTracesIsSupported()) return;\n var firstStackLines = (firstLineError.stack || \"\").split(\"\\n\");\n var lastStackLines = (lastLineError.stack || \"\").split(\"\\n\");\n var firstIndex = -1;\n var lastIndex = -1;\n var firstFileName;\n var lastFileName;\n for (var i = 0; i < firstStackLines.length; ++i) {\n var result = parseLineInfo(firstStackLines[i]);\n if (result) {\n firstFileName = result.fileName;\n firstIndex = result.line;\n break;\n }\n }\n for (var i = 0; i < lastStackLines.length; ++i) {\n var result = parseLineInfo(lastStackLines[i]);\n if (result) {\n lastFileName = result.fileName;\n lastIndex = result.line;\n break;\n }\n }\n if (firstIndex < 0 || lastIndex < 0 || !firstFileName || !lastFileName ||\n firstFileName !== lastFileName || firstIndex >= lastIndex) {\n return;\n }\n\n shouldIgnore = function(line) {\n if (bluebirdFramePattern.test(line)) return true;\n var info = parseLineInfo(line);\n if (info) {\n if (info.fileName === firstFileName &&\n (firstIndex <= info.line && info.line <= lastIndex)) {\n return true;\n }\n }\n return false;\n };\n}\n\nfunction CapturedTrace(parent) {\n ASSERT(parent === undefined || parent instanceof CapturedTrace);\n this._parent = parent;\n this._promisesCreated = 0;\n var length = this._length = 1 + (parent === undefined ? 0 : parent._length);\n captureStackTrace(this, CapturedTrace);\n // Unless the user manually nested > 32 indentation levels,\n // there must be cycles\n if (length > 32) this.uncycle();\n}\nutil.inherits(CapturedTrace, Error);\nContext.CapturedTrace = CapturedTrace;\n\nCapturedTrace.prototype.uncycle = function() {\n var length = this._length;\n if (length < 2) return;\n var nodes = [];\n var stackToIndex = {};\n\n for (var i = 0, node = this; node !== undefined; ++i) {\n nodes.push(node);\n node = node._parent;\n }\n // the node length is only used as heuristic to decide when to decycle, as\n // there may be multiple linked lists that share members and decycling one\n // will fail to update lenghts in the other. This is the correct length.\n length = this._length = i;\n ASSERT(nodes[0] === this);\n ASSERT(nodes[nodes.length - 1] instanceof CapturedTrace);\n\n for (var i = length - 1; i >= 0; --i) {\n var stack = nodes[i].stack;\n if (stackToIndex[stack] === undefined) {\n stackToIndex[stack] = i;\n }\n }\n for (var i = 0; i < length; ++i) {\n var currentStack = nodes[i].stack;\n var index = stackToIndex[currentStack];\n ASSERT(currentStack === nodes[index].stack);\n\n if (index !== undefined && index !== i) {\n if (index > 0) {\n ASSERT(nodes[index - 1]._parent === nodes[index]);\n nodes[index - 1]._parent = undefined;\n nodes[index - 1]._length = 1;\n }\n nodes[i]._parent = undefined;\n nodes[i]._length = 1;\n var cycleEdgeNode = i > 0 ? nodes[i - 1] : this;\n\n if (index < length - 1) {\n cycleEdgeNode._parent = nodes[index + 1];\n cycleEdgeNode._parent.uncycle();\n cycleEdgeNode._length =\n cycleEdgeNode._parent._length + 1;\n } else {\n cycleEdgeNode._parent = undefined;\n cycleEdgeNode._length = 1;\n }\n var currentChildLength = cycleEdgeNode._length + 1;\n for (var j = i - 2; j >= 0; --j) {\n nodes[j]._length = currentChildLength;\n currentChildLength++;\n }\n return;\n }\n }\n};\n\nCapturedTrace.prototype.attachExtraTrace = function(error) {\n if (error.__stackCleaned__) return;\n this.uncycle();\n var parsed = parseStackAndMessage(error);\n var message = parsed.message;\n var stacks = [parsed.stack];\n\n var trace = this;\n while (trace !== undefined) {\n stacks.push(cleanStack(trace.stack.split(\"\\n\")));\n trace = trace._parent;\n }\n removeCommonRoots(stacks);\n removeDuplicateOrEmptyJumps(stacks);\n util.notEnumerableProp(error, \"stack\", reconstructStack(message, stacks));\n util.notEnumerableProp(error, \"__stackCleaned__\", true);\n};\n\nvar captureStackTrace = (function stackDetection() {\n var v8stackFramePattern = /^\\s*at\\s*/;\n var v8stackFormatter = function(stack, error) {\n ASSERT(error !== null);\n\n if (typeof stack === \"string\") return stack;\n\n if (error.name !== undefined &&\n error.message !== undefined) {\n return error.toString();\n }\n return formatNonError(error);\n };\n\n //V8\n if (typeof Error.stackTraceLimit === \"number\" &&\n typeof Error.captureStackTrace === \"function\") {\n Error.stackTraceLimit += 6;\n stackFramePattern = v8stackFramePattern;\n formatStack = v8stackFormatter;\n var captureStackTrace = Error.captureStackTrace;\n\n // For node\n shouldIgnore = function(line) {\n return bluebirdFramePattern.test(line);\n };\n return function(receiver, ignoreUntil) {\n Error.stackTraceLimit += 6;\n captureStackTrace(receiver, ignoreUntil);\n Error.stackTraceLimit -= 6;\n };\n }\n var err = new Error();\n\n //SpiderMonkey\n if (typeof err.stack === \"string\" &&\n err.stack.split(\"\\n\")[0].indexOf(\"stackDetection@\") >= 0) {\n stackFramePattern = /@/;\n formatStack = v8stackFormatter;\n indentStackFrames = true;\n return function captureStackTrace(o) {\n o.stack = new Error().stack;\n };\n }\n\n var hasStackAfterThrow;\n try { throw new Error(); }\n catch(e) {\n hasStackAfterThrow = (\"stack\" in e);\n }\n // IE 10+\n if (!(\"stack\" in err) && hasStackAfterThrow &&\n typeof Error.stackTraceLimit === \"number\") {\n stackFramePattern = v8stackFramePattern;\n formatStack = v8stackFormatter;\n return function captureStackTrace(o) {\n Error.stackTraceLimit += 6;\n try { throw new Error(); }\n catch(e) { o.stack = e.stack; }\n Error.stackTraceLimit -= 6;\n };\n }\n\n formatStack = function(stack, error) {\n if (typeof stack === \"string\") return stack;\n\n if ((typeof error === \"object\" ||\n typeof error === \"function\") &&\n error.name !== undefined &&\n error.message !== undefined) {\n return error.toString();\n }\n return formatNonError(error);\n };\n\n return null;\n\n})([]);\n\nif (typeof console !== \"undefined\" && typeof console.warn !== \"undefined\") {\n printWarning = function (message) {\n console.warn(message);\n };\n if (util.isNode && process.stderr.isTTY) {\n printWarning = function(message, isSoft) {\n var color = isSoft ? \"\\u001b[33m\" : \"\\u001b[31m\";\n console.warn(color + message + \"\\u001b[0m\\n\");\n };\n } else if (!util.isNode && typeof (new Error().stack) === \"string\") {\n printWarning = function(message, isSoft) {\n console.warn(\"%c\" + message,\n isSoft ? \"color: darkorange\" : \"color: red\");\n };\n }\n}\n\nvar config = {\n warnings: warnings,\n longStackTraces: false,\n cancellation: false,\n monitoring: false,\n asyncHooks: false\n};\n\nif (longStackTraces) Promise.longStackTraces();\n\nreturn {\n asyncHooks: function() {\n return config.asyncHooks;\n },\n longStackTraces: function() {\n return config.longStackTraces;\n },\n warnings: function() {\n return config.warnings;\n },\n cancellation: function() {\n return config.cancellation;\n },\n monitoring: function() {\n return config.monitoring;\n },\n propagateFromFunction: function() {\n return propagateFromFunction;\n },\n boundValueFunction: function() {\n return boundValueFunction;\n },\n checkForgottenReturns: checkForgottenReturns,\n setBounds: setBounds,\n warn: warn,\n deprecated: deprecated,\n CapturedTrace: CapturedTrace,\n fireDomEvent: fireDomEvent,\n fireGlobalEvent: fireGlobalEvent\n};\n};\n"
},
{
"path": "src/direct_resolve.js",
"content": "\"use strict\";\nmodule.exports = function(Promise) {\nfunction returner() {\n return this.value;\n}\nfunction thrower() {\n throw this.reason;\n}\n\nPromise.prototype[\"return\"] =\nPromise.prototype.thenReturn = function (value) {\n if (value instanceof Promise) value.suppressUnhandledRejections();\n return this._then(\n returner, undefined, undefined, {value: value}, undefined);\n};\n\nPromise.prototype[\"throw\"] =\nPromise.prototype.thenThrow = function (reason) {\n return this._then(\n thrower, undefined, undefined, {reason: reason}, undefined);\n};\n\nPromise.prototype.catchThrow = function (reason) {\n if (arguments.length <= 1) {\n return this._then(\n undefined, thrower, undefined, {reason: reason}, undefined);\n } else {\n var _reason = arguments[1];\n var handler = function() {throw _reason;};\n return this.caught(reason, handler);\n }\n};\n\nPromise.prototype.catchReturn = function (value) {\n if (arguments.length <= 1) {\n if (value instanceof Promise) value.suppressUnhandledRejections();\n return this._then(\n undefined, returner, undefined, {value: value}, undefined);\n } else {\n var _value = arguments[1];\n if (_value instanceof Promise) _value.suppressUnhandledRejections();\n var handler = function() {return _value;};\n return this.caught(value, handler);\n }\n};\n};\n"
},
{
"path": "src/each.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL) {\nvar PromiseReduce = Promise.reduce;\nvar PromiseAll = Promise.all;\n\nfunction promiseAllThis() {\n return PromiseAll(this);\n}\n\nfunction PromiseMapSeries(promises, fn) {\n return PromiseReduce(promises, fn, INTERNAL, INTERNAL);\n}\n\nPromise.prototype.each = function (fn) {\n return PromiseReduce(this, fn, INTERNAL, 0)\n ._then(promiseAllThis, undefined, undefined, this, undefined);\n};\n\nPromise.prototype.mapSeries = function (fn) {\n return PromiseReduce(this, fn, INTERNAL, INTERNAL);\n};\n\nPromise.each = function (promises, fn) {\n return PromiseReduce(promises, fn, INTERNAL, 0)\n ._then(promiseAllThis, undefined, undefined, promises, undefined);\n};\n\nPromise.mapSeries = PromiseMapSeries;\n};\n\n"
},
{
"path": "src/errors.js",
"content": "\"use strict\";\nvar es5 = require(\"./es5\");\nvar Objectfreeze = es5.freeze;\nvar util = require(\"./util\");\nvar inherits = util.inherits;\nvar notEnumerableProp = util.notEnumerableProp;\n\nfunction subError(nameProperty, defaultMessage) {\n function SubError(message) {\n if (!(this instanceof SubError)) return new SubError(message);\n notEnumerableProp(this, \"message\",\n typeof message === \"string\" ? message : defaultMessage);\n notEnumerableProp(this, \"name\", nameProperty);\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, this.constructor);\n } else {\n Error.call(this);\n }\n }\n inherits(SubError, Error);\n return SubError;\n}\n\nvar _TypeError, _RangeError;\nvar Warning = subError(\"Warning\", \"warning\");\nvar CancellationError = subError(\"CancellationError\", \"cancellation error\");\nvar TimeoutError = subError(\"TimeoutError\", \"timeout error\");\nvar AggregateError = subError(\"AggregateError\", \"aggregate error\");\ntry {\n _TypeError = TypeError;\n _RangeError = RangeError;\n} catch(e) {\n _TypeError = subError(\"TypeError\", \"type error\");\n _RangeError = subError(\"RangeError\", \"range error\");\n}\n\nvar methods = (\"join pop push shift unshift slice filter forEach some \" +\n \"every map indexOf lastIndexOf reduce reduceRight sort reverse\").split(\" \");\n\nfor (var i = 0; i < methods.length; ++i) {\n if (typeof Array.prototype[methods[i]] === \"function\") {\n AggregateError.prototype[methods[i]] = Array.prototype[methods[i]];\n }\n}\n\nes5.defineProperty(AggregateError.prototype, \"length\", {\n value: 0,\n configurable: false,\n writable: true,\n enumerable: true\n});\nAggregateError.prototype[OPERATIONAL_ERROR_KEY] = true;\nvar level = 0;\nAggregateError.prototype.toString = function() {\n var indent = Array(level * 4 + 1).join(\" \");\n var ret = \"\\n\" + indent + \"AggregateError of:\" + \"\\n\";\n level++;\n indent = Array(level * 4 + 1).join(\" \");\n for (var i = 0; i < this.length; ++i) {\n var str = this[i] === this ? \"[Circular AggregateError]\" : this[i] + \"\";\n var lines = str.split(\"\\n\");\n for (var j = 0; j < lines.length; ++j) {\n lines[j] = indent + lines[j];\n }\n str = lines.join(\"\\n\");\n ret += str + \"\\n\";\n }\n level--;\n return ret;\n};\n\nfunction OperationalError(message) {\n if (!(this instanceof OperationalError))\n return new OperationalError(message);\n notEnumerableProp(this, \"name\", \"OperationalError\");\n notEnumerableProp(this, \"message\", message);\n this.cause = message;\n this[OPERATIONAL_ERROR_KEY] = true;\n\n if (message instanceof Error) {\n notEnumerableProp(this, \"message\", message.message);\n notEnumerableProp(this, \"stack\", message.stack);\n } else if (Error.captureStackTrace) {\n Error.captureStackTrace(this, this.constructor);\n }\n\n}\ninherits(OperationalError, Error);\n\n//Ensure all copies of the library throw the same error types\nvar errorTypes = Error[BLUEBIRD_ERRORS];\nif (!errorTypes) {\n errorTypes = Objectfreeze({\n CancellationError: CancellationError,\n TimeoutError: TimeoutError,\n OperationalError: OperationalError,\n RejectionError: OperationalError,\n AggregateError: AggregateError\n });\n es5.defineProperty(Error, BLUEBIRD_ERRORS, {\n value: errorTypes,\n writable: false,\n enumerable: false,\n configurable: false\n });\n}\n\nmodule.exports = {\n Error: Error,\n TypeError: _TypeError,\n RangeError: _RangeError,\n CancellationError: errorTypes.CancellationError,\n OperationalError: errorTypes.OperationalError,\n TimeoutError: errorTypes.TimeoutError,\n AggregateError: errorTypes.AggregateError,\n Warning: Warning\n};\n"
},
{
"path": "src/es5.js",
"content": "var isES5 = (function(){\n \"use strict\";\n return this === undefined;\n})();\n\nif (isES5) {\n module.exports = {\n freeze: Object.freeze,\n defineProperty: Object.defineProperty,\n getDescriptor: Object.getOwnPropertyDescriptor,\n keys: Object.keys,\n names: Object.getOwnPropertyNames,\n getPrototypeOf: Object.getPrototypeOf,\n isArray: Array.isArray,\n isES5: isES5,\n propertyIsWritable: function(obj, prop) {\n var descriptor = Object.getOwnPropertyDescriptor(obj, prop);\n return !!(!descriptor || descriptor.writable || descriptor.set);\n }\n };\n} else {\n var has = {}.hasOwnProperty;\n var str = {}.toString;\n var proto = {}.constructor.prototype;\n\n var ObjectKeys = function (o) {\n var ret = [];\n for (var key in o) {\n if (has.call(o, key)) {\n ret.push(key);\n }\n }\n return ret;\n };\n\n var ObjectGetDescriptor = function(o, key) {\n return {value: o[key]};\n };\n\n var ObjectDefineProperty = function (o, key, desc) {\n o[key] = desc.value;\n return o;\n };\n\n var ObjectFreeze = function (obj) {\n return obj;\n };\n\n var ObjectGetPrototypeOf = function (obj) {\n try {\n return Object(obj).constructor.prototype;\n }\n catch (e) {\n return proto;\n }\n };\n\n var ArrayIsArray = function (obj) {\n try {\n return str.call(obj) === \"[object Array]\";\n }\n catch(e) {\n return false;\n }\n };\n\n module.exports = {\n isArray: ArrayIsArray,\n keys: ObjectKeys,\n names: ObjectKeys,\n defineProperty: ObjectDefineProperty,\n getDescriptor: ObjectGetDescriptor,\n freeze: ObjectFreeze,\n getPrototypeOf: ObjectGetPrototypeOf,\n isES5: isES5,\n propertyIsWritable: function() {\n return true;\n }\n };\n}\n"
},
{
"path": "src/filter.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL) {\nvar PromiseMap = Promise.map;\n\nPromise.prototype.filter = function (fn, options) {\n return PromiseMap(this, fn, options, INTERNAL);\n};\n\nPromise.filter = function (promises, fn, options) {\n return PromiseMap(promises, fn, options, INTERNAL);\n};\n};\n"
},
{
"path": "src/finally.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, tryConvertToPromise, NEXT_FILTER) {\nvar util = require(\"./util\");\nvar CancellationError = Promise.CancellationError;\nvar errorObj = util.errorObj;\nvar catchFilter = require(\"./catch_filter\")(NEXT_FILTER);\n\nfunction PassThroughHandlerContext(promise, type, handler) {\n this.promise = promise;\n this.type = type;\n this.handler = handler;\n this.called = false;\n this.cancelPromise = null;\n}\n\nPassThroughHandlerContext.prototype.isFinallyHandler = function() {\n return this.type === FINALLY_TYPE;\n};\n\nfunction FinallyHandlerCancelReaction(finallyHandler) {\n this.finallyHandler = finallyHandler;\n}\n\nFinallyHandlerCancelReaction.prototype._resultCancelled = function() {\n checkCancel(this.finallyHandler);\n};\n\nfunction checkCancel(ctx, reason) {\n if (ctx.cancelPromise != null) {\n if (arguments.length > 1) {\n ctx.cancelPromise._reject(reason);\n } else {\n ctx.cancelPromise._cancel();\n }\n ctx.cancelPromise = null;\n return true;\n }\n return false;\n}\n\nfunction succeed() {\n return finallyHandler.call(this, this.promise._target()._settledValue());\n}\nfunction fail(reason) {\n if (checkCancel(this, reason)) return;\n errorObj.e = reason;\n return errorObj;\n}\nfunction finallyHandler(reasonOrValue) {\n var promise = this.promise;\n var handler = this.handler;\n\n if (!this.called) {\n this.called = true;\n var ret = this.isFinallyHandler()\n ? handler.call(promise._boundValue())\n : handler.call(promise._boundValue(), reasonOrValue);\n if (ret === NEXT_FILTER) {\n return ret;\n } else if (ret !== undefined) {\n promise._setReturnedNonUndefined();\n var maybePromise = tryConvertToPromise(ret, promise);\n if (maybePromise instanceof Promise) {\n if (this.cancelPromise != null) {\n if (maybePromise._isCancelled()) {\n var reason =\n new CancellationError(LATE_CANCELLATION_OBSERVER);\n promise._attachExtraTrace(reason);\n errorObj.e = reason;\n return errorObj;\n } else if (maybePromise.isPending()) {\n maybePromise._attachCancellationCallback(\n new FinallyHandlerCancelReaction(this));\n }\n }\n return maybePromise._then(\n succeed, fail, undefined, this, undefined);\n }\n }\n }\n\n if (promise.isRejected()) {\n checkCancel(this);\n errorObj.e = reasonOrValue;\n return errorObj;\n } else {\n checkCancel(this);\n return reasonOrValue;\n }\n}\n\nPromise.prototype._passThrough = function(handler, type, success, fail) {\n if (typeof handler !== \"function\") return this.then();\n return this._then(success,\n fail,\n undefined,\n new PassThroughHandlerContext(this, type, handler),\n undefined);\n};\n\nPromise.prototype.lastly =\nPromise.prototype[\"finally\"] = function (handler) {\n return this._passThrough(handler,\n FINALLY_TYPE,\n finallyHandler,\n finallyHandler);\n};\n\n\nPromise.prototype.tap = function (handler) {\n return this._passThrough(handler, TAP_TYPE, finallyHandler);\n};\n\nPromise.prototype.tapCatch = function (handlerOrPredicate) {\n var len = arguments.length;\n if(len === 1) {\n return this._passThrough(handlerOrPredicate,\n TAP_TYPE,\n undefined,\n finallyHandler);\n } else {\n var catchInstances = new Array(len - 1),\n j = 0, i;\n for (i = 0; i < len - 1; ++i) {\n var item = arguments[i];\n if (util.isObject(item)) {\n catchInstances[j++] = item;\n } else {\n return Promise.reject(new TypeError(\n \"tapCatch statement predicate: \"\n + OBJECT_ERROR + util.classString(item)\n ));\n }\n }\n catchInstances.length = j;\n var handler = arguments[i];\n return this._passThrough(catchFilter(catchInstances, handler, this),\n TAP_TYPE,\n undefined,\n finallyHandler);\n }\n\n};\n\nreturn PassThroughHandlerContext;\n};\n"
},
{
"path": "src/generators.js",
"content": "\"use strict\";\nmodule.exports = function(Promise,\n apiRejection,\n INTERNAL,\n tryConvertToPromise,\n Proxyable,\n debug) {\nvar errors = require(\"./errors\");\nvar TypeError = errors.TypeError;\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar errorObj = util.errorObj;\nvar tryCatch = util.tryCatch;\nvar yieldHandlers = [];\n\nfunction promiseFromYieldHandler(value, yieldHandlers, traceParent) {\n for (var i = 0; i < yieldHandlers.length; ++i) {\n traceParent._pushContext();\n var result = tryCatch(yieldHandlers[i])(value);\n traceParent._popContext();\n if (result === errorObj) {\n traceParent._pushContext();\n var ret = Promise.reject(errorObj.e);\n traceParent._popContext();\n return ret;\n }\n var maybePromise = tryConvertToPromise(result, traceParent);\n if (maybePromise instanceof Promise) return maybePromise;\n }\n return null;\n}\n\nfunction PromiseSpawn(generatorFunction, receiver, yieldHandler, stack) {\n if (debug.cancellation()) {\n var internal = new Promise(INTERNAL);\n var _finallyPromise = this._finallyPromise = new Promise(INTERNAL);\n this._promise = internal.lastly(function() {\n return _finallyPromise;\n });\n internal._captureStackTrace();\n internal._setOnCancel(this);\n } else {\n var promise = this._promise = new Promise(INTERNAL);\n promise._captureStackTrace();\n }\n this._stack = stack;\n this._generatorFunction = generatorFunction;\n this._receiver = receiver;\n this._generator = undefined;\n this._yieldHandlers = typeof yieldHandler === \"function\"\n ? [yieldHandler].concat(yieldHandlers)\n : yieldHandlers;\n this._yieldedPromise = null;\n this._cancellationPhase = false;\n}\nutil.inherits(PromiseSpawn, Proxyable);\n\nPromiseSpawn.prototype._isResolved = function() {\n return this._promise === null;\n};\n\nPromiseSpawn.prototype._cleanup = function() {\n this._promise = this._generator = null;\n if (debug.cancellation() && this._finallyPromise !== null) {\n this._finallyPromise._fulfill();\n this._finallyPromise = null;\n }\n};\n\nPromiseSpawn.prototype._promiseCancelled = function() {\n if (this._isResolved()) return;\n var implementsReturn = typeof this._generator[\"return\"] !== \"undefined\";\n\n var result;\n if (!implementsReturn) {\n var reason = new Promise.CancellationError(\n \"generator .return() sentinel\");\n Promise.coroutine.returnSentinel = reason;\n this._promise._attachExtraTrace(reason);\n this._promise._pushContext();\n result = tryCatch(this._generator[\"throw\"]).call(this._generator,\n reason);\n this._promise._popContext();\n } else {\n this._promise._pushContext();\n result = tryCatch(this._generator[\"return\"]).call(this._generator,\n undefined);\n this._promise._popContext();\n }\n this._cancellationPhase = true;\n this._yieldedPromise = null;\n this._continue(result);\n};\n\nPromiseSpawn.prototype._promiseFulfilled = function(value) {\n this._yieldedPromise = null;\n this._promise._pushContext();\n var result = tryCatch(this._generator.next).call(this._generator, value);\n this._promise._popContext();\n this._continue(result);\n};\n\nPromiseSpawn.prototype._promiseRejected = function(reason) {\n this._yieldedPromise = null;\n this._promise._attachExtraTrace(reason);\n this._promise._pushContext();\n var result = tryCatch(this._generator[\"throw\"])\n .call(this._generator, reason);\n this._promise._popContext();\n this._continue(result);\n};\n\nPromiseSpawn.prototype._resultCancelled = function() {\n if (this._yieldedPromise instanceof Promise) {\n var promise = this._yieldedPromise;\n this._yieldedPromise = null;\n promise.cancel();\n }\n};\n\nPromiseSpawn.prototype.promise = function () {\n return this._promise;\n};\n\nPromiseSpawn.prototype._run = function () {\n this._generator = this._generatorFunction.call(this._receiver);\n this._receiver =\n this._generatorFunction = undefined;\n this._promiseFulfilled(undefined);\n};\n\nPromiseSpawn.prototype._continue = function (result) {\n ASSERT(this._yieldedPromise == null);\n var promise = this._promise;\n if (result === errorObj) {\n this._cleanup();\n if (this._cancellationPhase) {\n return promise.cancel();\n } else {\n return promise._rejectCallback(result.e, false);\n }\n }\n\n var value = result.value;\n if (result.done === true) {\n this._cleanup();\n if (this._cancellationPhase) {\n return promise.cancel();\n } else {\n return promise._resolveCallback(value);\n }\n } else {\n var maybePromise = tryConvertToPromise(value, this._promise);\n if (!(maybePromise instanceof Promise)) {\n maybePromise =\n promiseFromYieldHandler(maybePromise,\n this._yieldHandlers,\n this._promise);\n ASSERT(maybePromise === null || maybePromise instanceof Promise);\n if (maybePromise === null) {\n this._promiseRejected(\n new TypeError(\n YIELDED_NON_PROMISE_ERROR.replace(\"%s\", String(value)) +\n FROM_COROUTINE_CREATED_AT +\n this._stack.split(\"\\n\").slice(1, -7).join(\"\\n\")\n )\n );\n return;\n }\n }\n maybePromise = maybePromise._target();\n var bitField = maybePromise._bitField;\n USE(bitField);\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n this._yieldedPromise = maybePromise;\n maybePromise._proxy(this, null);\n } else if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n Promise._async.invoke(\n this._promiseFulfilled, this, maybePromise._value()\n );\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n Promise._async.invoke(\n this._promiseRejected, this, maybePromise._reason()\n );\n } else {\n this._promiseCancelled();\n }\n }\n};\n\nPromise.coroutine = function (generatorFunction, options) {\n //Throw synchronously because Promise.coroutine is semantically\n //something you call at \"compile time\" to annotate static functions\n if (typeof generatorFunction !== \"function\") {\n throw new TypeError(NOT_GENERATOR_ERROR);\n }\n var yieldHandler = Object(options).yieldHandler;\n var PromiseSpawn$ = PromiseSpawn;\n var stack = new Error().stack;\n return function () {\n var generator = generatorFunction.apply(this, arguments);\n var spawn = new PromiseSpawn$(undefined, undefined, yieldHandler,\n stack);\n var ret = spawn.promise();\n spawn._generator = generator;\n spawn._promiseFulfilled(undefined);\n return ret;\n };\n};\n\nPromise.coroutine.addYieldHandler = function(fn) {\n if (typeof fn !== \"function\") {\n throw new TypeError(FUNCTION_ERROR + util.classString(fn));\n }\n yieldHandlers.push(fn);\n};\n\nPromise.spawn = function (generatorFunction) {\n debug.deprecated(\"Promise.spawn()\", \"Promise.coroutine()\");\n //Return rejected promise because Promise.spawn is semantically\n //something that will be called at runtime with possibly dynamic values\n if (typeof generatorFunction !== \"function\") {\n return apiRejection(NOT_GENERATOR_ERROR);\n }\n var spawn = new PromiseSpawn(generatorFunction, this);\n var ret = spawn.promise();\n spawn._run(Promise.spawn);\n return ret;\n};\n};\n"
},
{
"path": "src/join.js",
"content": "\"use strict\";\nmodule.exports =\nfunction(Promise, PromiseArray, tryConvertToPromise, INTERNAL, async) {\nvar util = require(\"./util\");\nvar canEvaluate = util.canEvaluate;\nvar tryCatch = util.tryCatch;\nvar errorObj = util.errorObj;\nvar reject;\n\nif (!__BROWSER__) {\nif (canEvaluate) {\n var thenCallback = function(i) {\n return new Function(\"value\", \"holder\", \" \\n\\\n 'use strict'; \\n\\\n holder.pIndex = value; \\n\\\n holder.checkFulfillment(this); \\n\\\n \".replace(/Index/g, i));\n };\n\n var promiseSetter = function(i) {\n return new Function(\"promise\", \"holder\", \" \\n\\\n 'use strict'; \\n\\\n holder.pIndex = promise; \\n\\\n \".replace(/Index/g, i));\n };\n\n var generateHolderClass = function(total) {\n var props = new Array(total);\n for (var i = 0; i < props.length; ++i) {\n props[i] = \"this.p\" + (i+1);\n }\n var assignment = props.join(\" = \") + \" = null;\";\n var cancellationCode= \"var promise;\\n\" + props.map(function(prop) {\n return \" \\n\\\n promise = \" + prop + \"; \\n\\\n if (promise instanceof Promise) { \\n\\\n promise.cancel(); \\n\\\n } \\n\\\n \";\n }).join(\"\\n\");\n var passedArguments = props.join(\", \");\n var name = \"Holder$\" + total;\n\n\n var code = \"return function(tryCatch, errorObj, Promise, async) { \\n\\\n 'use strict'; \\n\\\n function [TheName](fn) { \\n\\\n [TheProperties] \\n\\\n this.fn = fn; \\n\\\n this.asyncNeeded = true; \\n\\\n this.now = 0; \\n\\\n } \\n\\\n \\n\\\n [TheName].prototype._callFunction = function(promise) { \\n\\\n promise._pushContext(); \\n\\\n var ret = tryCatch(this.fn)([ThePassedArguments]); \\n\\\n promise._popContext(); \\n\\\n if (ret === errorObj) { \\n\\\n promise._rejectCallback(ret.e, false); \\n\\\n } else { \\n\\\n promise._resolveCallback(ret); \\n\\\n } \\n\\\n }; \\n\\\n \\n\\\n [TheName].prototype.checkFulfillment = function(promise) { \\n\\\n var now = ++this.now; \\n\\\n if (now === [TheTotal]) { \\n\\\n if (this.asyncNeeded) { \\n\\\n async.invoke(this._callFunction, this, promise); \\n\\\n } else { \\n\\\n this._callFunction(promise); \\n\\\n } \\n\\\n \\n\\\n } \\n\\\n }; \\n\\\n \\n\\\n [TheName].prototype._resultCancelled = function() { \\n\\\n [CancellationCode] \\n\\\n }; \\n\\\n \\n\\\n return [TheName]; \\n\\\n }(tryCatch, errorObj, Promise, async); \\n\\\n \";\n\n code = code.replace(/\\[TheName\\]/g, name)\n .replace(/\\[TheTotal\\]/g, total)\n .replace(/\\[ThePassedArguments\\]/g, passedArguments)\n .replace(/\\[TheProperties\\]/g, assignment)\n .replace(/\\[CancellationCode\\]/g, cancellationCode);\n\n return new Function(\"tryCatch\", \"errorObj\", \"Promise\", \"async\", code)\n (tryCatch, errorObj, Promise, async);\n };\n\n var holderClasses = [];\n var thenCallbacks = [];\n var promiseSetters = [];\n\n for (var i = 0; i < GENERATED_CLASS_COUNT; ++i) {\n holderClasses.push(generateHolderClass(i + 1));\n thenCallbacks.push(thenCallback(i + 1));\n promiseSetters.push(promiseSetter(i + 1));\n }\n\n reject = function (reason) {\n this._reject(reason);\n };\n}}\n\nPromise.join = function () {\n var last = arguments.length - 1;\n var fn;\n if (last > 0 && typeof arguments[last] === \"function\") {\n fn = arguments[last];\n if (!__BROWSER__) {\n if (last <= GENERATED_CLASS_COUNT && canEvaluate) {\n var ret = new Promise(INTERNAL);\n ret._captureStackTrace();\n var HolderClass = holderClasses[last - 1];\n var holder = new HolderClass(fn);\n var callbacks = thenCallbacks;\n\n for (var i = 0; i < last; ++i) {\n var maybePromise = tryConvertToPromise(arguments[i], ret);\n if (maybePromise instanceof Promise) {\n maybePromise = maybePromise._target();\n var bitField = maybePromise._bitField;\n USE(bitField);\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n maybePromise._then(callbacks[i], reject,\n undefined, ret, holder);\n promiseSetters[i](maybePromise, holder);\n holder.asyncNeeded = false;\n } else if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n callbacks[i].call(ret,\n maybePromise._value(), holder);\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n ret._reject(maybePromise._reason());\n } else {\n ret._cancel();\n }\n } else {\n callbacks[i].call(ret, maybePromise, holder);\n }\n }\n\n if (!ret._isFateSealed()) {\n if (holder.asyncNeeded) {\n var context = Promise._getContext();\n holder.fn = util.contextBind(context, holder.fn);\n }\n ret._setAsyncGuaranteed();\n ret._setOnCancel(holder);\n }\n return ret;\n }\n }\n }\n INLINE_SLICE(args, arguments);\n if (fn) args.pop();\n var ret = new PromiseArray(args).promise();\n return fn !== undefined ? ret.spread(fn) : ret;\n};\n\n};\n"
},
{
"path": "src/map.js",
"content": "\"use strict\";\nmodule.exports = function(Promise,\n PromiseArray,\n apiRejection,\n tryConvertToPromise,\n INTERNAL,\n debug) {\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar tryCatch = util.tryCatch;\nvar errorObj = util.errorObj;\nvar async = Promise._async;\n\nfunction MappingPromiseArray(promises, fn, limit, _filter) {\n this.constructor$(promises);\n this._promise._captureStackTrace();\n var context = Promise._getContext();\n this._callback = util.contextBind(context, fn);\n this._preservedValues = _filter === INTERNAL\n ? new Array(this.length())\n : null;\n this._limit = limit;\n this._inFlight = 0;\n this._queue = [];\n async.invoke(this._asyncInit, this, undefined);\n if (util.isArray(promises)) {\n for (var i = 0; i < promises.length; ++i) {\n var maybePromise = promises[i];\n if (maybePromise instanceof Promise) {\n maybePromise.suppressUnhandledRejections();\n }\n }\n }\n}\nutil.inherits(MappingPromiseArray, PromiseArray);\n\nMappingPromiseArray.prototype._asyncInit = function() {\n this._init$(undefined, RESOLVE_ARRAY);\n};\n\n// The following hack is required because the super constructor\n// might call promiseFulfilled before this.callback = fn is set\n//\n// The super constructor call must always be first so that fields\n// are initialized in the same order so that the sub-class instances\n// will share same memory layout as the super class instances\n\n// Override\nMappingPromiseArray.prototype._init = function () {};\n\n// Override\nMappingPromiseArray.prototype._promiseFulfilled = function (value, index) {\n ASSERT(!this._isResolved());\n var values = this._values;\n var length = this.length();\n var preservedValues = this._preservedValues;\n var limit = this._limit;\n\n // Callback has been called for this index if it's negative\n if (index < 0) {\n // Restore the actual index value\n index = (index * -1) - 1;\n values[index] = value;\n if (limit >= 1) {\n this._inFlight--;\n this._drainQueue();\n if (this._isResolved()) return true;\n }\n } else {\n if (limit >= 1 && this._inFlight >= limit) {\n values[index] = value;\n this._queue.push(index);\n return false;\n }\n if (preservedValues !== null) preservedValues[index] = value;\n\n var promise = this._promise;\n var callback = this._callback;\n var receiver = promise._boundValue();\n promise._pushContext();\n var ret = tryCatch(callback).call(receiver, value, index, length);\n var promiseCreated = promise._popContext();\n debug.checkForgottenReturns(\n ret,\n promiseCreated,\n preservedValues !== null ? \"Promise.filter\" : \"Promise.map\",\n promise\n );\n if (ret === errorObj) {\n this._reject(ret.e);\n return true;\n }\n\n // If the mapper function returned a promise we simply reuse\n // The MappingPromiseArray as a PromiseArray for round 2.\n // To mark an index as \"round 2\" its inverted by adding +1 and\n // multiplying by -1\n var maybePromise = tryConvertToPromise(ret, this._promise);\n if (maybePromise instanceof Promise) {\n maybePromise = maybePromise._target();\n var bitField = maybePromise._bitField;\n USE(bitField);\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n if (limit >= 1) this._inFlight++;\n values[index] = maybePromise;\n maybePromise._proxy(this, (index + 1) * -1);\n return false;\n } else if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n ret = maybePromise._value();\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n this._reject(maybePromise._reason());\n return true;\n } else {\n this._cancel();\n return true;\n }\n }\n values[index] = ret;\n }\n var totalResolved = ++this._totalResolved;\n if (totalResolved >= length) {\n if (preservedValues !== null) {\n this._filter(values, preservedValues);\n } else {\n this._resolve(values);\n }\n return true;\n }\n return false;\n};\n\nMappingPromiseArray.prototype._drainQueue = function () {\n var queue = this._queue;\n var limit = this._limit;\n var values = this._values;\n while (queue.length > 0 && this._inFlight < limit) {\n if (this._isResolved()) return;\n var index = queue.pop();\n this._promiseFulfilled(values[index], index);\n }\n};\n\nMappingPromiseArray.prototype._filter = function (booleans, values) {\n var len = values.length;\n var ret = new Array(len);\n var j = 0;\n for (var i = 0; i < len; ++i) {\n if (booleans[i]) ret[j++] = values[i];\n }\n ret.length = j;\n this._resolve(ret);\n};\n\nMappingPromiseArray.prototype.preservedValues = function () {\n return this._preservedValues;\n};\n\nfunction map(promises, fn, options, _filter) {\n if (typeof fn !== \"function\") {\n return apiRejection(FUNCTION_ERROR + util.classString(fn));\n }\n\n var limit = 0;\n if (options !== undefined) {\n if (typeof options === \"object\" && options !== null) {\n if (typeof options.concurrency !== \"number\") {\n return Promise.reject(\n new TypeError(\"'concurrency' must be a number but it is \" +\n util.classString(options.concurrency)));\n }\n limit = options.concurrency;\n } else {\n return Promise.reject(new TypeError(\n \"options argument must be an object but it is \" +\n util.classString(options)));\n }\n }\n limit = typeof limit === \"number\" &&\n isFinite(limit) && limit >= 1 ? limit : 0;\n return new MappingPromiseArray(promises, fn, limit, _filter).promise();\n}\n\nPromise.prototype.map = function (fn, options) {\n return map(this, fn, options, null);\n};\n\nPromise.map = function (promises, fn, options, _filter) {\n return map(promises, fn, options, _filter);\n};\n\n\n};\n"
},
{
"path": "src/method.js",
"content": "\"use strict\";\nmodule.exports =\nfunction(Promise, INTERNAL, tryConvertToPromise, apiRejection, debug) {\nvar util = require(\"./util\");\nvar ASSERT = require(\"./assert\");\nvar tryCatch = util.tryCatch;\n\nPromise.method = function (fn) {\n if (typeof fn !== \"function\") {\n throw new Promise.TypeError(FUNCTION_ERROR + util.classString(fn));\n }\n return function () {\n var ret = new Promise(INTERNAL);\n ret._captureStackTrace();\n ret._pushContext();\n var value = tryCatch(fn).apply(this, arguments);\n var promiseCreated = ret._popContext();\n debug.checkForgottenReturns(\n value, promiseCreated, \"Promise.method\", ret);\n ret._resolveFromSyncValue(value);\n return ret;\n };\n};\n\nPromise.attempt = Promise[\"try\"] = function (fn) {\n if (typeof fn !== \"function\") {\n return apiRejection(FUNCTION_ERROR + util.classString(fn));\n }\n var ret = new Promise(INTERNAL);\n ret._captureStackTrace();\n ret._pushContext();\n var value;\n if (arguments.length > 1) {\n debug.deprecated(\"calling Promise.try with more than 1 argument\");\n var arg = arguments[1];\n var ctx = arguments[2];\n value = util.isArray(arg) ? tryCatch(fn).apply(ctx, arg)\n : tryCatch(fn).call(ctx, arg);\n } else {\n value = tryCatch(fn)();\n }\n var promiseCreated = ret._popContext();\n debug.checkForgottenReturns(\n value, promiseCreated, \"Promise.try\", ret);\n ret._resolveFromSyncValue(value);\n return ret;\n};\n\nPromise.prototype._resolveFromSyncValue = function (value) {\n ASSERT(!this._isFollowing());\n if (value === util.errorObj) {\n this._rejectCallback(value.e, false);\n } else {\n this._resolveCallback(value, true);\n }\n};\n};\n"
},
{
"path": "src/nodeback.js",
"content": "\"use strict\";\nvar util = require(\"./util\");\nvar maybeWrapAsError = util.maybeWrapAsError;\nvar errors = require(\"./errors\");\nvar OperationalError = errors.OperationalError;\nvar es5 = require(\"./es5\");\n\nfunction isUntypedError(obj) {\n return obj instanceof Error &&\n es5.getPrototypeOf(obj) === Error.prototype;\n}\n\nvar rErrorKey = /^(?:name|message|stack|cause)$/;\nfunction wrapAsOperationalError(obj) {\n var ret;\n if (isUntypedError(obj)) {\n ret = new OperationalError(obj);\n ret.name = obj.name;\n ret.message = obj.message;\n ret.stack = obj.stack;\n var keys = es5.keys(obj);\n for (var i = 0; i < keys.length; ++i) {\n var key = keys[i];\n if (!rErrorKey.test(key)) {\n ret[key] = obj[key];\n }\n }\n return ret;\n }\n util.markAsOriginatingFromRejection(obj);\n return obj;\n}\n\nfunction nodebackForPromise(promise, multiArgs) {\n return function(err, value) {\n if (promise === null) return;\n if (err) {\n var wrapped = wrapAsOperationalError(maybeWrapAsError(err));\n promise._attachExtraTrace(wrapped);\n promise._reject(wrapped);\n } else if (!multiArgs) {\n promise._fulfill(value);\n } else {\n INLINE_SLICE(args, arguments, 1);\n promise._fulfill(args);\n }\n promise = null;\n };\n}\n\nmodule.exports = nodebackForPromise;\n"
},
{
"path": "src/nodeify.js",
"content": "\"use strict\";\nmodule.exports = function(Promise) {\nvar util = require(\"./util\");\nvar async = Promise._async;\nvar ASSERT = require(\"./assert\");\nvar tryCatch = util.tryCatch;\nvar errorObj = util.errorObj;\n\nfunction spreadAdapter(val, nodeback) {\n var promise = this;\n if (!util.isArray(val)) return successAdapter.call(promise, val, nodeback);\n var ret =\n tryCatch(nodeback).apply(promise._boundValue(), [null].concat(val));\n if (ret === errorObj) {\n async.throwLater(ret.e);\n }\n}\n\nfunction successAdapter(val, nodeback) {\n var promise = this;\n var receiver = promise._boundValue();\n ASSERT(typeof nodeback == \"function\");\n var ret = val === undefined\n ? tryCatch(nodeback).call(receiver, null)\n : tryCatch(nodeback).call(receiver, null, val);\n if (ret === errorObj) {\n async.throwLater(ret.e);\n }\n}\nfunction errorAdapter(reason, nodeback) {\n var promise = this;\n if (!reason) {\n var newReason = new Error(reason + \"\");\n newReason.cause = reason;\n reason = newReason;\n ASSERT(!!reason);\n }\n ASSERT(typeof nodeback == \"function\");\n var ret = tryCatch(nodeback).call(promise._boundValue(), reason);\n if (ret === errorObj) {\n async.throwLater(ret.e);\n }\n}\n\nPromise.prototype.asCallback = Promise.prototype.nodeify = function (nodeback,\n options) {\n if (typeof nodeback == \"function\") {\n var adapter = successAdapter;\n if (options !== undefined && Object(options).spread) {\n adapter = spreadAdapter;\n }\n this._then(\n adapter,\n errorAdapter,\n undefined,\n this,\n nodeback\n );\n }\n return this;\n};\n};\n"
},
{
"path": "src/promise.js",
"content": "\"use strict\";\nmodule.exports = function() {\nvar makeSelfResolutionError = function () {\n return new TypeError(CIRCULAR_RESOLUTION_ERROR);\n};\nvar reflectHandler = function() {\n return new Promise.PromiseInspection(this._target());\n};\nvar apiRejection = function(msg) {\n return Promise.reject(new TypeError(msg));\n};\nfunction Proxyable() {}\nvar UNDEFINED_BINDING = {};\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nutil.setReflectHandler(reflectHandler);\n\nvar getDomain = function() {\n var domain = process.domain;\n if (domain === undefined) {\n return null;\n }\n return domain;\n};\nvar getContextDefault = function() {\n return null;\n};\nvar getContextDomain = function() {\n return {\n domain: getDomain(),\n async: null\n };\n};\nvar AsyncResource = util.isNode && util.nodeSupportsAsyncResource ?\n require(\"async_hooks\").AsyncResource : null;\nvar getContextAsyncHooks = function() {\n return {\n domain: getDomain(),\n async: new AsyncResource(\"Bluebird::Promise\")\n };\n};\nvar getContext = util.isNode ? getContextDomain : getContextDefault;\nutil.notEnumerableProp(Promise, \"_getContext\", getContext);\nvar enableAsyncHooks = function() {\n getContext = getContextAsyncHooks;\n util.notEnumerableProp(Promise, \"_getContext\", getContextAsyncHooks);\n};\nvar disableAsyncHooks = function() {\n getContext = getContextDomain;\n util.notEnumerableProp(Promise, \"_getContext\", getContextDomain);\n};\n\nvar es5 = require(\"./es5\");\nvar Async = require(\"./async\");\nvar async = new Async();\nes5.defineProperty(Promise, \"_async\", {value: async});\nvar errors = require(\"./errors\");\nvar TypeError = Promise.TypeError = errors.TypeError;\nPromise.RangeError = errors.RangeError;\nvar CancellationError = Promise.CancellationError = errors.CancellationError;\nPromise.TimeoutError = errors.TimeoutError;\nPromise.OperationalError = errors.OperationalError;\nPromise.RejectionError = errors.OperationalError;\nPromise.AggregateError = errors.AggregateError;\nvar INTERNAL = function(){};\nvar APPLY = {};\nvar NEXT_FILTER = {};\nvar tryConvertToPromise = require(\"./thenables\")(Promise, INTERNAL);\nvar PromiseArray =\n require(\"./promise_array\")(Promise, INTERNAL,\n tryConvertToPromise, apiRejection, Proxyable);\nvar Context = require(\"./context\")(Promise);\n /*jshint unused:false*/\nvar createContext = Context.create;\n\nvar debug = require(\"./debuggability\")(Promise, Context,\n enableAsyncHooks, disableAsyncHooks);\nvar CapturedTrace = debug.CapturedTrace;\nvar PassThroughHandlerContext =\n require(\"./finally\")(Promise, tryConvertToPromise, NEXT_FILTER);\nvar catchFilter = require(\"./catch_filter\")(NEXT_FILTER);\nvar nodebackForPromise = require(\"./nodeback\");\nvar errorObj = util.errorObj;\nvar tryCatch = util.tryCatch;\nfunction check(self, executor) {\n if (self == null || self.constructor !== Promise) {\n throw new TypeError(CONSTRUCT_ERROR_INVOCATION);\n }\n if (typeof executor !== \"function\") {\n throw new TypeError(FUNCTION_ERROR + util.classString(executor));\n }\n\n}\n\nfunction Promise(executor) {\n if (executor !== INTERNAL) {\n check(this, executor);\n }\n this._bitField = NO_STATE;\n this._fulfillmentHandler0 = undefined;\n this._rejectionHandler0 = undefined;\n this._promise0 = undefined;\n this._receiver0 = undefined;\n this._resolveFromExecutor(executor);\n this._promiseCreated();\n this._fireEvent(\"promiseCreated\", this);\n}\n\nPromise.prototype.toString = function () {\n return \"[object Promise]\";\n};\n\nPromise.prototype.caught = Promise.prototype[\"catch\"] = function (fn) {\n var len = arguments.length;\n if (len > 1) {\n var catchInstances = new Array(len - 1),\n j = 0, i;\n for (i = 0; i < len - 1; ++i) {\n var item = arguments[i];\n if (util.isObject(item)) {\n catchInstances[j++] = item;\n } else {\n return apiRejection(\"Catch statement predicate: \" +\n OBJECT_ERROR + util.classString(item));\n }\n }\n catchInstances.length = j;\n fn = arguments[i];\n\n if (typeof fn !== \"function\") {\n throw new TypeError(\"The last argument to .catch() \" +\n \"must be a function, got \" + util.toString(fn));\n }\n return this.then(undefined, catchFilter(catchInstances, fn, this));\n }\n return this.then(undefined, fn);\n};\n\nPromise.prototype.reflect = function () {\n return this._then(reflectHandler,\n reflectHandler, undefined, this, undefined);\n};\n\nPromise.prototype.then = function (didFulfill, didReject) {\n if (debug.warnings() && arguments.length > 0 &&\n typeof didFulfill !== \"function\" &&\n typeof didReject !== \"function\") {\n var msg = \".then() only accepts functions but was passed: \" +\n util.classString(didFulfill);\n if (arguments.length > 1) {\n msg += \", \" + util.classString(didReject);\n }\n this._warn(msg);\n }\n return this._then(didFulfill, didReject, undefined, undefined, undefined);\n};\n\nPromise.prototype.done = function (didFulfill, didReject) {\n var promise =\n this._then(didFulfill, didReject, undefined, undefined, undefined);\n promise._setIsFinal();\n};\n\nPromise.prototype.spread = function (fn) {\n if (typeof fn !== \"function\") {\n return apiRejection(FUNCTION_ERROR + util.classString(fn));\n }\n return this.all()._then(fn, undefined, undefined, APPLY, undefined);\n};\n\nPromise.prototype.toJSON = function () {\n var ret = {\n isFulfilled: false,\n isRejected: false,\n fulfillmentValue: undefined,\n rejectionReason: undefined\n };\n if (this.isFulfilled()) {\n ret.fulfillmentValue = this.value();\n ret.isFulfilled = true;\n } else if (this.isRejected()) {\n ret.rejectionReason = this.reason();\n ret.isRejected = true;\n }\n return ret;\n};\n\nPromise.prototype.all = function () {\n if (arguments.length > 0) {\n this._warn(\".all() was passed arguments but it does not take any\");\n }\n return new PromiseArray(this).promise();\n};\n\nPromise.prototype.error = function (fn) {\n return this.caught(util.originatesFromRejection, fn);\n};\n\nPromise.getNewLibraryCopy = module.exports;\n\nPromise.is = function (val) {\n return val instanceof Promise;\n};\n\nPromise.fromNode = Promise.fromCallback = function(fn) {\n var ret = new Promise(INTERNAL);\n ret._captureStackTrace();\n var multiArgs = arguments.length > 1 ? !!Object(arguments[1]).multiArgs\n : false;\n var result = tryCatch(fn)(nodebackForPromise(ret, multiArgs));\n if (result === errorObj) {\n ret._rejectCallback(result.e, true);\n }\n if (!ret._isFateSealed()) ret._setAsyncGuaranteed();\n return ret;\n};\n\nPromise.all = function (promises) {\n return new PromiseArray(promises).promise();\n};\n\nPromise.cast = function (obj) {\n var ret = tryConvertToPromise(obj);\n if (!(ret instanceof Promise)) {\n ret = new Promise(INTERNAL);\n ret._captureStackTrace();\n ret._setFulfilled();\n ret._rejectionHandler0 = obj;\n }\n return ret;\n};\n\nPromise.resolve = Promise.fulfilled = Promise.cast;\n\nPromise.reject = Promise.rejected = function (reason) {\n var ret = new Promise(INTERNAL);\n ret._captureStackTrace();\n ret._rejectCallback(reason, true);\n return ret;\n};\n\nPromise.setScheduler = function(fn) {\n if (typeof fn !== \"function\") {\n throw new TypeError(FUNCTION_ERROR + util.classString(fn));\n }\n return async.setScheduler(fn);\n};\n\nPromise.prototype._then = function (\n didFulfill,\n didReject,\n _, // For fast-cast compatibility between bluebird versions\n receiver,\n internalData\n) {\n ASSERT(arguments.length === 5);\n var haveInternalData = internalData !== undefined;\n var promise = haveInternalData ? internalData : new Promise(INTERNAL);\n var target = this._target();\n var bitField = target._bitField;\n\n if (!haveInternalData) {\n promise._propagateFrom(this, PROPAGATE_ALL);\n promise._captureStackTrace();\n if (receiver === undefined &&\n BIT_FIELD_CHECK(IS_BOUND, this._bitField)) {\n if (!BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n receiver = this._boundValue();\n } else {\n receiver = target === this ? undefined : this._boundTo;\n }\n }\n this._fireEvent(\"promiseChained\", this, promise);\n }\n\n var context = getContext();\n if (!BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n var handler, value, settler = target._settlePromiseCtx;\n if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n value = target._rejectionHandler0;\n handler = didFulfill;\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n value = target._fulfillmentHandler0;\n handler = didReject;\n target._unsetRejectionIsUnhandled();\n } else {\n settler = target._settlePromiseLateCancellationObserver;\n value = new CancellationError(LATE_CANCELLATION_OBSERVER);\n target._attachExtraTrace(value);\n handler = didReject;\n }\n\n async.invoke(settler, target, {\n handler: util.contextBind(context, handler),\n promise: promise,\n receiver: receiver,\n value: value\n });\n } else {\n target._addCallbacks(didFulfill, didReject, promise,\n receiver, context);\n }\n\n return promise;\n};\n\nPromise.prototype._length = function () {\n ASSERT(arguments.length === 0);\n return this._bitField & LENGTH_MASK;\n};\n\nPromise.prototype._isFateSealed = function () {\n return (this._bitField & IS_FATE_SEALED) !== 0;\n};\n\nPromise.prototype._isFollowing = function () {\n return (this._bitField & IS_FOLLOWING) === IS_FOLLOWING;\n};\n\nPromise.prototype._setLength = function (len) {\n this._bitField = (this._bitField & LENGTH_CLEAR_MASK) |\n (len & LENGTH_MASK);\n};\n\nPromise.prototype._setFulfilled = function () {\n this._bitField = this._bitField | IS_FULFILLED;\n this._fireEvent(\"promiseFulfilled\", this);\n};\n\nPromise.prototype._setRejected = function () {\n this._bitField = this._bitField | IS_REJECTED;\n this._fireEvent(\"promiseRejected\", this);\n};\n\nPromise.prototype._setFollowing = function () {\n this._bitField = this._bitField | IS_FOLLOWING;\n this._fireEvent(\"promiseResolved\", this);\n};\n\nPromise.prototype._setIsFinal = function () {\n this._bitField = this._bitField | IS_FINAL;\n};\n\nPromise.prototype._isFinal = function () {\n return (this._bitField & IS_FINAL) > 0;\n};\n\nPromise.prototype._unsetCancelled = function() {\n this._bitField = this._bitField & (~IS_CANCELLED);\n};\n\nPromise.prototype._setCancelled = function() {\n this._bitField = this._bitField | IS_CANCELLED;\n this._fireEvent(\"promiseCancelled\", this);\n};\n\nPromise.prototype._setWillBeCancelled = function() {\n this._bitField = this._bitField | WILL_BE_CANCELLED;\n};\n\nPromise.prototype._setAsyncGuaranteed = function() {\n if (async.hasCustomScheduler()) return;\n var bitField = this._bitField;\n this._bitField = bitField |\n (((bitField & NO_ASYNC_GUARANTEE) >> ASYNC_GUARANTEE_SHIFT) ^\n IS_ASYNC_GUARANTEED);\n};\n\nPromise.prototype._setNoAsyncGuarantee = function() {\n this._bitField = (this._bitField | NO_ASYNC_GUARANTEE) &\n (~IS_ASYNC_GUARANTEED);\n};\n\nPromise.prototype._receiverAt = function (index) {\n ASSERT(!this._isFollowing());\n var ret = index === 0 ? this._receiver0 : this[\n index * CALLBACK_SIZE - CALLBACK_SIZE + CALLBACK_RECEIVER_OFFSET];\n //Only use the bound value when not calling internal methods\n if (ret === UNDEFINED_BINDING) {\n return undefined;\n } else if (ret === undefined && this._isBound()) {\n return this._boundValue();\n }\n return ret;\n};\n\nPromise.prototype._promiseAt = function (index) {\n ASSERT(index > 0);\n ASSERT(!this._isFollowing());\n return this[\n index * CALLBACK_SIZE - CALLBACK_SIZE + CALLBACK_PROMISE_OFFSET];\n};\n\nPromise.prototype._fulfillmentHandlerAt = function (index) {\n ASSERT(!this._isFollowing());\n ASSERT(index > 0);\n return this[\n index * CALLBACK_SIZE - CALLBACK_SIZE + CALLBACK_FULFILL_OFFSET];\n};\n\nPromise.prototype._rejectionHandlerAt = function (index) {\n ASSERT(!this._isFollowing());\n ASSERT(index > 0);\n return this[\n index * CALLBACK_SIZE - CALLBACK_SIZE + CALLBACK_REJECT_OFFSET];\n};\n\nPromise.prototype._boundValue = function() {};\n\nPromise.prototype._migrateCallback0 = function (follower) {\n var bitField = follower._bitField;\n var fulfill = follower._fulfillmentHandler0;\n var reject = follower._rejectionHandler0;\n var promise = follower._promise0;\n var receiver = follower._receiverAt(0);\n if (receiver === undefined) receiver = UNDEFINED_BINDING;\n this._addCallbacks(fulfill, reject, promise, receiver, null);\n};\n\nPromise.prototype._migrateCallbackAt = function (follower, index) {\n ASSERT(index > 0);\n var fulfill = follower._fulfillmentHandlerAt(index);\n var reject = follower._rejectionHandlerAt(index);\n var promise = follower._promiseAt(index);\n var receiver = follower._receiverAt(index);\n if (receiver === undefined) receiver = UNDEFINED_BINDING;\n this._addCallbacks(fulfill, reject, promise, receiver, null);\n};\n\nPromise.prototype._addCallbacks = function (\n fulfill,\n reject,\n promise,\n receiver,\n context\n) {\n ASSERT(typeof context === \"object\");\n ASSERT(!this._isFateSealed());\n ASSERT(!this._isFollowing());\n var index = this._length();\n\n if (index >= MAX_LENGTH - CALLBACK_SIZE) {\n index = 0;\n this._setLength(0);\n }\n\n if (index === 0) {\n ASSERT(this._promise0 === undefined);\n ASSERT(this._receiver0 === undefined);\n ASSERT(this._fulfillmentHandler0 === undefined);\n ASSERT(this._rejectionHandler0 === undefined);\n\n this._promise0 = promise;\n this._receiver0 = receiver;\n if (typeof fulfill === \"function\") {\n this._fulfillmentHandler0 = util.contextBind(context, fulfill);\n }\n if (typeof reject === \"function\") {\n this._rejectionHandler0 = util.contextBind(context, reject);\n }\n } else {\n ASSERT(this[base + CALLBACK_PROMISE_OFFSET] === undefined);\n ASSERT(this[base + CALLBACK_RECEIVER_OFFSET] === undefined);\n ASSERT(this[base + CALLBACK_FULFILL_OFFSET] === undefined);\n ASSERT(this[base + CALLBACK_REJECT_OFFSET] === undefined);\n var base = index * CALLBACK_SIZE - CALLBACK_SIZE;\n this[base + CALLBACK_PROMISE_OFFSET] = promise;\n this[base + CALLBACK_RECEIVER_OFFSET] = receiver;\n if (typeof fulfill === \"function\") {\n this[base + CALLBACK_FULFILL_OFFSET] =\n util.contextBind(context, fulfill);\n }\n if (typeof reject === \"function\") {\n this[base + CALLBACK_REJECT_OFFSET] =\n util.contextBind(context, reject);\n }\n }\n this._setLength(index + 1);\n return index;\n};\n\nPromise.prototype._proxy = function (proxyable, arg) {\n ASSERT(proxyable instanceof Proxyable);\n ASSERT(!(arg instanceof Promise));\n ASSERT(!this._isFollowing());\n ASSERT(arguments.length === 2);\n ASSERT(!this._isFateSealed());\n this._addCallbacks(undefined, undefined, arg, proxyable, null);\n};\n\nPromise.prototype._resolveCallback = function(value, shouldBind) {\n if (BIT_FIELD_CHECK(IS_FATE_SEALED, this._bitField)) return;\n if (value === this)\n return this._rejectCallback(makeSelfResolutionError(), false);\n var maybePromise = tryConvertToPromise(value, this);\n if (!(maybePromise instanceof Promise)) return this._fulfill(value);\n\n if (shouldBind) this._propagateFrom(maybePromise, PROPAGATE_BIND);\n\n\n var promise = maybePromise._target();\n\n if (promise === this) {\n this._reject(makeSelfResolutionError());\n return;\n }\n\n var bitField = promise._bitField;\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n var len = this._length();\n if (len > 0) promise._migrateCallback0(this);\n for (var i = 1; i < len; ++i) {\n promise._migrateCallbackAt(this, i);\n }\n this._setFollowing();\n this._setLength(0);\n this._setFollowee(maybePromise);\n } else if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n this._fulfill(promise._value());\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n this._reject(promise._reason());\n } else {\n var reason = new CancellationError(LATE_CANCELLATION_OBSERVER);\n promise._attachExtraTrace(reason);\n this._reject(reason);\n }\n};\n\nPromise.prototype._rejectCallback =\nfunction(reason, synchronous, ignoreNonErrorWarnings) {\n var trace = util.ensureErrorObject(reason);\n var hasStack = trace === reason;\n if (!hasStack && !ignoreNonErrorWarnings && debug.warnings()) {\n var message = \"a promise was rejected with a non-error: \" +\n util.classString(reason);\n this._warn(message, true);\n }\n this._attachExtraTrace(trace, synchronous ? hasStack : false);\n this._reject(reason);\n};\n\nPromise.prototype._resolveFromExecutor = function (executor) {\n if (executor === INTERNAL) return;\n ASSERT(typeof executor === \"function\");\n var promise = this;\n this._captureStackTrace();\n this._pushContext();\n var synchronous = true;\n var r = this._execute(executor, function(value) {\n promise._resolveCallback(value);\n }, function (reason) {\n promise._rejectCallback(reason, synchronous);\n });\n synchronous = false;\n this._popContext();\n\n if (r !== undefined) {\n promise._rejectCallback(r, true);\n }\n};\n\nPromise.prototype._settlePromiseFromHandler = function (\n handler, receiver, value, promise\n) {\n var bitField = promise._bitField;\n if (BIT_FIELD_CHECK(IS_CANCELLED)) return;\n promise._pushContext();\n var x;\n if (receiver === APPLY) {\n if (!value || typeof value.length !== \"number\") {\n x = errorObj;\n x.e = new TypeError(\"cannot .spread() a non-array: \" +\n util.classString(value));\n } else {\n x = tryCatch(handler).apply(this._boundValue(), value);\n }\n } else {\n x = tryCatch(handler).call(receiver, value);\n }\n var promiseCreated = promise._popContext();\n bitField = promise._bitField;\n if (BIT_FIELD_CHECK(IS_CANCELLED)) return;\n\n ASSERT(!promise._isFateSealed());\n\n if (x === NEXT_FILTER) {\n promise._reject(value);\n } else if (x === errorObj) {\n promise._rejectCallback(x.e, false);\n } else {\n debug.checkForgottenReturns(x, promiseCreated, \"\", promise, this);\n promise._resolveCallback(x);\n }\n};\n\nPromise.prototype._target = function() {\n var ret = this;\n while (ret._isFollowing()) ret = ret._followee();\n return ret;\n};\n\nPromise.prototype._followee = function() {\n ASSERT(this._isFollowing());\n ASSERT(this._rejectionHandler0 instanceof Promise);\n return this._rejectionHandler0;\n};\n\nPromise.prototype._setFollowee = function(promise) {\n ASSERT(this._isFollowing());\n ASSERT(!(this._rejectionHandler0 instanceof Promise));\n this._rejectionHandler0 = promise;\n};\n\nPromise.prototype._settlePromise = function(promise, handler, receiver, value) {\n ASSERT(!this._isFollowing());\n var isPromise = promise instanceof Promise;\n var bitField = this._bitField;\n var asyncGuaranteed = BIT_FIELD_CHECK(IS_ASYNC_GUARANTEED);\n if (BIT_FIELD_CHECK(IS_CANCELLED)) {\n if (isPromise) promise._invokeInternalOnCancel();\n\n if (receiver instanceof PassThroughHandlerContext &&\n receiver.isFinallyHandler()) {\n receiver.cancelPromise = promise;\n if (tryCatch(handler).call(receiver, value) === errorObj) {\n promise._reject(errorObj.e);\n }\n } else if (handler === reflectHandler) {\n promise._fulfill(reflectHandler.call(receiver));\n } else if (receiver instanceof Proxyable) {\n receiver._promiseCancelled(promise);\n } else if (isPromise || promise instanceof PromiseArray) {\n promise._cancel();\n } else {\n receiver.cancel();\n }\n } else if (typeof handler === \"function\") {\n //if promise is not instanceof Promise\n //it is internally smuggled data\n if (!isPromise) {\n handler.call(receiver, value, promise);\n } else {\n if (asyncGuaranteed) promise._setAsyncGuaranteed();\n this._settlePromiseFromHandler(handler, receiver, value, promise);\n }\n } else if (receiver instanceof Proxyable) {\n if (!receiver._isResolved()) {\n if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n receiver._promiseFulfilled(value, promise);\n } else {\n receiver._promiseRejected(value, promise);\n }\n }\n } else if (isPromise) {\n if (asyncGuaranteed) promise._setAsyncGuaranteed();\n if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n promise._fulfill(value);\n } else {\n promise._reject(value);\n }\n }\n};\n\nPromise.prototype._settlePromiseLateCancellationObserver = function(ctx) {\n var handler = ctx.handler;\n var promise = ctx.promise;\n var receiver = ctx.receiver;\n var value = ctx.value;\n if (typeof handler === \"function\") {\n if (!(promise instanceof Promise)) {\n handler.call(receiver, value, promise);\n } else {\n this._settlePromiseFromHandler(handler, receiver, value, promise);\n }\n } else if (promise instanceof Promise) {\n promise._reject(value);\n }\n};\n\nPromise.prototype._settlePromiseCtx = function(ctx) {\n this._settlePromise(ctx.promise, ctx.handler, ctx.receiver, ctx.value);\n};\n\nPromise.prototype._settlePromise0 = function(handler, value, bitField) {\n var promise = this._promise0;\n var receiver = this._receiverAt(0);\n this._promise0 = undefined;\n this._receiver0 = undefined;\n this._settlePromise(promise, handler, receiver, value);\n};\n\nPromise.prototype._clearCallbackDataAtIndex = function(index) {\n ASSERT(!this._isFollowing());\n ASSERT(index > 0);\n var base = index * CALLBACK_SIZE - CALLBACK_SIZE;\n this[base + CALLBACK_PROMISE_OFFSET] =\n this[base + CALLBACK_RECEIVER_OFFSET] =\n this[base + CALLBACK_FULFILL_OFFSET] =\n this[base + CALLBACK_REJECT_OFFSET] = undefined;\n};\n\nPromise.prototype._fulfill = function (value) {\n var bitField = this._bitField;\n if (BIT_FIELD_READ(IS_FATE_SEALED)) return;\n if (value === this) {\n var err = makeSelfResolutionError();\n this._attachExtraTrace(err);\n return this._reject(err);\n }\n this._setFulfilled();\n this._rejectionHandler0 = value;\n\n if (BIT_FIELD_READ(LENGTH_MASK) > 0) {\n if (BIT_FIELD_CHECK(IS_ASYNC_GUARANTEED)) {\n this._settlePromises();\n } else {\n async.settlePromises(this);\n }\n this._dereferenceTrace();\n }\n};\n\nPromise.prototype._reject = function (reason) {\n var bitField = this._bitField;\n if (BIT_FIELD_READ(IS_FATE_SEALED)) return;\n this._setRejected();\n this._fulfillmentHandler0 = reason;\n\n if (this._isFinal()) {\n ASSERT(this._length() === 0);\n return async.fatalError(reason, util.isNode);\n }\n\n if (BIT_FIELD_READ(LENGTH_MASK) > 0) {\n async.settlePromises(this);\n } else {\n this._ensurePossibleRejectionHandled();\n }\n};\n\nPromise.prototype._fulfillPromises = function (len, value) {\n for (var i = 1; i < len; i++) {\n var handler = this._fulfillmentHandlerAt(i);\n var promise = this._promiseAt(i);\n var receiver = this._receiverAt(i);\n this._clearCallbackDataAtIndex(i);\n this._settlePromise(promise, handler, receiver, value);\n }\n};\n\nPromise.prototype._rejectPromises = function (len, reason) {\n for (var i = 1; i < len; i++) {\n var handler = this._rejectionHandlerAt(i);\n var promise = this._promiseAt(i);\n var receiver = this._receiverAt(i);\n this._clearCallbackDataAtIndex(i);\n this._settlePromise(promise, handler, receiver, reason);\n }\n};\n\nPromise.prototype._settlePromises = function () {\n var bitField = this._bitField;\n var len = BIT_FIELD_READ(LENGTH_MASK);\n\n if (len > 0) {\n if (BIT_FIELD_CHECK(IS_REJECTED_OR_CANCELLED)) {\n var reason = this._fulfillmentHandler0;\n this._settlePromise0(this._rejectionHandler0, reason, bitField);\n this._rejectPromises(len, reason);\n } else {\n var value = this._rejectionHandler0;\n this._settlePromise0(this._fulfillmentHandler0, value, bitField);\n this._fulfillPromises(len, value);\n }\n this._setLength(0);\n }\n this._clearCancellationData();\n};\n\nPromise.prototype._settledValue = function() {\n ASSERT(!this._isFollowing());\n ASSERT(this._isFateSealed());\n var bitField = this._bitField;\n if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n return this._rejectionHandler0;\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n return this._fulfillmentHandler0;\n }\n // Implicit undefined for cancelled promise.\n};\n\nif (typeof Symbol !== \"undefined\" && Symbol.toStringTag) {\n es5.defineProperty(Promise.prototype, Symbol.toStringTag, {\n get: function () {\n return \"Object\";\n }\n });\n}\n\nfunction deferResolve(v) {this.promise._resolveCallback(v);}\nfunction deferReject(v) {this.promise._rejectCallback(v, false);}\n\nPromise.defer = Promise.pending = function() {\n debug.deprecated(\"Promise.defer\", \"new Promise\");\n var promise = new Promise(INTERNAL);\n return {\n promise: promise,\n resolve: deferResolve,\n reject: deferReject\n };\n};\n\nutil.notEnumerableProp(Promise,\n \"_makeSelfResolutionError\",\n makeSelfResolutionError);\n\nrequire(\"./method\")(Promise, INTERNAL, tryConvertToPromise, apiRejection,\n debug);\nrequire(\"./bind\")(Promise, INTERNAL, tryConvertToPromise, debug);\nrequire(\"./cancel\")(Promise, PromiseArray, apiRejection, debug);\nrequire(\"./direct_resolve\")(Promise);\nrequire(\"./synchronous_inspection\")(Promise);\nrequire(\"./join\")(\n Promise, PromiseArray, tryConvertToPromise, INTERNAL, async);\nPromise.Promise = Promise;\nPromise.version = \"__VERSION__\";\n};\n"
},
{
"path": "src/promise_array.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL, tryConvertToPromise,\n apiRejection, Proxyable) {\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar isArray = util.isArray;\n\n//To avoid eagerly allocating the objects\n//and also because undefined cannot be smuggled\nfunction toResolutionValue(val) {\n switch(val) {\n case RESOLVE_ARRAY: return [];\n case RESOLVE_OBJECT: return {};\n case RESOLVE_MAP: return new Map();\n }\n ASSERT(false);\n}\n\nfunction PromiseArray(values) {\n ASSERT(arguments.length === 1);\n var promise = this._promise = new Promise(INTERNAL);\n if (values instanceof Promise) {\n promise._propagateFrom(values, PROPAGATE_ALL);\n values.suppressUnhandledRejections();\n }\n promise._setOnCancel(this);\n this._values = values;\n this._length = 0;\n this._totalResolved = 0;\n this._init(undefined, RESOLVE_ARRAY);\n}\nutil.inherits(PromiseArray, Proxyable);\n\nPromiseArray.prototype.length = function () {\n return this._length;\n};\n\nPromiseArray.prototype.promise = function () {\n return this._promise;\n};\n\nPromiseArray.prototype._init = function init(_, resolveValueIfEmpty) {\n var values = tryConvertToPromise(this._values, this._promise);\n if (values instanceof Promise) {\n values = values._target();\n var bitField = values._bitField;\n USE(bitField);\n this._values = values;\n\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n ASSERT(typeof resolveValueIfEmpty === \"number\");\n ASSERT(resolveValueIfEmpty < 0);\n this._promise._setAsyncGuaranteed();\n return values._then(\n init,\n this._reject,\n undefined,\n this,\n resolveValueIfEmpty\n );\n } else if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n values = values._value();\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n return this._reject(values._reason());\n } else {\n return this._cancel();\n }\n }\n values = util.asArray(values);\n if (values === null) {\n var err = apiRejection(\n COLLECTION_ERROR + util.classString(values)).reason();\n this._promise._rejectCallback(err, false);\n return;\n }\n\n if (values.length === 0) {\n if (resolveValueIfEmpty === RESOLVE_CALL_METHOD) {\n this._resolveEmptyArray();\n }\n else {\n this._resolve(toResolutionValue(resolveValueIfEmpty));\n }\n return;\n }\n this._iterate(values);\n};\n\nPromiseArray.prototype._iterate = function(values) {\n var len = this.getActualLength(values.length);\n this._length = len;\n this._values = this.shouldCopyValues() ? new Array(len) : this._values;\n var result = this._promise;\n var isResolved = false;\n var bitField = null;\n for (var i = 0; i < len; ++i) {\n var maybePromise = tryConvertToPromise(values[i], result);\n\n if (maybePromise instanceof Promise) {\n maybePromise = maybePromise._target();\n bitField = maybePromise._bitField;\n } else {\n bitField = null;\n }\n\n if (isResolved) {\n if (bitField !== null) {\n maybePromise.suppressUnhandledRejections();\n }\n } else if (bitField !== null) {\n if (BIT_FIELD_CHECK(IS_PENDING_AND_WAITING_NEG)) {\n // Optimized for just passing the updates through\n maybePromise._proxy(this, i);\n this._values[i] = maybePromise;\n } else if (BIT_FIELD_CHECK(IS_FULFILLED)) {\n isResolved = this._promiseFulfilled(maybePromise._value(), i);\n } else if (BIT_FIELD_CHECK(IS_REJECTED)) {\n isResolved = this._promiseRejected(maybePromise._reason(), i);\n } else {\n isResolved = this._promiseCancelled(i);\n }\n } else {\n isResolved = this._promiseFulfilled(maybePromise, i);\n }\n ASSERT(typeof isResolved === \"boolean\");\n }\n if (!isResolved) result._setAsyncGuaranteed();\n};\n\nPromiseArray.prototype._isResolved = function () {\n return this._values === null;\n};\n\nPromiseArray.prototype._resolve = function (value) {\n ASSERT(!this._isResolved());\n ASSERT(!(value instanceof Promise));\n this._values = null;\n this._promise._fulfill(value);\n};\n\nPromiseArray.prototype._cancel = function() {\n if (this._isResolved() || !this._promise._isCancellable()) return;\n this._values = null;\n this._promise._cancel();\n};\n\nPromiseArray.prototype._reject = function (reason) {\n ASSERT(!this._isResolved());\n this._values = null;\n this._promise._rejectCallback(reason, false);\n};\n\nPromiseArray.prototype._promiseFulfilled = function (value, index) {\n ASSERT(!this._isResolved());\n ASSERT(isArray(this._values));\n ASSERT(typeof index === \"number\");\n this._values[index] = value;\n var totalResolved = ++this._totalResolved;\n if (totalResolved >= this._length) {\n this._resolve(this._values);\n return true;\n }\n return false;\n};\n\nPromiseArray.prototype._promiseCancelled = function() {\n this._cancel();\n return true;\n};\n\nPromiseArray.prototype._promiseRejected = function (reason) {\n ASSERT(!this._isResolved());\n ASSERT(isArray(this._values));\n this._totalResolved++;\n this._reject(reason);\n return true;\n};\n\nPromiseArray.prototype._resultCancelled = function() {\n if (this._isResolved()) return;\n var values = this._values;\n this._cancel();\n if (values instanceof Promise) {\n values.cancel();\n } else {\n for (var i = 0; i < values.length; ++i) {\n if (values[i] instanceof Promise) {\n values[i].cancel();\n }\n }\n }\n};\n\nPromiseArray.prototype.shouldCopyValues = function () {\n return true;\n};\n\nPromiseArray.prototype.getActualLength = function (len) {\n return len;\n};\n\nreturn PromiseArray;\n};\n"
},
{
"path": "src/promisify.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL) {\nvar THIS = {};\nvar util = require(\"./util\");\nvar nodebackForPromise = require(\"./nodeback\");\nvar withAppended = util.withAppended;\nvar maybeWrapAsError = util.maybeWrapAsError;\nvar canEvaluate = util.canEvaluate;\nvar ASSERT = require(\"./assert\");\nvar TypeError = require(\"./errors\").TypeError;\nvar defaultSuffix = AFTER_PROMISIFIED_SUFFIX;\nvar defaultPromisified = {__isPromisified__: true};\nvar noCopyProps = [\n \"arity\", // Firefox 4\n \"length\",\n \"name\",\n \"arguments\",\n \"caller\",\n \"callee\",\n \"prototype\",\n \"__isPromisified__\"\n];\nvar noCopyPropsPattern = new RegExp(\"^(?:\" + noCopyProps.join(\"|\") + \")$\");\n\nvar defaultFilter = function(name) {\n return util.isIdentifier(name) &&\n name.charAt(0) !== \"_\" &&\n name !== \"constructor\";\n};\n\nfunction propsFilter(key) {\n return !noCopyPropsPattern.test(key);\n}\n\nfunction isPromisified(fn) {\n try {\n return fn.__isPromisified__ === true;\n }\n catch (e) {\n return false;\n }\n}\n\nfunction hasPromisified(obj, key, suffix) {\n var val = util.getDataPropertyOrDefault(obj, key + suffix,\n defaultPromisified);\n return val ? isPromisified(val) : false;\n}\nfunction checkValid(ret, suffix, suffixRegexp) {\n // Verify that in the list of methods to promisify there is no\n // method that has a name ending in \"Async\"-suffix while\n // also having a method with the same name but no Async suffix\n for (var i = 0; i < ret.length; i += 2) {\n var key = ret[i];\n if (suffixRegexp.test(key)) {\n var keyWithoutAsyncSuffix = key.replace(suffixRegexp, \"\");\n for (var j = 0; j < ret.length; j += 2) {\n if (ret[j] === keyWithoutAsyncSuffix) {\n throw new TypeError(PROMISIFICATION_NORMAL_METHODS_ERROR\n .replace(\"%s\", suffix));\n }\n }\n }\n }\n}\n\nfunction promisifiableMethods(obj, suffix, suffixRegexp, filter) {\n var keys = util.inheritedDataKeys(obj);\n var ret = [];\n for (var i = 0; i < keys.length; ++i) {\n var key = keys[i];\n var value = obj[key];\n var passesDefaultFilter = filter === defaultFilter\n ? true : defaultFilter(key, value, obj);\n if (typeof value === \"function\" &&\n !isPromisified(value) &&\n !hasPromisified(obj, key, suffix) &&\n filter(key, value, obj, passesDefaultFilter)) {\n ret.push(key, value);\n }\n }\n checkValid(ret, suffix, suffixRegexp);\n return ret;\n}\n\nvar escapeIdentRegex = function(str) {\n return str.replace(/([$])/, \"\\\\$\");\n};\n\nvar makeNodePromisifiedEval;\nif (!__BROWSER__) {\n//Gives an optimal sequence of argument count to try given a formal parameter\n//.length for a function\nvar switchCaseArgumentOrder = function(likelyArgumentCount) {\n var ret = [likelyArgumentCount];\n var min = Math.max(0, likelyArgumentCount - 1 - PARAM_COUNTS_TO_TRY);\n for(var i = likelyArgumentCount - 1; i >= min; --i) {\n ret.push(i);\n }\n for(var i = likelyArgumentCount + 1; i <= PARAM_COUNTS_TO_TRY; ++i) {\n ret.push(i);\n }\n return ret;\n};\n\nvar argumentSequence = function(argumentCount) {\n return util.filledRange(argumentCount, \"_arg\", \"\");\n};\n\nvar parameterDeclaration = function(parameterCount) {\n return util.filledRange(\n Math.max(parameterCount, PARAM_COUNTS_TO_TRY), \"_arg\", \"\");\n};\n\nvar parameterCount = function(fn) {\n if (typeof fn.length === \"number\") {\n return Math.max(Math.min(fn.length, MAX_PARAM_COUNT + 1), 0);\n }\n //Unsupported .length for functions\n return 0;\n};\n\nmakeNodePromisifiedEval =\nfunction(callback, receiver, originalName, fn, _, multiArgs) {\n //-1 for the callback parameter\n var newParameterCount = Math.max(0, parameterCount(fn) - 1);\n var argumentOrder = switchCaseArgumentOrder(newParameterCount);\n var shouldProxyThis = typeof callback === \"string\" || receiver === THIS;\n\n function generateCallForArgumentCount(count) {\n var args = argumentSequence(count).join(\", \");\n var comma = count > 0 ? \", \" : \"\";\n var ret;\n if (shouldProxyThis) {\n ret = \"ret = callback.call(this, {{args}}, nodeback); break;\\n\";\n } else {\n ret = receiver === undefined\n ? \"ret = callback({{args}}, nodeback); break;\\n\"\n : \"ret = callback.call(receiver, {{args}}, nodeback); break;\\n\";\n }\n return ret.replace(\"{{args}}\", args).replace(\", \", comma);\n }\n\n function generateArgumentSwitchCase() {\n var ret = \"\";\n for (var i = 0; i < argumentOrder.length; ++i) {\n ret += \"case \" + argumentOrder[i] +\":\" +\n generateCallForArgumentCount(argumentOrder[i]);\n }\n\n ret += \" \\n\\\n default: \\n\\\n var args = new Array(len + 1); \\n\\\n var i = 0; \\n\\\n for (var i = 0; i < len; ++i) { \\n\\\n args[i] = arguments[i]; \\n\\\n } \\n\\\n args[i] = nodeback; \\n\\\n [CodeForCall] \\n\\\n break; \\n\\\n \".replace(\"[CodeForCall]\", (shouldProxyThis\n ? \"ret = callback.apply(this, args);\\n\"\n : \"ret = callback.apply(receiver, args);\\n\"));\n return ret;\n }\n\n var getFunctionCode = typeof callback === \"string\"\n ? (\"this != null ? this['\"+callback+\"'] : fn\")\n : \"fn\";\n var body = \"'use strict'; \\n\\\n var ret = function (Parameters) { \\n\\\n 'use strict'; \\n\\\n var len = arguments.length; \\n\\\n var promise = new Promise(INTERNAL); \\n\\\n promise._captureStackTrace(); \\n\\\n var nodeback = nodebackForPromise(promise, \" + multiArgs + \"); \\n\\\n var ret; \\n\\\n var callback = tryCatch([GetFunctionCode]); \\n\\\n switch(len) { \\n\\\n [CodeForSwitchCase] \\n\\\n } \\n\\\n if (ret === errorObj) { \\n\\\n promise._rejectCallback(maybeWrapAsError(ret.e), true, true);\\n\\\n } \\n\\\n if (!promise._isFateSealed()) promise._setAsyncGuaranteed(); \\n\\\n return promise; \\n\\\n }; \\n\\\n notEnumerableProp(ret, '__isPromisified__', true); \\n\\\n return ret; \\n\\\n \".replace(\"[CodeForSwitchCase]\", generateArgumentSwitchCase())\n .replace(\"[GetFunctionCode]\", getFunctionCode);\n body = body.replace(\"Parameters\", parameterDeclaration(newParameterCount));\n return new Function(\"Promise\",\n \"fn\",\n \"receiver\",\n \"withAppended\",\n \"maybeWrapAsError\",\n \"nodebackForPromise\",\n \"tryCatch\",\n \"errorObj\",\n \"notEnumerableProp\",\n \"INTERNAL\",\n body)(\n Promise,\n fn,\n receiver,\n withAppended,\n maybeWrapAsError,\n nodebackForPromise,\n util.tryCatch,\n util.errorObj,\n util.notEnumerableProp,\n INTERNAL);\n};\n}\n\nfunction makeNodePromisifiedClosure(callback, receiver, _, fn, __, multiArgs) {\n var defaultThis = (function() {return this;})();\n var method = callback;\n if (typeof method === \"string\") {\n callback = fn;\n }\n function promisified() {\n var _receiver = receiver;\n if (receiver === THIS) _receiver = this;\n ASSERT(typeof callback === \"function\");\n var promise = new Promise(INTERNAL);\n promise._captureStackTrace();\n var cb = typeof method === \"string\" && this !== defaultThis\n ? this[method] : callback;\n var fn = nodebackForPromise(promise, multiArgs);\n try {\n cb.apply(_receiver, withAppended(arguments, fn));\n } catch(e) {\n promise._rejectCallback(maybeWrapAsError(e), true, true);\n }\n if (!promise._isFateSealed()) promise._setAsyncGuaranteed();\n return promise;\n }\n util.notEnumerableProp(promisified, \"__isPromisified__\", true);\n return promisified;\n}\n\nvar makeNodePromisified = canEvaluate\n ? makeNodePromisifiedEval\n : makeNodePromisifiedClosure;\n\nfunction promisifyAll(obj, suffix, filter, promisifier, multiArgs) {\n ASSERT(typeof suffix === \"string\");\n ASSERT(typeof filter === \"function\");\n var suffixRegexp = new RegExp(escapeIdentRegex(suffix) + \"$\");\n var methods =\n promisifiableMethods(obj, suffix, suffixRegexp, filter);\n\n for (var i = 0, len = methods.length; i < len; i+= 2) {\n var key = methods[i];\n var fn = methods[i+1];\n var promisifiedKey = key + suffix;\n if (promisifier === makeNodePromisified) {\n obj[promisifiedKey] =\n makeNodePromisified(key, THIS, key, fn, suffix, multiArgs);\n } else {\n var promisified = promisifier(fn, function() {\n return makeNodePromisified(key, THIS, key,\n fn, suffix, multiArgs);\n });\n util.notEnumerableProp(promisified, \"__isPromisified__\", true);\n obj[promisifiedKey] = promisified;\n }\n }\n util.toFastProperties(obj);\n return obj;\n}\n\nfunction promisify(callback, receiver, multiArgs) {\n return makeNodePromisified(callback, receiver, undefined,\n callback, null, multiArgs);\n}\n\nPromise.promisify = function (fn, options) {\n if (typeof fn !== \"function\") {\n throw new TypeError(FUNCTION_ERROR + util.classString(fn));\n }\n if (isPromisified(fn)) {\n return fn;\n }\n options = Object(options);\n var receiver = options.context === undefined ? THIS : options.context;\n var multiArgs = !!options.multiArgs;\n var ret = promisify(fn, receiver, multiArgs);\n util.copyDescriptors(fn, ret, propsFilter);\n return ret;\n};\n\nPromise.promisifyAll = function (target, options) {\n if (typeof target !== \"function\" && typeof target !== \"object\") {\n throw new TypeError(PROMISIFY_TYPE_ERROR);\n }\n options = Object(options);\n var multiArgs = !!options.multiArgs;\n var suffix = options.suffix;\n if (typeof suffix !== \"string\") suffix = defaultSuffix;\n var filter = options.filter;\n if (typeof filter !== \"function\") filter = defaultFilter;\n var promisifier = options.promisifier;\n if (typeof promisifier !== \"function\") promisifier = makeNodePromisified;\n\n if (!util.isIdentifier(suffix)) {\n throw new RangeError(SUFFIX_NOT_IDENTIFIER);\n }\n\n var keys = util.inheritedDataKeys(target);\n for (var i = 0; i < keys.length; ++i) {\n var value = target[keys[i]];\n if (keys[i] !== \"constructor\" &&\n util.isClass(value)) {\n promisifyAll(value.prototype, suffix, filter, promisifier,\n multiArgs);\n promisifyAll(value, suffix, filter, promisifier, multiArgs);\n }\n }\n\n return promisifyAll(target, suffix, filter, promisifier, multiArgs);\n};\n};\n\n"
},
{
"path": "src/props.js",
"content": "\"use strict\";\nmodule.exports = function(\n Promise, PromiseArray, tryConvertToPromise, apiRejection) {\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar isObject = util.isObject;\nvar es5 = require(\"./es5\");\nvar Es6Map;\nif (typeof Map === \"function\") Es6Map = Map;\n\nvar mapToEntries = (function() {\n var index = 0;\n var size = 0;\n\n function extractEntry(value, key) {\n this[index] = value;\n this[index + size] = key;\n index++;\n }\n\n return function mapToEntries(map) {\n size = map.size;\n index = 0;\n var ret = new Array(map.size * 2);\n map.forEach(extractEntry, ret);\n return ret;\n };\n})();\n\nvar entriesToMap = function(entries) {\n var ret = new Es6Map();\n var length = entries.length / 2 | 0;\n for (var i = 0; i < length; ++i) {\n var key = entries[length + i];\n var value = entries[i];\n ret.set(key, value);\n }\n return ret;\n};\n\nfunction PropertiesPromiseArray(obj) {\n var isMap = false;\n var entries;\n if (Es6Map !== undefined && obj instanceof Es6Map) {\n entries = mapToEntries(obj);\n isMap = true;\n } else {\n var keys = es5.keys(obj);\n var len = keys.length;\n entries = new Array(len * 2);\n for (var i = 0; i < len; ++i) {\n var key = keys[i];\n entries[i] = obj[key];\n entries[i + len] = key;\n }\n }\n this.constructor$(entries);\n this._isMap = isMap;\n this._init$(undefined, isMap ? RESOLVE_MAP : RESOLVE_OBJECT);\n}\nutil.inherits(PropertiesPromiseArray, PromiseArray);\n\n//Override\nPropertiesPromiseArray.prototype._init = function () {};\n\n//Override\nPropertiesPromiseArray.prototype._promiseFulfilled = function (value, index) {\n ASSERT(!this._isResolved());\n ASSERT(!(value instanceof Promise));\n this._values[index] = value;\n var totalResolved = ++this._totalResolved;\n if (totalResolved >= this._length) {\n var val;\n if (this._isMap) {\n val = entriesToMap(this._values);\n } else {\n val = {};\n var keyOffset = this.length();\n for (var i = 0, len = this.length(); i < len; ++i) {\n val[this._values[i + keyOffset]] = this._values[i];\n }\n }\n this._resolve(val);\n return true;\n }\n return false;\n};\n\n// Override\nPropertiesPromiseArray.prototype.shouldCopyValues = function () {\n return false;\n};\n\n// Override\nPropertiesPromiseArray.prototype.getActualLength = function (len) {\n return len >> 1;\n};\n\nfunction props(promises) {\n var ret;\n var castValue = tryConvertToPromise(promises);\n\n if (!isObject(castValue)) {\n return apiRejection(PROPS_TYPE_ERROR);\n } else if (castValue instanceof Promise) {\n ret = castValue._then(\n Promise.props, undefined, undefined, undefined, undefined);\n } else {\n ret = new PropertiesPromiseArray(castValue).promise();\n }\n\n if (castValue instanceof Promise) {\n ret._propagateFrom(castValue, PROPAGATE_BIND);\n }\n return ret;\n}\n\nPromise.prototype.props = function () {\n return props(this);\n};\n\nPromise.props = function (promises) {\n return props(promises);\n};\n};\n"
},
{
"path": "src/queue.js",
"content": "\"use strict\";\nvar ASSERT = require(\"./assert\");\nfunction arrayMove(src, srcIndex, dst, dstIndex, len) {\n for (var j = 0; j < len; ++j) {\n dst[j + dstIndex] = src[j + srcIndex];\n src[j + srcIndex] = void 0;\n }\n}\n\nfunction Queue(capacity) {\n this._capacity = capacity;\n this._length = 0;\n this._front = 0;\n}\n\nQueue.prototype._willBeOverCapacity = function (size) {\n return this._capacity < size;\n};\n\nQueue.prototype._pushOne = function (arg) {\n var length = this.length();\n this._checkCapacity(length + 1);\n var i = (this._front + length) & (this._capacity - 1);\n this[i] = arg;\n this._length = length + 1;\n};\n\nQueue.prototype.push = function (fn, receiver, arg) {\n ASSERT(arguments.length === 3);\n ASSERT(typeof fn === \"function\");\n var length = this.length() + 3;\n if (this._willBeOverCapacity(length)) {\n //The fast array copies expect the\n //underlying array to be filled completely\n this._pushOne(fn);\n this._pushOne(receiver);\n this._pushOne(arg);\n return;\n }\n var j = this._front + length - 3;\n this._checkCapacity(length);\n var wrapMask = this._capacity - 1;\n this[(j + 0) & wrapMask] = fn;\n this[(j + 1) & wrapMask] = receiver;\n this[(j + 2) & wrapMask] = arg;\n this._length = length;\n};\n\nQueue.prototype.shift = function () {\n ASSERT(this.length() > 0);\n var front = this._front,\n ret = this[front];\n\n this[front] = undefined;\n this._front = (front + 1) & (this._capacity - 1);\n this._length--;\n return ret;\n};\n\nQueue.prototype.length = function () {\n return this._length;\n};\n\nQueue.prototype._checkCapacity = function (size) {\n if (this._capacity < size) {\n this._resizeTo(this._capacity << 1);\n }\n};\n\nQueue.prototype._resizeTo = function (capacity) {\n var oldCapacity = this._capacity;\n this._capacity = capacity;\n var front = this._front;\n var length = this._length;\n var moveItemsCount = (front + length) & (oldCapacity - 1);\n arrayMove(this, 0, this, oldCapacity, moveItemsCount);\n};\n\nmodule.exports = Queue;\n"
},
{
"path": "src/race.js",
"content": "\"use strict\";\nmodule.exports = function(\n Promise, INTERNAL, tryConvertToPromise, apiRejection) {\nvar util = require(\"./util\");\n\nvar raceLater = function (promise) {\n return promise.then(function(array) {\n return race(array, promise);\n });\n};\n\nfunction race(promises, parent) {\n var maybePromise = tryConvertToPromise(promises);\n\n if (maybePromise instanceof Promise) {\n return raceLater(maybePromise);\n } else {\n promises = util.asArray(promises);\n if (promises === null)\n return apiRejection(COLLECTION_ERROR + util.classString(promises));\n }\n\n var ret = new Promise(INTERNAL);\n if (parent !== undefined) {\n ret._propagateFrom(parent, PROPAGATE_ALL);\n }\n var fulfill = ret._fulfill;\n var reject = ret._reject;\n for (var i = 0, len = promises.length; i < len; ++i) {\n var val = promises[i];\n\n if (val === undefined && !(i in promises)) {\n continue;\n }\n\n Promise.cast(val)._then(fulfill, reject, undefined, ret, null);\n }\n //Yes, if promises were empty, it will be forever pending :-)\n return ret;\n}\n\nPromise.race = function (promises) {\n return race(promises, undefined);\n};\n\nPromise.prototype.race = function () {\n return race(this, undefined);\n};\n\n};\n"
},
{
"path": "src/reduce.js",
"content": "\"use strict\";\nmodule.exports = function(Promise,\n PromiseArray,\n apiRejection,\n tryConvertToPromise,\n INTERNAL,\n debug) {\nvar util = require(\"./util\");\nvar tryCatch = util.tryCatch;\n\nfunction ReductionPromiseArray(promises, fn, initialValue, _each) {\n this.constructor$(promises);\n var context = Promise._getContext();\n this._fn = util.contextBind(context, fn);\n if (initialValue !== undefined) {\n initialValue = Promise.resolve(initialValue);\n initialValue._attachCancellationCallback(this);\n }\n this._initialValue = initialValue;\n this._currentCancellable = null;\n if(_each === INTERNAL) {\n this._eachValues = Array(this._length);\n } else if (_each === 0) {\n this._eachValues = null;\n } else {\n this._eachValues = undefined;\n }\n this._promise._captureStackTrace();\n this._init$(undefined, RESOLVE_CALL_METHOD);\n}\nutil.inherits(ReductionPromiseArray, PromiseArray);\n\nReductionPromiseArray.prototype._gotAccum = function(accum) {\n if (this._eachValues !== undefined &&\n this._eachValues !== null &&\n accum !== INTERNAL) {\n this._eachValues.push(accum);\n }\n};\n\nReductionPromiseArray.prototype._eachComplete = function(value) {\n if (this._eachValues !== null) {\n this._eachValues.push(value);\n }\n return this._eachValues;\n};\n\n// Override\nReductionPromiseArray.prototype._init = function() {};\n\n// Override\nReductionPromiseArray.prototype._resolveEmptyArray = function() {\n this._resolve(this._eachValues !== undefined ? this._eachValues\n : this._initialValue);\n};\n\n// Override\nReductionPromiseArray.prototype.shouldCopyValues = function () {\n return false;\n};\n\n// Override\nReductionPromiseArray.prototype._resolve = function(value) {\n this._promise._resolveCallback(value);\n this._values = null;\n};\n\n// Override\nReductionPromiseArray.prototype._resultCancelled = function(sender) {\n if (sender === this._initialValue) return this._cancel();\n if (this._isResolved()) return;\n this._resultCancelled$();\n if (this._currentCancellable instanceof Promise) {\n this._currentCancellable.cancel();\n }\n if (this._initialValue instanceof Promise) {\n this._initialValue.cancel();\n }\n};\n\n// Override\nReductionPromiseArray.prototype._iterate = function (values) {\n this._values = values;\n var value;\n var i;\n var length = values.length;\n if (this._initialValue !== undefined) {\n value = this._initialValue;\n i = 0;\n } else {\n value = Promise.resolve(values[0]);\n i = 1;\n }\n\n this._currentCancellable = value;\n\n for (var j = i; j < length; ++j) {\n var maybePromise = values[j];\n if (maybePromise instanceof Promise) {\n maybePromise.suppressUnhandledRejections();\n }\n }\n\n if (!value.isRejected()) {\n for (; i < length; ++i) {\n var ctx = {\n accum: null,\n value: values[i],\n index: i,\n length: length,\n array: this\n };\n\n value = value._then(gotAccum, undefined, undefined, ctx, undefined);\n\n // Too many promises chained with asyncGuaranteed will result in\n // stack overflow. Break up long chains to reset stack.\n if ((i & 127) === 0) {\n value._setNoAsyncGuarantee();\n }\n }\n }\n\n if (this._eachValues !== undefined) {\n value = value\n ._then(this._eachComplete, undefined, undefined, this, undefined);\n }\n value._then(completed, completed, undefined, value, this);\n};\n\nPromise.prototype.reduce = function (fn, initialValue) {\n return reduce(this, fn, initialValue, null);\n};\n\nPromise.reduce = function (promises, fn, initialValue, _each) {\n return reduce(promises, fn, initialValue, _each);\n};\n\nfunction completed(valueOrReason, array) {\n if (this.isFulfilled()) {\n array._resolve(valueOrReason);\n } else {\n array._reject(valueOrReason);\n }\n}\n\nfunction reduce(promises, fn, initialValue, _each) {\n if (typeof fn !== \"function\") {\n return apiRejection(FUNCTION_ERROR + util.classString(fn));\n }\n var array = new ReductionPromiseArray(promises, fn, initialValue, _each);\n return array.promise();\n}\n\nfunction gotAccum(accum) {\n this.accum = accum;\n this.array._gotAccum(accum);\n var value = tryConvertToPromise(this.value, this.array._promise);\n if (value instanceof Promise) {\n this.array._currentCancellable = value;\n return value._then(gotValue, undefined, undefined, this, undefined);\n } else {\n return gotValue.call(this, value);\n }\n}\n\nfunction gotValue(value) {\n var array = this.array;\n var promise = array._promise;\n var fn = tryCatch(array._fn);\n promise._pushContext();\n var ret;\n if (array._eachValues !== undefined) {\n ret = fn.call(promise._boundValue(), value, this.index, this.length);\n } else {\n ret = fn.call(promise._boundValue(),\n this.accum, value, this.index, this.length);\n }\n if (ret instanceof Promise) {\n array._currentCancellable = ret;\n }\n var promiseCreated = promise._popContext();\n debug.checkForgottenReturns(\n ret,\n promiseCreated,\n array._eachValues !== undefined ? \"Promise.each\" : \"Promise.reduce\",\n promise\n );\n return ret;\n}\n};\n"
},
{
"path": "src/schedule.js",
"content": "\"use strict\";\nvar util = require(\"./util\");\nvar schedule;\nvar noAsyncScheduler = function() {\n throw new Error(NO_ASYNC_SCHEDULER);\n};\nvar NativePromise = util.getNativePromise();\n// This file figures out which scheduler to use for Bluebird. It normalizes\n// async task scheduling across target platforms. Note that not all JS target\n// platforms come supported. The scheduler is overridable with `setScheduler`.\n\n// Our scheduler for Node.js/io.js is setImmediate for recent\n// versions of node because of macrotask semantics.\n// The `typeof` check is for an edge case with nw.js.\nif (util.isNode && typeof MutationObserver === \"undefined\") {\n var GlobalSetImmediate = global.setImmediate;\n var ProcessNextTick = process.nextTick;\n schedule = util.isRecentNode\n ? function(fn) { GlobalSetImmediate.call(global, fn); }\n : function(fn) { ProcessNextTick.call(process, fn); };\n} else if (typeof NativePromise === \"function\" &&\n typeof NativePromise.resolve === \"function\") {\n var nativePromise = NativePromise.resolve();\n schedule = function(fn) {\n nativePromise.then(fn);\n };\n// Outside of Node, we're using MutationObservers because they provide low\n// latency. The second check is to guard against iOS standalone apps which\n// do not fire DOM mutation events for some reason on iOS 8.3+ and cordova\n// apps which have the same bug but are not `.navigator.standalone`\n} else if ((typeof MutationObserver !== \"undefined\") &&\n !(typeof window !== \"undefined\" &&\n window.navigator &&\n (window.navigator.standalone || window.cordova)) &&\n (\"classList\" in document.documentElement)) {\n schedule = (function() {\n // Using 2 mutation observers to batch multiple updates into one.\n var div = document.createElement(\"div\");\n var opts = {attributes: true};\n var toggleScheduled = false;\n var div2 = document.createElement(\"div\");\n var o2 = new MutationObserver(function() {\n div.classList.toggle(\"foo\");\n toggleScheduled = false;\n });\n o2.observe(div2, opts);\n\n var scheduleToggle = function() {\n if (toggleScheduled) return;\n toggleScheduled = true;\n div2.classList.toggle(\"foo\");\n };\n\n return function schedule(fn) {\n var o = new MutationObserver(function() {\n o.disconnect();\n fn();\n });\n o.observe(div, opts);\n scheduleToggle();\n };\n })();\n// setImmediate has higher latency but is still pretty good. This is useful for\n// cases where MutationObserver is not defined (older IE, for example).\n} else if (typeof setImmediate !== \"undefined\") {\n schedule = function (fn) {\n setImmediate(fn);\n };\n// setTimeout also works, it has the most latency but it does the trick.\n} else if (typeof setTimeout !== \"undefined\") {\n schedule = function (fn) {\n setTimeout(fn, 0);\n };\n} else {\n// Do __Not__ default to a sync scheduler, that would break Promises/A+\n// compliancy and cause race conditions.\n schedule = noAsyncScheduler;\n}\nmodule.exports = schedule;\n"
},
{
"path": "src/settle.js",
"content": "\"use strict\";\nmodule.exports =\n function(Promise, PromiseArray, debug) {\nvar ASSERT = require(\"./assert\");\nvar PromiseInspection = Promise.PromiseInspection;\nvar util = require(\"./util\");\n\nfunction SettledPromiseArray(values) {\n this.constructor$(values);\n}\nutil.inherits(SettledPromiseArray, PromiseArray);\n\nSettledPromiseArray.prototype._promiseResolved = function (index, inspection) {\n ASSERT(typeof index === \"number\");\n this._values[index] = inspection;\n var totalResolved = ++this._totalResolved;\n if (totalResolved >= this._length) {\n this._resolve(this._values);\n return true;\n }\n return false;\n};\n\n//override\nSettledPromiseArray.prototype._promiseFulfilled = function (value, index) {\n ASSERT(!this._isResolved());\n ASSERT(typeof index === \"number\");\n var ret = new PromiseInspection();\n ret._bitField = IS_FULFILLED;\n ret._settledValueField = value;\n return this._promiseResolved(index, ret);\n};\n//override\nSettledPromiseArray.prototype._promiseRejected = function (reason, index) {\n ASSERT(!this._isResolved());\n ASSERT(typeof index === \"number\");\n var ret = new PromiseInspection();\n ret._bitField = IS_REJECTED;\n ret._settledValueField = reason;\n return this._promiseResolved(index, ret);\n};\n\nPromise.settle = function (promises) {\n debug.deprecated(\".settle()\", \".reflect()\");\n return new SettledPromiseArray(promises).promise();\n};\n\nPromise.allSettled = function (promises) {\n return new SettledPromiseArray(promises).promise();\n};\n\nPromise.prototype.settle = function () {\n return Promise.settle(this);\n};\n};\n"
},
{
"path": "src/some.js",
"content": "\"use strict\";\nmodule.exports =\nfunction(Promise, PromiseArray, apiRejection) {\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar RangeError = require(\"./errors\").RangeError;\nvar AggregateError = require(\"./errors\").AggregateError;\nvar isArray = util.isArray;\nvar CANCELLATION = {};\n\n\nfunction SomePromiseArray(values) {\n this.constructor$(values);\n this._howMany = 0;\n this._unwrap = false;\n this._initialized = false;\n}\nutil.inherits(SomePromiseArray, PromiseArray);\n\nSomePromiseArray.prototype._init = function () {\n if (!this._initialized) {\n return;\n }\n if (this._howMany === 0) {\n this._resolve([]);\n return;\n }\n this._init$(undefined, RESOLVE_CALL_METHOD);\n var isArrayResolved = isArray(this._values);\n if (!this._isResolved() &&\n isArrayResolved &&\n this._howMany > this._canPossiblyFulfill()) {\n this._reject(this._getRangeError(this.length()));\n }\n};\n\nSomePromiseArray.prototype.init = function () {\n this._initialized = true;\n this._init();\n};\n\nSomePromiseArray.prototype.setUnwrap = function () {\n this._unwrap = true;\n};\n\nSomePromiseArray.prototype.howMany = function () {\n return this._howMany;\n};\n\nSomePromiseArray.prototype.setHowMany = function (count) {\n ASSERT(!this._isResolved());\n this._howMany = count;\n};\n\n//override\nSomePromiseArray.prototype._promiseFulfilled = function (value) {\n ASSERT(!this._isResolved());\n this._addFulfilled(value);\n if (this._fulfilled() === this.howMany()) {\n this._values.length = this.howMany();\n if (this.howMany() === 1 && this._unwrap) {\n this._resolve(this._values[0]);\n } else {\n this._resolve(this._values);\n }\n return true;\n }\n return false;\n\n};\n//override\nSomePromiseArray.prototype._promiseRejected = function (reason) {\n ASSERT(!this._isResolved());\n this._addRejected(reason);\n return this._checkOutcome();\n};\n\n//override\nSomePromiseArray.prototype._promiseCancelled = function () {\n if (this._values instanceof Promise || this._values == null) {\n return this._cancel();\n }\n ASSERT(!this._isResolved());\n this._addRejected(CANCELLATION);\n return this._checkOutcome();\n};\n\nSomePromiseArray.prototype._checkOutcome = function() {\n if (this.howMany() > this._canPossiblyFulfill()) {\n var e = new AggregateError();\n for (var i = this.length(); i < this._values.length; ++i) {\n if (this._values[i] !== CANCELLATION) {\n e.push(this._values[i]);\n }\n }\n if (e.length > 0) {\n this._reject(e);\n } else {\n this._cancel();\n }\n return true;\n }\n return false;\n};\n\nSomePromiseArray.prototype._fulfilled = function () {\n return this._totalResolved;\n};\n\nSomePromiseArray.prototype._rejected = function () {\n return this._values.length - this.length();\n};\n\n//Use the same array past .length() to store rejection reasons\nSomePromiseArray.prototype._addRejected = function (reason) {\n this._values.push(reason);\n};\n\nSomePromiseArray.prototype._addFulfilled = function (value) {\n this._values[this._totalResolved++] = value;\n};\n\nSomePromiseArray.prototype._canPossiblyFulfill = function () {\n return this.length() - this._rejected();\n};\n\nSomePromiseArray.prototype._getRangeError = function (count) {\n var message = \"Input array must contain at least \" +\n this._howMany + \" items but contains only \" + count + \" items\";\n return new RangeError(message);\n};\n\nSomePromiseArray.prototype._resolveEmptyArray = function () {\n this._reject(this._getRangeError(0));\n};\n\nfunction some(promises, howMany) {\n if ((howMany | 0) !== howMany || howMany < 0) {\n return apiRejection(POSITIVE_INTEGER_ERROR);\n }\n var ret = new SomePromiseArray(promises);\n var promise = ret.promise();\n ASSERT(promise.isPending());\n ASSERT(ret instanceof SomePromiseArray);\n ret.setHowMany(howMany);\n ret.init();\n return promise;\n}\n\nPromise.some = function (promises, howMany) {\n return some(promises, howMany);\n};\n\nPromise.prototype.some = function (howMany) {\n return some(this, howMany);\n};\n\nPromise._SomePromiseArray = SomePromiseArray;\n};\n"
},
{
"path": "src/synchronous_inspection.js",
"content": "\"use strict\";\nmodule.exports = function(Promise) {\nfunction PromiseInspection(promise) {\n if (promise !== undefined) {\n promise = promise._target();\n this._bitField = promise._bitField;\n this._settledValueField = promise._isFateSealed()\n ? promise._settledValue() : undefined;\n }\n else {\n this._bitField = 0;\n this._settledValueField = undefined;\n }\n}\n\nPromiseInspection.prototype._settledValue = function() {\n return this._settledValueField;\n};\n\nvar value = PromiseInspection.prototype.value = function () {\n if (!this.isFulfilled()) {\n throw new TypeError(INSPECTION_VALUE_ERROR);\n }\n return this._settledValue();\n};\n\nvar reason = PromiseInspection.prototype.error =\nPromiseInspection.prototype.reason = function () {\n if (!this.isRejected()) {\n throw new TypeError(INSPECTION_REASON_ERROR);\n }\n return this._settledValue();\n};\n\nvar isFulfilled = PromiseInspection.prototype.isFulfilled = function() {\n return (this._bitField & IS_FULFILLED) !== 0;\n};\n\nvar isRejected = PromiseInspection.prototype.isRejected = function () {\n return (this._bitField & IS_REJECTED) !== 0;\n};\n\nvar isPending = PromiseInspection.prototype.isPending = function () {\n return (this._bitField & IS_REJECTED_OR_FULFILLED_OR_CANCELLED) === 0;\n};\n\nvar isResolved = PromiseInspection.prototype.isResolved = function () {\n return (this._bitField & IS_REJECTED_OR_FULFILLED) !== 0;\n};\n\nPromiseInspection.prototype.isCancelled = function() {\n return (this._bitField & IS_CANCELLED_OR_WILL_BE_CANCELLED) !== 0;\n};\n\nPromise.prototype.__isCancelled = function() {\n return (this._bitField & IS_CANCELLED) === IS_CANCELLED;\n};\n\nPromise.prototype._isCancelled = function() {\n return this._target().__isCancelled();\n};\n\nPromise.prototype.isCancelled = function() {\n return (this._target()._bitField & IS_CANCELLED_OR_WILL_BE_CANCELLED) !== 0;\n};\n\nPromise.prototype.isPending = function() {\n return isPending.call(this._target());\n};\n\nPromise.prototype.isRejected = function() {\n return isRejected.call(this._target());\n};\n\nPromise.prototype.isFulfilled = function() {\n return isFulfilled.call(this._target());\n};\n\nPromise.prototype.isResolved = function() {\n return isResolved.call(this._target());\n};\n\nPromise.prototype.value = function() {\n return value.call(this._target());\n};\n\nPromise.prototype.reason = function() {\n var target = this._target();\n target._unsetRejectionIsUnhandled();\n return reason.call(target);\n};\n\nPromise.prototype._value = function() {\n return this._settledValue();\n};\n\nPromise.prototype._reason = function() {\n this._unsetRejectionIsUnhandled();\n return this._settledValue();\n};\n\nPromise.PromiseInspection = PromiseInspection;\n};\n"
},
{
"path": "src/thenables.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL) {\nvar ASSERT = require(\"./assert\");\nvar util = require(\"./util\");\nvar errorObj = util.errorObj;\nvar isObject = util.isObject;\n\nfunction tryConvertToPromise(obj, context) {\n if (isObject(obj)) {\n if (obj instanceof Promise) return obj;\n var then = getThen(obj);\n if (then === errorObj) {\n if (context) context._pushContext();\n var ret = Promise.reject(then.e);\n if (context) context._popContext();\n return ret;\n } else if (typeof then === \"function\") {\n //Make casting from another bluebird fast\n if (isAnyBluebirdPromise(obj)) {\n var ret = new Promise(INTERNAL);\n obj._then(\n ret._fulfill,\n ret._reject,\n undefined,\n ret,\n null\n );\n return ret;\n }\n return doThenable(obj, then, context);\n }\n }\n return obj;\n}\n\nfunction doGetThen(obj) {\n return obj.then;\n}\n\nfunction getThen(obj) {\n try {\n return doGetThen(obj);\n } catch (e) {\n errorObj.e = e;\n return errorObj;\n }\n}\n\nvar hasProp = {}.hasOwnProperty;\nfunction isAnyBluebirdPromise(obj) {\n try {\n return hasProp.call(obj, \"_promise0\");\n } catch (e) {\n return false;\n }\n}\n\nfunction doThenable(x, then, context) {\n ASSERT(typeof then === \"function\");\n var promise = new Promise(INTERNAL);\n var ret = promise;\n if (context) context._pushContext();\n promise._captureStackTrace();\n if (context) context._popContext();\n var synchronous = true;\n var result = util.tryCatch(then).call(x, resolve, reject);\n synchronous = false;\n\n if (promise && result === errorObj) {\n promise._rejectCallback(result.e, true, true);\n promise = null;\n }\n\n function resolve(value) {\n if (!promise) return;\n promise._resolveCallback(value);\n promise = null;\n }\n\n function reject(reason) {\n if (!promise) return;\n promise._rejectCallback(reason, synchronous, true);\n promise = null;\n }\n return ret;\n}\n\nreturn tryConvertToPromise;\n};\n"
},
{
"path": "src/timers.js",
"content": "\"use strict\";\nmodule.exports = function(Promise, INTERNAL, debug) {\nvar util = require(\"./util\");\nvar TimeoutError = Promise.TimeoutError;\n\nfunction HandleWrapper(handle) {\n this.handle = handle;\n}\n\nHandleWrapper.prototype._resultCancelled = function() {\n clearTimeout(this.handle);\n};\n\nvar afterValue = function(value) { return delay(+this).thenReturn(value); };\nvar delay = Promise.delay = function (ms, value) {\n var ret;\n var handle;\n if (value !== undefined) {\n ret = Promise.resolve(value)\n ._then(afterValue, null, null, ms, undefined);\n if (debug.cancellation() && value instanceof Promise) {\n ret._setOnCancel(value);\n }\n } else {\n ret = new Promise(INTERNAL);\n handle = setTimeout(function() { ret._fulfill(); }, +ms);\n if (debug.cancellation()) {\n ret._setOnCancel(new HandleWrapper(handle));\n }\n ret._captureStackTrace();\n }\n ret._setAsyncGuaranteed();\n return ret;\n};\n\nPromise.prototype.delay = function (ms) {\n return delay(ms, this);\n};\n\nvar afterTimeout = function (promise, message, parent) {\n var err;\n if (typeof message !== \"string\") {\n if (message instanceof Error) {\n err = message;\n } else {\n err = new TimeoutError(TIMEOUT_ERROR);\n }\n } else {\n err = new TimeoutError(message);\n }\n util.markAsOriginatingFromRejection(err);\n promise._attachExtraTrace(err);\n promise._reject(err);\n\n if (parent != null) {\n parent.cancel();\n }\n};\n\nfunction successClear(value) {\n clearTimeout(this.handle);\n return value;\n}\n\nfunction failureClear(reason) {\n clearTimeout(this.handle);\n throw reason;\n}\n\nPromise.prototype.timeout = function (ms, message) {\n ms = +ms;\n var ret, parent;\n\n var handleWrapper = new HandleWrapper(setTimeout(function timeoutTimeout() {\n if (ret.isPending()) {\n afterTimeout(ret, message, parent);\n }\n }, ms));\n\n if (debug.cancellation()) {\n parent = this.then();\n ret = parent._then(successClear, failureClear,\n undefined, handleWrapper, undefined);\n ret._setOnCancel(handleWrapper);\n } else {\n ret = this._then(successClear, failureClear,\n undefined, handleWrapper, undefined);\n }\n\n return ret;\n};\n\n};\n"
},
{
"path": "src/using.js",
"content": "\"use strict\";\nmodule.exports = function (Promise, apiRejection, tryConvertToPromise,\n createContext, INTERNAL, debug) {\n var util = require(\"./util\");\n var TypeError = require(\"./errors\").TypeError;\n var inherits = require(\"./util\").inherits;\n var errorObj = util.errorObj;\n var tryCatch = util.tryCatch;\n var NULL = {};\n\n function thrower(e) {\n setTimeout(function(){throw e;}, 0);\n }\n\n function castPreservingDisposable(thenable) {\n var maybePromise = tryConvertToPromise(thenable);\n if (maybePromise !== thenable &&\n typeof thenable._isDisposable === \"function\" &&\n typeof thenable._getDisposer === \"function\" &&\n thenable._isDisposable()) {\n maybePromise._setDisposable(thenable._getDisposer());\n }\n return maybePromise;\n }\n function dispose(resources, inspection) {\n var i = 0;\n var len = resources.length;\n var ret = new Promise(INTERNAL);\n function iterator() {\n if (i >= len) return ret._fulfill();\n var maybePromise = castPreservingDisposable(resources[i++]);\n if (maybePromise instanceof Promise &&\n maybePromise._isDisposable()) {\n try {\n maybePromise = tryConvertToPromise(\n maybePromise._getDisposer().tryDispose(inspection),\n resources.promise);\n } catch (e) {\n return thrower(e);\n }\n if (maybePromise instanceof Promise) {\n return maybePromise._then(iterator, thrower,\n null, null, null);\n }\n }\n iterator();\n }\n iterator();\n return ret;\n }\n\n function Disposer(data, promise, context) {\n this._data = data;\n this._promise = promise;\n this._context = context;\n }\n\n Disposer.prototype.data = function () {\n return this._data;\n };\n\n Disposer.prototype.promise = function () {\n return this._promise;\n };\n\n Disposer.prototype.resource = function () {\n if (this.promise().isFulfilled()) {\n return this.promise().value();\n }\n return NULL;\n };\n\n Disposer.prototype.tryDispose = function(inspection) {\n var resource = this.resource();\n var context = this._context;\n if (context !== undefined) context._pushContext();\n var ret = resource !== NULL\n ? this.doDispose(resource, inspection) : null;\n if (context !== undefined) context._popContext();\n this._promise._unsetDisposable();\n this._data = null;\n return ret;\n };\n\n Disposer.isDisposer = function (d) {\n return (d != null &&\n typeof d.resource === \"function\" &&\n typeof d.tryDispose === \"function\");\n };\n\n function FunctionDisposer(fn, promise, context) {\n this.constructor$(fn, promise, context);\n }\n inherits(FunctionDisposer, Disposer);\n\n FunctionDisposer.prototype.doDispose = function (resource, inspection) {\n var fn = this.data();\n return fn.call(resource, resource, inspection);\n };\n\n function maybeUnwrapDisposer(value) {\n if (Disposer.isDisposer(value)) {\n this.resources[this.index]._setDisposable(value);\n return value.promise();\n }\n return value;\n }\n\n function ResourceList(length) {\n this.length = length;\n this.promise = null;\n this[length-1] = null;\n }\n\n ResourceList.prototype._resultCancelled = function() {\n var len = this.length;\n for (var i = 0; i < len; ++i) {\n var item = this[i];\n if (item instanceof Promise) {\n item.cancel();\n }\n }\n };\n\n Promise.using = function () {\n var len = arguments.length;\n if (len < 2) return apiRejection(\n \"you must pass at least 2 arguments to Promise.using\");\n var fn = arguments[len - 1];\n if (typeof fn !== \"function\") {\n return apiRejection(FUNCTION_ERROR + util.classString(fn));\n }\n var input;\n var spreadArgs = true;\n if (len === 2 && Array.isArray(arguments[0])) {\n input = arguments[0];\n len = input.length;\n spreadArgs = false;\n } else {\n input = arguments;\n len--;\n }\n var resources = new ResourceList(len);\n for (var i = 0; i < len; ++i) {\n var resource = input[i];\n if (Disposer.isDisposer(resource)) {\n var disposer = resource;\n resource = resource.promise();\n resource._setDisposable(disposer);\n } else {\n var maybePromise = tryConvertToPromise(resource);\n if (maybePromise instanceof Promise) {\n resource =\n maybePromise._then(maybeUnwrapDisposer, null, null, {\n resources: resources,\n index: i\n }, undefined);\n }\n }\n resources[i] = resource;\n }\n\n var reflectedResources = new Array(resources.length);\n for (var i = 0; i < reflectedResources.length; ++i) {\n reflectedResources[i] = Promise.resolve(resources[i]).reflect();\n }\n\n var resultPromise = Promise.all(reflectedResources)\n .then(function(inspections) {\n for (var i = 0; i < inspections.length; ++i) {\n var inspection = inspections[i];\n if (inspection.isRejected()) {\n errorObj.e = inspection.error();\n return errorObj;\n } else if (!inspection.isFulfilled()) {\n resultPromise.cancel();\n return;\n }\n inspections[i] = inspection.value();\n }\n promise._pushContext();\n\n fn = tryCatch(fn);\n var ret = spreadArgs\n ? fn.apply(undefined, inspections) : fn(inspections);\n var promiseCreated = promise._popContext();\n debug.checkForgottenReturns(\n ret, promiseCreated, \"Promise.using\", promise);\n return ret;\n });\n\n var promise = resultPromise.lastly(function() {\n var inspection = new Promise.PromiseInspection(resultPromise);\n return dispose(resources, inspection);\n });\n resources.promise = promise;\n promise._setOnCancel(resources);\n return promise;\n };\n\n Promise.prototype._setDisposable = function (disposer) {\n this._bitField = this._bitField | IS_DISPOSABLE;\n this._disposer = disposer;\n };\n\n Promise.prototype._isDisposable = function () {\n return (this._bitField & IS_DISPOSABLE) > 0;\n };\n\n Promise.prototype._getDisposer = function () {\n return this._disposer;\n };\n\n Promise.prototype._unsetDisposable = function () {\n this._bitField = this._bitField & (~IS_DISPOSABLE);\n this._disposer = undefined;\n };\n\n Promise.prototype.disposer = function (fn) {\n if (typeof fn === \"function\") {\n return new FunctionDisposer(fn, this, createContext());\n }\n throw new TypeError();\n };\n\n};\n"
},
{
"path": "src/util.js",
"content": "\"use strict\";\nvar ASSERT = require(\"./assert\");\nvar es5 = require(\"./es5\");\n// Assume CSP if browser\nvar canEvaluate = typeof navigator == \"undefined\";\n\n//Try catch is not supported in optimizing\n//compiler, so it is isolated\nvar errorObj = {e: {}};\nvar tryCatchTarget;\nvar globalObject = typeof self !== \"undefined\" ? self :\n typeof window !== \"undefined\" ? window :\n typeof global !== \"undefined\" ? global :\n this !== undefined ? this : null;\n\nfunction tryCatcher() {\n try {\n var target = tryCatchTarget;\n tryCatchTarget = null;\n return target.apply(this, arguments);\n } catch (e) {\n errorObj.e = e;\n return errorObj;\n }\n}\nfunction tryCatch(fn) {\n ASSERT(typeof fn === \"function\");\n tryCatchTarget = fn;\n return tryCatcher;\n}\n\n//Un-magical enough that using this doesn't prevent\n//extending classes from outside using any convention\nvar inherits = function(Child, Parent) {\n var hasProp = {}.hasOwnProperty;\n\n function T() {\n this.constructor = Child;\n this.constructor$ = Parent;\n for (var propertyName in Parent.prototype) {\n if (hasProp.call(Parent.prototype, propertyName) &&\n propertyName.charAt(propertyName.length-1) !== \"$\"\n ) {\n this[propertyName + \"$\"] = Parent.prototype[propertyName];\n }\n }\n }\n T.prototype = Parent.prototype;\n Child.prototype = new T();\n return Child.prototype;\n};\n\n\nfunction isPrimitive(val) {\n return val == null || val === true || val === false ||\n typeof val === \"string\" || typeof val === \"number\";\n\n}\n\nfunction isObject(value) {\n return typeof value === \"function\" ||\n typeof value === \"object\" && value !== null;\n}\n\nfunction maybeWrapAsError(maybeError) {\n if (!isPrimitive(maybeError)) return maybeError;\n\n return new Error(safeToString(maybeError));\n}\n\nfunction withAppended(target, appendee) {\n var len = target.length;\n var ret = new Array(len + 1);\n var i;\n for (i = 0; i < len; ++i) {\n ret[i] = target[i];\n }\n ret[i] = appendee;\n return ret;\n}\n\nfunction getDataPropertyOrDefault(obj, key, defaultValue) {\n if (es5.isES5) {\n var desc = Object.getOwnPropertyDescriptor(obj, key);\n\n if (desc != null) {\n return desc.get == null && desc.set == null\n ? desc.value\n : defaultValue;\n }\n } else {\n return {}.hasOwnProperty.call(obj, key) ? obj[key] : undefined;\n }\n}\n\nfunction notEnumerableProp(obj, name, value) {\n if (isPrimitive(obj)) return obj;\n var descriptor = {\n value: value,\n configurable: true,\n enumerable: false,\n writable: true\n };\n es5.defineProperty(obj, name, descriptor);\n return obj;\n}\n\nfunction thrower(r) {\n throw r;\n}\n\nvar inheritedDataKeys = (function() {\n var excludedPrototypes = [\n Array.prototype,\n Object.prototype,\n Function.prototype\n ];\n\n var isExcludedProto = function(val) {\n for (var i = 0; i < excludedPrototypes.length; ++i) {\n if (excludedPrototypes[i] === val) {\n return true;\n }\n }\n return false;\n };\n\n if (es5.isES5) {\n var getKeys = Object.getOwnPropertyNames;\n return function(obj) {\n var ret = [];\n var visitedKeys = Object.create(null);\n while (obj != null && !isExcludedProto(obj)) {\n var keys;\n try {\n keys = getKeys(obj);\n } catch (e) {\n return ret;\n }\n for (var i = 0; i < keys.length; ++i) {\n var key = keys[i];\n if (visitedKeys[key]) continue;\n visitedKeys[key] = true;\n var desc = Object.getOwnPropertyDescriptor(obj, key);\n if (desc != null && desc.get == null && desc.set == null) {\n ret.push(key);\n }\n }\n obj = es5.getPrototypeOf(obj);\n }\n return ret;\n };\n } else {\n var hasProp = {}.hasOwnProperty;\n return function(obj) {\n if (isExcludedProto(obj)) return [];\n var ret = [];\n\n /*jshint forin:false */\n enumeration: for (var key in obj) {\n if (hasProp.call(obj, key)) {\n ret.push(key);\n } else {\n for (var i = 0; i < excludedPrototypes.length; ++i) {\n if (hasProp.call(excludedPrototypes[i], key)) {\n continue enumeration;\n }\n }\n ret.push(key);\n }\n }\n return ret;\n };\n }\n\n})();\n\nvar thisAssignmentPattern = /this\\s*\\.\\s*\\S+\\s*=/;\nfunction isClass(fn) {\n try {\n if (typeof fn === \"function\") {\n var keys = es5.names(fn.prototype);\n\n var hasMethods = es5.isES5 && keys.length > 1;\n var hasMethodsOtherThanConstructor = keys.length > 0 &&\n !(keys.length === 1 && keys[0] === \"constructor\");\n var hasThisAssignmentAndStaticMethods =\n thisAssignmentPattern.test(fn + \"\") && es5.names(fn).length > 0;\n\n if (hasMethods || hasMethodsOtherThanConstructor ||\n hasThisAssignmentAndStaticMethods) {\n return true;\n }\n }\n return false;\n } catch (e) {\n return false;\n }\n}\n\nvar fastProto = null;\nvar kInlineCacheCutoff = 10;\nfunction FastObject(o) {\n if (fastProto !== null && typeof fastProto.property) {\n var result = fastProto;\n fastProto = FastObject.prototype = null;\n return result;\n }\n fastProto = FastObject.prototype = o == null ? Object.create(null) : o;\n return new FastObject();\n}\n\n// Initialize the inline property cache of FastObject\nfor(var i = 0; i <= kInlineCacheCutoff; i++) {\n FastObject({});\n}\n\n\nfunction toFastProperties(obj) {\n FastObject(obj);\n ASSERT(\"%HasFastProperties\", true, obj);\n return obj;\n}\n\nvar rident = /^[a-z$_][a-z$_0-9]*$/i;\nfunction isIdentifier(str) {\n return rident.test(str);\n}\n\nfunction filledRange(count, prefix, suffix) {\n var ret = new Array(count);\n for(var i = 0; i < count; ++i) {\n ret[i] = prefix + i + suffix;\n }\n return ret;\n}\n\nfunction safeToString(obj) {\n try {\n return obj + \"\";\n } catch (e) {\n return \"[no string representation]\";\n }\n}\n\nfunction isError(obj) {\n return obj instanceof Error ||\n (obj !== null &&\n typeof obj === \"object\" &&\n typeof obj.message === \"string\" &&\n typeof obj.name === \"string\");\n}\n\nfunction markAsOriginatingFromRejection(e) {\n try {\n notEnumerableProp(e, OPERATIONAL_ERROR_KEY, true);\n }\n catch(ignore) {}\n}\n\nfunction originatesFromRejection(e) {\n if (e == null) return false;\n return ((e instanceof Error[BLUEBIRD_ERRORS].OperationalError) ||\n e[OPERATIONAL_ERROR_KEY] === true);\n}\n\nfunction canAttachTrace(obj) {\n return isError(obj) && es5.propertyIsWritable(obj, \"stack\");\n}\n\nvar ensureErrorObject = (function() {\n if (!(\"stack\" in new Error())) {\n return function(value) {\n if (canAttachTrace(value)) return value;\n try {throw new Error(safeToString(value));}\n catch(err) {return err;}\n };\n } else {\n return function(value) {\n if (canAttachTrace(value)) return value;\n return new Error(safeToString(value));\n };\n }\n})();\n\nfunction classString(obj) {\n return {}.toString.call(obj);\n}\n\nfunction copyDescriptors(from, to, filter) {\n var keys = es5.names(from);\n for (var i = 0; i < keys.length; ++i) {\n var key = keys[i];\n if (filter(key)) {\n try {\n es5.defineProperty(to, key, es5.getDescriptor(from, key));\n } catch (ignore) {}\n }\n }\n}\n\nvar asArray = function(v) {\n if (es5.isArray(v)) {\n return v;\n }\n return null;\n};\n\nif (typeof Symbol !== \"undefined\" && Symbol.iterator) {\n var ArrayFrom = typeof Array.from === \"function\" ? function(v) {\n return Array.from(v);\n } : function(v) {\n var ret = [];\n var it = v[Symbol.iterator]();\n var itResult;\n while (!((itResult = it.next()).done)) {\n ret.push(itResult.value);\n }\n return ret;\n };\n\n asArray = function(v) {\n if (es5.isArray(v)) {\n return v;\n } else if (v != null && typeof v[Symbol.iterator] === \"function\") {\n return ArrayFrom(v);\n }\n return null;\n };\n}\n\nvar isNode = typeof process !== \"undefined\" &&\n classString(process).toLowerCase() === \"[object process]\";\n\nvar hasEnvVariables = typeof process !== \"undefined\" &&\n typeof process.env !== \"undefined\";\n\nfunction env(key) {\n return hasEnvVariables ? process.env[key] : undefined;\n}\n\nfunction getNativePromise() {\n if (typeof Promise === \"function\") {\n try {\n var promise = new Promise(function(){});\n if (classString(promise) === \"[object Promise]\") {\n return Promise;\n }\n } catch (e) {}\n }\n}\n\nvar reflectHandler;\nfunction contextBind(ctx, cb) {\n if (ctx === null ||\n typeof cb !== \"function\" ||\n cb === reflectHandler) {\n return cb;\n }\n\n if (ctx.domain !== null) {\n cb = ctx.domain.bind(cb);\n }\n\n var async = ctx.async;\n if (async !== null) {\n var old = cb;\n cb = function() {\n INLINE_SLICE_LEFT_PADDED(2, args, arguments);\n args[0] = old;\n args[1] = this;\n return async.runInAsyncScope.apply(async, args);\n };\n }\n return cb;\n}\n\nvar ret = {\n setReflectHandler: function(fn) {\n reflectHandler = fn;\n },\n isClass: isClass,\n isIdentifier: isIdentifier,\n inheritedDataKeys: inheritedDataKeys,\n getDataPropertyOrDefault: getDataPropertyOrDefault,\n thrower: thrower,\n isArray: es5.isArray,\n asArray: asArray,\n notEnumerableProp: notEnumerableProp,\n isPrimitive: isPrimitive,\n isObject: isObject,\n isError: isError,\n canEvaluate: canEvaluate,\n errorObj: errorObj,\n tryCatch: tryCatch,\n inherits: inherits,\n withAppended: withAppended,\n maybeWrapAsError: maybeWrapAsError,\n toFastProperties: toFastProperties,\n filledRange: filledRange,\n toString: safeToString,\n canAttachTrace: canAttachTrace,\n ensureErrorObject: ensureErrorObject,\n originatesFromRejection: originatesFromRejection,\n markAsOriginatingFromRejection: markAsOriginatingFromRejection,\n classString: classString,\n copyDescriptors: copyDescriptors,\n isNode: isNode,\n hasEnvVariables: hasEnvVariables,\n env: env,\n global: globalObject,\n getNativePromise: getNativePromise,\n contextBind: contextBind\n};\nret.isRecentNode = ret.isNode && (function() {\n var version;\n if (process.versions && process.versions.node) {\n version = process.versions.node.split(\".\").map(Number);\n } else if (process.version) {\n version = process.version.split(\".\").map(Number);\n }\n return (version[0] === 0 && version[1] > 10) || (version[0] > 0);\n})();\nret.nodeSupportsAsyncResource = ret.isNode && (function() {\n var supportsAsync = false;\n try {\n var res = require(\"async_hooks\").AsyncResource;\n supportsAsync = typeof res.prototype.runInAsyncScope === \"function\";\n } catch (e) {\n supportsAsync = false;\n }\n return supportsAsync;\n})();\n\nif (ret.isNode) ret.toFastProperties(process);\n\ntry {throw new Error(); } catch (e) {ret.lastLineError = e;}\nmodule.exports = ret;\n"
},
{
"path": "test/browser/es5-sham.js",
"content": "// Copyright 2009-2012 by contributors, MIT License\n// vim: ts=4 sts=4 sw=4 expandtab\n\n// Module systems magic dance\n(function (definition) {\n // RequireJS\n if (typeof define == \"function\") {\n define(definition);\n // YUI3\n } else if (typeof YUI == \"function\") {\n YUI.add(\"es5-sham\", definition);\n // CommonJS and \n\n\n\n\n\n\n
![\"Promises/A+](\"http://promisesaplus.com/assets/logo-small.png\" "\\"Promises/A+"){kind=logo}
\n