@tgwf/co2 0.8.0 → 0.9.0-0

package/CHANGELOG.md

@@ -8,7 +8,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-- Include a new alternative, "Green Byte Model" with the figures after speaking to folks at the IEA and other places.
+
+
+# [0.9.0] - 2022-03-28
+
+### Added
+
+- Added newly implemented Sustainable Web Design model [thanks @dryden!]
+- Added new readme page for using both emissions models
+- Added new source of data to the Sustainable Web Design model from Ember Climate.
+### Changed
+
+- Changed the CO2 class to accept either the One Byte model or the Sustainable Web Design model
+### Fixed
+
+- Fixed various typos.
 
 # [0.8.0] - 2021-11-28
 
@@ -23,7 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- The 1bye model will give different numbers now. It's mentioned in `#fixed` but it's worth repeating.
+- The 1byte model will give different numbers now. It's mentioned in `#fixed` but it's worth repeating.
 
 ## [0.7.0] - 2021-11-28
 
@@ -61,9 +75,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Update README
-- Update the emissions figured for green energy after further research on methodology with @@JamieBeevor
-- Incorproate class based CO2 models from @soulgalore
+- Updated README
+- Updated the emissions figured for green energy after further research on methodology with @@JamieBeevor
+- Incorporated class based CO2 models from @soulgalore
 - Credit contributors
 
 
@@ -83,7 +97,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-Add the (currently unused) green byte model.
+Added the (currently unused) green byte model.
 
 ### Changed
 

package/README.md

@@ -3,24 +3,37 @@
 <img src="https://github.com/thegreenwebfoundation/co2.js/actions/workflows/unittests.yml/badge.svg" />
 
 
-We know computers use electricity, and because most of the electricity we use comes from burning fossil fuels to generate, there is an environmental cost to every upload and download we make over the internet.
+We know computers use electricity, and because most of the electricity we use comes from burning fossil fuels, there is an environmental cost to every upload and download we make over the internet.
 
 We can do something about this though. The same way we use performance budgets to make apps and websites faster and cheaper to run, we can use carbon budgets to make them faster, cheaper and _greener_.
 
 The CO2 package from [The Green Web Foundation][tgwf] lets you quickly estimate these emissions, to make measurable improvements as part of your workflow.
 
-It does this by implementing the 1byte model as used by the Shift Project, as introduced in their report on CO2 emissions from digital infrastructure, [Lean ICT: for a sober digital][soberDigital], to return a number for the estimated CO2 emissions for the corresponding number of bytes sent over the wire.
+### How it works
 
-It is currently used in the web performance tool [sitespeed.io][], to help developers build greener, more planet friendly digital services.
+It does this by implementing various models for converting the measurable usage of digital services into a figure for the estimated CO2 emissions.
+
+This defaults to the 1byte model as used by the Shift Project, as introduced in their report on CO2 emissions from digital infrastructure, [Lean ICT: for a sober digital][soberDigital], with the [Sustainable Web Design model][swd] as a popular alternative..
+
+For more information, see the documentation [for when to use the different models, with code samples to start you off](./src/readme.md).
+
+### Who uses it
+
+It is currently used in the web performance tool [sitespeed.io][], [ecoping][], [Websitecarbon.com](websitecarbon), and [ecograder][] to help developers build greener, more planet friendly digital services.
 
 If you want to build this kind of environmental information into your own software, and want some advice, we'd be happy to hear from you - please open an issue, remembering to link to your project.
 
-This is open source software, with all the guarantees associated, so if you want professional advice, to a deadline, and you have a budget please see the services offered by the [Green Web Foundation][tgwf-services].
+This is open source software, with all the guarantees associated. So if you want professional advice, to a deadline, and you have a budget please see the services offered by the [Green Web Foundation][tgwf-services].
 
+
+[sitespeed.io]: https://sitespeed.io
+[ecoping]: https://ecoping.earth
+[ecograder]: https://ecograder.com
+[websitecarbon]: https://www.websitecarbon.com
+[tgwf]: https://www.thegreenwebfoundation.org
+[tgwf-services]: https://www.thegreenwebfoundation.org/services
+[swd]: https://sustainablewebdesign.org/calculating-digital-emissions
 [soberDigital]: https://theshiftproject.org/en/lean-ict-2/
-[sitespeed.io]: https://sitespeed.io/
-[tgwf]: https://www.thegreenwebfoundation.org/
-[tgwf-services]: https://www.thegreenwebfoundation.org/services/
 
 
 ## Usage
@@ -29,7 +42,7 @@ This is open source software, with all the guarantees associated, so if you want
 
 #### Server-side
 
-This approach relies on the `fs` module and so can only be used on platforms, like Node.js, that support this.
+This approach relies on the `fs` module and so can only be used on platforms like Node.js, that support this.
 
 ```js
 
@@ -54,7 +67,7 @@ const co2Emission = new CO2();
 estimatedCO2 = co2Emission.perByte(bytesSent)
 
 console.log(`Sending a gigabyte, had a carbon footprint of ${estimatedCO2.toFixed(3)} grams of CO2`)
-
+****
 ```
 
 ### Checking for green power
