-
Notifications
You must be signed in to change notification settings - Fork 1.5k
/
extras.html
104 lines (62 loc) · 4.57 KB
/
extras.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
{% include anchor.html title="Extras" hash="extras" %}
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:https://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.
#### 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:https://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).
#### 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%}
#### Alternative IndexedDB adapter
{% highlight js %}
var PouchDB = require('pouchdb');
require('pouchdb/extras/idb-alt');
var db = new PouchDB('mydb', {adapter: 'idb-alt'});
{% endhighlight %}
PouchDB adapter using [level-js](https://github.com/maxogden/level.js) over IndexedDB as a storage backend. Mostly only interesting to PouchDB developers; someday, this may replace the standard IndexedDB adapter.
You can also download this plugin [as a standalone script](https://github.com/pouchdb/pouchdb/releases/download/{{ site.version }}/pouchdb.idb-alt.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%}
### 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!