simple-oracledb - npm Package Compare versions

Comparing version 1.1.56 to 1.1.57

docs/CHANGELOG.md

 | Date        | Version | Description |
 | ----------- | ------- | ----------- |
+| 2017-01-20  | v1.1.57 | connection.run, connection.transaction and oracledb.run actions can now return a promise instead of using a callback |
 | 2017-01-14  | v1.1.56 | pool.run actions now can return a promise instead of using a callback |
@@ -4,0 +5,0 @@ | 2017-01-13  | v1.1.55 | Maintenance |

lib/oracledb.js

@@ -8,3 +8,2 @@ 'use strict';
 var promiseHelper = require('./promise-helper');
-var singleAsyncCallback = require('./single-async-callback');
 
@@ -157,2 +156,3 @@ /**
  * must call the callback with an error (if any) and result.<br>
+ * For promise support, the action can simply return a promise instead of calling the provided callback.<br>
  * This function will ensure the connection is released properly and only afterwards will call the provided callback with the action error/result.<br>
@@ -205,2 +205,21 @@ * This function basically will remove the need of caller code to get and release a connection and focus on the actual database operation logic.<br>
  * });
+ *
+ * //full promise support for both oracledb.run and the action
+ * oracledb.run({
+ *  user: process.env.ORACLE_USER,
+ *  password: process.env.ORACLE_PASSWORD,
+ *  connectString: process.env.ORACLE_CONNECTION_STRING
+ * }, function (connection) {
+ *   //run some database operations in a transaction and return a promise
+ *   return connection.transaction([
+ *     function firstAction() {
+ *       return connection.insert(....); //returns a promise
+ *     },
+ *     function secondAction() {
+ *       return connection.update(....); //returns a promise
+ *     }
+ *   ]);
+ * }).then(function (result) {
+ *   //do something with the result
+ * });
  * ```
@@ -215,27 +234,5 @@ */
 
