dashboard-metric-engine

A lightweight Node.js package to compute business KPI metrics for dashboards and reporting.

Features

• Total sales and average order value
• Top-selling product and low-stock filtering
• Month-over-month growth percentage
• Profit margin percentage
• Dashboard-ready JSON output helper
• Minimal setup with CommonJS exports

Installation

npm install dashboard-metric-engine

For local development in this folder:

npm install

Usage

const {
  totalSales,
  averageOrderValue,
  topSellingProduct,
  lowStockProducts,
  growthPercentage,
  profitMargin,
  createDashboardMetrics
} = require("dashboard-metric-engine");

const orders = [
  { total: 1200, date: "2026-03-01" },
  { total: 800, date: "2026-03-10" },
  { total: 650, date: "2026-03-22" }
];

const products = [
  { name: "Starter Plan", sold: 180, stock: 14 },
  { name: "Pro Plan", sold: 260, stock: 7 },
  { name: "Enterprise Plan", sold: 95, stock: 3 }
];

console.log(totalSales(orders)); // 2650
console.log(averageOrderValue(orders)); // 883.3333333333334
console.log(topSellingProduct(products)); // { name: "Pro Plan", sold: 260, stock: 7 }
console.log(lowStockProducts(products, 10)); // [{...}, {...}]
console.log(growthPercentage(15000, 12000)); // 25
console.log(profitMargin(15000, 9800)); // 34.66666666666667

const dashboard = createDashboardMetrics(
  orders,
  products,
  15000,
  12000,
  15000,
  9800,
  10
);

console.log(JSON.stringify(dashboard, null, 2));

API

totalSales(orders)

Returns the sum of all order.total values.

averageOrderValue(orders)

Returns the average order value. If no orders are provided, returns 0.

topSellingProduct(products)

Returns the product object with the highest sold value. If list is empty, returns null.

lowStockProducts(products, threshold)

Returns products where stock < threshold.

growthPercentage(currentMonthRevenue, previousMonthRevenue)

Returns month-over-month growth percentage.

• If previous revenue is 0 and current is greater than 0, returns 100.
• If both are 0, returns 0.

profitMargin(revenue, cost)

Returns profit margin percentage using:

((revenue - cost) / revenue) * 100

If revenue is 0, returns 0.

createDashboardMetrics(...)

Returns a dashboard-ready object:

{
  "sales": {
    "total": 0,
    "averageOrderValue": 0,
    "orderCount": 0
  },
  "products": {
    "topSelling": null,
    "lowStock": []
  },
  "finance": {
    "growthPercentage": 0,
    "profitMargin": 0
  }
}

Run Demo

npm test