[GitHub] glynnbird opened a new issue #98: Make nano functions return a Promise

[GitBox <gi...@apache.org>]

glynnbird opened a new issue #98: Make nano functions return a Promise
URL: https://github.com/apache/couchdb-nano/issues/98
 
 
   Currently the nano library returns a `request` object when asked to make an API call on your behalf and the asynchronous reply is returned to your user-supplied callback function
   
   ```js
     db.get('mydoc', function(err, data) {
       console.log(err, data)
     });
   ```
   
   The convention of having a callback with the method signature `(err, data)` was *the way* to deal with asynchronous behaviour when the original Nano library was written, but things have moved on.
   
   ## Promises, promises
   
   Nowadays Node.js supports native [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - an object that returns synchronously from a function which either *resolves* successfully or *rejects* in error. If Nano returned a Promise instead of a `request` object, code could look like this:
   
   ```js
     db.get('mydoc').then((doc) => {
       doc.newdata = 'woo'
       return db.insert(doc)
     }).then((response) => {
        console.log('document updated')
     })
   ```
   
   or even, in an `async` function:
   
   ```js
       var doc = await db.get('mydoc')
       doc.newdata = 'woo'
       var response = await db.insert(doc)
       console.log('document updated')
   ```
   
   This isn't a new idea. [This PR](https://github.com/apache/couchdb-nano/pull/88) proposed making Promises an optional return value and the [nodejs-cloudant](|https://github.com/cloudant/nodejs-cloudant) library, which builds on Nano, offers Promise support as an option.
   
   I am propose to take this a step further for a Nano v7.*.* release:
   
   - return a Promise by default in all existing function calls that currently return a `request`
   - implement a handful of extra API calls that return streams (e.g. `db.listAsStream()`, `db.attachment.getAsStream('rabbit', 'picture.png')`) 
   
   This is a more comprehensive change than those previously proffered but does have the following advantages:
   
   - optional return values cause havoc with TypeScript - if a function can return *either* a Promise or Stream, then it becomes difficult to type check
   - code that doesn't use streams would still work - the `callback` would still be called if supplied
   - TypeScript definitions could be made to reflect the new return type, making TypeScript developers happy
   - users depending on Nano 6.x.x would remain unaffected
   - Nano fits into the expectations of the developer of today and can be used with `async`/`await` code
   
   ## What needs to change
   
   As @denisw spotted in [PR88](https://github.com/apache/couchdb-nano/pull/88), it's pretty easy to get the `relax function to return a Promise rather than a `request`, but then comes the tricky part!
   
   - write new `...AsStream|` functions for operations that return lots of data
   - update the tests (!) - as the callback mechanism is being retained, many of the existing tests may work but extra tests would be needed 
   - README - all of the code samples would need reworking
   - examples - all example code would need a refactor
   - TypeScript definitions
   
   I'm happy to have a go at these change but I'm seeking a nod of approval from the community before I make a start!
   

----------------------------------------------------------------
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:
users@infra.apache.org


With regards,
Apache Git Services