impact-equivalences

Explainable sustainability equivalencies for water, electricity, carbon, and AI usage.

Impact Equivalences helps turn abstract impact metrics into human-readable comparisons while exposing assumptions, confidence levels, methodology, and data provenance.

Impact Equivalences is an interpretation engine, not a regulatory-grade scientific calculator. AI estimates are approximate ranges and should not be treated as exact measurements.

Public-display guidance: show outputs as approximate comparisons with confidence and assumptions. Do not use tree comparisons as offset or carbon-neutrality claims.

Installation

Once published to npm:

npm install impact-equivalences

Using another package manager:

pnpm add impact-equivalences
yarn add impact-equivalences

Usage

Basic import

import impact from "impact-equivalences";

const result = impact.compare({
  domain: "water",
  value: 2500,
  unit: "m3",
});

console.log(result.equivalents[0]?.formatted);
// "1 Olympic swimming pool"

Water equivalencies

import { compare } from "impact-equivalences";

const water = compare({
  domain: "water",
  value: 10_000,
  unit: "liters",
});

console.log(water.normalized);
// { value: 10, unit: "m3" }

console.log(water.equivalents.map((item) => item.formatted));
// e.g. ["... showers", "... household days of water use", "... water bottles"]

Supported water units include m3, m³, liters, and gallons.

Electricity equivalencies

const electricity = impact.compare({
  domain: "electricity",
  value: 15,
  unit: "kWh",
});

console.log(electricity.equivalents.map((item) => item.formatted));
// e.g. ["... home days of electricity use", "... EV full charges"]

Supported electricity units include Wh, kWh, and MWh.

Carbon equivalencies

const carbon = impact.compare({
  domain: "carbon",
  value: 120,
  unit: "kgCO2e",
});

console.log(carbon.equivalents.map((item) => item.formatted));
// e.g. ["... short-haul passenger flights", "... gallons of gasoline burned"]

console.log(carbon.sources);
console.log(carbon.assumptions);

Supported carbon units include kgCO2e and tCO2e.

AI usage estimates

AI token-to-energy conversion does not have a single authoritative standard, so Impact Equivalences always returns ranges.

const ai = impact.ai.estimate({
  tokens: 10_000,
  profile: "frontier_model",
  region: "US-CA",
});

console.log(ai.electricity.wh);
// { min: 2, typical: 6, max: 15 }

console.log(ai.carbon.kgCO2e);
// approximate regional emissions range

console.log(ai.equivalents);
// electricity and carbon equivalency strings

console.log(ai.disclaimer);
console.log(ai.assumptions);
console.log(ai.sources);

You can also estimate from sessions or inference requests:

const aiFromUsage = impact.ai.estimate({
  sessions: 25,
  averageTokensPerSession: 3_000,
  inferenceRequests: 100,
  averageTokensPerRequest: 750,
  profile: "balanced_model",
  region: "US",
});

Custom regional emission factor

const customRegion = impact.ai.estimate({
  tokens: 50_000,
  profile: "frontier_model",
  region: {
    id: "CUSTOM-GRID",
    label: "Custom grid factor",
    kgCO2ePerKWh: 0.12,
    confidence: "medium",
    source: {
      id: "custom-source",
      name: "Internal grid factor dataset",
      url: "https://example.com",
      accessedAt: "2026-05-08",
    },
    assumptions: ["Average annual grid factor supplied by user."],
  },
});

Accessing provenance

Every equivalency includes its assumptions, confidence, methodology, boundary, and source.

const result = impact.compare({
  domain: "carbon",
  value: 1,
  unit: "tCO2e",
});

for (const equivalent of result.equivalents) {
  console.log(equivalent.formatted);
  console.log(equivalent.confidence);
  console.log(equivalent.methodology);
  console.log(equivalent.boundary);
  console.log(equivalent.source.name);
}

Methodological boundaries

• Water comparisons represent physical water volume only; they do not account for scarcity, source stress, quality, seasonality, or lifecycle impacts unless explicitly stated.
• Electricity comparisons represent energy consumed; emissions depend on grid location, timing, and average vs marginal factor choices.
• Carbon comparisons are simplified CO2/CO2e equivalencies; some factors are tailpipe or operational only and exclude upstream lifecycle impacts.
• AI estimates cover inference electricity and average-grid operational emissions only; they exclude training, embodied hardware emissions, user devices, networking, storage, cooling water, and lifecycle impacts unless explicitly stated.

Development

From the repository root:

npm install
npm test
npm run typecheck
npm run build
npm run test:smoke

Run the core package in watch mode:

npm run dev --workspace impact-equivalences

Release and publish from the repository root:

npm run release

This validates the package, creates and pushes the version tag, GitHub Actions creates the GitHub Release, and your local machine publishes impact-equivalences to npm. npm run publish is an alias for the same connected flow.

Contribution

Contributions are welcome.

Good first areas to improve:

• Add new equivalency datasets.
• Improve source documentation and methodology notes.
• Add regional electricity emission factors.
• Add localization/language packages under packages/*.
• Add snapshot tests for human-readable formatting.

Before opening a pull request, please run:

npm run typecheck
npm test
npm run build
npm audit

When adding or changing equivalencies, include:

• a source URL
• an accessed date
• assumptions
• confidence level
• methodology
• tests for expected behavior

Please avoid false precision. Prefer ranges and rounded values over overly specific outputs.

Licence

MIT. See LICENSE.