-        callback = singleAsyncCallback(callback);
-
-        this.getConnection(connectionAttributes, function onConnection(connectionError, connection) {
-            if (connectionError) {
-                callback(connectionError);
-            } else {
-                try {
-                    action(connection, function onActionDone(actionAsyncError, result) {
-                        connection.release(releaseOptions, function onConnectionRelease(releaseError) {
-                            if (actionAsyncError) {
-                                callback(actionAsyncError);
-                            } else if (releaseError && (!connectionAttributes.ignoreReleaseErrors)) {
-                                callback(releaseError);
-                            } else {
-                                callback(null, result);
-                            }
-                        });
-                    });
-                } catch (actionSyncError) {
-                    connection.release(releaseOptions, function onConnectionRelease() {
-                        callback(actionSyncError);
-                    });
-                }
-            }
-        });
+        var simpleOracleDB = require('./simple-oracledb');
+        var actionRunner = simpleOracleDB.createOnConnectionCallback(action, connectionAttributes, releaseOptions, callback);
+        this.getConnection(connectionAttributes, actionRunner);
     } else {
@@ -242,0 +239,0 @@ throw new Error('Illegal input provided.');

lib/pool.js

@@ -6,3 +6,2 @@ 'use strict';
 var Connection = require('./connection');
-var singleAsyncCallback = require('./single-async-callback');
 var extensions = require('./extensions');
@@ -188,2 +187,3 @@ var emitter = require('./emitter');
  * must call the callback with an error (if any) and result.<br>
+ * For promise support, the action can simply return a promise instead of calling the provided callback.<br>
  * The pool will ensure the connection is released properly and only afterwards will call the provided callback with the action error/result.<br>
@@ -262,37 +262,5 @@ * This function basically will remove the need of caller code to get and release a connection and focus on the actual database operation logic.<br>
 
-        callback = singleAsyncCallback(callback);
-
-        self.getConnection(function onConnection(connectionError, connection) {
-            if (connectionError) {
-                callback(connectionError);
-            } else {
-                try {
-                    var onActionDone = function (actionAsyncError, result) {
-                        connection.release(releaseOptions, function onConnectionRelease(releaseError) {
-                            if (actionAsyncError) {
-                                callback(actionAsyncError);
-                            } else if (releaseError && (!options.ignoreReleaseErrors)) {
-                                callback(releaseError);
-                            } else {
-                                callback(null, result);
-                            }
-                        });
-                    };
-
-                    onActionDone = singleAsyncCallback(onActionDone);
-
-                    var promise = action(connection, onActionDone);
-
-                    if (promiseHelper.isPromise(promise)) {
-                        promise.then(function onActionResult(result) {
-                            onActionDone(null, result);
-                        }).catch(onActionDone);
-                    }
-                } catch (actionSyncError) {
-                    connection.release(releaseOptions, function onConnectionRelease() {
-                        callback(actionSyncError);
-                    });
-                }
-            }
-        });
+        var simpleOracleDB = require('./simple-oracledb');
+        var actionRunner = simpleOracleDB.createOnConnectionCallback(action, options, releaseOptions, callback);
+        self.getConnection(actionRunner);
     } else {
@@ -299,0 +267,0 @@ callback(new Error('Illegal input provided.'));

lib/promise-helper.js

 'use strict';
 
+var singleAsyncCallback = require('./single-async-callback');
+
 /**
@@ -48,2 +50,23 @@ * Promise utility class.
 /**
+ * Ensures the provided function is invoked as an async function even if returning a promise.
+ *
+ * @function
+ * @memberof! PromiseHelper
+ * @private
+ * @param {Object} func - The function to invoke
+ * @param {function} callback - The callback to provide to the invoked function
+ */
+PromiseHelper.prototype.runAsync = function (func, callback) {
+    callback = singleAsyncCallback(callback);
+
+    var promise = func(callback);
+
+    if (this.isPromise(promise)) {
+        promise.then(function onDone(result) {
+            callback(null, result);
+        }).catch(callback);
+    }
+};
+
+/**
  * Calls the provided function with a callback.
@@ -50,0 +73,0 @@ *

lib/simple-oracledb.js

@@ -46,2 +46,4 @@ 'use strict';
 var Monitor = require('./monitor');
+var singleAsyncCallback = require('./single-async-callback');
+var promiseHelper = require('./promise-helper');
 
@@ -292,2 +294,61 @@ var proxyEventsDone = false;
 
+/**
+ * Internal utility function which returns a callback function which will invoke the requested action on the provided connection.
+ *
+ * @function
+ * @memberof! SimpleOracleDB
+ * @private
+ * @param {function} action - The function to invoke with the provided connection
+ * @param {Object} invocationOptions - See oracledb.run/pool.run
+ * @param {Object} releaseOptions - See oracledb.run/pool.run
+ * @param {function} callback - Invoked with result/error after the action is invoked and the connection is released
+ * @returns {function} The callback function
+ * @example
+ * ```js
+ * var actionRunner = simpleOracleDB.createOnConnectionCallback(function (connection) {
+ *   return connection.query('SELECT * FROM PEOPLE');
+ * }, {
+ *   ignoreReleaseErrors: false
+ * }, {
+ *   retryCount: 5
+ * }, callback);
+ * oracledb.getConnection(connectionAttributes, actionRunner);
+ * ```
+ */
+SimpleOracleDB.prototype.createOnConnectionCallback = function (action, invocationOptions, releaseOptions, callback) {
+    return function onConnection(connectionError, connection) {
+        if (connectionError) {
+            callback(connectionError);
+        } else {
+            try {
+                var onActionDone = function (actionAsyncError, result) {
+                    connection.release(releaseOptions, function onConnectionRelease(releaseError) {
+                        if (actionAsyncError) {
+                            callback(actionAsyncError);
+                        } else if (releaseError && (!invocationOptions.ignoreReleaseErrors)) {
+                            callback(releaseError);
+                        } else {
+                            callback(null, result);
+                        }
+                    });
+                };
+
+                onActionDone = singleAsyncCallback(onActionDone);
+
+                var promise = action(connection, onActionDone);
+
+                if (promiseHelper.isPromise(promise)) {
+                    promise.then(function onActionResult(result) {
+                        onActionDone(null, result);
+                    }).catch(onActionDone);
+                }
+            } catch (actionSyncError) {
+                connection.release(releaseOptions, function onConnectionRelease() {
+                    callback(actionSyncError);
+                });
+            }
+        }
+    };
+};
+
 module.exports = new SimpleOracleDB();

package.json

 {
   "name": "simple-oracledb",
-  "version": "1.1.56",
+  "version": "1.1.57",
   "description": "Extend capabilities of oracledb with simplified API for quicker development.",
@@ -5,0 +5,0 @@ "author": {

README.md

@@ -185,2 +185,3 @@ # simple-oracledb
 must call the callback with an error (if any) and result.<br>
+For promise support, the action can simply return a promise instead of calling the provided callback.<br>
 This function will ensure the connection is released properly and only afterwards will call the provided callback with the action error/result.<br>
@@ -223,2 +224,21 @@ This function basically will remove the need of caller code to get and release a connection and focus on the actual database operation logic.<br>
 });
+
+//full promise support for both oracledb.run and the action
+oracledb.run({
+ user: process.env.ORACLE_USER,
+ password: process.env.ORACLE_PASSWORD,
+ connectString: process.env.ORACLE_CONNECTION_STRING
+}, function (connection) {
+  //run some database operations in a transaction and return a promise
+  return connection.transaction([
+    function firstAction() {
+      return connection.insert(....); //returns a promise
+    },
+    function secondAction() {
+      return connection.update(....); //returns a promise
+    }
+  ]);
+}).then(function (result) {
+  //do something with the result
+});
 ```
@@ -295,2 +315,3 @@ <!-- markdownlint-enable MD009 MD031 MD036 -->
 must call the callback with an error (if any) and result.<br>
+For promise support, the action can simply return a promise instead of calling the provided callback.<br>
 The pool will ensure the connection is released properly and only afterwards will call the provided callback with the action error/result.<br>
@@ -721,2 +742,3 @@ This function basically will remove the need of caller code to get and release a connection and focus on the actual database operation logic.<br>
 Actions are basically javascript functions which get a callback when invoked, and must call that callback with error or result.<br>
+For promise support, actions can simply return a promise instead of using the provided callback.<br>
 All provided actions are executed in sequence unless options.sequence=false is provided (parallel invocation is only for IO operations apart of the oracle driver as the driver will queue operations on same connection).<br>
@@ -781,2 +803,16 @@ Once all actions are done, in case of any error in any action, a rollback will automatically get invoked, otherwise a commit will be invoked.<br>
 });
+
+//actions can return a promise instead of using callback (you can mix actions to either use callback or return a promise)
+connection.transaction([
+  function firstAction() {
+    return connection.insert(....); //return a promise
+  },
+  function secondAction() {
+    return connection.update(....); //return a promise
+  }
+], {
+  sequence: true
+}).then(function onTransactionResults(output) {
+  //continue flow...
+});
 ```
@@ -790,2 +826,3 @@ <!-- markdownlint-enable MD009 MD031 MD036 -->
 Actions are basically javascript functions which get a callback when invoked, and must call that callback with error or result.<br>
+For promise support, actions can simply return a promise instead of using the provided callback.<br>
 All provided actions are executed in sequence unless options.sequence=false is provided (parallel invocation is only for IO operations apart of the oracle driver as the driver will queue operations on same connection).<br>
@@ -886,2 +923,16 @@ This function is basically the same as connection.transaction with few exceptions<br>
 });
