@tgwf/co2 0.4.7 → 0.7.0

package/.all-contributorsrc

@@ -5,10 +5,35 @@
   "imageSize": 100,
   "commit": false,
   "contributors": [
+    {
+      "login": "JamieBeevor",
+      "name": "JamieB",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/26165947?v=4",
+      "profile": "https://greengumption.co.uk",
+      "contributions": [
+        "ideas",
+        "question",
+        "review"
+      ]
+    },
+    {
+    "login": "soulgalore",
+      "name": "Peter Hedenskog",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/540757?v=4",
+      "profile": "https://www.peterhedenskog.com",
+      "contributions": [
+        "code",
+        "ideas",
+        "review",
+        "infra",
+        "docs"
+      ]
+    }
   ],
   "contributorsPerLine": 7,
-  "projectName": "co2",
+  "projectName": "co2.js",
   "projectOwner": "thegreenwebfoundation",
   "repoType": "github",
-  "repoHost": "https://github.com"
+  "repoHost": "https://github.com",
+  "skipCi": true
 }

package/.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "root": true,
+  "env": {
+    "node": true,
+    "es6": true,
+    "jest/globals": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 8
+  },
+  "plugins": ["prettier", "jest"],
+  "extends": "eslint:recommended",
+  "rules": {
+    "prettier/prettier": [
+      "error",
+      {
+      }
+    ],
+    "no-unused-vars": "off"
+  }
+}

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

@@ -4,6 +4,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 a new alternative, "Green Byte Model" with the figures after speaking to folks at the IEA and other places.
+## [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
+
+- Added the function to load JSON, on the tgwg.hosting object, for use in the sustaiable web sitespeed plugin.
+
+## [0.6.0] - 2020-03-15
+
+### Added
+
+- Added the hosting-JSON for running local checks against an array instead of SQLite.
+
+### Changed
+
+- Swapped out checking against a sqlite database `hosting-json`in favour of simple array in,
+- Updated conventions for style - using kebab-cases over CamelCase for naming files
+
+### Removed
+
+- Extracted sqlite usage and dependencies into a separate module, `url2green`. This means  you no longer need to compile SQLite on install.
+
+## [0.5.0] - 2020-03-03
+
+### Changed
+
+- Update README
+- Update the emissions figured for green energy after further research on methodology with @@JamieBeevor
+- Incorproate class based CO2 models from @soulgalore
+- Credit contributors
+
 
 ## [0.4.7] - 2020-03-02
 

package/README.md

@@ -1,45 +1,97 @@
 # 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.
 
-The CO2 package from [The Green Web Foundation][tgwf] lets you quickly estimate these emissions, to allow people who build digital services to optimise for carbon, the same way we use performance budgets to optimise our software.
+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.
 
-It is currently used in the web performance tool [sitespeed.io], to help developers build greener, more planet friendly digital services.
+It is currently used in the web performance tool [sitespeed.io][], 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].
 
 [soberDigital]: https://theshiftproject.org/en/lean-ict-2/
-[sitespeedio]: https://sitespeed.io/
+[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 CO2 = require('@tgwf/co2')
+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`)
+
+```
+
+#### Browser-side
+
+For browser-based solutions, you must import the `co2.js` submodule directly from `node_modules`. For example, like this:
 
-estimatedCO2 = co2.perByte(bytesSent)
+```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 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`)
 
 ```
 
+### 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
 
 const greencheck = require('@tgwf/hosting')
 
-greencheck.check("google.com") // returns true if green, otherwise false
-greencheck.check(["google.com", "kochindustries.com"]) // returns an array of the green domains, in this case ["google.com"]
-greencheck.checkPage(["google.com"]) // returns an array of green domains, again in this case, ["google.com"]
+// returns true if green, otherwise false
+greencheck.check("google.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"])
 
 ```
 
+### 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/data/fixtures/url2green.test.json

@@ -0,0 +1 @@
+["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,13 @@
 {
   "name": "@tgwf/co2",
-  "version": "0.4.7",
+  "version": "0.7.0",
   "description": "Work out the co2 of your digital services",
   "main": "src/index.js",
   "scripts": {
-    "test": "jest"
+    "test": "jest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "travis": "npm run lint && jest"
   },
   "keywords": [
     "sustainability",
@@ -18,9 +21,17 @@
   "author": "Chris Adams",
   "license": "Apache-2.0",
   "devDependencies": {
-    "np": "^5.2.1",
-    "pagexray": "^2.5.9",
-    "jest": "25.1.0"
+    "@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
@@ -29,7 +40,10 @@
     "access": "public"
   },
   "dependencies": {
-    "better-sqlite3": "^5.4.3",
     "debug": "^4.1.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thegreenwebfoundation/co2.js.git"
   }
 }

package/src/1byte.js

@@ -1,4 +1,3 @@
-
 // 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;
 
@@ -19,10 +18,10 @@ const KWH_PER_BYTE_IN_DC = 0.00000000072;
 // Pull requests gratefully accepted
 const KWH_PER_BYTE_FOR_NETWORK = 0.00000000488;
 
-const KWH_PER_BYTE_FOR_DEVICES = 0.00000000013
+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
-}
+  CO2_PER_KWH_IN_DC_GREY,
+};

