@tgwf/co2 0.11.4 → 0.12.0

package/src/constants/index.js

@@ -1,3 +1,40 @@
 import fileSize from "./file-size.js";
+import testConstants from "./test-constants.js";
 
-export { fileSize };
+// SUSTAINABLE WEB DESIGN CONSTANTS
+// 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_GRID_INTENSITY = 442;
+const RENEWABLES_GRID_INTENSITY = 50;
+
+// Taken from: https://gitlab.com/wholegrain/carbon-api-2-0/-/blob/master/includes/carbonapi.php
+
+const FIRST_TIME_VIEWING_PERCENTAGE = 0.75;
+const RETURNING_VISITOR_PERCENTAGE = 0.25;
+const PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD = 0.02;
+
+export {
+  fileSize,
+  testConstants,
+  KWH_PER_GB,
+  END_USER_DEVICE_ENERGY,
+  NETWORK_ENERGY,
+  DATACENTER_ENERGY,
+  PRODUCTION_ENERGY,
+  GLOBAL_GRID_INTENSITY,
+  RENEWABLES_GRID_INTENSITY,
+  FIRST_TIME_VIEWING_PERCENTAGE,
+  RETURNING_VISITOR_PERCENTAGE,
+  PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD,
+};

package/src/helpers/index.js

@@ -1,3 +1,175 @@
+import { averageIntensity } from "../index.js";
+import {
+  GLOBAL_GRID_INTENSITY,
+  PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD,
+  FIRST_TIME_VIEWING_PERCENTAGE,
+  RETURNING_VISITOR_PERCENTAGE,
+} from "../constants/index.js";
 const formatNumber = (num) => parseFloat(num.toFixed(2));
 
