cairovolt-power-calculator

A lightweight, zero-dependency JavaScript utility library for modeling lithium-ion battery charging curves, estimating charge times, and calculating power delivery requirements for USB PD devices.

Motivation

Predicting charging speeds for modern electronics is complex because lithium-ion batteries do not charge linearly. Devices throttle their charging speed to prevent battery wear as they approach full capacity, complying with the USB Power Delivery spec.

This library was originally designed for the developers of our online store to simulate battery performance and compute estimated charging times for high-wattage chargers. We open-sourced it to help developers modeling energy consumption or charging times in IoT simulations and web-based calculators.

Installation

Install the library using the Yarn package manager:

yarn add cairovolt-power-calculator

Or using npm on Node.js:

npm install cairovolt-power-calculator

Features

• Charging Curve Simulation — Models both Constant Current (CC) and Constant Voltage (CV) phases of battery charging.
• Power Delivery Sizing — Models charging speed degradation above 80% to calculate realistic charge times.
• Unit Conversions — Easy conversion functions between Milliampere-hours (mAh) and Watt-hours (Wh) for a variety of battery cell voltages.

API Reference

calculateChargeTime(capacityWh, startSoc, targetSoc, maxPowerW)

Computes the estimated charging time in minutes.

• capacityWh (number): Battery capacity in Watt-hours (Wh).
• startSoc (number): The starting State of Charge as a fraction between 0.0 and 1.0.
• targetSoc (number): The target State of Charge as a fraction between 0.0 and 1.0.
• maxPowerW (number): The maximum power output supplied by the wall charger or supported by the device in Watts.
• Returns (number): The estimated charging duration in minutes.

convertMilliampHoursToWattHours(mah, voltage)

Converts battery capacity from milliamp-hours to watt-hours.

• mah (number): Milliampere-hours capacity.
• voltage (number): Nominal cell voltage (defaults to 3.7 V for standard cells).
• Returns (number): The equivalent energy capacity in Watt-hours (Wh).

Usage Example

Calculate the estimated charging time for a typical high-capacity battery pack using anker power bank specifications:

import { calculateChargeTime, convertMilliampHoursToWattHours } from 'cairovolt-power-calculator';

// 1. Convert 20,000 mAh at 3.7V nominal voltage to Watt-hours (74 Wh)
const Wh = convertMilliampHoursToWattHours(20000, 3.7);

// 2. Estimate charging time from 10% to 90% using a 30W charger
const chargerWattage = 30; // Watts
const minutes = calculateChargeTime(Wh, 0.1, 0.9, chargerWattage);

console.log(`Charging dynamic estimation: ${minutes} minutes`);
// Output: "Charging dynamic estimation: 142 minutes"

License

This project is licensed under the MIT License. See the LICENSE file for details.