pull out utility types, some naming cleanup

package.json

@@ -64,6 +64,7 @@
     "nock": "^13.2.4",
     "np": "^8.0.4",
     "prettier": "^2.6.2",
+    "type-fest": "^4.14.0",
     "typescript": "^5.4.2"
   },
   "jest": {

src/co2.js

@@ -53,7 +53,7 @@ class CO2 {
    *
    * @param {number} bytes
    * @param {boolean} green
-   * @return {number | AdjustedCO2ByComponentWithTotal} the amount of CO2 in grammes or its separate components
+   * @return {number | CO2ByComponentAndVisitWithTotal} the amount of CO2 in grammes or its separate components
    */
   perVisit(bytes, green = false) {
     if ("perVisit" in this.model) {

src/sustainable-web-design.js

@@ -48,13 +48,12 @@ class SustainableWebDesign {
    * Accept an object keys by the different system components, and
    * return an object with the co2 figures key by the each component
    *
-   * @template {AdjustedEnergyByComponent | EnergyByComponent} EnergyObject
-   * @template [CO2Object=EnergyObject extends AdjustedEnergyByComponent ? AdjustedCO2ByComponent : CO2ByComponent]
+   * @template {Record<string, number>} EnergyObject
    * @param {EnergyObject} energyByComponent - energy grouped by the four system components
    * // TODO (simon) check on this type for carbonIntensity
    * @param {(number | boolean)=} carbonIntensity - carbon intensity to apply to the datacentre values
    * @param {ModelAdjustments=} options - carbon intensity to apply to the datacentre values
-   * @return {CO2Object} the total number in grams of CO2 equivalent emissions
+   * @return {MapEnergyToCO2<EnergyObject>} the total number in grams of CO2 equivalent emissions
    */
   co2byComponent(
     energyByComponent,
@@ -108,7 +107,7 @@ class SustainableWebDesign {
       }
     }
 
-    return /** @type {CO2Object} */ (returnCO2ByComponent);
+    return /** @type {MapEnergyToCO2<EnergyObject>} */ (returnCO2ByComponent);
   }
 
   /**
@@ -169,7 +168,7 @@ class SustainableWebDesign {
    * @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 {ModelAdjustments=} options - an object containing the grid intensity and first/return visitor values
-   * @return {number | AdjustedCO2ByComponentWithTotal} the total number in grams of CO2 equivalent emissions, or an object containing the breakdown by component
+   * @return {number | CO2ByComponentAndVisitWithTotal} the total number in grams of CO2 equivalent emissions, or an object containing the breakdown by component
    */
   perVisit(
     bytes,
@@ -239,7 +238,7 @@ class SustainableWebDesign {
    * @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 {AdjustedEnergyByComponent} Object containing the energy in kilowatt hours, keyed by system component
+   * @return {EnergyByComponentAndVisit} Object containing the energy in kilowatt hours, keyed by system component
    */
   energyPerVisitByComponent(
     bytes,
@@ -277,7 +276,7 @@ class SustainableWebDesign {
         value * returnView * dataReloadRatio;
     }
 
-    return /** @type {AdjustedEnergyByComponent} */ (
+    return /** @type {EnergyByComponentAndVisit} */ (
       cacheAdjustedSegmentEnergy
     );
   }

src/types.js

@@ -55,7 +55,7 @@
  * @property {TraceResultVariables} variables - The variables used to calculate the CO2 estimate
  *
  * @typedef CO2EstimateTraceResultPerVisit
- * @property {number | AdjustedCO2ByComponentWithTotal} co2 - The CO2 estimate in grams/kilowatt-hour or its separate components
+ * @property {number | CO2ByComponentAndVisitWithTotal} co2 - The CO2 estimate in grams/kilowatt-hour or its separate components
  * @property {boolean} green - Whether the domain is green or not
  * @property {TraceResultVariables} variables - The variables used to calculate the CO2 estimate
  *
@@ -81,25 +81,17 @@
  * @property {number} productionEnergy
  * @property {number} dataCenterEnergy
  *
- * @typedef {Object} AdjustedEnergyByComponent
- * @type {{
- *   [K in keyof EnergyByComponent as `${K} - first`]: EnergyByComponent[K]
- * } & {
- *   [K in keyof EnergyByComponent as `${K} - subsequest`]: EnergyByComponent[K]
- * }}
+ * @typedef EnergyByComponentAndVisit
+ * @type {SegmentedByVisit<EnergyByComponent>}
  *
  * @typedef CO2ByComponent
  * @property {number} consumerDeviceCO2
  * @property {number} networkCO2
  * @property {number} productionCO2
  * @property {number} dataCenterCO2
  *
- * @typedef {Object} AdjustedCO2ByComponent
- * @type {{
- *   [K in keyof CO2ByComponent as `${K} - first`]: CO2ByComponent[K]
- * } & {
- *   [K in keyof CO2ByComponent as `${K} - subsequest`]: CO2ByComponent[K]
- * }}
+ * @typedef CO2ByComponentAndVisit
+ * @type {SegmentedByVisit<CO2ByComponent>}
  *
  * @typedef CO2ByComponentWithTotal
  * @property {number} consumerDeviceCO2
@@ -108,8 +100,8 @@
  * @property {number} dataCenterCO2
  * @property {number} total
  *
- * @typedef {Object} AdjustedCO2ByComponentWithTotal
- * @type {AdjustedCO2ByComponent & { total: number }}
+ * @typedef CO2ByComponentAndVisitWithTotal
+ * @type {CO2ByComponentAndVisit & { total: number }}
  *
  * @typedef PageXRayDomain
  * @property {number} transferSize
@@ -146,3 +138,19 @@
  * @typedef MultiDomainCheckResponse
  * @type {Record<string, PerDomainCheckResponse>}
  */
+
+/**
+ * @template {Record<string, unknown>} Object
+ * @typedef {{
+ *   [K in Exclude<keyof Object, symbol> as `${K} - first`]: Object[K]
+ * } & {
+ *   [K in Exclude<keyof Object, symbol> as `${K} - subsequest`]: Object[K]
+ * }} SegmentedByVisit
+ */
+
+/**
+ * @template {Record<string, unknown>} Object
+ * @typedef {{
+ *   [K in Extract<keyof Object, string> as import('type-fest').Replace<K, 'Energy', 'CO2'>]: Object[K]
+ * }} MapEnergyToCO2
+ */