{
  "name": "mpromise",
  "version": "0.4.3",
  "description": "Promises A+ conformant implementation",
  "main": "index.js",
  "scripts": {
    "test": "node node_modules/mocha/bin/_mocha"
  },
  "devDependencies": {
    "longjohn": "~0.2.1",
    "promises-aplus-tests": "~2.0.2",
    "mocha": "~1.13.0"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/aheckmann/mpromise"
  },
  "keywords": [
    "promise",
    "mongoose",
    "aplus",
    "a+",
    "plus"
  ],
  "author": {
    "name": "Aaron Heckmann",
    "email": "aaron.heckmann+github@gmail.com"
  },
  "license": "MIT",
  "readme": "#mpromise\n==========\n\n[![Build Status](https://travis-ci.org/aheckmann/mpromise.png)](https://travis-ci.org/aheckmann/mpromise)\n\nA [promises/A+](https://github.com/promises-aplus/promises-spec) conformant implementation, written for [mongoose](http://mongoosejs.com).\n\n## installation\n\n```\n$ npm install mpromise\n```\n\n## docs\n\nAn `mpromise` can be in any of three states, pending, fulfilled (success), or rejected (error). Once it is either fulfilled or rejected it's state can no longer be changed.\n\nThe exports object is the Promise constructor.\n\n```js\nvar Promise = require('mpromise');\n```\n\nThe constructor accepts an optional function which is executed when the promise is first resolved (either fulfilled or rejected).\n\n```js\nvar promise = new Promise(fn);\n```\n\nThis is the same as passing the `fn` to `onResolve` directly.\n\n```js\nvar promise = new Promise;\npromise.onResolve(function (err, args..) {\n  ...\n});\n```\n\n### Methods\n\n####fulfill\n\nFulfilling a promise with values:\n\n```js\nvar promise = new Promise;\npromise.fulfill(args...);\n```\n\nIf the promise has already been fulfilled or rejected, no action is taken.\n\n####reject\n\nRejecting a promise with a reason:\n\n```js\nvar promise = new Promise;\npromise.reject(reason);\n```\n\nIf the promise has already been fulfilled or rejected, no action is taken.\n\n####resolve\n\nNode.js callback style promise resolution `(err, args...)`:\n\n```js\nvar promise = new Promise;\npromise.resolve([reason], [arg1, arg2, ...]);\n```\n\nIf the promise has already been fulfilled or rejected, no action is taken.\n\n####onFulfill\n\nTo register a function for execution when the promise is fulfilled, pass it to `onFulfill`. When executed it will receive the arguments passed to `fulfill()`.\n\n```js\nvar promise = new Promise;\npromise.onFulfill(function (a, b) {\n  assert.equal(3, a + b);\n});\npromise.fulfill(1, 2);\n```\n\nThe function will only be called once when the promise is fulfilled, never when rejected.\n\nRegistering a function with `onFulfill` after the promise has already been fulfilled results in the immediate execution of the function with the original arguments used to fulfill the promise.\n\n```js\nvar promise = new Promise;\npromise.fulfill(\" :D \");\npromise.onFulfill(function (arg) {\n  console.log(arg); // logs \" :D \"\n})\n```\n\n####onReject\n\nTo register a function for execution when the promise is rejected, pass it to `onReject`. When executed it will receive the argument passed to `reject()`.\n\n```js\nvar promise = new Promise;\npromise.onReject(function (reason) {\n  assert.equal('sad', reason);\n});\npromise.reject('sad');\n```\n\nThe function will only be called once when the promise is rejected, never when fulfilled.\n\nRegistering a function with `onReject` after the promise has already been rejected results in the immediate execution of the function with the original argument used to reject the promise.\n\n```js\nvar promise = new Promise;\npromise.reject(\" :( \");\npromise.onReject(function (reason) {\n  console.log(reason); // logs \" :( \"\n})\n```\n\n####onResolve\n\nAllows registration of node.js style callbacks `(err, args..)` to handle either promise resolution type (fulfill or reject).\n\n```js\n// fulfillment\nvar promise = new Promise;\npromise.onResolve(function (err, a, b) {\n  console.log(a + b); // logs 3\n});\npromise.fulfill(1, 2);\n\n// rejection\nvar promise = new Promise;\npromise.onResolve(function (err) {\n  if (err) {\n    console.log(err.message); // logs \"failed\"\n  }\n});\npromise.reject(new Error('failed'));\n```\n\n####then\n\nCreates a new promise and returns it. If `onFulfill` or `onReject` are passed, they are added as SUCCESS/ERROR callbacks to this promise after the nextTick.\n\nConforms to [promises/A+](https://github.com/promises-aplus/promises-spec) specification and passes its [tests](https://github.com/promises-aplus/promises-tests).\n\n```js\n// promise.then(onFulfill, onReject);\n\nvar p = new Promise;\n\np.then(function (arg) {\n  return arg + 1;\n}).then(function (arg) {\n  throw new Error(arg + ' is an error!');\n}).then(null, function (err) {\n  assert.ok(err instanceof Error);\n  assert.equal('2 is an error', err.message);\n});\np.fullfill(1);\n```\n\n####end\n\nSignifies that this promise was the last in a chain of `then()s`: if a handler passed to the call to `then` which produced this promise throws, the exception be rethrown.\nYou can pass an OnReject handler to `end` so that exceptions will be handled (like a final catch clause);\nThis method returns it's promise for easy use with `return`.\n\n```js\nvar p = new Promise;\np.then(function(){ throw new Error('shucks') });\nsetTimeout(function () {\n  p.fulfill();\n  // error was caught and swallowed by the promise returned from\n  // p.then(). we either have to always register handlers on\n  // the returned promises or we can do the following...\n}, 10);\n\n// this time we use .end() which prevents catching thrown errors\nvar p = new Promise;\nsetTimeout(function () {\n  p.fulfill(); // throws \"shucks\"\n}, 10);\nreturn p.then(function(){ throw new Error('shucks') }).end(); // <--\n```\n\n\n### chain\n\nAllows direct promise to promise chaining (especially useful by a outside aggregating function). It doesn't use the asynchronous `resolve` algorithm and so excepts only another Promise as it's argument.\n\n```js\nfunction makeMeAPromise(i) {\n  var p = new Promise;\n  p.fulfill(i);\n  return p;\n}\n\nvar returnPromise = initialPromise = new Promise;\nfor (i=0; i<10; ++i)\n    returnPromise = returnPromise.chain(makeMeAPromise(i));\n\ninitialPromise.fulfill();\nreturn returnPromise;\n```\n\n###Event names\n\nIf you'd like to alter this implementations event names used to signify success and failure you may do so by setting `Promise.SUCCESS` or `Promise.FAILURE` respectively.\n\n```js\nPromise.SUCCESS = 'complete';\nPromise.FAILURE = 'err';\n```\n\n###Luke, use the Source\nFor more ideas read the [source](https://github.com/aheckmann/mpromise/blob/master/lib), [tests](https://github.com/aheckmann/mpromise/blob/master/test), or the [mongoose implementation](https://github.com/LearnBoost/mongoose/blob/3.6x/lib/promise.js).\n\n## license\n\n[MIT](https://github.com/aheckmann/mpromise/blob/master/LICENSE)\n",
  "readmeFilename": "README.md",
  "bugs": {
    "url": "https://github.com/aheckmann/mpromise/issues"
  },
  "_id": "mpromise@0.4.3",
  "dist": {
    "shasum": "b30dbade7104bd4413096b4437942c206121daeb"
  },
  "_from": "mpromise@0.4.3",
  "_resolved": "https://registry.npmjs.org/mpromise/-/mpromise-0.4.3.tgz"
}
