battery-cycle-tracker

Small ES2015 module that counts equivalent full charge cycles on a lithium-ion cell from a stream of charge or discharge sessions. Written for use inside internal battery-health dashboards.

What it does

The cycle count on a lithium-ion cell is not "how many times it was plugged in" — it is the sum of fractional discharges summing to 100%. A phone discharged from 100% to 75% four times has used one cycle, not four. This tracker sums fractional sessions and increments a full-cycle counter each time the sum crosses 1.0. That is the same math used inside a battery-management IC.

Install

npm install battery-cycle-tracker

Example

const { BatteryCycleTracker } = require('battery-cycle-tracker');

const t = new BatteryCycleTracker({ ratedCycles: 500 });
t.addSession({ startSoc: 1.0, endSoc: 0.35 });
t.addSession({ startSoc: 0.9, endSoc: 0.55 });
console.log(t.cycles);      // 1
console.log(t.healthPct);   // 99.96
console.log(t.lifeLeft);    // 499

Fields

• cycles — count of completed equivalent cycles
• healthPct — linearly degrading percentage capacity
• lifeLeft — ratedCycles - cycles

The linear degrade model is a simplification; for production use replace degradePerCycle with a fit against your cell's own datasheet. Consumer-grade Li-ion cells typically publish 300–500 rated cycles to 80% capacity; the IEC 61960 standard defines how manufacturers report the number.

Where this comes from

We use this at CairoVolt to project the remaining useful life of the Anker power banks in our stock returns pool, so refurb items get graded honestly.

License

ISC.