Transform Pouch
Apply a transform function to documents before and after they are stored in the database. These functions are triggered invisibly for every get()
, put()
, post()
, bulkDocs()
, allDocs()
, changes()
, and also to documents added via replication.
This allows you to:
- Encrypt and decrypt sensitive document fields
- Compress and uncompress large content (e.g. to avoid hitting browser storage limits)
- Remove or modify documents before storage (e.g. to massage data from CouchDB)
Note: This plugin was formerly known as filter-pouch
. The filter()
API is still supported, but deprecated.
Usage
To use this plugin, include the dist/pouchdb.transform-pouch.js
file after pouchdb.js
in your HTML page:
It's also available in Bower:
bower install transform-pouch
Or to use it in Node.js, just npm install it:
npm install transform-pouch
And then attach it to the PouchDB
object:
var PouchDB = ;PouchDB;
API
When you create a new PouchDB, you need to configure the transform functions:
var pouch = 'mydb';pouch;
Notes:
- You can provide an
incoming
function, anoutgoing
function, or both. - Your transform function must return the document itself, or a new document.
incoming
functions apply toput()
,post()
,bulkDocs()
, and incoming replications.outgoing
functions apply toget()
,allDocs()
,changes()
,query()
, and outgoing replications.- The
transform()
method is synchronous - no need for callbacks or promises.
Example: Encryption
Update! Check out crypto-pouch, which is based on this plugin, and runs in both the browser and Node. The instructions below will only work in Node.
Using the Node.js crypto library, let's first set up our encrypt/decrypt functions:
var crypto = ; { var cipher = crypto; var crypted = cipher; return crypted + cipher;} { var decipher = crypto; var dec = decipher; return dec + decipher;}
Obviously you would want to change the 'password'
to be something only the user knows!
Next, let's set up our transforms:
pouch;
(transform-pouch
will automatically ignore deleted documents, so you don't need to handle that case.)
Now, the documents are encrypted whenever they're stored in the database. If you want to verify, try opening them with a Pouch
where you haven't set up any transforms
. You'll see documents like:
secret: 'YrAtAEbvp0bPLil8EpbNeA==' _id: 'doc' _rev: '1-bfc37cd00225f68671fe3187c054f9e3'
whereas privileged users will see:
secret: 'my super secret text!' _id: 'doc' _rev: '1-bfc37cd00225f68671fe3187c054f9e3'
This works for remote CouchDB databases as well. In fact, only the encrypted data is sent over the wire, so it's ideal for protecting sensitive information.
Note on query()
Since the remote CouchDB doesn't have accesss to the untransformed document, map/reduce functions that are executed directly against CouchDB will be applied to the untransformed version. PouchDB doesn't have this limitation, because everything is local.
So for instance, if you try to emit()
an encrypted field in your map function:
{ ;}
... the emitted key will be encrypted when you query()
the remote database, but decrypted when you query()
a local database. So be aware that the query()
functionality is not exactly the same.
Building
npm install
npm run build
Testing
In Node
This will run the tests in Node using LevelDB:
npm test
You can also check for 100% code coverage using:
npm run coverage
If you have mocha installed globally you can run single test with:
TEST_DB=local mocha --reporter spec --grep search_phrase
The TEST_DB
environment variable specifies the database that PouchDB should use (see package.json
).
In the browser
Run npm run dev
and then point your favorite browser to https://127.0.0.1:8001/test/index.html.
The query param ?grep=mysearch
will search for tests matching mysearch
.
Automated browser tests
You can run e.g.
CLIENT=selenium:firefox npm test
CLIENT=selenium:phantomjs npm test
This will run the tests automatically and the process will exit with a 0 or a 1 when it's done. Firefox uses IndexedDB, and PhantomJS uses WebSQL.