kareem 2.4.0 → 2.5.0

package/LICENSE

@@ -186,7 +186,7 @@ Apache License
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright {yyyy} {name of copyright owner}
+   Copyright 2014-2022 mongoosejs
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/index.js

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * Create a new instance
+ */
 function Kareem() {
   this._pres = new Map();
   this._posts = new Map();
@@ -21,19 +24,27 @@ Kareem.overwriteResult = function overwriteResult() {
   this.args = [...arguments];
 };
 
+/**
+ * Execute all "pre" hooks for "name"
+ * @param {String} name The hook name to execute
+ * @param {*} context Overwrite the "this" for the hook
+ * @param {Array|Function} args Optional arguments or directly the callback
+ * @param {Function} [callback] The callback to call when executing all hooks are finished
+ * @returns {void}
+ */
 Kareem.prototype.execPre = function(name, context, args, callback) {
   if (arguments.length === 3) {
     callback = args;
     args = [];
   }
-  var pres = this._pres.get(name) || [];
-  var numPres = pres.length;
-  var numAsyncPres = pres.numAsync || 0;
-  var currentPre = 0;
-  var asyncPresLeft = numAsyncPres;
-  var done = false;
-  var $args = args;
-  var shouldSkipWrappedFunction = null;
+  const pres = this._pres.get(name) || [];
+  const numPres = pres.length;
+  const numAsyncPres = pres.numAsync || 0;
+  let currentPre = 0;
+  let asyncPresLeft = numAsyncPres;
+  let done = false;
+  const $args = args;
+  let shouldSkipWrappedFunction = null;
 
   if (!numPres) {
     return nextTick(function() {
@@ -41,14 +52,14 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
     });
   }
 
-  var next = function() {
+  function next() {
     if (currentPre >= numPres) {
       return;
     }
-    var pre = pres[currentPre];
+    const pre = pres[currentPre];
 
     if (pre.isAsync) {
-      var args = [
+      const args = [
         decorateNextFn(_next),
         decorateNextFn(function(error) {
           if (error) {
@@ -70,9 +81,9 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
 
       callMiddlewareFunction(pre.fn, context, args, args[0]);
     } else if (pre.fn.length > 0) {
-      var args = [decorateNextFn(_next)];
-      var _args = arguments.length >= 2 ? arguments : [null].concat($args);
-      for (var i = 1; i < _args.length; ++i) {
+      const args = [decorateNextFn(_next)];
+      const _args = arguments.length >= 2 ? arguments : [null].concat($args);
+      for (let i = 1; i < _args.length; ++i) {
         args.push(_args[i]);
       }
 
@@ -103,7 +114,7 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
         next();
       }
     }
-  };
+  }
 
   next.apply(null, [null].concat(args));
 
@@ -133,25 +144,41 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
   }
 };
 
+/**
+ * Execute all "pre" hooks for "name" synchronously
+ * @param {String} name The hook name to execute
+ * @param {*} context Overwrite the "this" for the hook
+ * @param {Array} [args] Apply custom arguments to the hook
+ * @returns {void}
+ */
 Kareem.prototype.execPreSync = function(name, context, args) {
-  var pres = this._pres.get(name) || [];
-  var numPres = pres.length;
+  const pres = this._pres.get(name) || [];
+  const numPres = pres.length;
 
-  for (var i = 0; i < numPres; ++i) {
+  for (let i = 0; i < numPres; ++i) {
     pres[i].fn.apply(context, args || []);
   }
 };
 
+/**
+ * Execute all "post" hooks for "name"
+ * @param {String} name The hook name to execute
+ * @param {*} context Overwrite the "this" for the hook
+ * @param {Array|Function} args Apply custom arguments to the hook
+ * @param {*} options Optional options or directly the callback
+ * @param {Function} [callback] The callback to call when executing all hooks are finished
+ * @returns {void}
+ */
 Kareem.prototype.execPost = function(name, context, args, options, callback) {
   if (arguments.length < 5) {
     callback = options;
     options = null;
   }
-  var posts = this._posts.get(name) || [];
-  var numPosts = posts.length;
-  var currentPost = 0;
+  const posts = this._posts.get(name) || [];
+  const numPosts = posts.length;
+  let currentPost = 0;
 
-  var firstError = null;
+  let firstError = null;
   if (options && options.error) {
     firstError = options.error;
   }
@@ -162,12 +189,12 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
     });
   }
 
-  var next = function() {
-    var post = posts[currentPost].fn;
-    var numArgs = 0;
-    var argLength = args.length;
-    var newArgs = [];
-    for (var i = 0; i < argLength; ++i) {
+  function next() {
+    const post = posts[currentPost].fn;
+    let numArgs = 0;
+    const argLength = args.length;
+    const newArgs = [];
+    for (let i = 0; i < argLength; ++i) {
       numArgs += args[i] && args[i]._kareemIgnore ? 0 : 1;
       if (!args[i] || !args[i]._kareemIgnore) {
         newArgs.push(args[i]);
@@ -175,7 +202,7 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
     }
 
     if (firstError) {
-      if (post.length === numArgs + 2) {
+      if (isErrorHandlingMiddleware(posts[currentPost], numArgs)) {
         const _cb = decorateNextFn(function(error) {
           if (error) {
             if (error instanceof Kareem.overwriteResult) {
@@ -222,7 +249,7 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
         next();
       });
 
-      if (post.length === numArgs + 2) {
+      if (isErrorHandlingMiddleware(posts[currentPost], numArgs)) {
         // Skip error handlers if no error
         if (++currentPost >= numPosts) {
           return callback.apply(null, [null].concat(args));
@@ -242,7 +269,12 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
         }
 
         if (isPromiseLike(maybePromiseLike)) {
-          return maybePromiseLike.then((res) => _cb(res), err => _cb(err));
+          return maybePromiseLike.then(
+            (res) => {
+              _cb(res instanceof Kareem.overwriteResult ? res : null);
+            },
+            err => _cb(err)
+          );
         }
 
         if (maybePromiseLike instanceof Kareem.overwriteResult) {
@@ -256,11 +288,18 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
         next();
       }
     }
-  };
+  }
 
   next();
 };
 
+/**
+ * Execute all "post" hooks for "name" synchronously
+ * @param {String} name The hook name to execute
+ * @param {*} context Overwrite the "this" for the hook
+ * @param {Array|Function} args Apply custom arguments to the hook
+ * @returns {Array} The used arguments
+ */
 Kareem.prototype.execPostSync = function(name, context, args) {
   const posts = this._posts.get(name) || [];
   const numPosts = posts.length;
@@ -275,18 +314,24 @@ Kareem.prototype.execPostSync = function(name, context, args) {
   return args;
 };
 
+/**
+ * Create a synchronous wrapper for "fn"
+ * @param {String} name The name of the hook
+ * @param {Function} fn The function to wrap
+ * @returns {Function} The wrapped function
+ */
 Kareem.prototype.createWrapperSync = function(name, fn) {
-  var kareem = this;
+  const _this = this;
   return function syncWrapper() {
-    kareem.execPreSync(name, this, arguments);
+    _this.execPreSync(name, this, arguments);
 
-    var toReturn = fn.apply(this, arguments);
+    const toReturn = fn.apply(this, arguments);
 
-    const result = kareem.execPostSync(name, this, [toReturn]);
+    const result = _this.execPostSync(name, this, [toReturn]);
 
     return result[0];
   };
-}
+};
 
 function _handleWrapError(instance, error, name, context, args, options, callback) {
   if (options.useErrorHandlers) {
@@ -298,9 +343,19 @@ function _handleWrapError(instance, error, name, context, args, options, callbac
   }
 }
 
+/**
+ * Executes pre hooks, followed by the wrapped function, followed by post hooks.
+ * @param {String} name The name of the hook
+ * @param {Function} fn The function for the hook
+ * @param {*} context Overwrite the "this" for the hook
+ * @param {Array} args Apply custom arguments to the hook
+ * @param {Object} [options]
+ * @param {Boolean} [options.checkForPromise]
+ * @returns {void}
+ */
 Kareem.prototype.wrap = function(name, fn, context, args, options) {
   const lastArg = (args.length > 0 ? args[args.length - 1] : null);
-  let argsWithoutCb = Array.from(args);
+  const argsWithoutCb = Array.from(args);
   typeof lastArg === 'function' && argsWithoutCb.pop();
   const _this = this;
 
@@ -311,7 +366,7 @@ Kareem.prototype.wrap = function(name, fn, context, args, options) {
     if (error && !(error instanceof Kareem.skipWrappedFunction)) {
       const numCallbackParams = options.numCallbackParams || 0;
       const errorArgs = options.contextParameter ? [context] : [];
-      for (var i = errorArgs.length; i < numCallbackParams; ++i) {
+      for (let i = errorArgs.length; i < numCallbackParams; ++i) {
         errorArgs.push(null);
       }
       return _handleWrapError(_this, error, name, context, errorArgs,
@@ -365,13 +420,18 @@ Kareem.prototype.wrap = function(name, fn, context, args, options) {
           }
           arguments[0]
             ? lastArg(arguments[0])
-            : lastArg.apply(context, arguments)
+            : lastArg.apply(context, arguments);
         });
       }
     }
   });
 };
 
+/**
+ * Filter current instance for something specific and return the filtered clone
+ * @param {Function} fn The filter function
+ * @returns {Kareem} The cloned and filtered instance
+ */
 Kareem.prototype.filter = function(fn) {
   const clone = this.clone();
 
@@ -408,12 +468,25 @@ Kareem.prototype.filter = function(fn) {
   return clone;
 };
 
+/**
+ * Check for a "name" to exist either in pre or post hooks
+ * @param {String} name The name of the hook
+ * @returns {Boolean} "true" if found, "false" otherwise
+ */
 Kareem.prototype.hasHooks = function(name) {
   return this._pres.has(name) || this._posts.has(name);
 };
 
+/**
+ * Create a Wrapper for "fn" on "name" and return the wrapped function
+ * @param {String} name The name of the hook
+ * @param {Function} fn The function to wrap
+ * @param {*} context Overwrite the "this" for the hook
+ * @param {Object} [options]
+ * @returns {Function} The wrapped function
+ */
 Kareem.prototype.createWrapper = function(name, fn, context, options) {
-  var _this = this;
+  const _this = this;
   if (!this.hasHooks(name)) {
     // Fast path: if there's no hooks for this function, just return the
     // function wrapped in a nextTick()
@@ -422,11 +495,20 @@ Kareem.prototype.createWrapper = function(name, fn, context, options) {
     };
   }
   return function() {
-    var _context = context || this;
+    const _context = context || this;
     _this.wrap(name, fn, _context, Array.from(arguments), options);
   };
 };
 
+/**
+ * Register a new hook for "pre"
+ * @param {String} name The name of the hook
+ * @param {Boolean} [isAsync]
+ * @param {Function} fn The function to register for "name"
+ * @param {never} error Unused
+ * @param {Boolean} [unshift] Wheter to "push" or to "unshift" the new hook
+ * @returns {Kareem}
+ */
 Kareem.prototype.pre = function(name, isAsync, fn, error, unshift) {
   let options = {};
   if (typeof isAsync === 'object' && isAsync !== null) {
@@ -458,8 +540,16 @@ Kareem.prototype.pre = function(name, isAsync, fn, error, unshift) {
   return this;
 };
 
+/**
+ * Register a new hook for "post"
+ * @param {String} name The name of the hook
+ * @param {Object} [options]
+ * @param {Function} fn The function to register for "name"
+ * @param {Boolean} [unshift] Wheter to "push" or to "unshift" the new hook
+ * @returns {Kareem}
+ */
 Kareem.prototype.post = function(name, options, fn, unshift) {
-  const hooks = this._posts.get(name) || [];
+  const posts = this._posts.get(name) || [];
 
   if (typeof options === 'function') {
     unshift = !!fn;
@@ -472,34 +562,44 @@ Kareem.prototype.post = function(name, options, fn, unshift) {
   }
 
   if (unshift) {
-    hooks.unshift(Object.assign({}, options, { fn: fn }));
+    posts.unshift(Object.assign({}, options, { fn: fn }));
   } else {
-    hooks.push(Object.assign({}, options, { fn: fn }));
+    posts.push(Object.assign({}, options, { fn: fn }));
   }
-  this._posts.set(name, hooks);
+  this._posts.set(name, posts);
   return this;
 };
 
+/**
+ * Clone the current instance
+ * @returns {Kareem} The cloned instance
+ */
 Kareem.prototype.clone = function() {
   const n = new Kareem();
 
-  for (let key of this._pres.keys()) {
+  for (const key of this._pres.keys()) {
     const clone = this._pres.get(key).slice();
     clone.numAsync = this._pres.get(key).numAsync;
     n._pres.set(key, clone);
   }
-  for (let key of this._posts.keys()) {
+  for (const key of this._posts.keys()) {
     n._posts.set(key, this._posts.get(key).slice());
   }
 
   return n;
 };
 
+/**
+ * Merge "other" into self or "clone"
+ * @param {Kareem} other The instance to merge with
+ * @param {Kareem} [clone] The instance to merge onto (if not defined, using "this")
+ * @returns {Kareem} The merged instance
+ */
 Kareem.prototype.merge = function(other, clone) {
   clone = arguments.length === 1 ? true : clone;
-  var ret = clone ? this.clone() : this;
+  const ret = clone ? this.clone() : this;
 
-  for (let key of other._pres.keys()) {
+  for (const key of other._pres.keys()) {
     const sourcePres = ret._pres.get(key) || [];
     const deduplicated = other._pres.get(key).
       // Deduplicate based on `fn`
@@ -509,7 +609,7 @@ Kareem.prototype.merge = function(other, clone) {
     combined.numAsync += deduplicated.filter(p => p.isAsync).length;
     ret._pres.set(key, combined);
   }
-  for (let key of other._posts.keys()) {
+  for (const key of other._posts.keys()) {
     const sourcePosts = ret._posts.get(key) || [];
     const deduplicated = other._posts.get(key).
       filter(p => sourcePosts.indexOf(p) === -1);
@@ -537,8 +637,8 @@ function isPromiseLike(v) {
 }
 
 function decorateNextFn(fn) {
-  var called = false;
-  var _this = this;
+  let called = false;
+  const _this = this;
   return function() {
     // Ensure this function can only be called once
     if (called) {
@@ -551,8 +651,15 @@ function decorateNextFn(fn) {
   };
 }
 
-const nextTick = typeof process === 'object' && process !== null && process.nextTick || function nextTick(cb) { 
-  setTimeout(cb, 0); 
+const nextTick = typeof process === 'object' && process !== null && process.nextTick || function nextTick(cb) {
+  setTimeout(cb, 0);
+};
+
+function isErrorHandlingMiddleware(post, numArgs) {
+  if (post.errorHandler) {
+    return true;
+  }
+  return post.fn.length === numArgs + 2;
 }
 
 module.exports = Kareem;

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "kareem",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Next-generation take on pre/post function hooks",
   "main": "index.js",
   "scripts": {
+    "lint": "eslint .",
     "test": "mocha ./test/*",
-    "test-travis": "nyc mocha ./test/*"
+    "test-coverage": "nyc --reporter lcov mocha ./test/*",
+    "docs": "node ./docs.js"
   },
   "repository": {
     "type": "git",
@@ -13,10 +15,17 @@
   },
   "devDependencies": {
     "acquit": "1.x",
-    "acquit-ignore": "0.1.x",
+    "acquit-ignore": "0.2.x",
+    "eslint": "8.20.0",
     "mocha": "9.2.0",
     "nyc": "15.1.0"
   },
   "author": "Valeri Karpov <val@karpov.io>",
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "files": [
+    "index.js"
+  ],
+  "engines": {
+    "node": ">=12.0.0"
+  }
 }

package/.github/workflows/test.yml

@@ -1,30 +0,0 @@
-name: Test
-on:
-  pull_request:
-  push:
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        node: [12, 14, 16, 18]
-        os: [ubuntu-20.04]
-        include:
-          - os: ubuntu-20.04
-            mongo-os: ubuntu2004
-    name: Node ${{ matrix.node }}
-    steps:
-      - uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # v3
-
-      - name: Setup node
-        uses: actions/setup-node@5b52f097d36d4b0b2f94ed6de710023fbb8b2236 # v3.1.0
-        with:
-          node-version: ${{ matrix.node }}
-
-      - run: npm install
-
-      - run: npm test

package/.travis.yml

@@ -1,12 +0,0 @@
-language: node_js
-node_js:
-  - "12"
-  - "10"
-  - "9"
-  - "8"
-  - "7"
-  - "6"
-  - "5"
-  - "4"
-script: "npm run-script test-travis"
-after_script: "npm install coveralls@2.10.0 && cat ./coverage/lcov.info | coveralls"