-export { formatNumber };
+function parseOptions(options) {
+  // CHeck that it is an object
+  if (typeof options !== "object") {
+    throw new Error("Options must be an object");
+  }
+
+  const adjustments = {};
+
+  if (options?.gridIntensity) {
+    adjustments.gridIntensity = {};
+    const { device, dataCenter, network } = options.gridIntensity;
+    if (device) {
+      if (typeof device === "object") {
+        if (!averageIntensity.data[device.country?.toUpperCase()]) {
+          console.warn(
+            `"${device.country}" is not a valid country. Please use a valid 3 digit ISO 3166 country code. \nSee https://developers.thegreenwebfoundation.org/co2js/data/ for more information. \nFalling back to global average grid intensity.`
+          );
+          adjustments.gridIntensity["device"] = {
+            value: GLOBAL_GRID_INTENSITY,
+          };
+        }
+        adjustments.gridIntensity["device"] = {
+          country: device.country,
+          value: parseFloat(
+            averageIntensity.data[device.country?.toUpperCase()]
+          ),
+        };
+      } else if (typeof device === "number") {
+        adjustments.gridIntensity["device"] = {
+          value: device,
+        };
+      } else {
+        adjustments.gridIntensity["device"] = {
+          value: GLOBAL_GRID_INTENSITY,
+        };
+        console.warn(
+          `The device grid intensity must be a number or an object. You passed in a ${typeof device}. \nFalling back to global average grid intensity.`
+        );
+      }
+    }
+    if (dataCenter) {
+      if (typeof dataCenter === "object") {
+        if (!averageIntensity.data[dataCenter.country?.toUpperCase()]) {
+          console.warn(
+            `"${dataCenter.country}" is not a valid country. Please use a valid 3 digit ISO 3166 country code. \nSee https://developers.thegreenwebfoundation.org/co2js/data/ for more information.  \nFalling back to global average grid intensity.`
+          );
+          adjustments.gridIntensity["dataCenter"] = {
+            value: GLOBAL_GRID_INTENSITY,
+          };
+        }
+        adjustments.gridIntensity["dataCenter"] = {
+          country: dataCenter.country,
+          value: parseFloat(
+            averageIntensity.data[dataCenter.country?.toUpperCase()]
+          ),
+        };
+      } else if (typeof dataCenter === "number") {
+        adjustments.gridIntensity["dataCenter"] = {
+          value: dataCenter,
+        };
+      } else {
+        adjustments.gridIntensity["dataCenter"] = {
+          value: GLOBAL_GRID_INTENSITY,
+        };
+        console.warn(
+          `The data center grid intensity must be a number or an object. You passed in a ${typeof dataCenter}. \nFalling back to global average grid intensity.`
+        );
+      }
+    }
+    if (network) {
+      if (typeof network === "object") {
+        if (!averageIntensity.data[network.country?.toUpperCase()]) {
+          console.warn(
+            `"${network.country}" is not a valid country. Please use a valid 3 digit ISO 3166 country code. \nSee https://developers.thegreenwebfoundation.org/co2js/data/ for more information.  Falling back to global average grid intensity. \nFalling back to global average grid intensity.`
+          );
+          adjustments.gridIntensity["network"] = {
+            value: GLOBAL_GRID_INTENSITY,
+          };
+        }
+        adjustments.gridIntensity["network"] = {
+          country: network.country,
+          value: parseFloat(
+            averageIntensity.data[network.country?.toUpperCase()]
+          ),
+        };
+      } else if (typeof network === "number") {
+        adjustments.gridIntensity["network"] = {
+          value: network,
+        };
+      } else {
+        adjustments.gridIntensity["network"] = {
+          value: GLOBAL_GRID_INTENSITY,
+        };
+        console.warn(
+          `The network grid intensity must be a number or an object. You passed in a ${typeof network}. \nFalling back to global average grid intensity.`
+        );
+      }
+    }
+  }
+
+  if (options?.dataReloadRatio) {
+    if (typeof options.dataReloadRatio === "number") {
+      if (options.dataReloadRatio >= 0 && options.dataReloadRatio <= 1) {
+        adjustments.dataReloadRatio = options.dataReloadRatio;
+      } else {
+        adjustments.dataReloadRatio =
+          PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD;
+        console.warn(
+          `The dataReloadRatio option must be a number between 0 and 1. You passed in ${options.dataReloadRatio}. \nFalling back to default value.`
+        );
+      }
+    } else {
+      adjustments.dataReloadRatio =
+        PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD;
+      console.warn(
+        `The dataReloadRatio option must be a number. You passed in a ${typeof options.dataReloadRatio}. \nFalling back to default value.`
+      );
+    }
+  }
+
+  if (options?.firstVisitPercentage) {
+    if (typeof options.firstVisitPercentage === "number") {
+      if (
+        options.firstVisitPercentage >= 0 &&
+        options.firstVisitPercentage <= 1
+      ) {
+        adjustments.firstVisitPercentage = options.firstVisitPercentage;
+      } else {
+        adjustments.firstVisitPercentage = FIRST_TIME_VIEWING_PERCENTAGE;
+        console.warn(
+          `The firstVisitPercentage option must be a number between 0 and 1. You passed in ${options.firstVisitPercentage}. \nFalling back to default value.`
+        );
+      }
+    } else {
+      adjustments.firstVisitPercentage = FIRST_TIME_VIEWING_PERCENTAGE;
+      console.warn(
+        `The firstVisitPercentage option must be a number. You passed in a ${typeof options.firstVisitPercentage}. \nFalling back to default value.`
+      );
+    }
+  }
+
+  if (options?.returnVisitPercentage) {
+    if (typeof options.returnVisitPercentage === "number") {
+      if (
+        options.returnVisitPercentage >= 0 &&
+        options.returnVisitPercentage <= 1
+      ) {
+        adjustments.returnVisitPercentage = options.returnVisitPercentage;
+      } else {
+        adjustments.returnVisitPercentage = RETURNING_VISITOR_PERCENTAGE;
+        console.warn(
+          `The returnVisitPercentage option must be a number between 0 and 1. You passed in ${options.returnVisitPercentage}. \nFalling back to default value.`
+        );
+      }
+    } else {
+      adjustments.returnVisitPercentage = RETURNING_VISITOR_PERCENTAGE;
+      console.warn(
+        `The returnVisitPercentage option must be a number. You passed in a ${typeof options.returnVisitPercentage}. \nFalling back to default value.`
+      );
+    }
+  }
+
+  return adjustments;
+}
+
+export { formatNumber, parseOptions };

package/src/sustainable-web-design.js

@@ -6,36 +6,25 @@
  * Updated calculations and figures from
  * https://sustainablewebdesign.org/calculating-digital-emissions/
  *
- *
  */
 import debugFactory from "debug";
 const log = debugFactory("tgwf:sustainable-web-design");
 
-import { fileSize } from "./constants/index.js";
+import {
+  fileSize,
+  KWH_PER_GB,
+  END_USER_DEVICE_ENERGY,
+  NETWORK_ENERGY,
+  DATACENTER_ENERGY,
+  PRODUCTION_ENERGY,
+  GLOBAL_GRID_INTENSITY,
+  RENEWABLES_GRID_INTENSITY,
+  FIRST_TIME_VIEWING_PERCENTAGE,
+  RETURNING_VISITOR_PERCENTAGE,
+  PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD,
+} from "./constants/index.js";
 import { formatNumber } from "./helpers/index.js";
 
