{"id":48003726,"url":"https://github.com/johanrd/proposal-intl-energy-units","last_synced_at":"2026-04-04T12:44:28.247Z","repository":{"id":320531703,"uuid":"1082429791","full_name":"johanrd/proposal-intl-energy-units","owner":"johanrd","description":"Draft proposal for adding the energy units `watt`, `kilowatt`, and `kilowatt-hour` to Intl.NumberFormat.","archived":false,"fork":false,"pushed_at":"2026-02-20T02:48:00.000Z","size":313,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T12:43:57.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johanrd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T08:23:25.000Z","updated_at":"2026-03-05T02:42:57.000Z","dependencies_parsed_at":"2025-10-24T10:27:13.100Z","dependency_job_id":null,"html_url":"https://github.com/johanrd/proposal-intl-energy-units","commit_stats":null,"previous_names":["johanrd/proposal-intl-energy-units"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/johanrd/proposal-intl-energy-units","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanrd%2Fproposal-intl-energy-units","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanrd%2Fproposal-intl-energy-units/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanrd%2Fproposal-intl-energy-units/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanrd%2Fproposal-intl-energy-units/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johanrd","download_url":"https://codeload.github.com/johanrd/proposal-intl-energy-units/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanrd%2Fproposal-intl-energy-units/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31400459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T12:44:27.658Z","updated_at":"2026-04-04T12:44:28.239Z","avatar_url":"https://github.com/johanrd.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proposal: Add Energy \u0026 Power Units (W, kW, kWh) to ECMA-402\n\n## Status\n\n**Stage**: 0 (seeking champion)\n\n**Champion**: TBD\n\n**Author**: Johan Røed (@johanrd)\n\n## Motivation\n\nElectric vehicles, construction equipment, and building systems report energy consumption in their APIs. An increasing number of web applications are being developed to support the electrification of transport, industry, and the built environment.\n\nIt would be helpful if ECMAScript could make developing these applications easier by providing `watt`, `kilowatt` and `kilowatt-hour` as supported units in `Intl.NumberFormat`.\n\nCurrently, developers must manually format these units.\n\n**Related issue**: https://github.com/tc39/ecma402/issues/739\n\n## Use Cases\n\n### 1. Energy consumption (kWh)\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\" width=\"380\"\u003e\u003cstrong\u003eElectricity billing \u0026 utility dashboards\u003c/strong\u003e\u003cbr\u003eSmart home monitoring, meter readings\u003c/td\u003e\n    \u003ctd width=\"180\"\u003e\u003ca href=\"https://play.google.com/store/apps/details?id=com.fortum.lmg\"\u003e\u003cimg src=\"img/1a fortum.png\" width=\"180\" alt=\"Fortum app showing 387 kWh total consumption\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\" width=\"380\"\u003e\u003cstrong\u003eEV charging sessions \u0026 battery state\u003c/strong\u003e\u003cbr\u003eCharging apps, fleet management, trip planning\u003cbr\u003e\u003csub\u003e\u003ca href=\"https://smartcar.com/docs/api-reference/signals/tractionbattery#param-capacity\"\u003eSmartcar API\u003c/a\u003e, \u003ca href=\"https://www.fms-standard.com/Truck/down_load/Technical_Specification_rFMS_vehicle_data_V4.0.0_17.09.2021.pdf\"\u003erFMS vehicle data spec\u003c/a\u003e\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"180\"\u003e\u003ca href=\"https://play.google.com/store/apps/details?id=com.circlek.ev\"\u003e\u003cimg src=\"img/1b circlek.png\" width=\"180\" alt=\"Circle K app showing 80 kWh delivered during a charging session\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\" width=\"380\"\u003e\u003cstrong\u003eSolar generation \u0026 feed-in\u003c/strong\u003e\u003cbr\u003eDaily/monthly production, grid export\u003c/td\u003e\n    \u003ctd width=\"180\"\u003e\u003ca href=\"https://play.google.com/store/apps/details?id=com.teslamotors.tesla\"\u003e\u003cimg src=\"img/1c tesla.png\" width=\"180\" alt=\"Tesla app showing 32.8 kWh generated today\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 2. Power ratings (W, kW)\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\" width=\"380\"\u003e\u003cstrong\u003eEV charging stations\u003c/strong\u003e\u003cbr\u003eCharging networks, station maps, session details\u003c/td\u003e\n    \u003ctd width=\"180\"\u003e\u003ca href=\"https://chargedrive.com/map\"\u003e\u003cimg src=\"img/2b chargeanddrive.png\" width=\"180\" alt=\"Chargedrive map showing 150 kW charging station\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\" width=\"380\"\u003e\u003cstrong\u003eSolar \u0026 HVAC systems\u003c/strong\u003e\u003cbr\u003ePanel output, inverter dashboards, heating/cooling\u003c/td\u003e\n    \u003ctd width=\"180\"\u003e\u003ca href=\"https://play.google.com/store/apps/details?id=com.teslamotors.tesla\"\u003e\u003cimg src=\"img/2c tesla.png\" width=\"180\" alt=\"Tesla app showing solar panel kW output and daily kWh generation\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\" width=\"380\"\u003e\u003cstrong\u003eReal-time device power draw\u003c/strong\u003e\u003cbr\u003eSmart plugs, energy meters\u003cbr\u003eAppliance ratings, LED lighting, home electronics\u003c/td\u003e\n    \u003ctd width=\"180\"\u003e\u003ca href=\"https://community.home-assistant.io/t/dashboard-real-time-power-meter-with-device-level-detail/420763\"\u003e\u003cimg src=\"img/2a homeassistant.png\" width=\"180\" alt=\"Home Assistant real-time power meter showing 287.9 W\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 3. Compound units\n- **Energy labelling** — `kilowatt-hour-per-year` (EU energy labels)\n- **Carbon accounting** — `gram-per-kilowatt-hour` (CO₂e `g/kWh`)\n- **EV efficiency** — `kilowatt-hour-per-kilometer`, `kilowatt-hour-per-mile` (CLDR also defines `kilowatt-hour-per-100-kilometer` as a [unit identifier](https://github.com/unicode-org/cldr/blob/main/common/validity/unit.xml))\n- **Energy density** — `kilowatt-hour-per-liter` (battery specs)\n- **Energy intensity** — `kilowatt-hour-per-kilogram` (industrial production)\n\n## Proposed Solution\n\nAdd three sanctioned single unit identifiers to [ECMA-402 §6.6.2 (IsSanctionedSingleUnitIdentifier), Table 2](https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers):\n\n\u003ctable\u003e\n  \u003ctr\u003e\n   \u003cth colspan=\"2\" align=\"left\"\u003eSingle Unit Identifier\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003ewatt\u003c/td\u003e\n   \u003ctd\u003eSI derived unit for power (appliance ratings, device specifications)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003ekilowatt\u003c/td\u003e\n   \u003ctd\u003eCommon power ratings (EV charging rate, solar, HVAC systems)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003ekilowatt-hour\u003c/td\u003e\n   \u003ctd\u003ePrimary unit for electrical energy consumption (utility bills, EV charging, home energy)\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nThese three units cover the vast majority of consumer-facing energy applications. ECMA-402 draws from CLDR; these identifiers are already defined and localized.\n\n**AvailableCanonicalUnits()** must include the three new identifiers in its return set.\n\n## API Examples\n\n#### Narrow width, US locale:\n```javascript\nnew Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt-hour', unitDisplay: 'narrow' }).format(1234.5)\n// \"1,234.5 kWh\"\n```\n\n#### Short width, French locale:\n```javascript\nnew Intl.NumberFormat('fr-FR', { style: 'unit', unit: 'kilowatt-hour', unitDisplay: 'short' }).format(1234.5)\n// \"1 234,5 kWh\"\n```\n\n#### Long width, German locale:\n```javascript\nnew Intl.NumberFormat('de-DE', { style: 'unit', unit: 'watt', unitDisplay: 'long' }).format(1200)\n// \"1.200 Watt\"\n```\n\n#### Power ratings across locales:\n```javascript\nnew Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt' }).format(5.2)  // \"5.2 kW\"\nnew Intl.NumberFormat('fr-FR', { style: 'unit', unit: 'kilowatt' }).format(5.2)  // \"5,2 kW\"\n```\n\n#### Compound units (once base units are sanctioned):\n```javascript\nnew Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt-hour-per-mile', unitDisplay: 'narrow' }).format(0.29)\n// \"0.29 kWh/mi\"\n```\n\n#### Today (before this proposal), these throw RangeError:\n```javascript\nnew Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt-hour' }).format(42.5)\n// RangeError: Invalid unit argument for option unit: kilowatt-hour\n```\n\n## Technical Considerations\n\n- **CLDR support**: All proposed units are already defined in Unicode CLDR with complete localization across all supported locales ([unit.xml](https://github.com/unicode-org/cldr/blob/main/common/validity/unit.xml))\n- **No breaking changes**: Purely additive\n- **Minimal payload impact**: Data already exists in CLDR, three units represent a minimal addition.\n- **Consistent with existing patterns**: Follows same conventions as `kilogram`/`kilometer`, `fluid-ounce`\n- **Userland workarounds and bugs**: Without native support, developers use libraries like [convert-units](https://www.npmjs.com/package/convert-units) (~150K weekly npm downloads), or build custom formatting logic leading to locale bugs ([de-CH kWh bug](https://github.com/home-assistant/frontend/issues/27254), [broken separators](https://community.home-assistant.io/t/decimal-and-thousand-separator-are-not-honored-in-templating/640567))\n- **Spec updates**: §6.6.2 IsSanctionedSingleUnitIdentifier (Table 2) and AvailableCanonicalUnits() return set\n\n## Appeal\n\nEnergy units have significantly broader utility than existing sanctioned units like `stone` (UK/Ireland body weight), `acre` (land area), or `fluid-ounce` (regional volume measurement), with universal SI standardization and rapidly growing web-facing applications:\n\n- **Electric Vehicles**: Projected to reach 40M annual sales by 2030\u003csup\u003e[[2]](https://www.iea.org/reports/global-ev-outlook-2024/executive-summary)\u003c/sup\u003e (charging networks: ChargePoint 1M+ sessions/month\u003csup\u003e[[3]](https://www.greencarreports.com/news/1115324_evgo-chargepoint-annual-reports-show-growth-in-electric-car-charging)\u003c/sup\u003e, EVgo 1.4M+ drivers\u003csup\u003e[[4]](https://apps.apple.com/us/app/evgo-fast-ev-charging/id1281660968)\u003c/sup\u003e)\n- **Building Energy Management**: Mandated by EU EPBD directive\u003csup\u003e[[1]](https://energy.ec.europa.eu/topics/energy-efficiency/energy-performance-buildings/energy-performance-buildings-directive_en)\u003c/sup\u003e\n- **Smart Home Market**: $101B in 2024\u003csup\u003e[[5]](https://www.skyquestt.com/report/smart-home-market)\u003c/sup\u003e, projected to reach $226B by 2032 (Home Assistant: 2M+ installations\u003csup\u003e[[6]](https://www.home-assistant.io/blog/2025/04/16/state-of-the-open-home-recap/)\u003c/sup\u003e)\n- **Energy Utility Portals**: Major US utilities (PG\u0026E: 16M\u003csup\u003e[[7]](https://www.pge.com/en/about/company-information/company-profile.html)\u003c/sup\u003e, SCE: 15M\u003csup\u003e[[8]](https://www.sce.com/about-us/who-we-are)\u003c/sup\u003e people served) provide kWh-based web dashboards\n\n## Community Support\n\n[Issue #739](https://github.com/tc39/ecma402/issues/739) has received 15 👍 reactions. There is also a thread on [Discourse](https://es.discourse.group/t/addition-of-power-energy-units-to-intl-numberformat/1702).\n\n## CLDR\n\nTC39-TG2 has recommended adding energy unit preference data to [CLDR](https://unicode-org.atlassian.net/browse/CLDR-19201) as the next step for advancing this proposal. Once this data exists in CLDR, the Stage 1 [Smart Unit Preferences](https://github.com/tc39/proposal-smart-unit-preferences) proposal would bring locale-aware automatic unit selection to ECMAScript — including magnitude-based scaling via CLDR's `geq` thresholds.\n\n### Unit Identifier Availability\n\n| Unit Identifier | In CLDR? | Notes |\n|----------------|----------|-------|\n| `kilowatt-hour` | Yes | Used in `energy/default` preferences |\n| `kilowatt` | Yes | Used in `power/engine` preferences |\n| `kilowatt-hour-per-100-kilometer` | Yes | Defined as `force-kilowatt-hour-per-100-kilometer` |\n| `watt-hour` | No | Would enable full prefix scaling if added. See [CLDR-11454](https://unicode-org.atlassian.net/browse/CLDR-11454) |\n| `milliampere-hour` | No | Not currently defined |\n\n## Future Considerations\n\nIf `watt-hour` is added to CLDR, it would also enable **battery capacity** formatting (Wh for laptops and portable devices). See [Why watt-hour?](#why-watt-hour)\n\nAdditional units could be considered in future proposals if demand emerges:\n\n#### Defined in CLDR:\n- `megawatt` - Industrial and power generation facilities\n- `gigawatt` - Large-scale power infrastructure\n- `milliwatt` - Low-power electronics\n\n#### Not currently in CLDR:\n- `watt-hour` - Base unit for energy scaling. See [Why watt-hour?](#why-watt-hour)\n- `megawatt-hour` - Utility-scale energy measurement\n- `gigawatt-hour` - Utility-scale energy measurement\n- `milliampere-hour` – `mAh` used for electronics and batteries\n\n#### Lower priority:\n- `joule`, `kilojoule` - Scientific applications (separate domain)\n- `british-thermal-unit` - HVAC\n- `horsepower` - Automotive (niche web usage)\n- `calorie`, `kilocalorie`, `foodcalorie` - Nutrition (separate domain)\n\n**Note**: Energy price comparison (currency/kWh) is a major consumer-facing use case, but ECMA-402 does not currently support compound currency-per-unit formatting.\n\n## FAQ\n\n### Why these three units?\n\nThese cover the overwhelming majority of consumer-facing energy applications in web development. Starting focused allows faster adoption, and all three units are already defined with production-quality formatting in CLDR.\n\n### Why watt-hour?\n\n`watt-hour` is not yet defined as an explicit unit in CLDR, so this proposal starts with the three units that have production-quality CLDR support today. If `watt-hour` were added to CLDR, it could be included in ECMA-402 as well — and there are good reasons to consider it:\n\n**It is the natural base unit for energy scaling.** `watt-hour` would enable the full prefix chain — Wh, kWh, MWh, GWh. Real-world applications span this entire range: from Wh for device consumption ([HA thread](https://community.home-assistant.io/t/energy-dashboard-use-wh-instead-of-kwh/724132)) to GWh for grid-scale reporting ([Electricity Maps](https://github.com/electricitymaps/electricitymaps-contrib/issues/4630)). If the [Smart Unit Preferences](https://github.com/tc39/proposal-smart-unit-preferences) proposal (Stage 1) lands, `watt-hour` in CLDR would give energy units automatic magnitude-based scaling — without it, energy would be one of the few common measurement domains without proper scaling support.\n\n**The current compound construction produces suboptimal formatting.** CLDR can construct `watt-hour` from components (`power-watt` + `duration-hour`), but the result is not production-quality:\n\n| Unit | CLDR Status | SHORT format (en) |\n|------|-------------|-------------------|\n| kilowatt-hour | ✅ Explicit definition | `12.345 kWh` |\n| watt-hour | ⚠️ Constructed from components | `12.345 W⋅hr` |\n\nThe constructed format uses a separator (`⋅`) and `hr` instead of the natural `Wh`. Other locales have similar issues (German: `W⋅Std.` instead of `Wh`). [CLDR-17881](https://unicode-org.atlassian.net/browse/CLDR-17881) recognizes that commonly-used compound units should have explicit definitions for better formatting.\n\n### Won't this increase bundle sizes?\nThese units are defined in CLDR with localization across all supported locales. Browsers may need to ship additional translation strings for the three units. However, the per-unit data is small (unit names, abbreviations, and grammatical forms), and three units represent a minimal addition.\n\n## References\n\n- CLDR-19201: https://unicode-org.atlassian.net/browse/CLDR-19201\n- Smart Unit Preferences (Stage 1): https://github.com/tc39/proposal-smart-unit-preferences\n- Issue #739: https://github.com/tc39/ecma402/issues/739\n- Issue #605: https://github.com/tc39/ecma402/issues/605 (related: metric-ton, cubic units)\n- CLDR Unit Validity: https://github.com/unicode-org/cldr/blob/main/common/validity/unit.xml\n- CLDR Unit Preferences: https://www.unicode.org/cldr/charts/45/supplemental/unit_preferences.html\n- ECMA-402 Spec: https://tc39.es/ecma402/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohanrd%2Fproposal-intl-energy-units","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohanrd%2Fproposal-intl-energy-units","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohanrd%2Fproposal-intl-energy-units/lists"}