support for crud hook functions, fixes #51

Author: masumsoft

README.md

@@ -15,6 +15,7 @@ Express-Cassandra is an advanced Cassandra ORM for NodeJS. No more hassling with
 * support for complex queries, streaming and token based pagination
 * support for user defined types/functions/aggregates
 * support for batching ORM operations for atomic updates
+* support for before and after hook functions for save/update/delete
 * builtin experimental support for automatic migrations
 
 This module uses datastax [cassandra-driver](https://github.com/datastax/nodejs-driver) for node and some of the base orm features are wrapper over a highly modified version of [apollo-cassandra](https://github.com/3logic/apollo-cassandra) module. The modifications made to the orm library was necessary to support missing features in the orm, keep it updated with the latest cassandra releases and to make it compatible with the advanced requirements of this module.

docs/management.md

@@ -122,4 +122,47 @@ models.instance.Person.findOne({name: 'John'}, function(err, john){
         //...
     });
 });
-```
+```
+
+## Hook Functions
+
+When you perform a save/update/delete operation, a hook function helps you to tap into it in order to change data or perform other operations. Following are the available hook functions you can define in your schema:
+
+```js
+module.exports = {
+    fields: {
+        ...
+    },
+    key: [...],
+    before_save: function (instance, options, next) {
+        next();
+    },
+    after_save: function (instance, options, next) {
+        next();
+    },
+    before_update: function (queryObject, updateValues, options, next) {
+        next();
+    },
+    after_update: function (queryObject, updateValues, options, next) {
+        next();
+    },
+    before_delete: function (queryObject, options, next) {
+        next();
+    },
+    after_delete: function (queryObject, options, next) {
+        next();
+    },
+}
+```
+
+* `before_save` if defined, will be automatically called each time before a save operation is performed. The `instance` will contain the model instance, so you could modify instance values or perform other things based on it. The `options` will contain the query options being passed to cassandra. You could also modify the options or do things based on it. The `next` is a callback function and after you're done, you must call it like `next()` to let the data saved in cassandra. Otherwise you may also send an error message like `next(err)` to halt the save operation. In this case the data will not be saved and the caller will receive the error message via callback.
+
+* `after_save` if defined, will be automatically called each time after a save operation is successfully performed. The `instance` will contain the model instance, so you could get the instance values that were actually used and perform other things based on it. Note that if you performed any database functions then the output of those functions will not be available in the instance object. For example if you used the `$db_function: 'uuid()'` to generate your id field, then the actual saved value will not be available in the instance object. If you need to know what id was generated, then you need to use the utility function `models.uuid()` in javascript and send that value in the id field instead of using $db_function. The `options` will contain the final query options passed to cassandra. The `next` is a callback function and after you're done, you must call it like `next()` to let the caller recieve it's callback. Otherwise you may also send an error message like `next(err)` and in this case the caller will receive the error message via callback.
+
+* `before_update` if defined, will be automatically called each time before an update operation is performed. The `queryObject` and the `updateValues` will contain the query and updated values part of the update operation as is, so you could modify them if required or perform other things based on them. The `options` will contain the query options being passed to cassandra. You could also modify the options or do things based on it. The `next` is a callback function and after you're done, you must call it like `next()` to let the data updated in cassandra. Otherwise you may also send an error message like `next(err)` to halt the update operation. In this case the data will not be updated and the caller will receive the error message via callback.
+
+* `after_update` if defined, will be automatically called each time after an update operation is successfully performed. The `queryObject` and the `updateValues` will contain the query and updated values part of the update operation as is, so you could get the query and values that were actually used and perform other things based on them. Note that if you performed any database functions then the output of those functions will not be available in the updateValues object. For example if you used the `$db_function: 'now()'` to update your `updatedAt` field, then the actual updated value will not be available in the `updateValues` object. If you need to know the updated value of the `updatedAt` field, then you need to generate the current timestamp in javascript and send that value in the updatedAt field instead of using $db_function. The `options` will contain the final query options passed to cassandra. The `next` is a callback function and after you're done, you must call it like `next()` to let the caller recieve it's callback. Otherwise you may also send an error message like `next(err)` and in this case the caller will receive the error message via callback.
+
+* `before_delete` if defined, will be automatically called each time before a delete operation is performed. The `queryObject` will contain the query part of the delete operation as is, so you could modify them if required or perform other things based on them. The `options` will contain the query options being passed to cassandra. You could also modify the options or do things based on it. The `next` is a callback function and after you're done, you must call it like `next()` to let the data deleted in cassandra. Otherwise you may also send an error message like `next(err)` to halt the delete operation. In this case the data will not be deleted and the caller will receive the error message via callback.
+
+* `after_delete` if defined, will be automatically called each time after a delete operation is successfully performed. The `queryObject` will contain the query part of the delete operation as is, so you could get the query that was actually used and perform other things based on it. The `options` will contain the final query options passed to cassandra. The `next` is a callback function and after you're done, you must call it like `next()` to let the caller recieve it's callback. Otherwise you may also send an error message like `next(err)` and in this case the caller will receive the error message via callback.

