@tgwf/co2 0.17.0 → 0.17.3-0

package/CHANGELOG.md

@@ -13,14 +13,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > - **Security** in case of vulnerabilities.
 
 ## Unreleased
-
-- Add ability to create adaptors which provide access to external data sources #134
-- Add access to the Electricity Maps API free tier #134
-- Allow access to individual models and their internal functions #195
+- Add carbon.txt validator lookup functionality #273
+- Add subpath exports for estimation models #271
 <!-- - _(Add a summary of your feature, and if relevant the issue, in your PR for merging into `main`)_ -->
 
 ## Released
 
+### [0.18.0-alpha2]
+
+#### Added
+* Annual grid carbon intensity, renewable percentage, carbon free percentage data from Electricity Maps for the years 2021 - 2025.
+
+### [0.18.0-alpha] - 2025-12-08
+
+#### Changed
+* Default carbon estimation model is now the Sustainaable Web Design Model version 4.
+
+### [0.17.0] - 2025-12-02
+
+#### Changed
+* Add `data` and `hosting` subpath exports
+* Add warning about switching default model to SWDMv4
+
+#### Security
+* Bump tar-fs from 2.1.3 to 2.1.4 by @dependabot[bot] in https://github.com/thegreenwebfoundation/co2.js/pull/265
+* Bump js-yaml by @dependabot[bot] in https://github.com/thegreenwebfoundation/co2.js/pull/268
+
 ### [0.16.8] - 2025-05-12
 
 #### Fixed

package/LICENSE

@@ -203,7 +203,7 @@ Marginal Carbon intensity data
 
 The marginal carbon intensity data bundled in CO2.js is published by the Green Web Foundation under the same permissive CC-BY-SA license as the average carbon intensity data. This data is largely based on the operating marginal intensity data published by International Financial Institutions Technical Working group (the IFI TWG) project within the United Nations Framework Convention on Climate Change (the UNFCCC), to harmonize project-level greenhouse gas emissions accounting.
 
-The data used in this report is provided on an ‘as is’ basis. Data is assembled using the best available data at the time of publication. Every effort has been made to ensure accuracy, and where possible we compare multiple sources to confirm their agreement. We take no responsibility for errors. 
+The data used in this report is provided on an ‘as is’ basis. Data is assembled using the best available data at the time of publication. Every effort has been made to ensure accuracy, and where possible we compare multiple sources to confirm their agreement. We take no responsibility for errors.
 
 
 For further information about the methodology used, see the following links
@@ -212,4 +212,14 @@ https://developers.thegreenwebfoundation.org/co2js/data/
 https://unfccc.int/climate-action/sectoral-engagement/ifis-harmonization-of-standards-for-ghg-accounting
 https://unfccc.int/sites/default/files/resource/IFITWG_Methodological_approach_to_common_dataset.pdf
 
+Electricity Maps Grid Intensity Data
+-----------------------------------------------------------------
+
+Electricity Maps Grid Intensity Data - The annual grid intensity data is republished from Electricity Maps under the Open Database License (ODbL). Users of this data through CO2.js must:
+
+- Attribute: Credit Electricity Maps as the source
+- Share-Alike: Keep derivative works under the same license
+- Keep open: Provide unrestricted versions if using DRM
 
+For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology
+For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/

package/README.md

@@ -12,6 +12,14 @@ One day, the internet will be powered by renewable energy. Until that day comes,
 
 ## [Documentation](https://developers.thegreenwebfoundation.org/co2js/overview/) | [Changelog](/CHANGELOG.md) | [Roadmap](https://developers.thegreenwebfoundation.org/co2js/roadmap/)
 
+> [!IMPORTANT]
+> Important note about upcoming changes in CO2.js v0.18
+In the next release of CO2.js (v0.18 – February 2026) we will be changing the default carbon estimation model to Sustainable Web Design Model version 4. If you are using CO2.js to perform carbon estimation, and are not explicitly declaring the model and version to use then you will be impacted by this change.
+>
+> You can install a PREVIEW release to test your code to see how this change will effect you. To do so, use the `npm install @tgwf/co2@next` command.
+>
+> We have detailed the impacts of this change for users of CO2.js in this GitHub issue – [Impact of changing from v3 to v4](https://github.com/thegreenwebfoundation/co2.js/issues/209#issuecomment-3624614392)
+
 ## What is CO2.js?
 
 CO2.js is a JavaScript library that enables developers a way to estimate the emissions related to use of their apps, websites, and software.
@@ -132,6 +140,17 @@ The average carbon intensity data from Ember is published under the Creative Com
 
 The marginal intensity data is published by the Green Web Foundation, under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa))
 
