@tgwf/co2 0.6.1 → 0.9.0-0

package/.github/workflows/unittests.yml

@@ -0,0 +1,26 @@
+name: Unit tests
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x, 14.x, 16.x]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Install 
+      run: npm ci
+    - name: Verify lint
+      run: npm run lint
+    - name: Run unit tests
+      run: npm test

package/CHANGELOG.md

@@ -5,12 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 -
+
 ## Unreleased
 
 
-- Include the new alternative, "Green Byte Model" with the figures after speaking to folks at the IEA and other places.
 
-## ## [0.6.1] - 2020-03-15
+# [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
+
+### Fixed
+
+- Update further dependencies
+- Fix embarassing order of magnitude typo in 1byte model (thanks @mstaschik!)
+
+## Added
+
+- Read JSON blob also as gzipped #44 (thanks @soulgalore)
+
+### Changed
+
+- The 1byte model will give different numbers now. It's mentioned in `#fixed` but it's worth repeating.
+
+## [0.7.0] - 2021-11-28
+
+### Fixed
+
+- Update tests to avoid network requests #50
+- Update dependencies across the board
+
+### Changed
+
+- Switch to github actions instead of travis for CI.
+
+## [0.6.1] - 2020-03-15
 
 ### Fixed
 
@@ -35,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
 
 
@@ -57,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

@@ -1,40 +1,77 @@
 # CO2
 
-<img src="https://travis-ci.org/thegreenwebfoundation/co2.js.svg?branch=master" />
+<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 cando something about this though. The same way we use performance budgets make apps and website faster and cheaper to run, we can use carbon budgets to make them faster, cheaper and _greener_.
+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 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..
 
-It is currently used in the web performance tool [sitespeed.io][], to help developers build greener, more planet friendly digital services.
+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
 
+### Calculating emissions per byte
+
+#### Server-side
+
+This approach relies on the `fs` module and so can only be used on platforms like Node.js, that support this.
+
 ```js
 
 const CO2 = require('@tgwf/co2')
-const bytesSent = 1_000_000
+const bytesSent = (1024 * 1024 * 1024)
 const co2Emission = new CO2();
 estimatedCO2 = co2Emission.perByte(bytesSent)
 
-console.log(`Sending a million bytes, had a carbon footprint of ${estimatedCO2.toFixed(3)} grams of CO2`)
+console.log(`Sending a gigabyte, had a carbon footprint of ${estimatedCO2.toFixed(3)} grams of CO2`)
+
+```
+
+#### Browser-side
 
+For browser-based solutions, you must import the `co2.js` submodule directly from `node_modules`. For example, like this:
+
+```js
+
+const CO2 = require('node_modules/@tgwf/co2/src/co2.js')
+const bytesSent = (1024 * 1024 * 1024)
+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
+
 Because different digital services and websites use different forms of power, there is also a module for checking if a domain uses green power or not, and whether the domains linked to on a page use green power as well.
 
 ```js
@@ -44,25 +81,14 @@ const greencheck = require('@tgwf/hosting')
 // returns true if green, otherwise false
 greencheck.check("google.com")
 
-// returns an array of the green domains, in this case ["google.
-greencheck.check(["google.com", "kochindustries.com"]) com"]
+// returns an array of the green domains, in this case ["google.com"].
+greencheck.check(["google.com", "kochindustries.com"])]
 
 // returns an array of green domains, again in this case, ["google.com"]
 greencheck.checkPage(["google.com"])
 
 ```
 
-Please note, we currently look at just the carbon cost of _generating_ the electricity, similar to how the IEA does, not the full life cycle cost of the energy, which would include things like:
-
-- the carbon associated with digging up the fuel
-- the carbon associated with mining the materials to build the power stations, datacentres
-- 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
-
-We'd like to do this, and we know how complicated this is likely to be.
-
-
 # Licenses
 
 Apache 2.0
-

package/data/fixtures/url2green.test.json

@@ -1 +1 @@
-["google.com"]
+["google.com","maxcdn.bootstrapcdn.com","thegreenwebfoundation.org","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"]

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@tgwf/co2",
-  "version": "0.6.1",
+  "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"
@@ -21,15 +22,17 @@
   "author": "Chris Adams",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@tgwf/url2green": "^0.3.0",
-    "eslint": "6.8.0",
-    "eslint-config-prettier": "6.10.0",
-    "eslint-plugin-jest": "23.8.1",
-    "eslint-plugin-prettier": "3.1.2",
-    "jest": "25.1.0",
-    "np": "^5.2.1",
-    "pagexray": "^2.5.9",
-    "prettier": "1.19.1"
+    "@tgwf/url2green": "^0.4.0",
+    "eslint": "^8.3.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-jest": "^25.2.4",
+    "eslint-plugin-prettier": "^4.0.0",
+    "jest": "^27.3.1",
+    "minimist": "^1.2.5",
+    "nock": "^13.2.1",
+    "np": "^7.6.0",
+    "pagexray": "^4.3.1",
+    "prettier": "^2.4.1"
   },
   "np": {
     "yarn": false

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
@@ -9,19 +17,55 @@ const CO2_PER_KWH_IN_DC_GREY = 519;
 
 // The device usage figure combines figures for:
 //  1. the usage for devices (which is small proportion of the energy use)
-//  2. the *making* the device, which is comparitively high.
+//  2. the *making* the device, which is comparatively high.
 
-const KWH_PER_BYTE_IN_DC = 0.00000000072;
+const KWH_PER_BYTE_IN_DC = 7.2e-11;
 
 // this is probably best left as something users can define, or
 // a weighted average based on total usage.
+// Using a simple mean for now, as while web traffic to end users might trend
+// towards wifi and mobile,
+// Web traffic between servers is likely wired networks
+
+const FIXED_NETWORK_WIRED = 4.29e-10;
+const FIXED_NETWORK_WIFI = 1.52e-10;
+const FOUR_G_MOBILE = 8.84e-10;
+
 // Pull requests gratefully accepted
-const KWH_PER_BYTE_FOR_NETWORK = 0.00000000488;
+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;
+  }
+}
 
-const KWH_PER_BYTE_FOR_DEVICES = 0.00000000013;
 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

@@ -0,0 +1,17 @@
+"use strict";
+
+const oneByte = require("./1byte");
+
+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(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) {
@@ -57,10 +42,10 @@ class CO2 {
       co2PerDomain.push({
         domain,
         co2,
-        transferSize: pageXray.domains[domain].transferSize
+        transferSize: pageXray.domains[domain].transferSize,
       });
     }
-    co2PerDomain.sort(function(a, b) {
+    co2PerDomain.sort(function (a, b) {
       return b.co2 - a.co2;
     });
 
@@ -105,10 +90,10 @@ class CO2 {
       all.push({
         type,
         co2: co2PerContentType[type].co2,
-        transferSize: co2PerContentType[type].transferSize
+        transferSize: co2PerContentType[type].transferSize,
       });
     }
-    all.sort(function(a, b) {
+    all.sort(function (a, b) {
       return b.co2 - a.co2;
     });
     return all;
@@ -125,7 +110,7 @@ class CO2 {
       );
       allAssets.push({ url: asset.url, co2: co2ForTransfer, transferSize });
     }
-    allAssets.sort(function(a, b) {
+    allAssets.sort(function (a, b) {
       return b.co2 - a.co2;
     });