feat(hooks): decouple hooks from toolchain

opbi · May 5, 2020 · b9528ff · b9528ff
1 parent 7b6311b
commit b9528ff
Show file tree

Hide file tree

Showing 40 changed files with 2,864 additions and 1,090 deletions.
diff --git a/README.md b/README.md
@@ -41,12 +41,198 @@
 
 ### Purpose
 
+Turn scattered repeatitive control mechanism or observability code from interwined blocks to more readable, reusable, testable ones.
+
+By abstract out common control mechanism and observability code into well-tested, composable hooks, it can effectively half the verboseness of your code. This helps to achieve codebase that is self-explanatory of its business logic and technical behaviour. Additionally, conditionally turning certain mechanism off makes testing the code very handy.
+
+Let's measure the effect in LOC (Line of Code) and LOI (Level of Indent) by an example of cancelling user subscription on server-side with some minimal error handling of retry and restore. The simplification effect will be magnified with increasing complexity of the control mechanism.
+
+> Using @opbi/hooks Hooks: LOC = 16, LOI = 2
+```js
+// import userProfileApi from './api/user-profile';
+// import subscriptionApi from './api/subscription';
+// import restoreSubscription from './restore-subscription'
+
+import { errorRetry, errorHandler, chain } from '@opbi/hooks';
+
+const retryOnTimeoutError = errorRetry({
+  condition: e => e.type === 'TimeoutError'
+});
+
+const restoreOnServerError = errorHandler({
+  condition: e => e.code > 500,
+  handler: (e, p, m, c) => restoreSubscription(p, m, c),
+});
+
+const cancelSubscription = async ({ userId }, meta, context) => {
+  const { subscriptionId } = await chain(
+    retryOnTimeoutError
+  )(userProfileApi.getSubscription)( { userId }, meta, context );
+
+  await chain(
+    errorRetry(), restoreOnServerError,
+  )(subscriptionApi.cancel)({ subscriptionId }, meta, context);
+};
+
+// export default cancelSubscription;
+```
+
+> Vanilla JavaScript: LOC = 32, LOI = 4
+```js
+// import userProfileApi from './api/user-profile';
+// import subscriptionApi from './api/subscription';
+// import restoreSubscription from './restore-subscription'
+
+const cancelSubscription = async({ userId }, meta, context) => {
+  let subscriptionId;
+
+  try {
+    const result = await userProfileApi.getSubscription({ userId }, meta, context);
+    subscriptionId = result.subscriptionId;
+  } catch (e) {
+    if(e.type === 'TimeoutError'){
+      const result = await userProfileApi.getSubscription({ userId }, meta, context);
+      subscriptionId = result.subscriptionId;
+    }
+    throw e;
+  }
+
+  try {
+    try {
+      await subscriptionApi.cancel({ subscriptionId }, meta, context);
+    } catch (e) {
+      if(e.code > 500) {
+        await restoreSubscription({ subscriptionId }, meta, context);
+      }
+      throw e;
+    }
+  } catch (e) {
+    try {
+      return await subscriptionApi.cancel({ subscriptionId }, meta, context);
+    } catch (e) {
+      if(e.code > 500) {
+        await restoreSubscription({ subscriptionId }, meta, context);
+      }
+      throw e;
+    }
+  }
+}
+
+// export default cancelSubscription;
+```
+---
 ### How to Use
 
 #### Install
 ```shell
-yarn add @opbi/hooks (-D)
+yarn add @opbi/hooks
+```
+
+#### Standard Function
+
+Standardisation of function signature is powerful that it creates predictable value flows throughout the functions and hooks chain, making functions more friendly to meta-programming. Moreover, it is also now a best-practice to use object destruct assign for key named parameters.
+
+Via exploration and the development of hooks, we set a function signature standard to define the order of different kinds of variables as expected and we call it `action function`:
+```js
+/**
+ * The standard function signature.
+ * @param  {object} param   - parameters input to the function
+ * @param  {object} meta    - metadata tagged for function observability(logger, metrics), e.g. requestId
+ * @param  {object} context - contextual callable instances or unrecorded metadata, e.g. logger, req
+ */
+function (param, meta, context) {}
 ```
 