package/src/co2.js

@@ -1,166 +1,157 @@
-'use strict';
+"use strict";
 
-const url = require('url');
-const oneByte = require('./1byte.js');
+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
+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 = 495;
+const CO2_PER_KWH_NETWORK_GREY = 475;
 
-// the better way would be do to this with a weighted average of types of RE generation
-// from solar, to wind, to biomass, and hydro and so on, based on how much they
-// are used.
-// For now, let's use a quoted figure from Ecotricity, which quotes OFGEM, the UK regulator
-// and it's better than most quoted figures which pretend there is *no* footprint
-// for RE.
-// More here:
-// https://www.ecotricity.co.uk/layout/set/popup/layout/set/print/for-your-home/britain-s-greenest-energy-company/lifecycle-carbon-emissions
-// https://twitter.com/mrchrisadams/status/1227972969756086284
-// https://en.wikipedia.org/wiki/Life-cycle_greenhouse-gas_emissions_of_energy_sources
+// 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 CO2_PER_KWH_IN_DC_GREEN = 33;
+class CO2 {
+  constructor(options) {
+    this.options = options;
+  }
 
+  perByte(bytes, green) {
+    // return a CO2 figure for energy used to shift the corresponding
+    // the data transfer.
 
-function getCO2PerByte(bytes, green) {
-  // return a CO2 figure for energy used to shift the corresponding
-  // the data transfer.
+    if (bytes < 1) {
+      return 0;
+    }
 
-  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;
 
-  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;
 
-    // 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;
+    }
 
-    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 KwHPerByte = KWH_PER_BYTE_IN_DC + KWH_PER_BYTE_FOR_NETWORK;
-  return bytes * KwHPerByte * CO2_PER_KWH_IN_DC_GREY;
-}
-
-function getCO2PerDomain(pageXray, greenDomains) {
-  const co2PerDomain = [];
-  for (let domain of Object.keys(pageXray.domains)) {
-    let co2;
-    if (greenDomains && greenDomains.indexOf(domain) > -1) {
-      co2 = getCO2PerByte(pageXray.domains[domain].transferSize, true);
-    } else {
-      co2 = getCO2PerByte(pageXray.domains[domain].transferSize);
+  perDomain(pageXray, greenDomains) {
+    const co2PerDomain = [];
+    for (let domain of Object.keys(pageXray.domains)) {
+      let co2;
+      if (greenDomains && greenDomains.indexOf(domain) > -1) {
+        co2 = this.perByte(pageXray.domains[domain].transferSize, true);
+      } else {
+        co2 = this.perByte(pageXray.domains[domain].transferSize);
+      }
+      co2PerDomain.push({
+        domain,
+        co2,
+        transferSize: pageXray.domains[domain].transferSize,
+      });
     }
-    co2PerDomain.push({
-      domain,
-      co2,
-      transferSize: pageXray.domains[domain].transferSize
+    co2PerDomain.sort(function (a, b) {
+      return b.co2 - a.co2;
     });
-  }
-  co2PerDomain.sort(function (a, b) {
-    return b.co2 - a.co2;
-  });
 
-  return co2PerDomain;
-}
+    return co2PerDomain;
+  }
 
-function getCO2perPage(pageXray, green) {
-  // Accept an xray object, and if we receive a boolean as the second
-  // argument, we assume every request we make is sent to a server
-  // running on renwewable power.
+  perPage(pageXray, green) {
+    // Accept an xray object, and if we receive a boolean as the second
+    // argument, we assume every request we make is sent to a server
+    // running on renwewable power.
 
-  // if we receive an array of domains, return a number accounting the
-  // reduced CO2 from green hosted domains
+    // if we receive an array of domains, return a number accounting the
+    // reduced CO2 from green hosted domains
 
-  const domainCO2 = getCO2PerDomain(pageXray, green);
-  let totalCO2 = 0;
-  for (let domain of domainCO2) {
-    totalCO2 += domain.co2;
+    const domainCO2 = this.perDomain(pageXray, green);
+    let totalCO2 = 0;
+    for (let domain of domainCO2) {
+      totalCO2 += domain.co2;
+    }
+    return totalCO2;
   }
-  return totalCO2;
-}
 
-function getCO2PerContentType(pageXray, greenDomains) {
-  const co2PerContentType = {};
-  for (let asset of pageXray.assets) {
-    const domain = url.parse(asset.url).domain;
-    const transferSize = asset.transferSize;
-    const co2ForTransfer = getCO2PerByte(
-      transferSize,
-      greenDomains && greenDomains.indexOf(domain) > -1
-    );
-    const contentType = asset.type;
-    if (!co2PerContentType[contentType]) {
-      co2PerContentType[contentType] = { co2: 0, transferSize: 0 };
+  perContentType(pageXray, greenDomains) {
+    const co2PerContentType = {};
+    for (let asset of pageXray.assets) {
+      const domain = url.parse(asset.url).domain;
+      const transferSize = asset.transferSize;
+      const co2ForTransfer = this.perByte(
+        transferSize,
+        greenDomains && greenDomains.indexOf(domain) > -1
+      );
+      const contentType = asset.type;
+      if (!co2PerContentType[contentType]) {
+        co2PerContentType[contentType] = { co2: 0, transferSize: 0 };
+      }
+      co2PerContentType[contentType].co2 += co2ForTransfer;
+      co2PerContentType[contentType].transferSize += transferSize;
     }
-    co2PerContentType[contentType].co2 += co2ForTransfer;
-    co2PerContentType[contentType].transferSize += transferSize;
-  }
-  // restructure and sort
-  const all = [];
-  for (let type of Object.keys(co2PerContentType)) {
-    all.push({
-      type,
-      co2: co2PerContentType[type].co2,
-      transferSize: co2PerContentType[type].transferSize
+    // restructure and sort
+    const all = [];
+    for (let type of Object.keys(co2PerContentType)) {
+      all.push({
+        type,
+        co2: co2PerContentType[type].co2,
+        transferSize: co2PerContentType[type].transferSize,
+      });
+    }
+    all.sort(function (a, b) {
+      return b.co2 - a.co2;
     });
+    return all;
   }
-  all.sort(function (a, b) {
-    return b.co2 - a.co2;
-  });
-  return all;
-}
 
-function dirtiestResources(pageXray, greenDomains) {
-  const allAssets = [];
-  for (let asset of pageXray.assets) {
-    const domain = url.parse(asset.url).domain;
-    const transferSize = asset.transferSize;
-    const co2ForTransfer = getCO2PerByte(
-      transferSize,
-      greenDomains && greenDomains.indexOf(domain) > -1
-    );
-    allAssets.push({ url: asset.url, co2: co2ForTransfer, transferSize });
-  }
-  allAssets.sort(function (a, b) {
-    return b.co2 - a.co2;
-  });
+  dirtiestResources(pageXray, greenDomains) {
+    const allAssets = [];
+    for (let asset of pageXray.assets) {
+      const domain = url.parse(asset.url).domain;
+      const transferSize = asset.transferSize;
+      const co2ForTransfer = this.perByte(
+        transferSize,
+        greenDomains && greenDomains.indexOf(domain) > -1
+      );
+      allAssets.push({ url: asset.url, co2: co2ForTransfer, transferSize });
+    }
+    allAssets.sort(function (a, b) {
+      return b.co2 - a.co2;
+    });
 
-  return allAssets.slice(0, allAssets.length > 10 ? 10 : allAssets.length);
-}
+    return allAssets.slice(0, allAssets.length > 10 ? 10 : allAssets.length);
+  }
 
-function getCO2PerParty(pageXray, greenDomains) {
-  let firstParty = 0;
-  let thirdParty = 0;
-  // calculate co2 per first/third party
-  const firstPartyRegEx = pageXray.firstPartyRegEx;
-  for (let d of Object.keys(pageXray.domains)) {
-    if (!d.match(firstPartyRegEx)) {
-      thirdParty += getCO2PerByte(
-        pageXray.domains[d].transferSize,
-        greenDomains && greenDomains.indexOf(d) > -1
-      );
-    } else {
-      firstParty += getCO2PerByte(
-        pageXray.domains[d].transferSize,
-        greenDomains && greenDomains.indexOf(d) > -1
-      );
+  perParty(pageXray, greenDomains) {
+    let firstParty = 0;
+    let thirdParty = 0;
+    // calculate co2 per first/third party
+    const firstPartyRegEx = pageXray.firstPartyRegEx;
+    for (let d of Object.keys(pageXray.domains)) {
+      if (!d.match(firstPartyRegEx)) {
+        thirdParty += this.perByte(
+          pageXray.domains[d].transferSize,
+          greenDomains && greenDomains.indexOf(d) > -1
+        );
+      } else {
+        firstParty += this.perByte(
+          pageXray.domains[d].transferSize,
+          greenDomains && greenDomains.indexOf(d) > -1
+        );
+      }
     }
+    return { firstParty, thirdParty };
   }
-  return { firstParty, thirdParty };
 }
 
-module.exports = {
-  perByte: getCO2PerByte,
-  perDomain: getCO2PerDomain,
-  perPage: getCO2perPage,
-  perParty: getCO2PerParty,
-  perContentType: getCO2PerContentType,
-  dirtiestResources
-};
+module.exports = CO2;