docs/_includes/api/extras.html

{% include anchor.html edit="true" title="Extras" hash="extras" %}

{% include alert/start.html variant="warning"%}
{% markdown %}

**Deprecation note:** the `extras/` API is deprecated and will be removed in
a future version of PouchDB. You are encourage to use [custom builds](custom.html) instead.

{% endmarkdown %}
{% include alert/end.html%}

PouchDB offers some "extra" APIs that are designed for PouchDB plugin authors, or for those who want to use non-standard adapters like in-memory and LocalStorage.

These can be especially useful when you are using [Browserify](http://browserify.org/)/[Webpack](https://github.com/webpack/webpack), because they can reduce your overall code size by deduplicating packages. If you're not using Browserify/Webpack, you can also download them [as standalone scripts](/adapters.html#pouchdb_in_the_browser).

### Browser adapter plugins

These adapters are alternatives to PouchDB's built-in IndexedDB/WebSQL adapters. They fully pass the PouchDB test suite.

#### In-memory adapter

{% highlight js %}
var PouchDB = require('pouchdb');
require('pouchdb/extras/memory');

var db = new PouchDB('mydb', {adapter: 'memory'});
{% endhighlight %}

Fully in-memory PouchDB adapter. Data will not be saved after a browser refresh!

This adapter can be useful for unit tests or for environments that don't support IndexedDB/WebSQL. Based on [MemDOWN](https://github.com/Level/memdown).

You can also download this plugin [as a standalone script](https://github.com/pouchdb/pouchdb/releases/download/{{ site.version }}/pouchdb.memory.js).

{% include alert/start.html variant="warning"%}
{% markdown %}

If you want to use an in-memory PouchDB in Node.js/io.js, you should [directly require MemDOWN instead](/adapters.html#pouchdb_in_node_js).

{% endmarkdown %}
{% include alert/end.html%}

#### LocalStorage adapter

{% highlight js %}
var PouchDB = require('pouchdb');
require('pouchdb/extras/localstorage');

var db = new PouchDB('mydb', {adapter: 'localstorage'});
{% endhighlight %}

PouchDB adapter using [LocalStorage](http://www.w3.org/TR/webstorage/). Intended for browsers and environments that don't support IndexedDB or WebSQL. Based on [localstorage-down](https://github.com/No9/localstorage-down).

You can also download this plugin [as a standalone script](https://github.com/pouchdb/pouchdb/releases/download/{{ site.version }}/pouchdb.localstorage.js).

{% include alert/start.html variant="info"%}
{% markdown %}

When you include these plugins in your project, they will be automatically picked up as a "third" option when you create a new PouchDB without an adapter specified (e.g. `new PouchDB('mydb')`).

So for instance, if the user loads PouchDB in a browser that does not support WebSQL or IndexedDB, and if you are using the in-memory plugin, then PouchDB will automatically use the memory adapter instead of WebSQL or IndexedDB.

{% endmarkdown %}
{% include alert/end.html%}

#### FruitDOWN adapter

{% highlight js %}
var PouchDB = require('pouchdb');
require('pouchdb/extras/fruitdown');

var db = new PouchDB('mydb', {adapter: 'fruitdown'});
{% endhighlight %}

PouchDB adapter using [FruitDOWN](https://github.com/nolanlawson/fruitdown).
This is an alternative to the default IndexedDB adapter that ships with PouchDB, which works over all implementations of IndexedDB, including Apple's version.

It is slower and more inefficient than PouchDB's default IndexedDB adapter, but it's handy if you need to use IndexedDB in Safari, iOS, WKWebView, etc.

You can also download this plugin [as a standalone script](https://github.com/pouchdb/pouchdb/releases/download/{{ site.version }}/pouchdb.fruitdown.js).

#### node-websql adapter

{% highlight js %}
var PouchDB = require('pouchdb');
require('pouchdb/extras/websql');

var db = new PouchDB('mydatabase.db', {adapter: 'websql'});
{% endhighlight %}

PouchDB adapter using WebSQL in Node, via [node-websql](https://github.com/nolanlawson/node-websql).
This allows you to use the efficient WebSQL-based PouchDB directly over SQLite.

Unlike the LocalStorage/memory/FruitDOWN adapters, this adapter is designed only
to run in Node.js. In the browser, PouchDB already comes with WebSQL support.

### APIs for plugin authors

These APIs are designed for PouchDB plugin authors, who may want to re-use some PouchDB code to avoid duplication.

To use these APIs, you should save PouchDB as a required npm dependency (`npm install --save pouchdb`) and then require them like so:

#### Ajax

{% highlight js %}
var ajax = require('pouchdb/extras/ajax');
{% endhighlight %}

The `ajax()` function as used by PouchDB. Essentially a shim in the style of `jQuery.ajax`.

#### Checkpointer

{% highlight js %}
var Checkpointer = require('pouchdb/extras/checkpointer');
{% endhighlight %}

The `Checkpointer` function as used by PouchDB's replicator. Writes checkpoints as `_local` docs so that replication can resume where it last left off.

#### Promise

{% highlight js %}
var Promise = require('pouchdb/extras/promise');
{% endhighlight %}

The ES6 `Promise` shim as used by PouchDB. Expect this to be `lie` where a global `Promise` does not exist, the global `Promise` is used when supported.

#### Caveats

These APIs are not rigorously documented and may change frequently. Refer to the [source code](https://github.com/pouchdb/pouchdb/tree/master/extras) for the details of the APIs.

If your plugin depends on a particular version of PouchDB, please notify your users. Unless you like to live dangerously, you should also nail down the version of PouchDB you are using in your `package.json`. And if you need any other internal modules, please submit a pull request!