@@ -76,22 +89,6 @@ greencheck.checkPage(["google.com"])
 
 ```
 
-### Notes
-
-Please note, we currently look at just the carbon cost of _generating_ the electricity, similar to how the [International Energy Agency (IEA)] does, not the full life cycle cost of the energy.
-
-Doing this would include things like:
-
-- the carbon emitted when carrying out activity associated with digging up the fuel
-- the carbon associated with mining the materials to _build_ the power stations, datacentres, and so on
-- the end of life costs
-- the maintenance costs over the life of the datacentres, power generation and end user devices, and the rest of the internet
-
-Life cycle figures do exist, but they are very difficult to do well. If you're interested in contributing to this, we'd love to hear from you.
-
-
 # Licenses
 
 Apache 2.0
-
-[International Energy Agency (IEA)]: https://www.iea.org/

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@tgwf/co2",
-  "version": "0.8.0",
+  "version": "0.9.0-0",
   "description": "Work out the co2 of your digital services",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
+    "test:watch": "jest --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "travis": "npm run lint && jest"

package/src/1byte.js

@@ -1,6 +1,14 @@
 // Use the 1byte model for now from the Shift Project, and assume a US grid mix figure they use of around 519 g co2 for the time being. It's lower for Europe, and in particular, France, but for v1, we don't include this
 const CO2_PER_KWH_IN_DC_GREY = 519;
 
+// this figure is from the IEA's 2018 report for a global average:
+const CO2_PER_KWH_NETWORK_GREY = 475;
+
+// TODO - these figures need to be updated, as the figures for green
+// shouldn't really be zero now we know that carbon intensity figures
+// for renewables still usually include the life cycle emissions
+const CO2_PER_KWH_IN_DC_GREEN = 0;
+
 // the 1 byte model gives figures for energy usage for:
 
 // datacentres
@@ -28,9 +36,36 @@ const KWH_PER_BYTE_FOR_NETWORK =
   (FIXED_NETWORK_WIRED + FIXED_NETWORK_WIFI + FOUR_G_MOBILE) / 3;
 
 const KWH_PER_BYTE_FOR_DEVICES = 1.3e-10;
+
+class OneByte {
+  constructor(options) {
+    this.options = options;
+
+    this.KWH_PER_BYTE_FOR_NETWORK = KWH_PER_BYTE_FOR_NETWORK;
+  }
+
+  perByte(bytes, green) {
+    if (bytes < 1) {
+      return 0;
+    }
+
+    if (green) {
+      // if we have a green datacentre, use the lower figure for renewable energy
+      const Co2ForDC = bytes * KWH_PER_BYTE_IN_DC * CO2_PER_KWH_IN_DC_GREEN;
+
+      // but for the worest of the internet, we can't easily check, so assume
+      // grey for now
+      const Co2forNetwork =
+        bytes * KWH_PER_BYTE_FOR_NETWORK * CO2_PER_KWH_NETWORK_GREY;
+
+      return Co2ForDC + Co2forNetwork;
+    }
+
+    const KwHPerByte = KWH_PER_BYTE_IN_DC + KWH_PER_BYTE_FOR_NETWORK;
+    return bytes * KwHPerByte * CO2_PER_KWH_IN_DC_GREY;
+  }
+}
+
 module.exports = {
-  KWH_PER_BYTE_IN_DC,
-  KWH_PER_BYTE_FOR_NETWORK,
-  KWH_PER_BYTE_FOR_DEVICES,
-  CO2_PER_KWH_IN_DC_GREY,
+  OneByte,
 };

package/src/1byte.test.js

@@ -2,15 +2,16 @@
 
 const oneByte = require("./1byte");
 
-describe("onebyte", function () {
-  describe("perByte", function () {
-    it.only("returns a simple average of the different networks", function () {
+describe("onebyte", () => {
+  describe("perByte", () => {
+    it.only("returns a simple average of the different networks", () => {
       // we limit this to 12 figures with toFixed(12), because
       // we have a recurring 333333 afterwards
       // 4.88e-10 is the same as 0.000000000488
       const expected_val = (0.000000000488).toFixed(12);
+      const instance = new oneByte.OneByte();
 
-      expect(oneByte.KWH_PER_BYTE_FOR_NETWORK.toFixed(12)).toBe(expected_val);
+      expect(instance.KWH_PER_BYTE_FOR_NETWORK.toFixed(12)).toBe(expected_val);
     });
   });
 });

package/src/co2.js

@@ -1,48 +1,33 @@
 "use strict";
 
 const url = require("url");
-const oneByte = require("./1byte.js");
-
-const KWH_PER_BYTE_IN_DC = oneByte.KWH_PER_BYTE_IN_DC;
-const KWH_PER_BYTE_FOR_NETWORK = oneByte.KWH_PER_BYTE_FOR_NETWORK;
-const CO2_PER_KWH_IN_DC_GREY = oneByte.CO2_PER_KWH_IN_DC_GREY;
-
-// this figure is from the IEA's 2018 report for a global average:
-const CO2_PER_KWH_NETWORK_GREY = 475;
-
-// The IEA figures cover electricity but as far as I can tell, it does not
-// cover life cycle emissions, and the 1byte models appears to do the same
-// so, we use zero emissions for green infra in the DC
-// https://github.com/thegreenwebfoundation/co2.js/issues/2
-const CO2_PER_KWH_IN_DC_GREEN = 0;
+const onebyte = require("./1byte.js");
 
 class CO2 {
   constructor(options) {
     this.options = options;
-  }
 
-  perByte(bytes, green) {
-    // return a CO2 figure for energy used to shift the corresponding
-    // the data transfer.
+    // default model
+    this.model = new onebyte.OneByte();
 
-    if (bytes < 1) {
-      return 0;
-    }
-
-    if (green) {
-      // if we have a green datacentre, use the lower figure for renewable energy
-      const Co2ForDC = bytes * KWH_PER_BYTE_IN_DC * CO2_PER_KWH_IN_DC_GREEN;
-
-      // but for the rest of the internet, we can't easily check, so assume
-      // grey for now
-      const Co2forNetwork =
-        bytes * KWH_PER_BYTE_FOR_NETWORK * CO2_PER_KWH_NETWORK_GREY;
-
-      return Co2ForDC + Co2forNetwork;
+    if (options) {
+      this.model = new options.model();
     }
+  }
 
-    const KwHPerByte = KWH_PER_BYTE_IN_DC + KWH_PER_BYTE_FOR_NETWORK;
-    return bytes * KwHPerByte * CO2_PER_KWH_IN_DC_GREY;
+  //
+  //
+  /**
+   * Accept a figure in bytes for data transfer, and a boolean for whether
+   * the domain shows as 'green', and return a CO2 figure for energy used to shift the corresponding
+   * the data transfer.
+   *
+   * @param {number} bytes
+   * @param {boolean} green
+   * @return {number} the amount of CO2 in grammes
+   */
+  perByte(bytes, green) {
+    return this.model.perByte(bytes, green);
   }
 
   perDomain(pageXray, greenDomains) {

package/src/co2.test.js

@@ -4,147 +4,286 @@ const fs = require("fs");
 const path = require("path");
 
 const CO2 = require("./co2");
+const swd = require("./sustainable-web-design");
 const pagexray = require("pagexray");
 
-describe("co2", function () {
+describe("co2", () => {
   let har, co2;
-  const TGWF_GREY_VALUE = 0.20497;
-  const TGWF_GREEN_VALUE = 0.54704;
-  const TGWF_MIXED_VALUE = 0.16718;
-
-  const MILLION = 1000000;
-  const MILLION_GREY = 0.29081;
-  const MILLION_GREEN = 0.23196;
-
-  beforeEach(function () {
-    co2 = new CO2();
-    har = JSON.parse(
-      fs.readFileSync(
-        path.resolve(__dirname, "../data/fixtures/tgwf.har"),
-        "utf8"
-      )
-    );
-  });
 
-  describe("perByte", function () {
-    it("returns a CO2 number for data transfer using 'grey' power", function () {
-      expect(co2.perByte(MILLION).toPrecision(5)).toBe(
-        MILLION_GREY.toPrecision(5)
+  describe("1 byte model", () => {
+    const TGWF_GREY_VALUE = 0.20497;
+    const TGWF_GREEN_VALUE = 0.54704;
+    const TGWF_MIXED_VALUE = 0.16718;
+
+    const MILLION = 1000000;
+    const MILLION_GREY = 0.29081;
+    const MILLION_GREEN = 0.23196;
+
+    beforeEach(() => {
+      co2 = new CO2();
+      har = JSON.parse(
+        fs.readFileSync(
+          path.resolve(__dirname, "../data/fixtures/tgwf.har"),
+          "utf8"
+        )
       );
     });
 
-    it("returns a lower CO2 number for data transfer from domains using entirely 'green' power", function () {
-      expect(co2.perByte(MILLION, false).toPrecision(5)).toBe(
-        MILLION_GREY.toPrecision(5)
-      );
-      expect(co2.perByte(MILLION, true).toPrecision(5)).toBe(
-        MILLION_GREEN.toPrecision(5)
-      );
+    describe("perByte", () => {
+      it("returns a CO2 number for data transfer using 'grey' power", () => {
+        expect(co2.perByte(MILLION).toPrecision(5)).toBe(
+          MILLION_GREY.toPrecision(5)
+        );
+      });
+
+      it("returns a lower CO2 number for data transfer from domains using entirely 'green' power", () => {
+        expect(co2.perByte(MILLION).toPrecision(5)).toBe(
+          MILLION_GREY.toPrecision(5)
+        );
+        expect(co2.perByte(MILLION, true).toPrecision(5)).toBe(
+          MILLION_GREEN.toPrecision(5)
+        );
+      });
     });
-  });
 
-  describe("perPage", function () {
-    it("returns CO2 for total transfer for page", function () {
-      const pages = pagexray.convert(har);
-      const pageXrayRun = pages[0];
+    describe("perPage", () => {
+      it("returns CO2 for total transfer for page", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
 
-      expect(co2.perPage(pageXrayRun).toPrecision(5)).toBe(
-        TGWF_GREY_VALUE.toPrecision(5)
-      );
+        expect(co2.perPage(pageXrayRun).toPrecision(5)).toBe(
+          TGWF_GREY_VALUE.toPrecision(5)
+        );
+      });
+      it("returns lower CO2 for page served from green site", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+        let green = [
+          "www.thegreenwebfoundation.org",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+        expect(co2.perPage(pageXrayRun, green)).toBeLessThan(TGWF_GREY_VALUE);
+      });
+      it("returns a lower CO2 number where *some* domains use green power", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+        // green can be true, or a array containing entries
+        let green = [
+          "www.thegreenwebfoundation.org",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+        expect(co2.perPage(pageXrayRun, green).toPrecision(5)).toBe(
+          TGWF_MIXED_VALUE.toPrecision(5)
+        );
+      });
     });
-    it("returns lower CO2 for page served from green site", function () {
-      const pages = pagexray.convert(har);
-      const pageXrayRun = pages[0];
-      let green = [
-        "www.thegreenwebfoundation.org",
-        "fonts.googleapis.com",
-        "ajax.googleapis.com",
-        "assets.digitalclimatestrike.net",
-        "cdnjs.cloudflare.com",
-        "graphite.thegreenwebfoundation.org",
-        "analytics.thegreenwebfoundation.org",
-        "fonts.gstatic.com",
-        "api.thegreenwebfoundation.org",
-      ];
-      expect(co2.perPage(pageXrayRun, green)).toBeLessThan(TGWF_GREY_VALUE);
+    describe("perDomain", () => {
+      it("shows object listing Co2 for each domain", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+        const res = co2.perDomain(pageXrayRun);
+
+        const domains = [
+          "thegreenwebfoundation.org",
+          "www.thegreenwebfoundation.org",
+          "maxcdn.bootstrapcdn.com",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+
+        for (let obj of res) {
+          expect(domains.indexOf(obj.domain)).toBeGreaterThan(-1);
+          expect(typeof obj.co2).toBe("number");
+        }
+      });
+      it("shows lower Co2 for green domains", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+
+        const greenDomains = [
+          "www.thegreenwebfoundation.org",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+        const res = co2.perDomain(pageXrayRun);
+        const resWithGreen = co2.perDomain(pageXrayRun, greenDomains);
+
+        for (let obj of res) {
+          expect(typeof obj.co2).toBe("number");
+        }
+        for (let obj of greenDomains) {
+          let index = 0;
+          expect(resWithGreen[index].co2).toBeLessThan(res[index].co2);
+          index++;
+        }
+      });
     });
-    it("returns a lower CO2 number where *some* domains use green power", function () {
-      const pages = pagexray.convert(har);
-      const pageXrayRun = pages[0];
-      // green can be true, or a array containing entries
-      let green = [
-        "www.thegreenwebfoundation.org",
-        "fonts.googleapis.com",
-        "ajax.googleapis.com",
-        "assets.digitalclimatestrike.net",
-        "cdnjs.cloudflare.com",
-        "graphite.thegreenwebfoundation.org",
-        "analytics.thegreenwebfoundation.org",
-        "fonts.gstatic.com",
-        "api.thegreenwebfoundation.org",
-      ];
-      expect(co2.perPage(pageXrayRun, green).toPrecision(5)).toBe(
-        TGWF_MIXED_VALUE.toPrecision(5)
+  });
+
+  describe("Sustainable Web Design model", () => {
+    // the SWD model should have slightly higher values as
+    // we include more of the system in calculations for the
+    // same levels of data transfer
+    const MILLION = 1000000;
+    const MILLION_GREY = 0.33343;
+    const MILLION_GREEN = 0.28908;
+
+    const TGWF_GREY_VALUE = 0.23501;
+    const TGWF_GREEN_VALUE = 0.54704;
+    const TGWF_MIXED_VALUE = 0.20652;
+
+    beforeEach(() => {
+      co2 = new CO2({ model: swd });
+      har = JSON.parse(
+        fs.readFileSync(
+          path.resolve(__dirname, "../data/fixtures/tgwf.har"),
+          "utf8"
+        )
       );
     });
-  });
-  describe("perDomain", function () {
-    it("shows object listing Co2 for each domain", function () {
-      const pages = pagexray.convert(har);
-      const pageXrayRun = pages[0];
-      const res = co2.perDomain(pageXrayRun);
-
-      const domains = [
-        "thegreenwebfoundation.org",
-        "www.thegreenwebfoundation.org",
-        "maxcdn.bootstrapcdn.com",
-        "fonts.googleapis.com",
-        "ajax.googleapis.com",
-        "assets.digitalclimatestrike.net",
-        "cdnjs.cloudflare.com",
-        "graphite.thegreenwebfoundation.org",
-        "analytics.thegreenwebfoundation.org",
-        "fonts.gstatic.com",
-        "api.thegreenwebfoundation.org",
-      ];
-
-      for (let obj of res) {
-        expect(domains.indexOf(obj.domain)).toBeGreaterThan(-1);
-        expect(typeof obj.co2).toBe("number");
-      }
+
+    describe("perByte", () => {
+      it("returns a CO2 number for data transfer", () => {
+        co2.perByte(MILLION);
+        expect(co2.perByte(MILLION).toPrecision(5)).toBe(
+          MILLION_GREY.toPrecision(5)
+        );
+      });
+
+      it("returns a lower CO2 number for data transfer from domains using entirely 'green' power", () => {
+        expect(co2.perByte(MILLION, false).toPrecision(5)).toBe(
+          MILLION_GREY.toPrecision(5)
+        );
+
+        expect(co2.perByte(MILLION, true).toPrecision(5)).toBe(
+          MILLION_GREEN.toPrecision(5)
+        );
+      });
     });
-    it("shows lower Co2 for green domains", function () {
-      const pages = pagexray.convert(har);
-      const pageXrayRun = pages[0];
-
-      const greenDomains = [
-        "www.thegreenwebfoundation.org",
-        "fonts.googleapis.com",
-        "ajax.googleapis.com",
-        "assets.digitalclimatestrike.net",
-        "cdnjs.cloudflare.com",
-        "graphite.thegreenwebfoundation.org",
-        "analytics.thegreenwebfoundation.org",
-        "fonts.gstatic.com",
-        "api.thegreenwebfoundation.org",
-      ];
-      const res = co2.perDomain(pageXrayRun);
-      const resWithGreen = co2.perDomain(pageXrayRun, greenDomains);
-
-      for (let obj of res) {
-        expect(typeof obj.co2).toBe("number");
-      }
-      for (let obj of greenDomains) {
-        let index = 0;
-        expect(resWithGreen[index].co2).toBeLessThan(res[index].co2);
-        index++;
-      }
+
+    describe("perPage", () => {
+      it("returns CO2 for total transfer for page", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+
+        expect(co2.perPage(pageXrayRun).toPrecision(5)).toBe(
+          TGWF_GREY_VALUE.toPrecision(5)
+        );
+      });
+      it("returns lower CO2 for page served from green site", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+        let green = [
+          "www.thegreenwebfoundation.org",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+        expect(co2.perPage(pageXrayRun, green)).toBeLessThan(TGWF_GREY_VALUE);
+      });
+      it("returns a lower CO2 number where *some* domains use green power", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+        // green can be true, or a array containing entries
+        let green = [
+          "www.thegreenwebfoundation.org",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+        expect(co2.perPage(pageXrayRun, green).toPrecision(5)).toBe(
+          TGWF_MIXED_VALUE.toPrecision(5)
+        );
+      });
+    });
+    describe("perDomain", () => {
+      it("shows object listing Co2 for each domain", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+        const res = co2.perDomain(pageXrayRun);
+
+        const domains = [
+          "thegreenwebfoundation.org",
+          "www.thegreenwebfoundation.org",
+          "maxcdn.bootstrapcdn.com",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+
+        for (let obj of res) {
+          expect(domains.indexOf(obj.domain)).toBeGreaterThan(-1);
+          expect(typeof obj.co2).toBe("number");
+        }
+      });
+      it("shows lower Co2 for green domains", () => {
+        const pages = pagexray.convert(har);
+        const pageXrayRun = pages[0];
+
+        const greenDomains = [
+          "www.thegreenwebfoundation.org",
+          "fonts.googleapis.com",
+          "ajax.googleapis.com",
+          "assets.digitalclimatestrike.net",
+          "cdnjs.cloudflare.com",
+          "graphite.thegreenwebfoundation.org",
+          "analytics.thegreenwebfoundation.org",
+          "fonts.gstatic.com",
+          "api.thegreenwebfoundation.org",
+        ];
+        const res = co2.perDomain(pageXrayRun);
+        const resWithGreen = co2.perDomain(pageXrayRun, greenDomains);
+
+        for (let obj of res) {
+          expect(typeof obj.co2).toBe("number");
+        }
+        for (let obj of greenDomains) {
+          let index = 0;
+          expect(resWithGreen[index].co2).toBeLessThan(res[index].co2);
+          index++;
+        }
+      });
     });
   });
-  // describe('perContentType', function () {
-  //   test.skip('shows a breakdown of emissions by content type');
-  // });
-  // describe('dirtiestResources', function () {
-  //   it.skip('shows the top 10 resources by CO2 emissions');
-  // });
 });

package/src/constants/file-size.js

@@ -0,0 +1,5 @@
+const GIGABYTE = 1024 * 1024 * 1024;
+
+module.exports = {
+  GIGABYTE,
+};

package/src/constants/index.js

@@ -0,0 +1,3 @@
+const fileSize = require("./file-size");
+
+module.exports = { fileSize };

package/src/helpers/index.js

@@ -0,0 +1,5 @@
+const formatNumber = (num) => parseFloat(num.toFixed(2));
+
+module.exports = {
+  formatNumber,
+};

package/src/hosting-api.test.js

@@ -3,9 +3,9 @@
 const hosting = require("./hosting-api");
 const nock = require("nock");
 
-describe("hostingAPI", function () {
-  describe("checking a single domain with #check", function () {
-    it("using the API", async function () {
+describe("hostingAPI", () => {
+  describe("checking a single domain with #check", () => {
+    it("using the API", async () => {
       const scope = nock("https://api.thegreenwebfoundation.org/")
         .get("/greencheck/google.com")
         .reply(200, {
@@ -16,8 +16,8 @@ describe("hostingAPI", function () {
       expect(res).toEqual(true);
     });
   });
-  describe("implicitly checking multiple domains with #check", function () {
-    it("using the API", async function () {
+  describe("implicitly checking multiple domains with #check", () => {
+    it("using the API", async () => {
       const scope = nock("https://api.thegreenwebfoundation.org/")
         .get("/v2/greencheckmulti/[%22google.com%22,%22kochindustries.com%22]")
         .reply(200, {

package/src/hosting-database.test.js

@@ -12,15 +12,15 @@ const dbPath = path.resolve(
   "url2green.test.db"
 );
 
-describe("hostingDatabase", function () {
-  describe("checking a single domain with #check", function () {
-    test("tries to use a local database if available ", async function () {
+describe("hostingDatabase", () => {
+  describe("checking a single domain with #check", () => {
+    test("tries to use a local database if available ", async () => {
       const res = await hosting.check("google.com", dbPath);
       expect(res).toEqual(true);
     });
   });
-  describe("implicitly checking multiple domains with #check", function () {
-    test("tries to use a local database if available", async function () {
+  describe("implicitly checking multiple domains with #check", () => {
+    test("tries to use a local database if available", async () => {
       const res = await hosting.check(
         ["google.com", "kochindustries.com"],
         dbPath

package/src/hosting-json.test.js

@@ -3,7 +3,7 @@
 const hosting = require("./hosting-json");
 const path = require("path");
 
-describe("hostingJSON", function () {
+describe("hostingJSON", () => {
   const jsonPath = path.resolve(
     __dirname,
     "..",
@@ -18,22 +18,22 @@ describe("hostingJSON", function () {
     "fixtures",
     "url2green.test.json.gz"
   );
-  describe("checking a single domain with #check", function () {
-    test("against the list of domains as JSON", async function () {
+  describe("checking a single domain with #check", () => {
+    test("against the list of domains as JSON", async () => {
       const db = await hosting.loadJSON(jsonPath);
       const res = await hosting.check("google.com", db);
       expect(res).toEqual(true);
     });
   });
-  describe("checking a single domain with #check", function () {
-    test("against the list of domains as JSON loaded from a gzipped JSON", async function () {
+  describe("checking a single domain with #check", () => {
+    test("against the list of domains as JSON loaded from a gzipped JSON", async () => {
       const db = await hosting.loadJSON(jsonPathGz);
       const res = await hosting.check("google.com", db);
       expect(res).toEqual(true);
     });
   });
-  describe("implicitly checking multiple domains with #check", function () {
-    test("against the list of domains as JSON", async function () {
+  describe("implicitly checking multiple domains with #check", () => {
+    test("against the list of domains as JSON", async () => {
       const db = await hosting.loadJSON(jsonPath);
       const domains = ["google.com", "kochindustries.com"];
 

package/src/hosting.test.js

@@ -14,9 +14,9 @@ const jsonPath = path.resolve(
   "url2green.test.json"
 );
 
-describe("hosting", function () {
+describe("hosting", () => {
   let har;
-  beforeEach(function () {
+  beforeEach(() => {
     har = JSON.parse(
       fs.readFileSync(
         path.resolve(__dirname, "../data/fixtures/tgwf.har"),
@@ -24,8 +24,8 @@ describe("hosting", function () {
       )
     );
   });
-  describe("checking all domains on a page object with #checkPage ", function () {
-    it("it returns a list of green domains, when passed a page object", async function () {
+  describe("checking all domains on a page object with #checkPage ", () => {
+    it("it returns a list of green domains, when passed a page object", async () => {
       const pages = pagexray.convert(har);
       const pageXrayRun = pages[0];
       const db = await hosting.loadJSON(jsonPath);
@@ -53,23 +53,23 @@ describe("hosting", function () {
     //   'it returns an empty list, when passed a page object with no green domains'
     // );
   });
-  describe("checking a single domain with #check", function () {
-    it("use the API instead", async function () {
+  describe("checking a single domain with #check", () => {
+    it("use the API instead", async () => {
       const db = await hosting.loadJSON(jsonPath);
       const res = await hosting.check("google.com", db);
       expect(res).toEqual(true);
     });
   });
-  describe("implicitly checking multiple domains with #check", function () {
-    it("Use the API", async function () {
+  describe("implicitly checking multiple domains with #check", () => {
+    it("Use the API", async () => {
       const db = await hosting.loadJSON(jsonPath);
 
       const res = await hosting.check(["google.com", "kochindustries.com"], db);
       expect(res).toContain("google.com");
     });
   });
-  describe("explicitly checking multiple domains with #checkMulti", function () {
-    it("use the API", async function () {
+  describe("explicitly checking multiple domains with #checkMulti", () => {
+    it("use the API", async () => {
       const db = await hosting.loadJSON(jsonPath);
       const res = await hosting.check(["google.com", "kochindustries.com"], db);
       expect(res).toContain("google.com");

package/src/readme.md

@@ -0,0 +1,66 @@
+# How to use the different models in CO2.js
+
+CO2js offers two models for understanding the environmental impact of compute - the 1byte model (`1byte.js`), and the Sustainable Web Design model (`swd.js`)
+
+### The 1byte model
+
+The default model in use is the 1byte model as used by the Shift Project, as introduced in their report on CO2 emissions from digital infrastructure, [Lean ICT: for a sober digital][soberDigital].
+
+This returns a number for the estimated CO2 emissions for the corresponding number of bytes sent over the wire, and has been used for video streaming, file downloads and websites.
+
+```js
+// assume you have imported or required the CO2 class from 1byte.js
+// for your runtime - either a browser, nodejs, etc.
+
+const bytesSent = (1024 * 1024 * 1024)
+const co2Emission = new CO2();
+const estimatedCO2 = co2Emission.perByte(bytesSent)
+```
+
+
+### The Sustainable Web Design model
+
+As of version 0.9, CO2.js also provides the  [Sustainable Web Design model][swd] for calculating emissions from digital services. As the name suggests, this has been designed for helping understand the environmental impact of websites. Further details are available on the [Sustainable Web Design website explaining the model](https://sustainablewebdesign.org/calculating-digital-emissions/), but for convenience, a short summary is below.
+
+#### How the SWD works
+
+This model uses data transfer as an proxy indicator for total resource usage, and uses this number to extrapolate energy usage numbers for your application as a fraction of the energy used by the total system comprised of:
+
+1. the use-phase energy of datacentres serving content
+2. the use-phase energy network transfering the data
+3. the use-phase energy of user device an user is accessing content on
+4. the total embodied energy used to create all of the above
+
+![swd model](../images/swd-energy-usage.png)
+
+It then converts these energy figures to carbon emissions, based on the carbon intensity of electricity from the [Ember annual global electricity review][Ember-annual-global-electricity-review].
+
+The carbon intensity of electricity figures for the swd model include the the full lifecycle emissions including upstream methane, supply-chain and manufacturing emissions, and include all gases, converted into CO2 equivalent over a 100 year timescale.
+
+This follows the approach used by the IPCC 5th Assessment Report Annex 3 (2014), for the carbon intensity of electricity.
+
+[Ember's methodology notes][ember-methodology] detail where the rest of this data comes from in more detail, as well as any further assumptions made.
+
+
+[ember-methodology]: https://ember-climate.org/app/uploads/2022/03/GER22-Methodology.pdf
+
+[Ember-annual-global-electricity-review]: https://ember-climate.org/insights/research/european-electricity-review-2022/
+
+
+
+
+### Sample usage
+
+```js
+// assume you have imported or required the CO2 class from swd.js
+// for your runtime - either a browser, nodejs, etc.
+
+// assume a 1 megabyte webpage
+const bytesSent = (1024 * 1024 * 1024)
+
+const co2Emission = new CO2();
+const estimatedCO2ForTransfer = co2Emission.emissionsPerVisitInGrams(bytesSent)
+```
+
+[soberDigital]: https://theshiftproject.org/en/lean-ict-2/
+[swd]: https://sustainablewebdesign.org/calculating-digital-emissions

package/src/sustainable-web-design.js

@@ -0,0 +1,224 @@
+"use strict";
+
+/**
+ * Sustainable Web Design
+ *
+ * Updated calculations and figures from
+ * https://sustainablewebdesign.org/calculating-digital-emissions/
+ *
+ *
+ */
+const { fileSize } = require("./constants");
+const { formatNumber } = require("./helpers");
+
+// this refers to the estimated total energy use for the internet around 2000 TWh,
+// divided by the total transfer it enables around 2500 exabytes
+const KWH_PER_GB = 0.81;
+
+// these constants outline how the energy is attributed to
+// different parts of the system in the SWD model
+const END_USER_DEVICE_ENERGY = 0.52;
+const NETWORK_ENERGY = 0.14;
+const DATACENTER_ENERGY = 0.15;
+const PRODUCTION_ENERGY = 0.19;
+
+// These carbon intensity figures https://ember-climate.org/data/data-explorer
+// - Global carbon intensity for 2021
+const GLOBAL_INTENSITY = 442;
+const RENEWABLES_INTENSITY = 50;
+
+// Taken from: https://gitlab.com/wholegrain/carbon-api-2-0/-/blob/master/includes/carbonapi.php
+
+const FIRST_TIME_VIEWING_PERCENTAGE = 0.25;
+const RETURNING_VISITOR_PERCENTAGE = 0.75;
+const PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD = 0.02;
+
+class SustainableWebDesign {
+  constructor(options) {
+    this.options = options;
+  }
+
+  /**
+   * Accept a figure for bytes transferred and return an object representing
+   * the share of the total enrgy use of the entire system, broken down
+   * by each corresponding system component
+   *
+   * @param {number}  bytes - the data transferred in bytes
+   * @return {object} Object containing the energy in kilowatt hours, keyed by system component
+   */
+  energyPerByteByComponent(bytes) {
+    const transferedBytesToGb = bytes / fileSize.GIGABYTE;
+    const energyUsage = transferedBytesToGb * KWH_PER_GB;
+
+    // return the total energy, with breakdown by component
+    return {
+      consumerDeviceEnergy: energyUsage * END_USER_DEVICE_ENERGY,
+      networkEnergy: energyUsage * NETWORK_ENERGY,
+      productionEnergy: energyUsage * PRODUCTION_ENERGY,
+      dataCenterEnergy: energyUsage * DATACENTER_ENERGY,
+    };
+  }
+  /**
+   * Accept an object keys by the different system components, and
+   * return an object with the co2 figures key by the each component
+   *
+   * @param {object} energyBycomponent - energy grouped by the four system components
+   * @param {number} [carbonIntensity] - carbon intensity to apply to the datacentre values
+   * @return {number} the total number in grams of CO2 equivalent emissions
+   */
+  co2byComponent(energyBycomponent, carbonIntensity = GLOBAL_INTENSITY) {
+    const returnCO2ByComponent = {};
+    for (const [key, value] of Object.entries(energyBycomponent)) {
+      // we update the datacentre, as that's what we have information
+      // about.
+      if (key === "dataCenterEnergy") {
+        returnCO2ByComponent[key] = value * carbonIntensity;
+      } else {
+        // We don't have info about the device location,
+        // nor the network path used, nor the production emissions
+        // so we revert to global figures
+        returnCO2ByComponent[key] = value * GLOBAL_INTENSITY;
+      }
+    }
+    return returnCO2ByComponent;
+  }
+
+  /**
+   * Accept a figure for bytes transferred and return a single figure for CO2
+   * emissions. Where information exists about the origin data is being
+   * fetched from, a different carbon intensity figure
+   * is applied for the datacentre share of the carbon intensity.
+   *
+   * @param {number} bytes - the data transferred in bytes
+   * @param {number} `carbonIntensity` the carbon intensity for datacentre (average figures, not marginal ones)
+   * @return {number} the total number in grams of CO2 equivalent emissions
+   */
+  perByte(bytes, carbonIntensity = GLOBAL_INTENSITY) {
+    const energyBycomponent = this.energyPerByteByComponent(bytes);
+
+    // when faced with falsy values, fallback to global intensity
+    if (Boolean(carbonIntensity) === false) {
+      carbonIntensity = GLOBAL_INTENSITY;
+    }
+    // if we have a boolean, we have a green result from the green web checker
+    // use the renewables intensity
+    if (carbonIntensity === true) {
+      carbonIntensity = RENEWABLES_INTENSITY;
+    }
+
+    // otherwise when faced with non numeric values throw an error
+    if (typeof carbonIntensity !== "number") {
+      throw new Error(
+        `perByte expects a numeric value or boolean for the carbon intensity value. Received: ${carbonIntensity}`
+      );
+    }
+
+    const co2ValuesbyComponent = this.co2byComponent(
+      energyBycomponent,
+      carbonIntensity
+    );
+
+    // pull out our values…
+    const co2Values = Object.values(co2ValuesbyComponent);
+
+    // so we can return their sum
+    return co2Values.reduce(
+      (prevValue, currentValue) => prevValue + currentValue
+    );
+  }
+
+  /**
+   * Accept a figure for bytes transferred and return the number of kilowatt hours used
+   * by the total system for this data transfer
+   *
+   * @param {number} bytes
+   * @return {number} the number of kilowatt hours used
+   */
+  energyPerByte(bytes) {
+    const energyByComponent = this.energyPerByteByComponent(bytes);
+
+    // pull out our values…
+    const energyValues = Object.values(energyByComponent);
+
+    // so we can return their sum
+    return energyValues.reduce(
+      (prevValue, currentValue) => prevValue + currentValue
+    );
+  }
+
+  /**
+   * Accept a figure for bytes transferred, and return an object containing figures
+   * per system component, with the caching assumptions applied. This tries to account
+   * for webpages being loaded from a cache by browsers, so if you had a thousand page views,
+   * and tried to work out the energy per visit, the numbers would reflect the reduced amounts
+   * of transfer.
+   *
+   * @param {number} bytes - the data transferred in bytes for loading a webpage
+   * @param {number} firstView - what percentage of visits are loading this page for the first time
+   * @param {number} returnView - what percentage of visits are loading this page for subsequent times
+   * @param {number} dataReloadRatio - what percentage of a page is reloaded on each subsequent page view
+   *
+   * @return {object} Object containing the energy in kilowatt hours, keyed by system component
+   */
+  energyPerVisitByComponent(
+    bytes,
+    firstView = FIRST_TIME_VIEWING_PERCENTAGE,
+    returnView = RETURNING_VISITOR_PERCENTAGE,
+    dataReloadRatio = PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD
+  ) {
+    const energyBycomponent = this.energyPerByteByComponent(bytes);
+    const cacheAdjustedSegmentEnergy = {};
+
+    for (const [key, value] of Object.entries(energyBycomponent)) {
+      // represent the first load
+      cacheAdjustedSegmentEnergy[key] = value * firstView;
+
+      // then represent the subsequent load
+      cacheAdjustedSegmentEnergy[key] += value * returnView * dataReloadRatio;
+    }
+
+    return cacheAdjustedSegmentEnergy;
+  }
+
+  /**
+   * Accept a figure for bytes, and return the total figure for energy per visit
+   * using the default caching assumptions for loading a single website
+   *
+   * @param {number} bytes
+   * @return {number} the total energy use for the visit, after applying the caching assumptions
+   */
+  energyPerVisit(bytes) {
+    // fetch the values using the default caching assumptions
+    const energyValues = Object.values(this.energyPerVisitByComponent(bytes));
+
+    // return the summed of the values to return our single number
+    return energyValues.reduce(
+      (prevValue, currentValue) => prevValue + currentValue
+    );
+  }
+
+  // TODO: this method looks like it applies the carbon intensity
+  // change to the *entire* system, not just the datacenter.
+  emissionsPerVisitInGrams(energyPerVisit, carbonintensity = GLOBAL_INTENSITY) {
+    return formatNumber(energyPerVisit * carbonintensity);
+  }
+
+  annualEnergyInKwh(energyPerVisit, monthlyVisitors = 1000) {
+    return energyPerVisit * monthlyVisitors * 12;
+  }
+
+  annualEmissionsInGrams(co2grams, monthlyVisitors = 1000) {
+    return co2grams * monthlyVisitors * 12;
+  }
+
+  annualSegmentEnergy(annualEnergy) {
+    return {
+      consumerDeviceEnergy: formatNumber(annualEnergy * END_USER_DEVICE_ENERGY),
+      networkEnergy: formatNumber(annualEnergy * NETWORK_ENERGY),
+      dataCenterEnergy: formatNumber(annualEnergy * DATACENTER_ENERGY),
+      productionEnergy: formatNumber(annualEnergy * PRODUCTION_ENERGY),
+    };
+  }
+}
+
+module.exports = SustainableWebDesign;

package/src/sustainable-web-design.test.js

@@ -0,0 +1,81 @@
+const SustainableWebDesign = require("./sustainable-web-design");
+
+describe("sustainable web design model", () => {
+  const swd = new SustainableWebDesign();
+  const averageWebsiteInBytes = 2257715.2;
+
+  describe("energyPerByteByComponent", () => {
+    it("should return a object with numbers for each system component", () => {
+      const groupedEnergy = swd.energyPerByteByComponent(averageWebsiteInBytes);
+
+      expect(groupedEnergy.consumerDeviceEnergy).toBeCloseTo(0.00088564, 8);
+      expect(groupedEnergy.networkEnergy).toBeCloseTo(0.00023844, 8);
+      expect(groupedEnergy.productionEnergy).toBeCloseTo(0.0003236, 8);
+      expect(groupedEnergy.dataCenterEnergy).toBeCloseTo(0.00025547, 8);
+    });
+  });
+
+  describe("energyPerByte", () => {
+    it("should return a number in kilowatt hours for the given data transfer in bytes", () => {
+      const energyForTransfer = swd.energyPerByte(averageWebsiteInBytes);
+      expect(energyForTransfer).toBeCloseTo(0.00170316, 7);
+    });
+  });
+
+  describe("perByte", () => {
+    it("should return a single number for CO2 emissions", () => {
+      expect(typeof swd.perByte(2257715.2)).toBe("number");
+    });
+  });
+
+  describe("energyPerVisit", function () {
+    it("should return a number", () => {
+      expect(typeof swd.energyPerVisit(averageWebsiteInBytes)).toBe("number");
+    });
+
+    it("should calculate the correct energy", () => {
+      expect(swd.energyPerVisit(averageWebsiteInBytes)).toBe(
+        0.0004513362121582032
+      );
+    });
+  });
+
+  describe("emissionsPerVisitInGrams", function () {
+    it("should calculate the correct co2 per visit", () => {
+      const averageWebsiteInBytes = 2257715.2;
+      const energy = swd.energyPerVisit(averageWebsiteInBytes);
+      expect(swd.emissionsPerVisitInGrams(energy)).toEqual(0.2);
+    });
+
+    it("should accept a dynamic KwH value", () => {
+      const averageWebsiteInBytes = 2257715.2;
+      const energy = swd.energyPerVisit(averageWebsiteInBytes);
+      expect(swd.emissionsPerVisitInGrams(energy, 245)).toEqual(0.11);
+    });
+  });
+
+  describe("annualEnergyInKwh", function () {
+    it("should calculate the correct energy in kWh", () => {
+      expect(swd.annualEnergyInKwh(averageWebsiteInBytes)).toBe(27092582400);
+    });
+  });
+
+  describe("annualEmissionsInGrams", function () {
+    it("should calculate the corrent energy in grams", () => {
+      expect(swd.annualEmissionsInGrams(averageWebsiteInBytes)).toBe(
+        27092582400
+      );
+    });
+  });
+
+  describe("annualSegmentEnergy", function () {
+    it("should return the correct values", () => {
+      expect(swd.annualSegmentEnergy(averageWebsiteInBytes)).toEqual({
+        consumerDeviceEnergy: 1174011.9,
+        dataCenterEnergy: 338657.28,
+        networkEnergy: 316080.13,
+        productionEnergy: 428965.89,
+      });
+    });
+  });
+});