+#### Config the Hooks
+
+All the hooks in @opbi/hooks are configurable with possible default settings.
+
+In the [cancelSubscription](#purpose) example, *errorRetry()* is using its default settings, while *restoreOnServerError* is configured *errorHandler*. Descriptive names of hook configurations help to make the behaviour very self-explanatory. Patterns composed of configured hooks can certainly be reused.
+
+```js
+const restoreOnServerError = errorHandler({
+  condition: e => e.code > 500,
+  handler: (e, p, m, c) => restoreSubscription(p, m, c),
+});
+```
+
+#### Chain the Hooks
+
+> "The order of the hooks in the chain matters."
+
+<a href="https://innolitics.com/articles/javascript-decorators-for-promise-returning-functions/">
+  <img alt="decorators" width="640" src="https://innolitics.com/img/javascript-decorators.png"/>
+</a>
+
+Under the hood, the hooks are implemented in the [decorators](https://innolitics.com/articles/javascript-decorators-for-promise-returning-functions) pattern. The pre-hooks, action function, after-hooks/error-hooks are invoked in a pattern as illustrated above. In the [cancelSubscription](#purpose) example, as *errorRetry(), restoreOnServerError* are all error hooks, *restoreOnServerError* will be invoked first before *errorRetry* is invoked.
+
+---
+#### Ecosystem
+
+Currently available hooks:
+
+* [errorCounter](https://github.com/opbi/hooks/blob/master/src/hooks/error-counter.js)
+* [errorHandler](https://github.com/opbi/hooks/blob/master/src/hooks/error-handler.js)
+* [errorMute](https://github.com/opbi/hooks/blob/master/src/hooks/error-mute.js)
+* [errorRetry](https://github.com/opbi/hooks/blob/master/src/hooks/error-retry.js)
+* [errorTag](https://github.com/opbi/hooks/blob/master/src/hooks/error-tag.js)
+* [eventLogger](https://github.com/opbi/hooks/blob/master/src/hooks/event-logger.js)
+* [eventPoller](https://github.com/opbi/hooks/blob/master/src/hooks/event-poller.js)
+* [eventTimer](https://github.com/opbi/hooks/blob/master/src/hooks/event-timer.js)
+
+> Hooks are named in a convention to reveal where and how it works `[hook point][what it is/does]`, e.g. *errorCounter, eventLogger*. Hook points are named `before, after, error` and `event` (multiple points).
+
+
+#### Extension
+
+You can easily create more standardised hooks with [addHooks](https://github.com/opbi/hooks/blob/master/src/hooks/helpers/add-hooks.js) helper. Open source them aligning with the above standards via pull requests or individual packages are highly encouraged.
+
+---
+#### Decorators
+Hooks here are essentially configurable decorators, while different in the way of usage. We found the name 'hooks' better describe the motion that they are attached to functions not modifying their original data process flow (keep it pure). Decorators are coupled with class methods, while hooks help to decouple definition and control, attaching to any function on demand.
+
+```js
+//decorators
+class SubscriptionAPI:
+  //...
+  @errorRetry()
+  cancel: () => {}
+```
+```js
+//hooks
+  chain(
+    errorRetry()
+  )(subscriptionApi.cancel)
+```
+#### Adaptors
+To make plugging in @opbi/hooks hooks to existing systems easier, adaptors are introduced to bridge different function signature standards.
+```js
+const handler = chain(
+  adaptorExpress(),
+  errorRetry()
+)(subscriptionApi.cancel)
+
+handler(req, res, next);
+```
+#### Refactor
+To help adopting the hooks by testing them out with minimal refactor on non-standard signature functions, there's an unreleased [adaptor](https://github.com/opbi/hooks/blob/adapator-non-standard/src/hooks/adaptors/nonstandard.js) to bridge the function signatures. It is not recommended to use this for anything but trying the hooks out, especially observability hooks are not utilised this way.
+
+#### Reducers
+Integration with Redux is TBC.
+
+#### Pipe Operator
+We are excited to see how pipe operator will be rolled out and hooks can be elegantly plugged in.
+```js
+const cancelSubscription = ({ userId }, meta, context)
+  |> chain(timeoutErrorRetry)(userProfileApi.getSubscription)
+  |> chain(restoreOnServerError, timeoutErrorRetry)(subscriptionApi.cancel);
+```
+---
+### Inspiration
+* [Financial-Times/n-express-monitor](https://github.com/Financial-Times/n-express-monitor)
+* [recompose](https://github.com/acdlite/recompose)
+* [ramda](https://github.com/ramda/ramda)
+* [funcy](https://github.com/suor/funcy/)
+---
 ### License
 [MIT](License)
diff --git a/package.json b/package.json
@@ -10,38 +10,42 @@
   },
   "devDependencies": {
     "@babel/cli": "^7.8.4",
-    "@babel/core": "^7.8.7",
-    "@babel/plugin-proposal-object-rest-spread": "^7.8.3",
-    "@babel/preset-env": "^7.8.7",
-    "@babel/preset-typescript": "^7.8.3",
+    "@babel/core": "^7.9.6",
+    "@babel/plugin-proposal-object-rest-spread": "^7.9.6",
+    "@babel/preset-env": "^7.9.6",
+    "@babel/preset-typescript": "^7.9.0",
     "@commitlint/cli": "^8.3.5",
     "@commitlint/config-conventional": "^8.3.4",
     "@commitlint/prompt-cli": "^8.3.5",
     "babel-core": "^7.0.0-bridge.0",
     "babel-eslint": "^10.1.0",
-    "babel-jest": "^25.1.0",
+    "babel-jest": "^26.0.1",
     "babel-plugin-module-resolver": "^4.0.0",
-    "coveralls": "^3.0.9",
-    "documentation": "^12.1.4",
+    "coveralls": "^3.1.0",
+    "documentation": "^12.3.0",
     "eslint": "^6.8.0",
-    "eslint-config-airbnb-base": "^14.0.0",
-    "eslint-config-prettier": "^6.10.0",
+    "eslint-config-airbnb-base": "^14.1.0",
+    "eslint-config-prettier": "^6.11.0",
     "eslint-config-standard-jsdoc": "^9.3.0",
     "eslint-import-resolver-node": "^0.3.3",
-    "eslint-plugin-import": "^2.18.2",
-    "eslint-plugin-jest": "^23.8.1",
-    "eslint-plugin-jsdoc": "^22.0.0",
-    "eslint-plugin-prettier": "^3.1.2",
-    "eslint_d": "^8.1.0",
+    "eslint-plugin-import": "^2.20.2",
+    "eslint-plugin-jest": "^23.9.0",
+    "eslint-plugin-jsdoc": "^24.0.2",
+    "eslint-plugin-prettier": "^3.1.3",
+    "eslint_d": "^8.1.1",
     "gh-pages": "^2.2.0",
-    "husky": "^4.2.3",
-    "jest": "^25.1.0",
-    "prettier": "^1.19.1",
-    "semantic-release": "^17.0.4",
+    "husky": "^4.2.5",
+    "jest": "^26.0.1",
+    "prettier": "^2.0.5",
+    "semantic-release": "^17.0.7",
     "typescript": "^3.8.3"
   },
   "engines": {
     "node": ">=8.16"
   },
-  "main": "dist/index.js"
+  "main": "dist/index.js",
+  "dependencies": {
+    "compose-function": "^3.0.3",
+    "moment": "^2.25.3"
+  }
 }
diff --git a/src/__tests__/__snapshots__/index.js.snap b/src/__tests__/__snapshots__/index.js.snap
diff --git a/src/__tests__/index.js b/src/__tests__/index.js
diff --git a/src/constants.js b/src/constants.js
diff --git a/src/decorator.js b/src/decorator.js
diff --git a/src/hooks/__tests__/__snapshots__/event-log.js.snap b/src/hooks/__tests__/__snapshots__/event-log.js.snap
@@ -0,0 +1,78 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`eventLogger log chained events from upper level function call 1`] = `
+Array [
+  Array [
+    Object {
+      "event": "upper.original",
+    },
+    "upper.original",
+  ],
+  Array [
+    Object {
+      "event": "upper",
+    },
+    "upper",
+  ],
+]
+`;
+
+exports[`eventLogger log the error event when input function fails 1`] = `Array []`;
+
+exports[`eventLogger log the error event when input function fails 2`] = `
+Array [
+  Array [
+    Object {
+      "error": Object {
+        "message": "error",
+      },
+      "event": "original",
+    },
+    "error",
+  ],
+]
+`;
+
+exports[`eventLogger log the parsed error when errorParse set 1`] = `Array []`;
+
+exports[`eventLogger log the parsed error when errorParse set 2`] = `
+Array [
+  Array [
+    Object {
+      "error": Object {
+        "message": "error",
+        "stack": "Error: error
+    at ",
+      },
+      "event": "original",
+    },
+    "error",
+  ],
+]
+`;
+
+exports[`eventLogger log the success event with param when enabled 1`] = `
+Array [
+  Array [
+    Object {
+      "event": "original",
+      "param": Object {
+        "text": "yes",
+      },
+    },
+    "original",
+  ],
+]
+`;
+
+exports[`eventLogger log the success event with result when enabled 1`] = `
+Array [
+  Array [
+    Object {
+      "event": "original",
+      "result": "yes",
+    },
+    "original",
+  ],
+]
+`;