What is Cardio?

Cardio is a node.js module that tells you how long an async function took to run.

Use it as a wrapper around an async function and you get the execution duration and arguments provided to your function within a callback. You can now use this information to plot graphs, create models based on different arguments provided, or simply make a note somewhere for analysis.

Cardio works best in production environments where you may expect variance in execution time based on arguments provided, environmental overheads, or other real world parameters.

Cardio has zero dependencies on external libraries

This allows Cardio to stay under 15kB when packaged

Usage

Import cardio-node by running npm install cardio-node or yarn add cardio-node

Use the module in code using require:

const { cardioWrapper } = require('cardio-node');

Or using ES6 Imports:

import { cardioWrapper } from 'cardio-node';

Wrap your async function using cardioWrapper in your application. You can substitute the call to your async function with the call to what is returned by cardioWrapper:

const countSheep = async (arg1, arg2) => {
  // ...perform elaborate sheep counting here
  return arg1 + arg2;
};

const countSheepWithCardio = cardioWrapper(
  'count-sheep',
  countSheep,
  (cardioName, invocation, args) => {
    // You have args here if you want access to what was passed to countSheep
    const durationRounded = new Number(invocation.duration).toPrecision(2);
    console.log(
      `Function registered as ${cardioName} took ${durationRounded} milliseconds to run`
    );
  }
);

(async () => {
  const numberOfSheep = await countSheepWithCardio(4, 5);
  console.log(`Counted ${numberOfSheep} sheep in total`);
})();

Output:

Function registered as count-sheep took 0.073 milliseconds to run
Counted 9 sheep in total

Take a look at the code for a sample application for a full fledged example of how you can use cardio-node.

API

The cardioWrapper method takes in the following arguments:

| Argument | Type | Description | | ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- | | cardioName | string | A name for that function so that Cardio and you can track it | | functionToMeasure | async function or Promise | The function that you want to pass to Cardio to measure and track | | cardioCallback | function | A callback with the measurements recorded by Cardio after your function has finished running |

cardioCallback gives you three arguments:

| Argument | Type | Description | | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | | cardioName | string | The string you passed to cardioWrapper() for the function that has finished running | | invocation | Object | The object created by Cardio containing the metrics or measurements recorded | | args | Array | The arguments passed to your function for the current invocation. Useful for comparing invocations for pure functions |

invocation object has the following fields:

| Field | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------ | | duration | number | Number of milliseconds taken for execution. This number is highly precise and might need rounding/truncation | | applicationError | boolean | Indicates whether an error was encountered in the execution of the function |

Inspiration

I was on vacation with a few friends and we found the gym closed in our hotel due to covid. It was 37C outside so going for a run was out of the question. Discussions around not getting any cardio done somehow eventually mixed with discussions about code.

Shoutout to @tallpants and @deusv0lt for brainstorming.

Built using TSDX