Reusable Composition of Functional Hooks for Error Handling, Log, Metrics and Mo...

toolchain

:snowboarder: the swiss knife to lift business logic to be production ready

Purpose

There're a large amount of semi-automatable codes in most production codebases, especially around input validation/null check, error/exception handling, observability anchors(log, metrics, tracing) and various other elements to thread functions together to achieve business goals stably. All those are essential for production code, while they are slowly corrupting the readability/maintability of the codebase, incuring huge communication cost between teams due to a lack of common standards. Fortunately, without AI, it is still possible to automate some of those common programming actions with a standard.

With the power of function composition in Javascript, it becomes very simple to modularize those control mechanisms in the form of well-tested reusable decorators. This makes the core business logic functions extremely conscise and easy to read/test/migrate.

How to Use

Install

yarn add @opbi/toolchain

Concepts & Conventions

A few concepts and conventions are introduced to make a standard for those decorators to work well with each other. We'll call a core logic function action , and it comes with a standard function signature of (param<object>, meta<object>, context<object>) . param is the arg of the input values to the core logic action, and with object destruct assigning it is a best-practice to make function calls. meta is the arg to be used primarily by logger, metrics clients to anchor meta-data of the function calls to provide the background where and how this call happened. context is the arg where you append instances of e.g. logger, metrics and other functions down to the action calling chain.

The decorators come with a standard config step decorator(config)(action) , and are named in the format of [hook point]-[client/behaviour] , e.g. errorCounter, eventLogger .

There are generally three hook points: before, after, error , and when a decorator is hooked into both after and error, we call it event .

Compose & Reuse

Say we're going to build a simple module to parse and upload a list of json files to a database. Using the decorators, we can write minimum code in json-file-reader.js and db-batch-write.js just to cover the essential logics and get them tested. Then assemble those step actions in the main module.

//json-to-db.js
import {
  errorCounter,
  errorMute,
  errorRetry,
  eventLogger,
  eventTimer,
  recompose,
} from '@opbi/toolchain/dist/decorators';

import jsonFileReader from './json-file-reader';
import dbBatchWrite from './db-batch-write';

const actionErrorLessThan = number =>
  (e, p, m, { metrics }, action) =>
    metrics &&
    metrics.find({ action, type: 'error' }).value() < number;

const labelBatchSize = (p, m, c) => ({ batchSize: c.batch.size });

const jsonToDb = async ({ fileList }, meta, context) => {
  const data = await recompose(
    errorMute({ condition: actionErrorLessThan(20) }),
    eventTimer(),
    eventLogger(),
    errorCounter(),
  )(jsonFileReader)({ fileList }, meta, context);

  await recompose(
    eventTimer({ parseLabel: labelBatchSize }),
    errorRetry(),
    eventLogger(),
    errorCounter(),
    errorMute({ condition: e => e.code === 11000}),
  )(dbBatchWrite)({ data }, meta, context);
};

export default jsonToDb;

The order of the decorators in the recompose chain matters.

The afterHooks and errorHooks are from bottom to top, while the beforeHooks will be executed from top to bottom and meta/context would be passed from top to bottom.

In the 1st recompose, because of the errorMute on the top position, before the number of errors counted by errorCounter reaches 20, any error populated from jsonFileReader would be muted so that jsonToDb process is not stopped.

In the 2nd recompose above error with code 11000 would be muted and will not be populated to errorCounter , eventLogger , errorRetry , eventTimer . The eventTimer at the very top would time in the whole duration of execution even if multiple retries happened.

You can see from above that, we can actually make decorator config function with names to make the behaviour highly descriptive. This makes it even possible to package and reuse function control patterns, which is a very efficient way to leverage the power of meta-programming.

//patterns/observerable-retry.js
import {
  errorCounter,
  errorRetry,
  eventLogger,
  eventTimer,
  recompose,
} from '@opbi/toolchain/dist/decorators';

export default recompose(
  eventTimer(),
  errorRetry(),
  eventLogger(),
  errorCounter(),
);

Error Handling

Furthermore, this makes error handling very handy combing custom hanlders with universal handler.

//cancel-subscription.js
import {
  errorHandler,
  errorRetry,
  recompose,
} from '@opbi/toolchain/dist/decorators';

import userProfileApi from './api/user-profile';
import subscriptionApi from './api/subscription';

import universalErrorPage from './handler/error-page';

const errorForbiddenHandler = {
  condition: e => e.code === 403,
  handler: (e, p, m, { res }) => res.status(403).redirect('/');
}

const timeoutErrorRetry = errorRetry({
  condition: e => e.type === 'TimeoutError'
});

const cancelSubscription = async ({ userId }, meta, context) => {
  const { subscriptionId } = await recompose(
    errorHandler({ condition: e => e.code !== 403, handler: universalErrorPage })
    errorHandler(errorForbiddenHandler),
    timeoutErrorRetry
  )(userProfileApi.getSubscription)(
    { userId }, meta, context
  );

  await recompose(
    errorHandler({
      condition: e => e.code > 500,
      handler: (e, { subscriptionId }, m, c) => subscriptionApi.restore({ subscriptionId }, m, c),
    }),
    timeoutErrorRetry,
  )(subscriptionApi.cancel)({ subscriptionId }, meta, context);
};

export default cancelSubscription;

Ecosystem

Currently available decorators are as following:

• callPolling
• errorCounter
• errorHandler
• errorMute
• errorRetry
• errorTag
• eventLogger
• eventTimer

Extension

You can also create more decorators for yourself or the ecosystem with the reliable standard decorator creator(coming soon). It helps you to maintain a standard across your decorators to ensure compatibility and consistent develop experience.

License

MIT