ember-2.3.2-RSVP.Promise.json

{
  "data": {
    "id": "ember-2.3.2-RSVP.Promise",
    "type": "class",
    "attributes": {
      "name": "RSVP.Promise",
      "shortname": "RSVP.Promise",
      "classitems": [],
      "plugins": [],
      "extensions": [],
      "plugin_for": [],
      "extension_for": [],
      "module": "ember",
      "file": "bower_components/rsvp/lib/rsvp/promise.js",
      "line": 34,
      "description": "Promise objects represent the eventual result of an asynchronous operation. The\nprimary way of interacting with a promise is through its `then` method, which\nregisters callbacks to receive either a promise’s eventual value or the reason\nwhy the promise cannot be fulfilled.\n\nTerminology\n-----------\n\n- `promise` is an object or function with a `then` method whose behavior conforms to this specification.\n- `thenable` is an object or function that defines a `then` method.\n- `value` is any legal JavaScript value (including undefined, a thenable, or a promise).\n- `exception` is a value that is thrown using the throw statement.\n- `reason` is a value that indicates why a promise was rejected.\n- `settled` the final resting state of a promise, fulfilled or rejected.\n\nA promise can be in one of three states: pending, fulfilled, or rejected.\n\nPromises that are fulfilled have a fulfillment value and are in the fulfilled\nstate.  Promises that are rejected have a rejection reason and are in the\nrejected state.  A fulfillment value is never a thenable.\n\nPromises can also be said to *resolve* a value.  If this value is also a\npromise, then the original promise's settled state will match the value's\nsettled state.  So a promise that *resolves* a promise that rejects will\nitself reject, and a promise that *resolves* a promise that fulfills will\nitself fulfill.\n\n\nBasic Usage:\n------------\n\n```js\nvar promise = new Promise(function(resolve, reject) {\n  // on success\n  resolve(value);\n\n  // on failure\n  reject(reason);\n});\n\npromise.then(function(value) {\n  // on fulfillment\n}, function(reason) {\n  // on rejection\n});\n```\n\nAdvanced Usage:\n---------------\n\nPromises shine when abstracting away asynchronous interactions such as\n`XMLHttpRequest`s.\n\n```js\nfunction getJSON(url) {\n  return new Promise(function(resolve, reject){\n    var xhr = new XMLHttpRequest();\n\n    xhr.open('GET', url);\n    xhr.onreadystatechange = handler;\n    xhr.responseType = 'json';\n    xhr.setRequestHeader('Accept', 'application/json');\n    xhr.send();\n\n    function handler() {\n      if (this.readyState === this.DONE) {\n        if (this.status === 200) {\n          resolve(this.response);\n        } else {\n          reject(new Error('getJSON: `' + url + '` failed with status: [' + this.status + ']'));\n        }\n      }\n    };\n  });\n}\n\ngetJSON('/posts.json').then(function(json) {\n  // on fulfillment\n}, function(reason) {\n  // on rejection\n});\n```\n\nUnlike callbacks, promises are great composable primitives.\n\n```js\nPromise.all([\n  getJSON('/posts'),\n  getJSON('/comments')\n]).then(function(values){\n  values[0] // => postsJSON\n  values[1] // => commentsJSON\n\n  return values;\n});\n```",
      "params": [
        {
          "name": "resolver",
          "description": "",
          "type": "Function"
        },
        {
          "name": "label",
          "description": "optional string for labeling the promise.\nUseful for tooling.",
          "type": "String"
        }
      ],
      "is_constructor": 1,
      "methods": [
        {
          "file": "bower_components/rsvp/lib/rsvp/promise.js",
          "line": 184,
          "description": "The primary way of interacting with a promise is through its `then` method,\nwhich registers callbacks to receive either a promise's eventual value or the\nreason why the promise cannot be fulfilled.\n\n```js\nfindUser().then(function(user){\n  // user is available\n}, function(reason){\n  // user is unavailable, and you are given the reason why\n});\n```\n\nChaining\n--------\n\nThe return value of `then` is itself a promise.  This second, 'downstream'\npromise is resolved with the return value of the first promise's fulfillment\nor rejection handler, or rejected if the handler throws an exception.\n\n```js\nfindUser().then(function (user) {\n  return user.name;\n}, function (reason) {\n  return 'default name';\n}).then(function (userName) {\n  // If `findUser` fulfilled, `userName` will be the user's name, otherwise it\n  // will be `'default name'`\n});\n\nfindUser().then(function (user) {\n  throw new Error('Found user, but still unhappy');\n}, function (reason) {\n  throw new Error('`findUser` rejected and we're unhappy');\n}).then(function (value) {\n  // never reached\n}, function (reason) {\n  // if `findUser` fulfilled, `reason` will be 'Found user, but still unhappy'.\n  // If `findUser` rejected, `reason` will be '`findUser` rejected and we're unhappy'.\n});\n```\nIf the downstream promise does not specify a rejection handler, rejection reasons will be propagated further downstream.\n\n```js\nfindUser().then(function (user) {\n  throw new PedagogicalException('Upstream error');\n}).then(function (value) {\n  // never reached\n}).then(function (value) {\n  // never reached\n}, function (reason) {\n  // The `PedgagocialException` is propagated all the way down to here\n});\n```\n\nAssimilation\n------------\n\nSometimes the value you want to propagate to a downstream promise can only be\nretrieved asynchronously. This can be achieved by returning a promise in the\nfulfillment or rejection handler. The downstream promise will then be pending\nuntil the returned promise is settled. This is called *assimilation*.\n\n```js\nfindUser().then(function (user) {\n  return findCommentsByAuthor(user);\n}).then(function (comments) {\n  // The user's comments are now available\n});\n```\n\nIf the assimliated promise rejects, then the downstream promise will also reject.\n\n```js\nfindUser().then(function (user) {\n  return findCommentsByAuthor(user);\n}).then(function (comments) {\n  // If `findCommentsByAuthor` fulfills, we'll have the value here\n}, function (reason) {\n  // If `findCommentsByAuthor` rejects, we'll have the reason here\n});\n```\n\nSimple Example\n--------------\n\nSynchronous Example\n\n```javascript\nvar result;\n\ntry {\n  result = findResult();\n  // success\n} catch(reason) {\n  // failure\n}\n```\n\nErrback Example\n\n```js\nfindResult(function(result, err){\n  if (err) {\n    // failure\n  } else {\n    // success\n  }\n});\n```\n\nPromise Example;\n\n```javascript\nfindResult().then(function(result){\n  // success\n}, function(reason){\n  // failure\n});\n```\n\nAdvanced Example\n--------------\n\nSynchronous Example\n\n```javascript\nvar author, books;\n\ntry {\n  author = findAuthor();\n  books  = findBooksByAuthor(author);\n  // success\n} catch(reason) {\n  // failure\n}\n```\n\nErrback Example\n\n```js\n\nfunction foundBooks(books) {\n\n}\n\nfunction failure(reason) {\n\n}\n\nfindAuthor(function(author, err){\n  if (err) {\n    failure(err);\n    // failure\n  } else {\n    try {\n      findBoooksByAuthor(author, function(books, err) {\n        if (err) {\n          failure(err);\n        } else {\n          try {\n            foundBooks(books);\n          } catch(reason) {\n            failure(reason);\n          }\n        }\n      });\n    } catch(error) {\n      failure(err);\n    }\n    // success\n  }\n});\n```\n\nPromise Example;\n\n```javascript\nfindAuthor().\n  then(findBooksByAuthor).\n  then(function(books){\n    // found books\n}).catch(function(reason){\n  // something went wrong\n});\n```",
          "itemtype": "method",
          "name": "then",
          "params": [
            {
              "name": "onFulfillment",
              "description": "",
              "type": "Function"
            },
            {
              "name": "onRejection",
              "description": "",
              "type": "Function"
            },
            {
              "name": "label",
              "description": "optional string for labeling the promise.\nUseful for tooling.",
              "type": "String"
            }
          ],
          "return": {
            "description": "",
            "type": "Promise"
          },
          "class": "RSVP.Promise"
        },
        {
          "file": "bower_components/rsvp/lib/rsvp/promise.js",
          "line": 410,
          "description": "`catch` is simply sugar for `then(undefined, onRejection)` which makes it the same\nas the catch block of a try/catch statement.\n\n```js\nfunction findAuthor(){\n  throw new Error('couldn't find that author');\n}\n\n// synchronous\ntry {\n  findAuthor();\n} catch(reason) {\n  // something went wrong\n}\n\n// async with promises\nfindAuthor().catch(function(reason){\n  // something went wrong\n});\n```",
          "itemtype": "method",
          "name": "catch",
          "params": [
            {
              "name": "onRejection",
              "description": "",
              "type": "Function"
            },
            {
              "name": "label",
              "description": "optional string for labeling the promise.\nUseful for tooling.",
              "type": "String"
            }
          ],
          "return": {
            "description": "",
            "type": "Promise"
          },
          "class": "RSVP.Promise"
        },
        {
          "file": "bower_components/rsvp/lib/rsvp/promise.js",
          "line": 442,
          "description": "`finally` will be invoked regardless of the promise's fate just as native\ntry/catch/finally behaves\n\nSynchronous example:\n\n```js\nfindAuthor() {\n  if (Math.random() > 0.5) {\n    throw new Error();\n  }\n  return new Author();\n}\n\ntry {\n  return findAuthor(); // succeed or fail\n} catch(error) {\n  return findOtherAuther();\n} finally {\n  // always runs\n  // doesn't affect the return value\n}\n```\n\nAsynchronous example:\n\n```js\nfindAuthor().catch(function(reason){\n  return findOtherAuther();\n}).finally(function(){\n  // author was either found, or not\n});\n```",
          "itemtype": "method",
          "name": "finally",
          "params": [
            {
              "name": "callback",
              "description": "",
              "type": "Function"
            },
            {
              "name": "label",
              "description": "optional string for labeling the promise.\nUseful for tooling.",
              "type": "String"
            }
          ],
          "return": {
            "description": "",
            "type": "Promise"
          },
          "class": "RSVP.Promise"
        }
      ],
      "events": [],
      "properties": []
    },
    "relationships": {
      "parent-class": {
        "data": null
      },
      "descendants": {
        "data": []
      },
      "module": {
        "data": {
          "id": "ember-2.3.2-ember",
          "type": "module"
        }
      },
      "project-version": {
        "data": {
          "id": "ember-2.3.2",
          "type": "project-version"
        }
      }
    }
  }
}