JavaScript and Maps (in that order)

In which we explain how to use PouchDB

This is a follow up to my previous PouchDB post, so if you can’t read that you probably are going to want to. 

PouchDB is local storage primarily using IndexedDB, but with a WebSQL fallback, even if you arn’t doing crazy replications PouchDB may still be a easier to use because, do you understand IndexedDB? Because I don’t. Pouch on the other hand has an API based on CouchDB’s API which in turn is based on HTTP.  Your DB stores documents, which is just JSON but with two special fields (note the underscores):

  • _id: this you can add your self, but if not it’s added for you, this is the documents key, if you want to find it you’ll need this.
  • _rev: this is the documents revision, this is what couch has instead of transactions, if you want to modify a document or delete it, you need the _rev of the version you want to change, that way if someone else modifies it first it won’t match.
  • There are actually 7 more, but we you can safely ignore them for now.

You update Couch via http and all the methods are based on HTTP verbs, Pouch’s methods are the same (though it should be pointed out that HTTP verbs are traditionally written in all caps but are not case sensitive, but JavaScript methods are case sensitive and lowercase):

  • POST: create a new new document and assigns it a random _id, use this if you don’t care what the key is (i.e. your using it programmatically).
  • PUT: Use this to either update a document, in which case you need to supply the _id and _rev, or to create a document with your chosen _id, in which case you don’t need _rev. 
  • GET:  This is for getting a document, you need the _id obviously. 
  • DELETE/REMOVE: This is one deviation between Couch and Pouch as “delete” is a reserved word in JavaScript, don’t forget you need the _rev.   This actually just adds _deleted:true which in Couch means that next time the database is compacted previous version can be removed, note you can’t remove it entirely because if you did you wouldn’t be able to tell other databases so when you replicated. 

Now onto Pouch specific things: the first thing to know is that like IndexedDB Pouch is asynchronous. , compare this which is synchronous JavaScript code

with this async code

The reason for this async set up is so as not to block the execution, unless you are using workers (which you likely aren’t, see my previous post) all of your script is in one thread, but the IndexedDB is in another thread and when you ask it to get you something instead of putting you on hold it just asks you for a number to call you when it’s found it. Pouch follows the Node.js convention of the first argument given to any callback will be an error argument which will be null/undefined/false if there is not an error meaning you can use if(!err) to check for an error and be the last argument you give to the function (the callback that is), hopefully this makes more sense:

Ok now for some basic Pouch usage which we will demonstrate by building a sample app …sort of, this post is really long so instead were going to create a class that will serve as the core of the app we will make next time, for serious.

Note unlike the previous code, this code is going to be in CoffeeScript, when I’m not writing directly for the browser this is what I tend to use for a variety of reasons which I go into excessive detail about at the end of this previous post.

So the first thing we’re going to need is a constructor function, it’s going to take a url as its first argument and implement the pattern from my previous post.The second argument its going to take is an on change function, this is the function that will be called every time a document is changed either remotely or locally.

We want to be able to

  • Add a new document
  • Get a document
  • Delete one

Which put together looks like

And there you have a basic PouchDB class next time we’ll make a working app for real, just have to figure out what I was originally going to show something based on leaflet like my leaflet.pouch but that might require too much knowledge of how leaflet works, feel free to hit me up on twitter with suggestions.