+Electricity Maps Grid Intensity Data - The annual grid intensity data is republished from Electricity Maps under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/summary/). Users of this data through CO2.js must:
+
+- Attribute: Credit Electricity Maps as the source
+- Share-Alike: Keep derivative works under the same license
+- Keep open: Provide unrestricted versions if using DRM
+
+For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology
+For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/
+
+Data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) are available through Electricity Maps as a paid service. Users requiring this data should visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing). 
+
 See LICENCE for more.
 
 ## Contributors

package/dist/cjs/co2.js

@@ -38,26 +38,25 @@ var import_sustainable_web_design_v4 = __toESM(require("./sustainable-web-design
 var import_helpers = require("./helpers/index.js");
 class CO2 {
   constructor(options) {
-    this.model = new import_sustainable_web_design_v3.default();
+    this.model = new import_sustainable_web_design_v4.default();
     if ((options == null ? void 0 : options.model) === "1byte") {
       this.model = new import_byte.default();
     } else if ((options == null ? void 0 : options.model) === "swd") {
-      this.model = new import_sustainable_web_design_v3.default();
-      if ((options == null ? void 0 : options.version) === 4) {
+      this.model = new import_sustainable_web_design_v4.default();
+      if ((options == null ? void 0 : options.version) === 3) {
+        this.model = new import_sustainable_web_design_v3.default();
+      } else if ((options == null ? void 0 : options.version) === 4) {
         this.model = new import_sustainable_web_design_v4.default();
       }
-    } else if (!(options == null ? void 0 : options.model)) {
-      console.warn(`------
-WARNING: We are changing the default estimation model in CO2.js to Sustainable Web Design v4 in the next version (v0.18) of CO2.js. This change will take place in February 2026.
-
-If you would like to keep using Sustainable Web Design v3, please make sure to explicitly set it in your code. See https://developers.thegreenwebfoundation.org/co2js/models/#using-sustainable-web-design-model-version-3 for details.
-------
-  `);
     } else if (options == null ? void 0 : options.model) {
       throw new Error(
         `"${options.model}" is not a valid model. Please use "1byte" for the OneByte model, and "swd" for the Sustainable Web Design model.
 See https://developers.thegreenwebfoundation.org/co2js/models/ to learn more about the models available in CO2.js.`
       );
+    } else if (!(options == null ? void 0 : options.model) && (options == null ? void 0 : options.version)) {
+      throw new Error(
+        `"Specified version ${options == null ? void 0 : options.version} but an estimation model is missing. Please specify a model to use for the version you have set.`
+      );
     }
     if ((options == null ? void 0 : options.rating) && typeof options.rating !== "boolean") {
       throw new Error(

package/dist/cjs/co2.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/co2.js"],
-  "sourcesContent": ["\"use strict\";\n\n/**\n * @typedef {Object} CO2EstimateTraceResultPerByte\n * @property {number|CO2EstimateComponentsPerByte} co2 - The CO2 estimate in grams or its separate components\n * @property {boolean} green - Whether the domain is green or not\n * @property {TraceResultVariablesPerByte} variables - The variables used to calculate the CO2 estimate\n */\n\n/**\n * @typedef {Object} CO2EstimateTraceResultPerVisit\n * @property {number|CO2EstimateComponentsPerVisit} co2 - The CO2 estimate in grams or its separate components\n * @property {boolean} green - Whether the domain is green or not\n * @property {TraceResultVariablesPerVisit} variables - The variables used to calculate the CO2 estimate\n */\n\n/**\n * @typedef {Object} TraceResultVariablesPerByte\n * @property {GridIntensityVariables} gridIntensity - The grid intensity related variables\n */\n/**\n * @typedef {Object} TraceResultVariablesPerVisit\n * @property {GridIntensityVariables} gridIntensity - The grid intensity related variables\n * @property {number} dataReloadRatio - What percentage of a page is reloaded on each subsequent page view\n * @property {number} firstVisitPercentage - What percentage of visits are loading this page for subsequent times\n * @property {number} returnVisitPercentage - What percentage of visits are loading this page for the second or more time\n */\n\n/**\n * @typedef {Object} GridIntensityVariables\n * @property {string} description - The description of the variables\n * @property {number} network - The network grid intensity set by the user or the default\n * @property {number} dataCenter - The data center grid intensity set by the user or the default\n * @property {number} device - The device grid intensity set by the user or the default\n * @property {number} production - The production grid intensity set by the user or the default\n */\n\n/**\n * @typedef {Object} CO2EstimateComponentsPerByte\n * @property {number} networkCO2 - The CO2 estimate for networking in grams\n * @property {number} dataCenterCO2 - The CO2 estimate for data centers in grams\n * @property {number} consumerDeviceCO2 - The CO2 estimate for consumer devices in grams\n * @property {number} productionCO2 - The CO2 estimate for device production in grams\n * @property {string} rating - The rating of the CO2 estimate based on the Sustainable Web Design Model\n * @property {number} total - The total CO2 estimate in grams\n */\n\n/**\n * @typedef {Object} CO2EstimateComponentsPerVisit\n * @property {number} 'networkCO2 - first' - The CO2 estimate for networking in grams on first visit\n * @property {number} 'networkCO2 - subsequent' - The CO2 estimate for networking in grams on subsequent visits\n * @property {number} 'dataCenterCO2 - first' - The CO2 estimate for data centers in grams on first visit\n * @property {number} 'dataCenterCO2 - subsequent' - The CO2 estimate for data centers in grams on subsequent visits\n * @property {number} 'consumerDeviceCO2 - first' - The CO2 estimate for consumer devices in grams on first visit\n * @property {number} 'consumerDeviceCO2 - subsequent' - The CO2 estimate for consumer devices in grams on subsequent visits\n * @property {number} 'productionCO2 - first' - The CO2 estimate for device production in grams on first visit\n * @property {number} 'productionCO2 - subsequent' - The CO2 estimate for device production in grams on subsequent visits\n * @property {string} rating - The rating of the CO2 estimate based on the Sustainable Web Design Model\n * @property {number} total - The total CO2 estimate in grams\n */\n\nimport OneByte from \"./1byte.js\";\nimport SustainableWebDesignV3 from \"./sustainable-web-design-v3.js\";\nimport SustainableWebDesignV4 from \"./sustainable-web-design-v4.js\";\n\nimport {\n  parseByteTraceOptions,\n  parseVisitTraceOptions,\n} from \"./helpers/index.js\";\n\nclass CO2 {\n  constructor(options) {\n    this.model = new SustainableWebDesignV3();\n    // Using optional chaining allows an empty object to be passed\n    // in without breaking the code.\n    if (options?.model === \"1byte\") {\n      this.model = new OneByte();\n    } else if (options?.model === \"swd\") {\n      this.model = new SustainableWebDesignV3();\n      if (options?.version === 4) {\n        this.model = new SustainableWebDesignV4();\n      }\n    } else if (!options?.model) {\n      console.warn(`------\nWARNING: We are changing the default estimation model in CO2.js to Sustainable Web Design v4 in the next version (v0.18) of CO2.js. This change will take place in February 2026.\n\nIf you would like to keep using Sustainable Web Design v3, please make sure to explicitly set it in your code. See https://developers.thegreenwebfoundation.org/co2js/models/#using-sustainable-web-design-model-version-3 for details.\n------\n  `);\n    } else if (options?.model) {\n      throw new Error(\n        `\"${options.model}\" is not a valid model. Please use \"1byte\" for the OneByte model, and \"swd\" for the Sustainable Web Design model.\\nSee https://developers.thegreenwebfoundation.org/co2js/models/ to learn more about the models available in CO2.js.`\n      );\n    }\n\n    if (options?.rating && typeof options.rating !== \"boolean\") {\n      throw new Error(\n        `The rating option must be a boolean. Please use true or false.\\nSee https://developers.thegreenwebfoundation.org/co2js/options/ to learn more about the options available in CO2.js.`\n      );\n    }\n\n    // This flag checks to see if the model itself has a rating system.\n    const allowRatings = !!this.model.allowRatings;\n\n    /** @private */\n    this._segment = options?.results === \"segment\";\n    // This flag is set by the user to enable the rating system.\n    this._rating = options?.rating === true;\n\n    // The rating system is only supported in the Sustainable Web Design Model.\n    if (!allowRatings && this._rating) {\n      throw new Error(\n        `The rating system is not supported in the model you are using. Try using the Sustainable Web Design model instead.\\nSee https://developers.thegreenwebfoundation.org/co2js/models/ to learn more about the models available in CO2.js.`\n      );\n    }\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, and a boolean for whether\n   * the domain shows as 'green', and return a CO2 figure for energy used to shift the corresponding\n   * the data transfer.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @return {number|CO2EstimateComponentsPerByte} the amount of CO2 in grammes or its separate components\n   */\n  perByte(bytes, green = false) {\n    return this.model.perByte(bytes, green, this._segment, this._rating);\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, and a boolean for whether\n   * the domain shows as 'green', and return a CO2 figure for energy used to shift the corresponding\n   * the data transfer.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @return {number|CO2EstimateComponentsPerVisit} the amount of CO2 in grammes or its separate components\n   */\n  perVisit(bytes, green = false) {\n    if (this.model?.perVisit) {\n      return this.model.perVisit(bytes, green, this._segment, this._rating);\n    } else {\n      throw new Error(\n        `The perVisit() method is not supported in the model you are using. Try using perByte() instead.\\nSee https://developers.thegreenwebfoundation.org/co2js/methods/ to learn more about the methods available in CO2.js.`\n      );\n    }\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, a boolean for whether\n   * the domain shows as 'green', and an options object.\n   * Returns an object containing CO2 figure, green boolean, and object of the variables used in calculating the CO2 figure.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @param {Object} options\n   * @return {CO2EstimateTraceResultPerByte} the amount of CO2 in grammes\n   */\n  perByteTrace(bytes, green = false, options = {}) {\n    const adjustments = parseByteTraceOptions(\n      options,\n      this.model.version,\n      green\n    );\n\n    // Filter out the trace items that aren't relevant to this function.\n    const { gridIntensity, ...traceVariables } = adjustments;\n    const {\n      dataReloadRatio,\n      firstVisitPercentage,\n      returnVisitPercentage,\n      ...otherVariables\n    } = traceVariables;\n    return {\n      co2: this.model.perByte(\n        bytes,\n        green,\n        this._segment,\n        this._rating,\n        adjustments\n      ),\n      green,\n      variables: {\n        description:\n          \"Below are the variables used to calculate this CO2 estimate.\",\n        bytes,\n        gridIntensity: {\n          description:\n            \"The grid intensity (grams per kilowatt-hour) used to calculate this CO2 estimate.\",\n          ...adjustments.gridIntensity,\n        },\n        ...otherVariables,\n      },\n    };\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, a boolean for whether\n   * the domain shows as 'green', and an options object.\n   * Returns an object containing CO2 figure, green boolean, and object of the variables used in calculating the CO2 figure.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @param {Object} options\n   * @return {CO2EstimateTraceResultPerVisit} the amount of CO2 in grammes\n   */\n  perVisitTrace(bytes, green = false, options = {}) {\n    if (this.model?.perVisit) {\n      const adjustments = parseVisitTraceOptions(\n        options,\n        this.model.version,\n        green\n      );\n      const { gridIntensity, ...variables } = adjustments;\n\n      return {\n        co2: this.model.perVisit(\n          bytes,\n          green,\n          this._segment,\n          this._rating,\n          adjustments\n        ),\n        green,\n        variables: {\n          description:\n            \"Below are the variables used to calculate this CO2 estimate.\",\n          bytes,\n          gridIntensity: {\n            description:\n              \"The grid intensity (grams per kilowatt-hour) used to calculate this CO2 estimate.\",\n            ...adjustments.gridIntensity,\n          },\n          ...variables,\n        },\n      };\n    } else {\n      throw new Error(\n        `The perVisitTrace() method is not supported in the model you are using. Try using perByte() instead.\\nSee https://developers.thegreenwebfoundation.org/co2js/methods/ to learn more about the methods available in CO2.js.`\n      );\n    }\n  }\n\n  SustainableWebDesignV3() {\n    return new SustainableWebDesignV3();\n  }\n\n  SustainableWebDesignV4() {\n    return new SustainableWebDesignV4();\n  }\n\n  OneByte() {\n    return new OneByte();\n  }\n}\n\nexport { CO2 };\nexport default CO2;\n"],
-  "mappings": "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",
-  "names": ["SustainableWebDesignV3", "OneByte", "SustainableWebDesignV4"]
+  "sourcesContent": ["\"use strict\";\n\n/**\n * @typedef {Object} CO2EstimateTraceResultPerByte\n * @property {number|CO2EstimateComponentsPerByte} co2 - The CO2 estimate in grams or its separate components\n * @property {boolean} green - Whether the domain is green or not\n * @property {TraceResultVariablesPerByte} variables - The variables used to calculate the CO2 estimate\n */\n\n/**\n * @typedef {Object} CO2EstimateTraceResultPerVisit\n * @property {number|CO2EstimateComponentsPerVisit} co2 - The CO2 estimate in grams or its separate components\n * @property {boolean} green - Whether the domain is green or not\n * @property {TraceResultVariablesPerVisit} variables - The variables used to calculate the CO2 estimate\n */\n\n/**\n * @typedef {Object} TraceResultVariablesPerByte\n * @property {GridIntensityVariables} gridIntensity - The grid intensity related variables\n */\n/**\n * @typedef {Object} TraceResultVariablesPerVisit\n * @property {GridIntensityVariables} gridIntensity - The grid intensity related variables\n * @property {number} dataReloadRatio - What percentage of a page is reloaded on each subsequent page view\n * @property {number} firstVisitPercentage - What percentage of visits are loading this page for subsequent times\n * @property {number} returnVisitPercentage - What percentage of visits are loading this page for the second or more time\n */\n\n/**\n * @typedef {Object} GridIntensityVariables\n * @property {string} description - The description of the variables\n * @property {number} network - The network grid intensity set by the user or the default\n * @property {number} dataCenter - The data center grid intensity set by the user or the default\n * @property {number} device - The device grid intensity set by the user or the default\n * @property {number} production - The production grid intensity set by the user or the default\n */\n\n/**\n * @typedef {Object} CO2EstimateComponentsPerByte\n * @property {number} networkCO2 - The CO2 estimate for networking in grams\n * @property {number} dataCenterCO2 - The CO2 estimate for data centers in grams\n * @property {number} consumerDeviceCO2 - The CO2 estimate for consumer devices in grams\n * @property {number} productionCO2 - The CO2 estimate for device production in grams\n * @property {string} rating - The rating of the CO2 estimate based on the Sustainable Web Design Model\n * @property {number} total - The total CO2 estimate in grams\n */\n\n/**\n * @typedef {Object} CO2EstimateComponentsPerVisit\n * @property {number} 'networkCO2 - first' - The CO2 estimate for networking in grams on first visit\n * @property {number} 'networkCO2 - subsequent' - The CO2 estimate for networking in grams on subsequent visits\n * @property {number} 'dataCenterCO2 - first' - The CO2 estimate for data centers in grams on first visit\n * @property {number} 'dataCenterCO2 - subsequent' - The CO2 estimate for data centers in grams on subsequent visits\n * @property {number} 'consumerDeviceCO2 - first' - The CO2 estimate for consumer devices in grams on first visit\n * @property {number} 'consumerDeviceCO2 - subsequent' - The CO2 estimate for consumer devices in grams on subsequent visits\n * @property {number} 'productionCO2 - first' - The CO2 estimate for device production in grams on first visit\n * @property {number} 'productionCO2 - subsequent' - The CO2 estimate for device production in grams on subsequent visits\n * @property {string} rating - The rating of the CO2 estimate based on the Sustainable Web Design Model\n * @property {number} total - The total CO2 estimate in grams\n */\n\nimport OneByte from \"./1byte.js\";\nimport SustainableWebDesignV3 from \"./sustainable-web-design-v3.js\";\nimport SustainableWebDesignV4 from \"./sustainable-web-design-v4.js\";\n\nimport {\n  parseByteTraceOptions,\n  parseVisitTraceOptions,\n} from \"./helpers/index.js\";\n\nclass CO2 {\n  constructor(options) {\n    this.model = new SustainableWebDesignV4();\n    // Using optional chaining allows an empty object to be passed\n    // in without breaking the code.\n    if (options?.model === \"1byte\") {\n      this.model = new OneByte();\n    } else if (options?.model === \"swd\") {\n      this.model = new SustainableWebDesignV4();\n      if (options?.version === 3) {\n        this.model = new SustainableWebDesignV3();\n      } else if (options?.version === 4) {\n        this.model = new SustainableWebDesignV4();\n      }\n    } else if (options?.model) {\n      throw new Error(\n        `\"${options.model}\" is not a valid model. Please use \"1byte\" for the OneByte model, and \"swd\" for the Sustainable Web Design model.\\nSee https://developers.thegreenwebfoundation.org/co2js/models/ to learn more about the models available in CO2.js.`,\n      );\n    } else if (!options?.model && options?.version) {\n      throw new Error(\n        `\"Specified version ${options?.version} but an estimation model is missing. Please specify a model to use for the version you have set.`,\n      );\n    }\n\n    if (options?.rating && typeof options.rating !== \"boolean\") {\n      throw new Error(\n        `The rating option must be a boolean. Please use true or false.\\nSee https://developers.thegreenwebfoundation.org/co2js/options/ to learn more about the options available in CO2.js.`,\n      );\n    }\n\n    // This flag checks to see if the model itself has a rating system.\n    const allowRatings = !!this.model.allowRatings;\n\n    /** @private */\n    this._segment = options?.results === \"segment\";\n    // This flag is set by the user to enable the rating system.\n    this._rating = options?.rating === true;\n\n    // The rating system is only supported in the Sustainable Web Design Model.\n    if (!allowRatings && this._rating) {\n      throw new Error(\n        `The rating system is not supported in the model you are using. Try using the Sustainable Web Design model instead.\\nSee https://developers.thegreenwebfoundation.org/co2js/models/ to learn more about the models available in CO2.js.`,\n      );\n    }\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, and a boolean for whether\n   * the domain shows as 'green', and return a CO2 figure for energy used to shift the corresponding\n   * the data transfer.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @return {number|CO2EstimateComponentsPerByte} the amount of CO2 in grammes or its separate components\n   */\n  perByte(bytes, green = false) {\n    return this.model.perByte(bytes, green, this._segment, this._rating);\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, and a boolean for whether\n   * the domain shows as 'green', and return a CO2 figure for energy used to shift the corresponding\n   * the data transfer.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @return {number|CO2EstimateComponentsPerVisit} the amount of CO2 in grammes or its separate components\n   */\n  perVisit(bytes, green = false) {\n    if (this.model?.perVisit) {\n      return this.model.perVisit(bytes, green, this._segment, this._rating);\n    } else {\n      throw new Error(\n        `The perVisit() method is not supported in the model you are using. Try using perByte() instead.\\nSee https://developers.thegreenwebfoundation.org/co2js/methods/ to learn more about the methods available in CO2.js.`,\n      );\n    }\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, a boolean for whether\n   * the domain shows as 'green', and an options object.\n   * Returns an object containing CO2 figure, green boolean, and object of the variables used in calculating the CO2 figure.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @param {Object} options\n   * @return {CO2EstimateTraceResultPerByte} the amount of CO2 in grammes\n   */\n  perByteTrace(bytes, green = false, options = {}) {\n    const adjustments = parseByteTraceOptions(\n      options,\n      this.model.version,\n      green,\n    );\n\n    // Filter out the trace items that aren't relevant to this function.\n    const { gridIntensity, ...traceVariables } = adjustments;\n    const {\n      dataReloadRatio,\n      firstVisitPercentage,\n      returnVisitPercentage,\n      ...otherVariables\n    } = traceVariables;\n    return {\n      co2: this.model.perByte(\n        bytes,\n        green,\n        this._segment,\n        this._rating,\n        adjustments,\n      ),\n      green,\n      variables: {\n        description:\n          \"Below are the variables used to calculate this CO2 estimate.\",\n        bytes,\n        gridIntensity: {\n          description:\n            \"The grid intensity (grams per kilowatt-hour) used to calculate this CO2 estimate.\",\n          ...adjustments.gridIntensity,\n        },\n        ...otherVariables,\n      },\n    };\n  }\n\n  /**\n   * Accept a figure in bytes for data transfer, a boolean for whether\n   * the domain shows as 'green', and an options object.\n   * Returns an object containing CO2 figure, green boolean, and object of the variables used in calculating the CO2 figure.\n   *\n   * @param {number} bytes\n   * @param {boolean} green\n   * @param {Object} options\n   * @return {CO2EstimateTraceResultPerVisit} the amount of CO2 in grammes\n   */\n  perVisitTrace(bytes, green = false, options = {}) {\n    if (this.model?.perVisit) {\n      const adjustments = parseVisitTraceOptions(\n        options,\n        this.model.version,\n        green,\n      );\n      const { gridIntensity, ...variables } = adjustments;\n\n      return {\n        co2: this.model.perVisit(\n          bytes,\n          green,\n          this._segment,\n          this._rating,\n          adjustments,\n        ),\n        green,\n        variables: {\n          description:\n            \"Below are the variables used to calculate this CO2 estimate.\",\n          bytes,\n          gridIntensity: {\n            description:\n              \"The grid intensity (grams per kilowatt-hour) used to calculate this CO2 estimate.\",\n            ...adjustments.gridIntensity,\n          },\n          ...variables,\n        },\n      };\n    } else {\n      throw new Error(\n        `The perVisitTrace() method is not supported in the model you are using. Try using perByte() instead.\\nSee https://developers.thegreenwebfoundation.org/co2js/methods/ to learn more about the methods available in CO2.js.`,\n      );\n    }\n  }\n\n  SustainableWebDesignV3() {\n    return new SustainableWebDesignV3();\n  }\n\n  SustainableWebDesignV4() {\n    return new SustainableWebDesignV4();\n  }\n\n  OneByte() {\n    return new OneByte();\n  }\n}\n\nexport { CO2 };\nexport default CO2;\n"],
+  "mappings": "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",
+  "names": ["SustainableWebDesignV4", "OneByte", "SustainableWebDesignV3"]
 }

package/dist/cjs/data/electricity-maps/index.js

@@ -0,0 +1,50 @@
+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 __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var electricity_maps_exports = {};
+__export(electricity_maps_exports, {
+  default: () => electricity_maps_default,
+  yearly2021: () => import_yearly_2021.default,
+  yearly2022: () => import_yearly_2022.default,
+  yearly2023: () => import_yearly_2023.default,
+  yearly2024: () => import_yearly_2024.default,
+  yearly2025: () => import_yearly_2025.default
+});
+module.exports = __toCommonJS(electricity_maps_exports);
+var import_yearly_2025 = __toESM(require("./yearly_2025.js"));
+var import_yearly_2024 = __toESM(require("./yearly_2024.js"));
+var import_yearly_2023 = __toESM(require("./yearly_2023.js"));
+var import_yearly_2022 = __toESM(require("./yearly_2022.js"));
+var import_yearly_2021 = __toESM(require("./yearly_2021.js"));
+var electricity_maps_default = {
+  yearly2025: import_yearly_2025.default,
+  yearly2024: import_yearly_2024.default,
+  yearly2023: import_yearly_2023.default,
+  yearly2022: import_yearly_2022.default,
+  yearly2021: import_yearly_2021.default
+};
+//# sourceMappingURL=index.js.map

package/dist/cjs/data/electricity-maps/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/data/electricity-maps/index.js"],
+  "sourcesContent": ["import yearly2025 from \"./yearly_2025.js\";\nimport yearly2024 from \"./yearly_2024.js\";\nimport yearly2023 from \"./yearly_2023.js\";\nimport yearly2022 from \"./yearly_2022.js\";\nimport yearly2021 from \"./yearly_2021.js\";\n\nexport { yearly2025, yearly2024, yearly2023, yearly2022, yearly2021 };\n\nexport default {\n  yearly2025,\n  yearly2024,\n  yearly2023,\n  yearly2022,\n  yearly2021,\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA,uCAAAA;AAAA,EAAA,qCAAAC;AAAA,EAAA,qCAAAC;AAAA,EAAA,qCAAAC;AAAA,EAAA,qCAAAC;AAAA;AAAA;AAAA,yBAAuB;AACvB,yBAAuB;AACvB,yBAAuB;AACvB,yBAAuB;AACvB,yBAAuB;AAIvB,IAAO,2BAAQ;AAAA,EACb,+BAAAA;AAAA,EACA,+BAAAD;AAAA,EACA,+BAAAD;AAAA,EACA,+BAAAD;AAAA,EACA,+BAAAD;AACF;",
+  "names": ["yearly2021", "yearly2022", "yearly2023", "yearly2024", "yearly2025"]
+}