Middleware utility for your Promises
Add pre and post middleware hooks to any function returning a Promise.
Read the post on Medium for some example.
Install
yarn add promised-hooks
# or
npm install promised-hooks --save`Warp your Class/function/object
In order to add "pre" and "post" hooks to your promise you need to wrap their containing object (Class/function/object)
const hooks = require('promised-hooks');
// Class
class User {
// some method that returns a Promise
someMethod() { ... }
}
// Function
function User() {
}
User.prototype.someMethod = function someMethod() { ... }
// Object
const api = {
save: function() { ... }
};
// Wrap them to add "pre" and "post" hooks functionalities to their methods
hooks.wrap(User);
hooks.wrap(api);Add middleware
pre() method
Adds a middelware to a promise that will be resolved or rejected before the method you are targetting. If the middelware rejects the Promise the original method is not executed. All the parameters sent to the original methods are available in the arguments of your middleware.
const hooks = require('promised-hooks');
class User {
// instance methods
save() { ... }
// works also with static methods
static otherMethod() { ... }
}
hooks.wrap(User);
User.pre('save', doSometingBeforeSaving);
function doSometingBeforeSaving() {
// Access the arguments passed if needed
const args = Array.prototype.slice.apply(arguments);
// the scope (this) is the original Object wrapped
// return a Promise
return new Promise((resolve, reject) => {
// ... do some async stuff
// then resolve or reject
resolve();
});
}Override
You can override the original arguments sent to the target method by resolving the middleware with an object containing an "__override" property.
User.pre('save', doSometingBeforeSaving);
function doSometingBeforeSaving() {
return new Promise((resolve, reject) => {
// ...
resolve({ __override: 123 }); // single argument
// or
resolve({ __override: [ 123, 'arg2' ] }); // multi arguments
});
/**
* With the above override, the User.save() method will
* receive those arguments instead of the one originally provided
*/
}post() method
Adds a middelware to be executed after the method you are targetting has been resolved. If the post middleware fails and rejects the Promise, the original Promise still resolves and the "post" errors are added the response (see below).
If you resolve your post middelware with an object containing an "__override" property (same as with "pre" hook), it will override the original response.
const hooks = require('promised-hooks');
class User {
// instance methods
save() { ... }
// works also with static (prototype) methods
static otherMethod() { ... }
}
hooks.wrap(User);
// Several middleware can be added at once with an Array
User.post('save', [postMiddleware1, postMiddleware2]);
function postMiddleware1(data) {
// data is the resolved value from the original promised method
// or previous "post" hooks with an __override property
// do some async stuff ...
// and resolve a Promise
return Promise.resolve();
// If needed, you can override the response
return Promise.resolve({ __override: 'my new response' });
}
function postMiddleware2(data) {
return new Promise((resolve, reject) => {
// call async service...
myApi.doSomething((err) => {
if (err) {
/* if the async fails you would then reject your promise.
* The original response is *not* overriden
* (see errors in "post" hook below)
*/
return reject(err);
}
// no error
return resolve();
});
});
}Errors in "post" hooks
If one of the "post" hook fails and rejects its Promise then a Symbol is added on the response containing an Array with the errors. If the response is a primitive('string', 'number', boolean) then it is first converted to an object with a "result" property.
// For example, if the response returned by the targeted method is:
'my response'
// in case there are "post" hooks error it will be converted to:
{
result: 'my response'
}You access the errors Array with the hooks.ERRORS Symbol.
const hooks = require('promised-hooks');
class User {
save() { ... }
}
hooks.wrap(User);
User.post('save', postMiddleware);
function postMiddleware() {
return new Promise((resolve, reject) => {
// call async service...
myApi.doSomething((err) => {
if (err) {
return reject(err);
}
return resolve();
});
});
}
// Somewhere else in your code
const user = new User();
user.save().then((response) => {
// The save occurred without issue but
// let's check for any "post" hook error
if (response[hooks.ERRORS]) {
// deal with errors
}
...
});Scope (this)
The scope (this) of the middelware is set by default on the "wrapped" object. If you need to change it at runtime, you can declare a __scopeHook function
on the object that will be called for each hook. This method, when called, receives 3 parameters:
- the target method
- the arguments (array of arguments sent to the targeted method)
- the hook method name
class User {
save() {}
__scopeHook(targetMethod, args, hookMethod) {
console.log(targetMethod); // "save"
console.log(args); // [123]
console.log(hookMethod); // "hashPassword"
// You can here return any object for the scope
if (hookMethod === 'hashPassword') {
return { x: 'abc' }; // set the scope
}
// If you return "undefined" the scope is not changed
return undefined;
}
}
hooks.wrap(User);
User.pre('save', function hashPassword() {
// Check the scope
console.log(this); // { x: 'abc' }
});
// ...
const user = new User();
user.save(123).then( ... );Example
const hooks = require('promised-hooks');
class User {
save(userData) {
return new Promise((resolve, reject) {
// ...your logic to save a user then
resolve(response);
});
}
// works also on static methods
static otherMethod() { ... }
}
// Wrap the class to add hooks functionalities
hooks.wrap(User);
// Hash a user password before saving
User.pre('save', (userData) => {
/**
* INFO: If you need to access the User class from this middelware
* you can not use an arrow function as the scope is lost.
* Use a normal function and *this* will be your Class
*/
if (typeof userData.password !== 'undefined') {
userData.password = hashString(userData.password);
}
return Promise.resolve();
// ----------
function hashString(str) {
// ... logic to hash a string
return hashedString;
}
});
// Let's email our newly created user
User.post('save', (response) => {
// response is what the target method returns
const email = response.email;
// Return a method that returns a Promise
return yourMailService.sendEmail(email);
});
// Create new user
const user = new User();
// Save user
user.save({ name: 'John', password: 'snow' })
.then((response) => {
// Save success
// Check if there are any errors in our "post" middleware
if (response.[hooks.ERRORS]) {
// deal with Post hook error
}
}, (err) => {
// Save failed
});Credits
I have been inspired by the hooks-fixed library from @vkarpov15 to write this small utility.