| {% include anchor.html edit="true" title="API overview" hash="overview" %} |
| |
| PouchDB has an asynchronous API, supporting both [callbacks](http://docs.nodejitsu.com/articles/getting-started/control-flow/what-are-callbacks) and [promises][promise]. |
| |
| Most of the API is exposed as: |
| |
| {% highlight js %} |
| db.doSomething(args..., [options], [callback]) |
| {% endhighlight %} |
| |
| … where both the `options` and `callback` are optional. |
| |
| Callbacks use the standard Node.js idiom of: |
| |
| {% highlight js %} |
| function(error, result) { /* ... */ } |
| {% endhighlight %} |
| |
| … where the `error` will be undefined if there's no error. |
| |
| If you don't specify a `callback`, then the API returns a [promise][]. In [supported browsers](http://caniuse.com/#feat=promises) or Node.js, native promises are used, falling back to the minimal library [lie][] as needed. |
| |
| {% include alert/start.html variant="info"%} |
| {% markdown %} |
| |
| **Using Ionic/Angular?** You can wrap PouchDB promises in [`$q.when()`](https://docs.angularjs.org/api/ng/service/$q#when). This will notify Angular to update the UI when the PouchDB promise has resolved. |
| |
| {% endmarkdown %} |
| {% include alert/end.html%} |
| |
| For more info, check out the [guide to asynchronous code](/guides/async-code.html). |
| |
| [promise]: https://www.promisejs.org/ |
| [lie]: https://github.com/calvinmetcalf/lie |
| [event emitter]: http://nodejs.org/api/events.html#events_class_events_eventemitter |
