⚡ powercost

Convert electricity consumption → actual cost — spot energy, grid fees, energy tax and VAT, itemised. A tiny, dependency-free SDK that runs in the browser or Node, with tariff data as lazy-loaded packs. Sweden-first; calibrated to real tariffs.

▶ Playground · 📖 Docs

· zero runtime dependencies · ~9 kB

Install

npm i powercost

Or use it with no build step on a static site:

<script type="module">
  import { price } from 'https://esm.sh/powercost';
</script>

Quick start

import { price } from 'powercost';
import { swedenDb } from 'powercost/data/se';   // lazy data pack

const cost = await price({
  consumption: [
    { start: '2026-04-15T18:00:00+02:00', end: '2026-04-15T18:15:00+02:00', kwh: 0.40 },
  ],
  config: {
    zone: 'SE3',
    providerPlanId: 'tibber-kvartspris',
    gridOperatorId: 'vattenfall-e4-25a',
    reportCurrency: 'USD',
  },
  db: swedenDb,
  live: true,                    // fetch spot + FX live, client-side
});

cost.total.format();             // "1.23 SEK"
cost.marginalInclVat.format();   // "0.92 SEK"  — what these kWh actually cost
cost.presentation.total;         // { amount: 0.13, currency: 'USD' }

The cost model

A Swedish bill is two companies plus the state, modelled as composable tariff components:

| Piece | Billed by | What it is | |---|---|---| | Spot energy | Provider (elhandel) | Day-ahead market price per bidding zone, 15-min | | Provider påslag / fees | Provider | Markup + variable costs + monthly fee | | Grid transfer + fixed | Grid operator (elnät) | Per-kWh transfer + fixed subscription per fuse | | Energy tax | State, via the grid invoice | Energiskatt per kWh | | VAT (moms) | State | 25% on top of everything — including the tax |

Every response separates marginalInclVat (the per-kWh cost that scales with use — what load-shifting / net-profit decisions need) from total (the full bill incl. amortised fixed fees). Money is exact integer arithmetic, never floats.

Live data, serverless

With live: true, prices are fetched directly from the browser — no proxy, no backend:

• Spot from elprisetjustnu (CORS-open)
• FX from the ECB Data Portal API (CORS-open)

Prefer your own prices? Pass spot / fx sources instead of live.

Data packs

Tariff data is separate from the engine and loaded on demand:

const { swedenDb } = await import('powercost/data/se');

A pack is just a module exporting a TariffDb built from the component grammar (fixed, per_kwh incl. spot-linked, tiered, demand, vat) — all temporal. New countries / operators are new packs — PRs welcome.

Develop

npm test           # engine + clients (offline)
npm run build      # → dist/ (esbuild ESM + .d.ts types)
npm run example    # worked example (Node, via tsx)
npm run build:site # build + copy into public/dist for the static site

The site (public/) deploys to GitHub Pages via .github/workflows/pages.yml.

License

MIT © warting