src/orm/apollo_error.js

@@ -79,18 +79,36 @@ const AERROR_TYPES = {
   'model.save.dberror': {
     msg: 'Error during save query on DB -> %s',
   },
+  'model.save.before.error': {
+    msg: 'Error in before_save lifecycle function -> %s',
+  },
+  'model.save.after.error': {
+    msg: 'Error in after_save lifecycle function -> %s',
+  },
   'model.update.invalidvalue': {
     msg: 'Invalid Value: "%s" for Field: %s',
   },
   'model.update.dberror': {
     msg: 'Error during update query on DB -> %s',
   },
+  'model.update.before.error': {
+    msg: 'Error in before_update lifecycle function -> %s',
+  },
+  'model.update.after.error': {
+    msg: 'Error in after_update lifecycle function -> %s',
+  },
   'model.delete.invalidvalue': {
     msg: 'Invalid Value: "%s" for Field: %s (Type: %s)',
   },
   'model.delete.dberror': {
     msg: 'Error during delete query on DB -> %s',
   },
+  'model.delete.before.error': {
+    msg: 'Error in before_delete lifecycle function -> %s',
+  },
+  'model.delete.after.error': {
+    msg: 'Error in after_delete lifecycle function -> %s',
+  },
 };
 
 const ERR_NAME_PREFIX = 'apollo';

src/orm/base_model.js

