glynnbird commented on a change in pull request #102: Promise support for Nano - Issue 98 URL: https://github.com/apache/couchdb-nano/pull/102#discussion_r204399168
########## File path: migration_6_to_7.md ########## @@ -0,0 +1,96 @@ +# Migration Guide for moving from Nano 6.x to 7.x + +Version 7.0.0 saw a major switch in return values from the majority of Nano functions. The version 6 version of Nano always returned a [request](https://www.npmjs.com/package/request) object from any function call that made an HTTP/HTTPS request. + + +In Nano 6: + +```js +// Nano 6 +var db = nano.db.use('mydb') +var x = db.get('mydoc') +// x is a request object +``` + +In Nano 7: + +```js +// Nano 7 +const db = nano.db.use('mydb') +const x = await db.get('mydoc') +``` + +If you are not using the streaming properties of Nano 6's return value, you may not need to change any code at all. This document outlines the areas that have changed and what you need to do to your code. + +## Streaming + +If you were using the returned request object to: + +- pipe the result to another stream +- listen to HTTP events ( `.on('data', function() {} )` etc) + +then **you will need to change your code** to make it work with Nano v7. There are handful of new `..AsStream` function calls the *do* return a request object. They are: + +- 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 + +There are non-streaming versions of all of the above functions that return a Promise - simply remove the "AsStream" suffix. + +There isn't an `...AsStream` function for every CouchDB operation - only for ones which may result in lots of data being moved around or where binary data is being passed around (attachments). The streaming functions are useful to pipe data data through your app between CouchDB and your client without your app having to buffer all of the data in memory at once. + +## Promises + +In Nano 7, most functions return a native [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) instead of a request object. + +If you have code in the *callback* style, then Nano 7 will still work: + +```js +// Nano 7 +db.get('mydoc', (err, data) => { + console.log(err, data) +}) +``` + +but you have the option of using the returned *Promise* to deal with the return of asynchronous data: + +```js +db.get('mydoc').then((doc) => { + console.log(doc) +}).catch((err) => { + console.log(err) +}) +``` + +The Promise style of code lets you code sequences of asynchronou calls at the same level of indentation (the callback style forces you to indent further to the right with each call!): Review comment: 👍 ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