+
+//actions can return a promise instead of using callback (you can mix actions to either use callback or return a promise)
+connection.run([
+  function firstAction() {
+    return connection.insert(....); //return a promise
+  },
+  function secondAction() {
+    return connection.update(....); //return a promise
+  }
+], {
+  sequence: true
+}).then(function onActionsResults(output) {
+  //continue flow...
+});
 ```
@@ -1103,2 +1154,3 @@ <!-- markdownlint-enable MD009 MD031 MD036 -->
 | ----------- | ------- | ----------- |
+| 2017-01-20  | v1.1.57 | connection.run, connection.transaction and oracledb.run actions can now return a promise instead of using a callback |
 | 2017-01-14  | v1.1.56 | pool.run actions now can return a promise instead of using a callback |
@@ -1105,0 +1157,0 @@ | 2017-01-13  | v1.1.55 | Maintenance |

test/spec/oracledb-spec.js

@@ -774,3 +774,58 @@ 'use strict';
         });
+
+        it('valid full promise support', function (done) {
+            var releaseCalled = false;
+
+            var oracledb = createOracleDB(true);
+
+            oracledb.getConnection = function (connectionAttributes, callback) {
+                assert.deepEqual(connectionAttributes, {
+                    user: 'test',
+                    password: 'mypass',
+                    connectString: 'mydb'
+                });
+
+                callback(null, {
+                    release: function (options, cb) {
+                        assert.deepEqual(options, {
+                            force: true
+                        });
+
+                        releaseCalled = true;
+
+                        setTimeout(cb, 0);
+                    }
+                });
+            };
+
+            global.Promise = PromiseLib;
+
+            oracledb.run({
+                user: 'test',
+                password: 'mypass',
+                connectString: 'mydb'
+            }, function (connection) {
+                assert.isDefined(connection);
+
+                return new PromiseLib(function (resolve) {
+                    setTimeout(function () {
+                        resolve({
+                            result: true,
+                            number: 123
+                        });
+                    }, 0);
+                });
+            }).then(function (result) {
+                assert.isTrue(releaseCalled);
+                assert.deepEqual(result, {
+                    result: true,
+                    number: 123
+                });
+
+                done();
+            }).catch(function () {
+                assert.fail();
+            });
+        });
     });
 });

test/spec/promise-helper-spec.js

@@ -66,2 +66,54 @@ 'use strict';
 
+    describe('runAsync', function () {
+        it('async valid', function (done) {
+            promiseHelper.runAsync(function (callback) {
+                callback(null, 'test output');
+            }, function (error, output) {
+                assert.isNull(error);
+                assert.strictEqual(output, 'test output');
+
+                done();
+            });
+        });
+
+        it('async error', function (done) {
+            promiseHelper.runAsync(function (callback) {
+                callback(new Error('test'));
+            }, function (error, output) {
+                assert.isDefined(error);
+                assert.strictEqual(error.message, 'test');
+                assert.isUndefined(output);
+
+                done();
+            });
+        });
+
+        it('promise valid', function (done) {
+            promiseHelper.runAsync(function () {
+                return new PromiseLib(function (resolve) {
+                    resolve('test output');
+                });
+            }, function (error, output) {
+                assert.isNull(error);
+                assert.strictEqual(output, 'test output');
+
+                done();
+            });
+        });
+
+        it('promise error', function (done) {
+            promiseHelper.runAsync(function () {
+                return new PromiseLib(function (resolve, reject) {
+                    reject(new Error('test'));
+                });
+            }, function (error, output) {
+                assert.isDefined(error);
+                assert.strictEqual(error.message, 'test');
+                assert.isUndefined(output);
+
+                done();
+            });
+        });
+    });
+
     describe('runPromise', function () {
@@ -68,0 +120,0 @@ it('Promise not supported', function () {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

830194

increased by1.59%

Lines of code

17217

increased by1.44%

Number of lines in readme file

1222

increased by4.44%

No dependency changes