@tgwf/co2 0.16.6 → 0.16.8

package/dist/esm/index.js

@@ -2,11 +2,11 @@ import co2 from "./co2.js";
 import hosting from "./hosting.js";
 import averageIntensity from "./data/average-intensities.min.js";
 import marginalIntensity from "./data/marginal-intensities-2021.min.js";
-var src_default = { co2, hosting, averageIntensity, marginalIntensity };
+var index_default = { co2, hosting, averageIntensity, marginalIntensity };
 export {
   averageIntensity,
   co2,
-  src_default as default,
+  index_default as default,
   hosting,
   marginalIntensity
 };

package/dist/esm/sustainable-web-design-v3.js

@@ -37,6 +37,14 @@ class SustainableWebDesign {
     this.options = options;
     this.version = 3;
   }
+  /**
+   * 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;
@@ -47,6 +55,14 @@ class SustainableWebDesign {
       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_GRID_INTENSITY, options = {}) {
     let deviceCarbonIntensity = GLOBAL_GRID_INTENSITY;
     let networkCarbonIntensity = GLOBAL_GRID_INTENSITY;
@@ -81,6 +97,19 @@ class SustainableWebDesign {
     }
     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 data centre share of the carbon intensity.
+   *
+   * @param {number} bytes - the data transferred in bytes
+   * @param {boolean} carbonIntensity - a boolean indicating whether the data center is green or not
+   * @param {boolean} segmentResults - a boolean indicating whether to return the results broken down by component
+   * @param {boolean} ratingResults - a boolean indicating whether to return the rating based on the Sustainable Web Design Model
+   * @param {object} options - an object containing the grid intensity and first/return visitor values
+   * @return {number|object} the total number in grams of CO2 equivalent emissions, or an object containing the breakdown by component
+   */
   perByte(bytes, carbonIntensity = false, segmentResults = false, ratingResults = false, options = {}) {
     if (bytes < 1) {
       bytes = 0;
@@ -88,7 +117,7 @@ class SustainableWebDesign {
     const energyBycomponent = this.energyPerByteByComponent(bytes, options);
     if (typeof carbonIntensity !== "boolean") {
       throw new Error(
-        `perByte expects a boolean for the carbon intensity value. Received: ${carbonIntensity}`
+        "perByte expects a boolean for the carbon intensity value. Received: ".concat(carbonIntensity)
       );
     }
     const co2ValuesbyComponent = this.co2byComponent(
@@ -118,11 +147,22 @@ class SustainableWebDesign {
     }
     return co2ValuesSum;
   }
+  /**
+   * Accept a figure for bytes transferred and return a single figure for CO2
+   * emissions. This method applies caching assumptions from the original Sustainable Web Design model.
+   *
+   * @param {number} bytes - the data transferred in bytes
+   * @param {boolean} carbonIntensity - a boolean indicating whether the data center is green or not
+   * @param {boolean} segmentResults - a boolean indicating whether to return the results broken down by component
+   * @param {boolean} ratingResults - a boolean indicating whether to return the rating based on the Sustainable Web Design Model
+   * @param {object} options - an object containing the grid intensity and first/return visitor values
+   * @return {number|object} the total number in grams of CO2 equivalent emissions, or an object containing the breakdown by component
+   */
   perVisit(bytes, carbonIntensity = false, segmentResults = false, ratingResults = false, options = {}) {
     const energyBycomponent = this.energyPerVisitByComponent(bytes, options);
     if (typeof carbonIntensity !== "boolean") {
       throw new Error(
-        `perVisit expects a boolean for the carbon intensity value. Received: ${carbonIntensity}`
+        "perVisit expects a boolean for the carbon intensity value. Received: ".concat(carbonIntensity)
       );
     }
     const co2ValuesbyComponent = this.co2byComponent(
@@ -152,6 +192,13 @@ class SustainableWebDesign {
     }
     return co2ValuesSum;
   }
+  /**
+   * 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);
     const energyValues = Object.values(energyByComponent);
@@ -159,6 +206,20 @@ class SustainableWebDesign {
       (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, options = {}, firstView = FIRST_TIME_VIEWING_PERCENTAGE, returnView = RETURNING_VISITOR_PERCENTAGE, dataReloadRatio = PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD) {
     if (options.dataReloadRatio || options.dataReloadRatio === 0) {
       dataReloadRatio = options.dataReloadRatio;
@@ -173,11 +234,18 @@ class SustainableWebDesign {
     const cacheAdjustedSegmentEnergy = {};
     const energyValues = Object.values(energyBycomponent);
     for (const [key, value] of Object.entries(energyBycomponent)) {
-      cacheAdjustedSegmentEnergy[`${key} - first`] = value * firstView;
-      cacheAdjustedSegmentEnergy[`${key} - subsequent`] = value * returnView * dataReloadRatio;
+      cacheAdjustedSegmentEnergy["".concat(key, " - first")] = value * firstView;
+      cacheAdjustedSegmentEnergy["".concat(key, " - subsequent")] = 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) {
     let firstVisits = 0;
     let subsequentVisits = 0;
@@ -213,6 +281,12 @@ class SustainableWebDesign {
       productionEnergy: formatNumber(annualEnergy * PRODUCTION_ENERGY)
     };
   }
+  /**
+   * Determines the rating of a website's sustainability based on its CO2 emissions.
+   *
+   * @param {number} co2e - The CO2 emissions of the website in grams.
+   * @returns {string} The sustainability rating, ranging from "A+" (best) to "F" (worst).
+   */
   ratingScale(co2e) {
     return outputRating(co2e, this.version);
   }

package/dist/esm/sustainable-web-design-v4.js

@@ -62,6 +62,12 @@ class SustainableWebDesign {
     this.options = options;
     this.version = 4;
   }
+  /**
+   * Calculate the operational energy of data transfer for each system segment
+   *
+   * @param {number} bytes
+   * @returns {object}
+   */
   operationalEnergyPerSegment(bytes) {
     const transferedBytesToGb = bytes / fileSize.GIGABYTE;
     const dataCenter = transferedBytesToGb * OPERATIONAL_KWH_PER_GB_DATACENTER;
@@ -73,6 +79,13 @@ class SustainableWebDesign {
       device
     };
   }
+  /**
+   * Calculate the operational emissions of data transfer for each system segment
+   *
+   * @param {number} bytes
+   * @param {object} options
+   * @returns {object}
+   */
   operationalEmissions(bytes, options = {}) {
     const { dataCenter, network, device } = this.operationalEnergyPerSegment(bytes);
     let dataCenterGridIntensity = GLOBAL_GRID_INTENSITY;
@@ -99,6 +112,12 @@ class SustainableWebDesign {
       device: deviceEmissions
     };
   }
+  /**
+   * Calculate the embodied energy of data transfer for each system segment
+   *
+   * @param {number} bytes
+   * @returns {object}
+   */
   embodiedEnergyPerSegment(bytes) {
     const transferedBytesToGb = bytes / fileSize.GIGABYTE;
     const dataCenter = transferedBytesToGb * EMBODIED_KWH_PER_GB_DATACENTER;
@@ -110,6 +129,12 @@ class SustainableWebDesign {
       device
     };
   }
+  /**
+   * Calculate the embodied emissions of data transfer for each system segment
+   *
+   * @param {number} bytes
+   * @returns {object}
+   */
   embodiedEmissions(bytes) {
     const { dataCenter, network, device } = this.embodiedEnergyPerSegment(bytes);
     const dataCenterGridIntensity = GLOBAL_GRID_INTENSITY;
@@ -124,6 +149,7 @@ class SustainableWebDesign {
       device: deviceEmissions
     };
   }
+  // NOTE: Setting green: true should result in a greenHostingFactor of 1.0
   perByte(bytes, green = false, segmented = false, ratingResults = false, options = {}) {
     if (bytes < 1) {
       return 0;
@@ -176,7 +202,7 @@ class SustainableWebDesign {
       dataReloadRatio = options.dataReloadRatio;
     }
     const firstVisitEmissions = operationalEmissions.dataCenter * (1 - greenHostingFactor) + embodiedEmissions.dataCenter + operationalEmissions.network + embodiedEmissions.network + operationalEmissions.device + embodiedEmissions.device;
-    const returnVisitEmissions = (operationalEmissions.dataCenter * (1 - greenHostingFactor) + embodiedEmissions.dataCenter + operationalEmissions.network + embodiedEmissions.network + operationalEmissions.device + embodiedEmissions.device) * (1 - dataReloadRatio);
+    const returnVisitEmissions = firstVisitEmissions * dataReloadRatio;
     const total = firstVisitEmissions * firstViewRatio + returnVisitEmissions * returnViewRatio;
     let rating = null;
     if (ratingResults) {
@@ -200,6 +226,12 @@ class SustainableWebDesign {
     }
     return total;
   }
+  /**
+   * Determines the rating of a website's sustainability based on its CO2 emissions.
+   *
+   * @param {number} co2e - The CO2 emissions of the website in grams.
+   * @returns {string} The sustainability rating, ranging from "A+" (best) to "F" (worst).
+   */
   ratingScale(co2e) {
     return outputRating(co2e, this.version);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgwf/co2",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "description": "Work out the co2 of your digital services",
   "main": "dist/cjs/index-node.js",
   "module": "dist/esm/index.js",
@@ -14,7 +14,7 @@
     }
   },
   "scripts": {
-    "test": "jest src",
+    "test": "jest src --silent",
     "test:watch": "jest --watch src",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
@@ -46,7 +46,7 @@
   "devDependencies": {
     "@tgwf/url2green": "^0.4.1",
     "all-contributors-cli": "^6.26.1",
-    "esbuild": "^0.14.47",
+    "esbuild": "^0.25.0",
     "esbuild-jest": "^0.5.0",
     "esbuild-plugin-glob": "^1.1.2",
     "eslint": "^8.15.0",