@toolsnap/percentage-utils

A lightweight, zero-dependency utility library for common percentage calculations in JavaScript and Node.js.

Installation

npm install @toolsnap/percentage-utils

Why This Library?

Percentage calculations are everywhere — discounts, tax rates, growth metrics, progress bars, financial analysis — yet developers frequently implement them inline with subtle bugs (division by zero, floating-point drift, sign errors). This package provides three battle-tested functions that handle edge cases and let you control precision.

For an interactive online calculator, check out the Percentage Calculator on Risetop — it covers all the same operations with a clean UI and supports batch calculations.

API

calculatePercentage(part, total, decimals = 2)

Returns what percentage part is of total.

const { calculatePercentage } = require('@toolsnap/percentage-utils');

calculatePercentage(25, 200);      // 12.5
calculatePercentage(3, 7, 4);      // 42.8571
calculatePercentage(0, 100);       // 0

Throws if total is zero or either argument is non-finite.

percentageChange(oldValue, newValue, decimals = 2)

Returns the percentage change from oldValue to newValue. Positive means increase, negative means decrease.

const { percentageChange } = require('@toolsnap/percentage-utils');

percentageChange(100, 120);        // 20
percentageChange(50, 25);          // -50
percentageChange(200, 200);        // 0
percentageChange(30, 45, 1);       // 50

Throws if oldValue is zero.

percentageOf(percentage, total, decimals = 2)

Returns what percentage% of total is.

const { percentageOf } = require('@toolsnap/percentage-utils');

percentageOf(25, 200);             // 50
percentageOf(15.5, 1000, 1);       // 155
percentageOf(0, 500);              // 0
percentageOf(100, 99);             // 99

Real-World Examples

E-commerce Discount Calculation

const { calculatePercentage } = require('@toolsnap/percentage-utils');

const originalPrice = 89.99;
const salePrice = 59.99;
const discount = calculatePercentage(originalPrice - salePrice, originalPrice);

console.log(`You save ${discount}%!`);
// You save 33.34%!

Revenue Growth Report

const { percentageChange, percentageOf } = require('@toolsnap/percentage-utils');

const q1 = 45000;
const q2 = 58000;
const growth = percentageChange(q1, q2);
const q2Target = percentageOf(15, q1); // 15% growth target

console.log(`Q2 grew ${growth}% vs target of 15%`);
console.log(`Target was $${q2Target} — actual $${q2}`);

Progress Bar

const { calculatePercentage } = require('@toolsnap/percentage-utils');

function renderProgress(completed, total) {
  const pct = calculatePercentage(completed, total, 1);
  const bar = '█'.repeat(Math.round(pct / 5)) + '░'.repeat(20 - Math.round(pct / 5));
  return `[${bar}] ${pct}%`;
}

console.log(renderProgress(73, 100));
// [█████████████░░░░░░] 73%

Browser Usage

This is a CommonJS module. For browser use, bundle with webpack, esbuild, or use the global export pattern:

<script>
// After bundling
const { calculatePercentage } = window.percentageUtils;
</script>

Related Tools

• Percentage Calculator — Free online percentage calculator with step-by-step solutions
• Math Tools Collection — More free calculators and converters

License

MIT