@@ -1775,16 +1775,52 @@ BaseModel.update = function f(queryObject, updateValues, options, callback) {
   if (options.retry) queryOptions.retry = options.retry;
   if (options.serialConsistency) queryOptions.serialConsistency = options.serialConsistency;
 
-  this._execute_table_query(query, queryParams, queryOptions, (err, results) => {
-    if (typeof callback === 'function') {
-      if (err) {
-        callback(buildError('model.update.dberror', err));
+  // set dummy hook function if not present in schema
+  const schema = this._properties.schema;
+  if (typeof schema.before_update !== 'function') {
+    schema.before_update = function f1(queryObj, updateVal, optionsObj, next) {
+      next();
+    };
+  }
+
+  if (typeof schema.after_update !== 'function') {
+    schema.after_update = function f1(queryObj, updateVal, optionsObj, next) {
+      next();
+    };
+  }
+
+  schema.before_update(queryObject, updateValues, options, (error) => {
+    if (error) {
+      if (typeof callback === 'function') {
+        callback(buildError('model.update.before.error', error));
         return;
       }
-      callback(null, results);
-    } else if (err) {
-      throw buildError('model.update.dberror', err);
+      throw buildError('model.update.before.error', error);
     }
+
+    this._execute_table_query(query, queryParams, queryOptions, (err, results) => {
+      if (typeof callback === 'function') {
+        if (err) {
+          callback(buildError('model.update.dberror', err));
+          return;
+        }
+        schema.after_update(queryObject, updateValues, options, (error1) => {
+          if (error1) {
+            callback(buildError('model.update.after.error', error1));
+            return;
+          }
+          callback(null, results);
+        });
+      } else if (err) {
+        throw buildError('model.update.dberror', err);
+      } else {
+        schema.after_update(queryObject, updateValues, options, (error1) => {
+          if (error1) {
+            throw buildError('model.update.after.error', error1);
+          }
+        });
+      }
+    });
   });
 
   return {};
@@ -1833,16 +1869,52 @@ BaseModel.delete = function f(queryObject, options, callback) {
   if (options.retry) queryOptions.retry = options.retry;
   if (options.serialConsistency) queryOptions.serialConsistency = options.serialConsistency;
 
-  this._execute_table_query(query, queryParams, queryOptions, (err, results) => {
-    if (typeof callback === 'function') {
-      if (err) {
-        callback(buildError('model.delete.dberror', err));
+  // set dummy hook function if not present in schema
+  const schema = this._properties.schema;
+  if (typeof schema.before_delete !== 'function') {
+    schema.before_delete = function f1(queryObj, optionsObj, next) {
+      next();
+    };
+  }
+
+  if (typeof schema.after_delete !== 'function') {
+    schema.after_delete = function f1(queryObj, optionsObj, next) {
+      next();
+    };
+  }
+
+  schema.before_delete(queryObject, options, (error) => {
+    if (error) {
+      if (typeof callback === 'function') {
+        callback(buildError('model.delete.before.error', error));
         return;
       }
-      callback(null, results);
-    } else if (err) {
-      throw buildError('model.delete.dberror', err);
+      throw buildError('model.delete.before.error', error);
     }
+
+    this._execute_table_query(query, queryParams, queryOptions, (err, results) => {
+      if (typeof callback === 'function') {
+        if (err) {
+          callback(buildError('model.delete.dberror', err));
+          return;
+        }
+        schema.after_delete(queryObject, options, (error1) => {
+          if (error1) {
+            callback(buildError('model.delete.after.error', error1));
+            return;
+          }
+          callback(null, results);
+        });
+      } else if (err) {
+        throw buildError('model.delete.dberror', err);
+      } else {
+        schema.after_delete(queryObject, options, (error1) => {
+          if (error1) {
+            throw buildError('model.delete.after.error', error1);
+          }
+        });
+      }
+    });
   });
 
   return {};
@@ -2027,16 +2099,51 @@ BaseModel.prototype.save = function fn(options, callback) {
   if (options.retry) queryOptions.retry = options.retry;
   if (options.serialConsistency) queryOptions.serialConsistency = options.serialConsistency;
 
-  this.constructor._execute_table_query(query, queryParams, queryOptions, (err, result) => {
-    if (typeof callback === 'function') {
-      if (err) {
-        callback(buildError('model.save.dberror', err));
+  // set dummy hook function if not present in schema
+  if (typeof schema.before_save !== 'function') {
+    schema.before_save = function f(instance, option, next) {
+      next();
+    };
+  }
+
+  if (typeof schema.after_save !== 'function') {
+    schema.after_save = function f(instance, option, next) {
+      next();
+    };
+  }
+
+  schema.before_save(this, options, (error) => {
+    if (error) {
+      if (typeof callback === 'function') {
+        callback(buildError('model.save.before.error', error));
         return;
       }
-      callback(null, result);
-    } else if (err) {
-      throw buildError('model.save.dberror', err);
+      throw buildError('model.save.before.error', error);
     }
+
+    this.constructor._execute_table_query(query, queryParams, queryOptions, (err, result) => {
+      if (typeof callback === 'function') {
+        if (err) {
+          callback(buildError('model.save.dberror', err));
+          return;
+        }
+        schema.after_save(this, options, (error1) => {
+          if (error1) {
+            callback(buildError('model.save.after.error', error1));
+            return;
+          }
+          callback(null, result);
+        });
+      } else if (err) {
+        throw buildError('model.save.dberror', err);
+      } else {
+        schema.after_save(this, options, (error1) => {
+          if (error1) {
+            throw buildError('model.save.after.error', error1);
+          }
+        });
+      }
+    });
   });
 
   return {};

test/models/PersonModel.js

@@ -119,4 +119,22 @@ module.exports = {
       key: [['userID', 'age'], 'active'],
     },
   },
+  before_save: (instance, options, next) => {
+    next();
+  },
+  after_save: (instance, options, next) => {
+    next();
+  },
+  before_update: (queryObject, updateValues, options, next) => {
+    next();
+  },
+  after_update: (queryObject, updateValues, options, next) => {
+    next();
+  },
+  before_delete: (queryObject, options, next) => {
+    next();
+  },
+  after_delete: (queryObject, options, next) => {
+    next();
+  },
 };