-// 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.75;
-const RETURNING_VISITOR_PERCENTAGE = 0.25;
-const PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD = 0.02;
-
 class SustainableWebDesign {
   constructor(options) {
     this.options = options;
@@ -65,24 +54,61 @@ class SustainableWebDesign {
    * 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 {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) {
+  co2byComponent(
+    energyByComponent,
+    carbonIntensity = GLOBAL_GRID_INTENSITY,
+    options = {}
+  ) {
+    let deviceCarbonIntensity = GLOBAL_GRID_INTENSITY;
+    let networkCarbonIntensity = GLOBAL_GRID_INTENSITY;
+    let dataCenterCarbonIntensity = GLOBAL_GRID_INTENSITY;
+
+    let globalEmissions = GLOBAL_GRID_INTENSITY;
+
+    if (options?.gridIntensity) {
+      const { device, network, dataCenter } = options.gridIntensity;
+
+      if (device?.value) {
+        deviceCarbonIntensity = device.value;
+      }
+      if (network?.value) {
+        networkCarbonIntensity = network.value;
+      }
+      // If the user has set a carbon intensity value for the datacentre, then that overrides everything and is used
+      if (dataCenter?.value) {
+        dataCenterCarbonIntensity = dataCenter.value;
+      }
+    }
+
+    // If the user passes in a TRUE value (green web host), then use the renewables intensity value
+    if (carbonIntensity === true) {
+      dataCenterCarbonIntensity = RENEWABLES_GRID_INTENSITY;
+    }
+
     const returnCO2ByComponent = {};
-    for (const [key, value] of Object.entries(energyBycomponent)) {
+    for (const [key, value] of Object.entries(energyByComponent)) {
       // we update the datacentre, as that's what we have information
       // about.
       if (key.startsWith("dataCenterEnergy")) {
-        returnCO2ByComponent[key] = value * carbonIntensity;
+        returnCO2ByComponent[key.replace("Energy", "CO2")] =
+          value * dataCenterCarbonIntensity;
+      } else if (key.startsWith("consumerDeviceEnergy")) {
+        returnCO2ByComponent[key.replace("Energy", "CO2")] =
+          value * deviceCarbonIntensity;
+      } else if (key.startsWith("networkEnergy")) {
+        returnCO2ByComponent[key.replace("Energy", "CO2")] =
+          value * networkCarbonIntensity;
       } 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;
+        // Use the global intensity for the remaining segments
+        returnCO2ByComponent[key.replace("Energy", "CO2")] =
+          value * globalEmissions;
       }
     }
+
     return returnCO2ByComponent;
   }
 
@@ -96,38 +122,38 @@ class SustainableWebDesign {
    * @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;
-    }
+  perByte(
+    bytes,
+    carbonIntensity = false,
+    segmentResults = false,
+    options = {}
+  ) {
+    const energyBycomponent = this.energyPerByteByComponent(bytes, options);
 
     // otherwise when faced with non numeric values throw an error
-    if (typeof carbonIntensity !== "number") {
+    if (typeof carbonIntensity !== "boolean") {
       throw new Error(
-        `perByte expects a numeric value or boolean for the carbon intensity value. Received: ${carbonIntensity}`
+        `perByte expects a boolean for the carbon intensity value. Received: ${carbonIntensity}`
       );
     }
 
     const co2ValuesbyComponent = this.co2byComponent(
       energyBycomponent,
-      carbonIntensity
+      carbonIntensity,
+      options
     );
 
     // pull out our values…
     const co2Values = Object.values(co2ValuesbyComponent);
-
-    // so we can return their sum
-    return co2Values.reduce(
+    const co2ValuesSum = co2Values.reduce(
       (prevValue, currentValue) => prevValue + currentValue
     );
+
+    if (segmentResults) {
+      return { ...co2ValuesbyComponent, total: co2ValuesSum };
+    }
+
+    return co2ValuesSum;
   }
 
   /**
@@ -138,38 +164,39 @@ class SustainableWebDesign {
    * @param {number} `carbonIntensity` the carbon intensity for datacentre (average figures, not marginal ones)
    * @return {number} the total number in grams of CO2 equivalent emissions
    */
-  perVisit(bytes, carbonIntensity = GLOBAL_INTENSITY) {
-    const energyBycomponent = this.energyPerVisitByComponent(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;
-    }
+  perVisit(
+    bytes,
+    carbonIntensity = false,
+    segmentResults = false,
+    options = {}
+  ) {
+    const energyBycomponent = this.energyPerVisitByComponent(bytes, options);
 
-    // otherwise when faced with non numeric values throw an error
-    if (typeof carbonIntensity !== "number") {
+    if (typeof carbonIntensity !== "boolean") {
+      // otherwise when faced with non numeric values throw an error
       throw new Error(
-        `perVisit expects a numeric value or boolean for the carbon intensity value. Received: ${carbonIntensity}`
+        `perVisit expects a boolean for the carbon intensity value. Received: ${carbonIntensity}`
       );
     }
 
     const co2ValuesbyComponent = this.co2byComponent(
       energyBycomponent,
-      carbonIntensity
+      carbonIntensity,
+      options
     );
 
     // pull out our values…
     const co2Values = Object.values(co2ValuesbyComponent);
-
-    // so we can return their sum
-    return co2Values.reduce(
+    const co2ValuesSum = co2Values.reduce(
       (prevValue, currentValue) => prevValue + currentValue
     );
+
+    if (segmentResults) {
+      return { ...co2ValuesbyComponent, total: co2ValuesSum };
+    }
+
+    // so we can return their sum
+    return co2ValuesSum;
   }
 
   /**
@@ -207,10 +234,23 @@ class SustainableWebDesign {
    */
   energyPerVisitByComponent(
     bytes,
+    options = {},
     firstView = FIRST_TIME_VIEWING_PERCENTAGE,
     returnView = RETURNING_VISITOR_PERCENTAGE,
     dataReloadRatio = PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD
   ) {
+    if (options.dataReloadRatio) {
+      dataReloadRatio = options.dataReloadRatio;
+    }
+
+    if (options.firstVisitPercentage) {
+      firstView = options.firstVisitPercentage;
+    }
+
+    if (options.returnVisitPercentage) {
+      returnView = options.returnVisitPercentage;
+    }
+
     const energyBycomponent = this.energyPerByteByComponent(bytes);
     const cacheAdjustedSegmentEnergy = {};
 
@@ -264,9 +304,10 @@ class SustainableWebDesign {
     return firstVisits + subsequentVisits;
   }
 
-  // TODO: this method looks like it applies the carbon intensity
-  // change to the *entire* system, not just the datacenter.
-  emissionsPerVisitInGrams(energyPerVisit, carbonintensity = GLOBAL_INTENSITY) {
+  emissionsPerVisitInGrams(
+    energyPerVisit,
+    carbonintensity = GLOBAL_GRID_INTENSITY
+  ) {
     return formatNumber(energyPerVisit * carbonintensity);
   }
 

package/dist/cjs/1byte.test.js

@@ -1,27 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod));
-var import_byte = __toESM(require("./1byte.js"));
-describe("onebyte", () => {
-  describe("perByte", () => {
-    it("returns a simple average of the different networks", () => {
-      const expected_val = 488e-12 .toFixed(12);
-      const instance = new import_byte.default();
-      expect(instance.KWH_PER_BYTE_FOR_NETWORK.toFixed(12)).toBe(expected_val);
-    });
-  });
-});
-//# sourceMappingURL=1byte.test.js.map

package/dist/cjs/1byte.test.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/1byte.test.js"],
-  "sourcesContent": ["\"use strict\";\n\nimport OneByte from \"./1byte.js\";\n\ndescribe(\"onebyte\", () => {\n  describe(\"perByte\", () => {\n    it(\"returns a simple average of the different networks\", () => {\n      // we limit this to 12 figures with toFixed(12), because\n      // we have a recurring 333333 afterwards\n      // 4.88e-10 is the same as 0.000000000488\n      const expected_val = (0.000000000488).toFixed(12);\n      const instance = new OneByte();\n\n      expect(instance.KWH_PER_BYTE_FOR_NETWORK.toFixed(12)).toBe(expected_val);\n    });\n  });\n});\n"],
-  "mappings": ";;;;;;;;;;;;;;;;AAEA,kBAAoB;AAEpB,SAAS,WAAW,MAAM;AACxB,WAAS,WAAW,MAAM;AACxB,OAAG,sDAAsD,MAAM;AAI7D,YAAM,eAAgB,SAAgB,QAAQ,EAAE;AAChD,YAAM,WAAW,IAAI,oBAAQ;AAE7B,aAAO,SAAS,yBAAyB,QAAQ,EAAE,CAAC,EAAE,KAAK,YAAY;AAAA,IACzE,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
-  "names": []
-}