From 6f4b08bc9221ebc84fb1bee7e864ffac335860c8 Mon Sep 17 00:00:00 2001 From: Simon Fishel Date: Sun, 24 Mar 2024 15:18:55 -0700 Subject: [PATCH] pull out utility types, some naming cleanup --- package-lock.json | 35 +++++++++++++++++++++++++------- package.json | 1 + src/co2.js | 2 +- src/sustainable-web-design.js | 13 ++++++------ src/types.js | 38 +++++++++++++++++++++-------------- 5 files changed, 59 insertions(+), 30 deletions(-) diff --git a/package-lock.json b/package-lock.json index 9365387..eea1be0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -25,6 +25,7 @@ "np": "^8.0.4", "pagexray": "^4.4.2", "prettier": "^2.6.2", + "type-fest": "^4.14.0", "typescript": "^5.4.2" }, "engines": { @@ -5572,6 +5573,18 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/globals/node_modules/type-fest": { + "version": "0.20.2", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", + "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "dev": true, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/globalyzer": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/globalyzer/-/globalyzer-0.1.0.tgz", @@ -11809,12 +11822,12 @@ } }, "node_modules/type-fest": { - "version": "0.20.2", - "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", - "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.14.0.tgz", + "integrity": "sha512-on5/Cw89wwqGZQu+yWO0gGMGu8VNxsaW9SB2HE8yJjllEk7IDTwnSN1dUVldYILhYPN5HzD7WAaw2cc/jBfn0Q==", "dev": true, "engines": { - "node": ">=10" + "node": ">=16" }, "funding": { "url": "https://github.com/sponsors/sindresorhus" @@ -16449,6 +16462,14 @@ "dev": true, "requires": { "type-fest": "^0.20.2" + }, + "dependencies": { + "type-fest": { + "version": "0.20.2", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", + "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "dev": true + } } }, "globalyzer": { @@ -21053,9 +21074,9 @@ "dev": true }, "type-fest": { - "version": "0.20.2", - "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz", - "integrity": "sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==", + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.14.0.tgz", + "integrity": "sha512-on5/Cw89wwqGZQu+yWO0gGMGu8VNxsaW9SB2HE8yJjllEk7IDTwnSN1dUVldYILhYPN5HzD7WAaw2cc/jBfn0Q==", "dev": true }, "typedarray-to-buffer": { diff --git a/package.json b/package.json index 35f715a..78bca32 100644 --- a/package.json +++ b/package.json @@ -65,6 +65,7 @@ "np": "^8.0.4", "pagexray": "^4.4.2", "prettier": "^2.6.2", + "type-fest": "^4.14.0", "typescript": "^5.4.2" }, "jest": { diff --git a/src/co2.js b/src/co2.js index 001f53a..73557a1 100644 --- a/src/co2.js +++ b/src/co2.js @@ -53,7 +53,7 @@ class CO2 { * * @param {number} bytes * @param {boolean} green - * @return {number | AdjustedCO2ByComponentWithTotal} the amount of CO2 in grammes + * @return {number | CO2ByComponentAndVisitWithTotal} the amount of CO2 in grammes */ perVisit(bytes, green = false) { if ("perVisit" in this.model) { diff --git a/src/sustainable-web-design.js b/src/sustainable-web-design.js index 4642366..d03801f 100644 --- a/src/sustainable-web-design.js +++ b/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} 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} the total number in grams of CO2 equivalent emissions */ co2byComponent( energyByComponent, @@ -108,7 +107,7 @@ class SustainableWebDesign { } } - return /** @type {CO2Object} */ (returnCO2ByComponent); + return /** @type {MapEnergyToCO2} */ (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 ); } diff --git a/src/types.js b/src/types.js index d9badb7..87f110a 100644 --- a/src/types.js +++ b/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 + * @property {number | CO2ByComponentAndVisitWithTotal} co2 - The CO2 estimate in grams/kilowatt-hour * @property {boolean} green - Whether the domain is green or not * @property {TraceResultVariables} variables - The variables used to calculate the CO2 estimate * @@ -81,12 +81,8 @@ * @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} * * @typedef CO2ByComponent * @property {number} consumerDeviceCO2 @@ -94,12 +90,8 @@ * @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} * * @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} */ + +/** + * @template {Record} Object + * @typedef {{ + * [K in Exclude as `${K} - first`]: Object[K] + * } & { + * [K in Exclude as `${K} - subsequest`]: Object[K] + * }} SegmentedByVisit + */ + +/** + * @template {Record} Object + * @typedef {{ + * [K in Extract as import('type-fest').Replace]: Object[K] + * }} MapEnergyToCO2 + */