Overview

{% include anchor.html edit="true" title="API overview" hash="overview" %} PouchDB has an asynchronous API, supporting callbacks, [promises][promise], and async functions. For beginners, we recommend promises, although you are free to use whatever format you prefer. If you are unsure, check out our guide to asynchronous code. Most of the API is exposed as: {% highlight "js" %} db.doSomething(args..., [options], [callback]) {% endhighlight %} … where both the options and callback are optional. ### Callbacks 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. ### Promises If you don't specify a callback, then the API returns a [promise][]. In supported browsers 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/AngularJS?** You can wrap PouchDB promises in $q.when(). This will notify AngularJS to update the UI when the PouchDB promise has resolved. {% endmarkdown %} {% include alert/end.html%} To use a custom promise implementation with PouchDB, you must redefine a global Promise object before loading PouchDB: {% highlight "html" %} {% endhighlight %} ### Async functions Another option is to use async/await pattern instead of promises chain (ie. .then().catch()). async/await is widely supported by all major browsers and Node.js. Use a transpiler with async/await polyfill such as Babel if you need to support older browsers. Note that the samples for async/await in the API documentation assume that your code is inside an async function. So for instance: {% highlight "js" %} async function myFunction() { // your code goes in here } {% endhighlight %} Any await not inside of an async function is a syntax error. For more information about async/await, read [our introductory blog post]({{ site.baseurl }}/2015/03/05/taming-the-async-beast-with-es7.html). [promise]: https://www.promisejs.org/ [lie]: https://github.com/calvinmetcalf/lie [event emitter]: http://nodejs.org/api/events.html#events\_class\_events\_eventemitter