\n Loading your news items, please wait...\n
\n\n\n {{newsItem}}\n
\n\n There was an error: {{ newsItemsQuery.message }}\n
\n```\n\nOf course, this pattern works just as well for other apps like React, Vue,\nAurelia, etc. Just keep in mind that some work might need to be done to hook up\ninto your library of choice. See the [Usage In Popular Frameworks](#usage-in-popular-frameworks)\nfor how to do this.\n\n## API Reference\n\n### Constructor Factory: `oversee(method)`\n\n* Parameters:\n * `[function]` **`method`** (required)\n The function that returns a promise when invoked.\n* Returns:\n * `[Object]` **`overseenPromise`**\n The wrapped promise with all the properties documented below.\n\nThe main method to wrap a promise. This does not affect the original `method` or\noverride any of its properties. Do not call with `new`, since this is a pure\nfactory function.\n\n### Instance Properties\n\n#### `state`\n\n* Type: `string`\n\nThe current progress of the wrapped promise's execution. Will be one of:\n\n* `'ready'` - The promise has not been invoked yet.\n* `'executing'` - The promise has been invoked and is currently pending.\n* `'success'` - The promise has successfully resolved.\n* `'error'` - The promise was rejected.\n\nNote that you should *probably* not mutate this value manually. If you want to\nchange or reset the instance, you should call [`instance.resetToReady()`](#api-resettoready)\nor [`instance.resetToExecuting()`](#api-resettoexecuting).\n\nIf you manually mutate `instance.state`, this will trigger invocation of any\ncallback passed to [`instance.subscribe`](#api-subscribe).\n\nThis utility does not support cancelling an in-progress promise.\n\n#### `message`\n\n* Type: `string`\n\nA human-readable account of what happened if the wrapped promise encountered an\nerror. By default, `message` will be set to either `error.message` (if\navailable) or simply by calling `error.toString()`. To override this behaviour,\nsee [`instance.setErrorParser`](#api-seterrorparser).\n\nIf you manually mutate `instance.message`, this will trigger invocation of any\ncallback passed to [`instance.subscribe`](#api-subscribe).\n\n#### `result`\n\n* Type: `undefined` or `any` or `Error`\n\nIf the wrapped promise was resolved successfully, `instance.result` will be set\nto whatever data it was resolved with. If the wrapped promise was rejected with\nan error, `instance.result` will be set to whatever error object it was rejected\nwith.\n\nIf the instance has not been invoked yet (with `instance.run()`) or it is\ncurrently executing (but has not resolved/rejected yet) then `instance.result`\nwill be `undfined`.\n\nIf you manually mutate `instance.result`, this will trigger invocation of any\ncallback passed to [`instance.subscribe`](#api-subscribe).\n\n#### isSuccessful\n\n* Type: `boolean`\n\nWhether the wrapped promise has resolved successfully.\n\n#### isNotSuccessful\n\n* Type: `boolean`\n\nWhether the wrapped promise has not resolved successfully. This could be for\nseveral reasons:\n\n* The request has not started yet (`instance.run()` has not been invoked).\n* The request is currently executing.\n* The request encountered an error.\n\n#### isReady\n\n* Type: `boolean`\n\nWhether the wrapped promise has not started yet (`instance.run()` has not been\ninvoked).\n\n#### isNotReady\n\n* Type: `boolean`\n\nWhether the wrapped promise is in a state other than `ready`. This could be for\nseveral reasons:\n\n* The request is currently executing.\n* The request has resolved successfully.\n* The request encountered an error.\n\n#### isExecuting\n\n* Type: `boolean`\n\nWhether the wrapped promise is currently in the process of running.\n\n#### isNotExecuting\n\n* Type: `boolean`\n\nWhether the wrapped promise is not currently running. This could be for several\nreasons:\n\n* The request has not started yet (`instance.run()` has not been invoked).\n* The request has resolved successfully.\n* The request encountered an error.\n\n#### hasError\n\n* Type: `boolean`\n\nWhether the wrapped promise has completed but has been rejected with an error.\n\n#### hasNoError\n\n* Type: `boolean`\n\nWhether the wrapped promise is not currently completed with an error. This could\nbe for several reasons:\n\n* The request has not started yet (`instance.run()` has not been invoked).\n* The request has resolved successfully.\n* The request is currently executing.\n\n#### hasMessage\n\n* Type: `boolean`\n\nWhether the wrapped promise has anything assigned to its `instance.message`\nproperty. This is usually the case if the request has encountered an error, but\nit can also be assigned at any time.\n\n#### hasNoMessage\n\n* Type: `boolean`\n\nWhether the wrapped promise does not have anything assigned to its\n`instance.message` property. This will usually be the case when the request has\nnot encountered an error, ie: it is unstarted, currently executing or has been\nresolved successfully. Be aware that `instance.result` can also be manually\nassigned at any time.\n\n#### hasResult\n\n* Type: `boolean`\n\nWhether the wrapped promise has anything assigned to its `instance.result`\nproperty. This will usually be the case if the request has completed\nsuccessfully (in which case, `instance.result` will be the response payload) or\nif the request was rejected with an error (in which case, `instance.result`)\nwill be the error that the request was rejected with. Be aware that\n`instance.result` can also be manually assigned at any time.\n\n#### hasNoResult\n\n* Type: `boolean`\n\nWhether the wrapped promise does not have anything assigned to its\n`instance.result` property. This is usually the case if the request is unstarted\nor currently executing, but it can also be assigned at any time.\n\n### Instance Methods\n\n#### `run()`\n\n* Parameters:\n * `[any]` **`[arg1, [arg2, ...argN]]`** (optional)\n Any arguments that should be passed to the original `method` when invoked.\n* Returns:\n * `[Promise]` **`invokedPromise`**\n A `then`-able promise that is the result of invoking the original `method`.\n\nIf the original `method` would take any arguments when invoking it normally,\npass them into `run`.\n\n#### `subscribe(callback)`\n\n* Parameters:\n * `[function]` **`[callback]`** (required)\n A method to invoke when the internal state of the instance has changed.\n* Returns:\n * `[overseenPromise]` **`this`**\n The instance of the `overseenPromise` to which this method belongs.\n\nPassing a function into this method will act as a listener for updates to the\ninstance's internal state. `callback` will be invoked with the following\narguments:\n\n1. `[string]` **`event`**\n The type of internal happening that just occurred. Will be one of:\n * `BEGIN_EXECUTING` - The wrapped promise begins executing (usually in\n reaction to `.run()` being invoked)\n * `COMPLETED_SUCCESSFULLY` - The wrapped promise has finished executing and\n there was no error. Any data that the promise was resolved with is now\n available to be accessed at `instance.result`.\n * `COMPLETED_UNSUCCESSFULLY` - The wrapped promise has finished executing but\n there was an error. More information about the error is now available to be\n accessed at `instance.result`, and human-readable error message is available\n to be accessed at `instance.message`.\n * `MESSAGE_CHANGED` - The user has manually set a new value of\n `instance.message`. This event will not be fired any other time (even if some\n other event causes the `message` property to be changed).\n * `STATE_CHANGED` - The user has manually set a new value of\n `instance.state`. This event will not be fired any other time (even if some\n other event causes the `state` property to be changed).\n * `RESULT_CHANGED` - The user has manually set a new value of\n `instance.result`. This event will not be fired any other time (even if some\n other event causes the `result` property to be changed).\n2. `[any]` **`meta`** (optional)\n Any relevant metadata that is associated with the `event`.\n\nIf `instance.subscribe` is invoked more than once, only the last invocation will\nhave its callback registered -- other previous calls will be overwritten.\n\nTo stop listening to events / state changes, call [`instance.unsubscribe`](#api-unsubscribe).\n\n#### `unsubscribe()`\n\n* Parameters: none\n* Returns:\n * `[overseenPromise]` **`this`**\n The instance of the `overseenPromise` to which this method belongs.\n\nRemoves the subscription to `callback` passed to [`instance.subscribe`](#api-subscribe).\nThe `callback` will no longer be invoked for any internal state change.\n\n#### `resetToReady()`\n\n* Parameters: none\n* Returns:\n * `[overseenPromise]` **`this`**\n The instance of the `overseenPromise` to which this method belongs.\n\nCalling this method will reset the internal state of the `instance` to be as if\nit had not been called for the first time yet. This will set the following\nproperty values:\n\n* `instance.state` will now be `'ready'`\n* `instance.message` will now be `''`\n* `instance.result` will now be `undefined`\n\nThis method does not affect any functions passed to [`subscribe`](#api-subscribe)\nor [`setErrorHandler`](#api-seterrorhander).\n\n#### `resetToExecuting()`\n\n* Parameters: none\n* Returns:\n * `[overseenPromise]` **`this`**\n The instance of the `overseenPromise` to which this method belongs.\n\nCalling this method will reset the internal state of the `instance` to be as if\nit were currently executing the wrapped promise. This will set the following\nproperty values:\n\n* `instance.state` will now be `'executing'`\n* `instance.message` will now be `''`\n* `instance.result` will now be `undefined`\n\nThis method does not affect any functions passed to [`subscribe`](#api-subscribe)\nor [`setErrorHandler`](#api-seterrorhander).\n\n#### `setErrorParser(parserFunction)`\n\n* Parameters:\n * `[function]` **`[parserFunction]`** (required)\n A method to invoke when an error has occurred to get an error message.\n* Returns:\n * `[overseenPromise]` **`this`**\n The instance of the `overseenPromise` to which this method belongs.\n\nFor the instance to automatically assign a `message` when the wrapped promise\nencounters an error, it needs to know how to parse the error that has occurred.\nBy default, `message` will be set to either `error.message` (if available) or\nsimply by calling `error.toString()`.\n\nIf your errors do not conform to this shape, you can tell the instance how to\nextract a human-readable error message from your specific error shapes.\n\nThe `errorHandler` function will be invoked with the `error` thrown by the\nrejected wrapped promise, and it must return a human-readable error message\nstring.\n\nFor example, if your errors look like this:\n\n```json\n{\n \"data\": null,\n \"whatWentWrong\": \"API is down for maintenance.\"\n}\n```\n\nThen you should pass in a function that extracts the `whatWentWrong` property:\n\n```js\n/**\n * A function that can extract the error message from your specific error objects\n */\nfunction myErrorParser(error) {\n return error.whatWentWrong;\n}\n\n/**\n * Create the instance as usual\n */\nconst myInstance = oversee( api.getSomeInfo );\n\n/**\n * Register the error parser\n */\nmyInstance.setErrorParser(myErrorParser);\n```\n\n## Usage In Popular Frameworks\n\nSince `oversee-promise` maintains its own internal state, you need to tell your\nlibrary/framework when it should ingest the new state and (potentially)\nre-render your view.\n\nTo do this, pass a callback function into the `subscribe` method of your wrapped\npromise. See below for common examples:\n\n### AngularJS (v1.x)\n\nIn your controller:\n\n```js\n/**\n* Wrap the promise as usual.\n*/\nconst newsItemsQuery = oversee( yourApi.getNewsItems );\n\n/**\n* Call `$scope.$apply()` when the internal state has updated.\n*/\nnewsItemsQuery.subscribe($scope.$apply);\n```\n\n### React\n\n```jsx\n/**\n * A method that calls React's `render`\n */\nfunction onRequestChanged() {\n ReactDOM.render(