node-oracledb

19. Promises in node-oracledb

Node-oracledb supports Promises with all asynchronous methods. The native Promise
implementation is used in Node 0.12 and greater. Promise support is not
enabled by default in Node 0.10.

If an asynchronous method is invoked without a callback, it returns a
Promise:

var oracledb = require('oracledb');
oracledb.getConnection(
  {
    user          : "hr",
    password      : "welcome",
    connectString : "localhost/XE"
  })
  .then(function(conn) {
    return conn.execute(
      "SELECT department_id, department_name " +
        "FROM departments " +
        "WHERE manager_id < :id",
      [110]  // bind value for :id
    )
      .then(function(result) {
        console.log(result.rows);
        return conn.close();
      })
      .catch(function(err) {
        console.error(err);
        return conn.close();
      });
  })
  .catch(function(err) {
    console.error(err);
  });

With Oracle's sample HR schema, the output is:

[ [ 60, 'IT' ], [ 90, 'Executive' ], [ 100, 'Finance' ] ]

Notice there are two promise "chains": one to get a connection and the
other to use it. This is required because it is only possible to
refer to the connection within the function to which it was passed.

When invoking asynchronous methods, it is possible to accidentally
get a Promise by forgetting to pass a callback function:

oracledb.getConnection(
  {
    user          : "hr",
    password      : "welcome",
    connectString : "localhost/WRONG_SERVICE_NAME"
  });
  . . .

Since the returned promise will not have a catch block, as the
developer intended to use the callback programming style, any
rejections that occur will go unnoticed. Node.js 4.0 added the
unhandledRejection event to prevent such rejections from going
unnoticed:

process.on('unhandledRejection', (reason, p) => {
  console.error("Unhandled Rejection at: ", p, " reason: ", reason);
  // application specific logging, throwing an error, or other logic here
});
oracledb.getConnection(
  {
    user          : "hr",
    password      : "welcome",
    connectString : "localhost/WRONG_SERVICE_NAME"
  });
  . . .

Whereas the code without the unhandledRejection exception silently
exited, adding the handler could, for example, show:

$ node myapp.js
Unhandled Rejection at:  Promise {
  <rejected> [Error: ORA-12514: TNS:listener does not currently know of service requested in connect descriptor
] }  reason:  [Error: ORA-12514: TNS:listener does not currently know of service requested in connect descriptor
]

19.1 Custom Promise Libraries

The Promise implementation is designed to be overridden, allowing a
custom Promise library to be used. An external library can also be
used to add Promise support to Node 0.10.

var mylib = require('myfavpromiseimplementation');
oracledb.Promise = mylib;

Promises can be completely disabled by setting

oracledb.Promise = null;

If your code uses the promise style in Node 0.10 but you have not
installed your own promise library then you will get an error like:

$ node mypromiseapp.js
node_modules/oracledb/lib/util.js:53
    throw new Error(getErrorMessage(errorCode, messageArg1));
          ^
Error: NJS-009: invalid number of parameters
    at Object.assert (node_modules/oracledb/lib/util.js:53:11)
    at Oracledb.getConnection (node_modules/oracledb/lib/oracledb.js:71:12)
    at Oracledb.getConnection (node_modules/oracledb/lib/util.js:72:19)
    at Object.<anonymous> (mypromiseapp.js:8:10)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)
    at startup (node.js:119:16)

Because node-oracledb Promises support is not enabled by default when
using Node 0.10, the callback API is expected. The error stack trace
indicates that line 10 of mypromiseapp.js forgot to pass the
callback. Either install your own Promise library or use the callback
programming style.