Introducing CouchDB Nano 7.0.0
The latest release of the official Node.js library for Apache CouchDB
Nano doesn’t try to do too much as a library — a Nano function call usually maps to single HTTP API call, and it maintains the same parameter names as the HTTP API so with its use, you naturally pick up the underlying CouchDB interface.
Today sees the release of Nano version 7.0.0 which contains the following features:
- Nano adds a number of
...AsStream()functions that return a streamable object, for operations that tend to return a lot of data or have long-running HTTP requests.
- Updated TypeScript definitions that accurately model the parameters and return values of all functions.
- Updated README and source code snippets.
- Various bug fixes
Callbacks vs Promises
The previous versions of Nano used the callback style to handle asynchronous data transfer. Let’s say you wanted to fetch a document whose
_id field was "rita", your Nano code would have looked like this:
The callback style involved giving the library a function to be called when the result of an HTTP call was received, The function’s parameter signature followed the “
data" convention so that code would have to use an
if statement or two to determine whether there was an error and to decide how to proceed. The trouble with the callback style was that your code tended to indent with each asynchronous call, getting further to the right with each request:
Add to that the complexity of checking the
err value after each call, the code became get pretty messy. In Nano 7, you can still use the callback style - the above code will still work - but the recommended approach is to use the Promise that is now returned from each function call. Your code now reads:
The code isn’t any shorter, but it doesn’t indent with every asynchronous action. Successfully retreived data is fed to the subsequent
then functions and any errors are corralled by the single
catch function at the bottom of the sequence.
If we’re happy to launch multiple HTTP requests at conce, we could simplify the code with:
Now things are starting to get very readable, almost normal in fact.
Just as an aside, it’s much more efficent to fetch the three documents in a single API call, but it’s just a demo:
In some cases, your code is just a conduit between your app’s user and the data stored in CouchDB. Imagine in your Express app you are exposing an HTTP API call which, when called, fetches data from CouchDB. Your app doesn’t need to hold the data in memory, it can just stream the data from CouchDB to your HTTP client. In Nano 6, all of the function calls returned a streamable object, but in Nano 7 only certain function calls (functions whose name ends with “AsStream”) do:
The functions that return streams are those that tend to deal with bulk data:
nano.db.listAsStream- fetch a list of database names
db.attachment.insertAsStream- insert an attachment from a stream
db.attachment.getAsStream- retrieve an attachment as a stream
db.listAsStream- fetch a list of documents
db.findAsStream- query a database using a "Mango" selector
db.searchAsStream- perform a Lucene-style query
db.viewAsStream- query a MapReduce view
db.changesAsStream- fetch a database's changes feed
Getting started with Nano
Download the package from npm:
Import the library into your project:
Configure your CouchDB connection:
Create a database and insert some documents:
Get all the documents:
Query documents where
a >= 2:
Migrating from Nano 6
Nano still supports callbacks so the chances are that your code may not need any changes to work with Nano 7. If you are relying on the streaming capabilities of Nano 6, then you’ll need to make some changes and look for the new
Nano’s TypeScript definitions are now part of the project and accurately reflect the returned types. To get the best out of TypeScript and CouchDB, you can make your own TypeScript classes that model your app’s data and build on the core Nano definitions:
Keep in touch
Nano is an open source project released under the Apache-2.0 license under the auspices of the Apache Foundation. If you have feedback then feel free to raise and issue or contribute a pull request and become a contributor. We’d love to hear from you!