@grnsft/if 0.6.0 → 0.7.0

package/manifests/outputs/pipelines/zeros.yaml

@@ -8,7 +8,7 @@ initialize:
     sum-zero-and-one:
       path: builtin
       method: Sum
-      global-config:
+      config:
         input-parameters:
           - some-value
           - zero-value
@@ -16,7 +16,7 @@ initialize:
     sum-zero-and-zero:
       path: builtin
       method: Sum
-      global-config:
+      config:
         input-parameters:
           - zero-value
           - zero-value
@@ -24,7 +24,7 @@ initialize:
     subtract-one-and-zero:
       path: builtin
       method: Subtract
-      global-config:
+      config:
         input-parameters:
           - some-value
           - zero-value
@@ -32,7 +32,7 @@ initialize:
     subtract-zero-and-zero:
       path: builtin
       method: Sum
-      global-config:
+      config:
         input-parameters:
           - zero-value
           - zero-value
@@ -40,7 +40,7 @@ initialize:
     subtract-zero-and-one:
       path: builtin
       method: Subtract
-      global-config:
+      config:
         input-parameters:
           - zero-value
           - some-value
@@ -48,28 +48,28 @@ initialize:
     coefficient-one-times-zero:
       path: builtin
       method: Coefficient
-      global-config:
+      config:
         input-parameter: zero-value
         coefficient: 1
         output-parameter: zero-times-one-coefficient
     coefficient-zero-times-one:
       path: builtin
       method: Coefficient
-      global-config:
+      config:
         input-parameter: some-value
         coefficient: 0
         output-parameter: one-times-zero-coefficient
     coefficient-zero-times-zero:
       path: builtin
       method: Coefficient
-      global-config:
+      config:
         input-parameter: zero-value
         coefficient: 0
         output-parameter: zero-times-zero-coefficient
     multiply-one-times-zero:
       path: builtin
       method: Multiply
-      global-config:
+      config:
         input-parameters:
           - some-value
           - zero-value
@@ -77,7 +77,7 @@ initialize:
     multiply-zero-times-one:
       path: builtin
       method: Multiply
-      global-config:
+      config:
         input-parameters:
           - zero-value
           - zero-value
@@ -85,28 +85,28 @@ initialize:
     exponent-one-to-zero:
       path: builtin
       method: Exponent
-      global-config:
+      config:
         input-parameter: some-value
         exponent: 0
         output-parameter: one-raised-to-zero-power
     exponent-zero-to-zero:
       path: builtin
       method: Exponent
-      global-config:
+      config:
         input-parameter: zero-value
         exponent: 0
         output-parameter: zero-raised-to-zero-power
     exponent-zero-to-one:
       path: builtin
       method: Exponent
-      global-config:
+      config:
         input-parameter: zero-value
         exponent: 1
         output-parameter: zero-raised-to-first-power
     sci:
       path: builtin
       method: Sci
-      global-config:
+      config:
         functional-unit: zero-value
 execution:
   command: >-
@@ -116,20 +116,20 @@ execution:
   environment:
     if-version: 0.5.0
     os: macOS
-    os-version: '14.5'
+    os-version: "14.5"
     node-version: 18.14.2
     date-time: 2024-07-19T06:36:00.790Z (UTC)
     dependencies:
-      - '@babel/core@7.22.10'
-      - '@babel/preset-typescript@7.23.3'
-      - '@commitlint/cli@18.6.0'
-      - '@commitlint/config-conventional@18.6.0'
-      - '@grnsft/if-core@0.0.10'
-      - '@jest/globals@29.7.0'
-      - '@types/jest@29.5.8'
-      - '@types/js-yaml@4.0.9'
-      - '@types/luxon@3.4.2'
-      - '@types/node@20.9.0'
+      - "@babel/core@7.22.10"
+      - "@babel/preset-typescript@7.23.3"
+      - "@commitlint/cli@18.6.0"
+      - "@commitlint/config-conventional@18.6.0"
+      - "@grnsft/if-core@0.0.10"
+      - "@jest/globals@29.7.0"
+      - "@types/jest@29.5.8"
+      - "@types/js-yaml@4.0.9"
+      - "@types/luxon@3.4.2"
+      - "@types/node@20.9.0"
       - axios-mock-adapter@1.22.0
       - axios@1.7.2
       - cross-env@7.0.3
@@ -171,13 +171,13 @@ tree:
           - exponent-zero-to-zero
           - sci
       inputs:
-        - timestamp: '2023-12-12T00:00:00.000Z'
+        - timestamp: "2023-12-12T00:00:00.000Z"
           duration: 1
           some-value: 1
           zero-value: 0
           carbon: 10
       outputs:
-        - timestamp: '2023-12-12T00:00:00.000Z'
+        - timestamp: "2023-12-12T00:00:00.000Z"
           duration: 1
           some-value: 1
           zero-value: 0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grnsft/if",
   "description": "Impact Framework",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "author": {
     "name": "Green Software Foundation",
     "email": "info@gsf.com"
@@ -20,7 +20,7 @@
   "dependencies": {
     "@commitlint/cli": "^18.6.0",
     "@commitlint/config-conventional": "^18.6.0",
-    "@grnsft/if-core": "^0.0.16",
+    "@grnsft/if-core": "^0.0.25",
     "axios": "^1.7.2",
     "csv-parse": "^5.5.6",
     "csv-stringify": "^6.4.6",
@@ -58,11 +58,12 @@
   "homepage": "https://greensoftware.foundation",
   "keywords": [
     "engine",
+    "framework",
     "green software foundation",
     "greensoftware",
     "if",
     "impact",
-    "models"
+    "plugins"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -86,7 +87,6 @@
     "lint": "gts lint",
     "pre-commit": "lint-staged",
     "prepare": "husky install",
-    "prepublish": "npm run build",
     "release": "release-it",
     "test": "jest --verbose --testPathPattern=src/__tests__/"
   },

package/src/__mocks__/mock-manifest.yaml

@@ -6,7 +6,7 @@ initialize:
     memory-energy-from-memory-util:
       path: builtin
       method: Coefficient
-      global-config:
+      config:
         input-parameter: memory/utilization
         coefficient: 0.0001
         output-parameter: memory/energy
@@ -59,7 +59,6 @@ tree:
       pipeline:
         compute:
           - memory-energy-from-memory-util
-      config: null
       inputs:
         - timestamp: 2023-12-12T00:00:00.000Z
           duration: 3600

package/src/if-env/config/env-template.yml

@@ -6,7 +6,7 @@ initialize:
     memory-energy-from-memory-util: # you can name this any way you like!
       method: Coefficient # the name of the function exported from the plugin
       path: "builtin" # the import path
-      global-config: # anmy config required by the plugin
+      config: # any config required by the plugin
         input-parameter: "memory/utilization"
         coefficient: 0.0001 #kwH/GB
         output-parameter: "memory/energy"
@@ -16,7 +16,6 @@ tree:
       pipeline: # the pipeline is an ordered list of plugins you want to execute
         compute:
           - memory-energy-from-memory-util # must match the name in initialize!
-      config: # any plugin specific, node-level config
       inputs:
         - timestamp: 2023-12-12T00:00:00.000Z # ISO 8061 string
           duration: 3600 # units of seconds

package/src/if-run/builtins/coefficient/README.md

@@ -8,9 +8,9 @@ For example, you could multiply `cpu/energy` by 10 and name the result `energy-p
 
 ## Parameters
 
-### Plugin global config
+### Plugin config
 
-Three parameters are required in global config: `input-parameter`, `coefficient` and `output-parameter`.
+Three parameters are required in config: `input-parameter`, `coefficient` and `output-parameter`.
 
 - `input-parameter`: a string matching an existing key in the `inputs` array
 - `coefficient`: the value to multiply `input-parameter` by.
@@ -21,16 +21,32 @@ Three parameters are required in global config: `input-parameter`, `coefficient`
 The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method`
 of the parameters of the inputs and outputs
 
-- `inputs`: describe parameters of the `input-parameter` of the global config. Each parameter has:
+- `inputs`: describe parameters of the `input-parameter` of the config. Each parameter has:
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
-- `outputs`: describe parameters of the `output-parameter` of the global config. Each parameter has:
+- `outputs`: describe parameters of the `output-parameter` of the config. Each parameter has:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+
+### Mapping
+
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
+
+```yaml
+coefficient:
+  method: Coefficient
+  path: 'builtin'
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
 ### Inputs
 
@@ -38,7 +54,7 @@ All of `input-parameters` must be available in the input array.
 
 ## Returns
 
-- `output-parameter`: the product of all `input-parameters` with the parameter name defined by `output-parameter` in global config.
+- `output-parameter`: the product of all `input-parameters` with the parameter name defined by `output-parameter` in config.
 
 ## Calculation
 
@@ -56,9 +72,11 @@ const config = {
   coefficient: 10,
   'output-parameter': 'carbon-product',
 };
+const parametersMetadata = {inputs: {}, outputs: {}};
+const mapping = {};
 
-const coeff = Coefficient(config);
-const result = coeff.execute([
+const coeff = Coefficient(config, parametersMetadata, mapping);
+const result = await coeff.execute([
   {
     duration: 3600,
     timestamp: '2021-01-01T00:00:00Z',
@@ -80,19 +98,25 @@ initialize:
     coefficient:
       method: Coefficient
       path: 'builtin'
-      global-config:
+      config:
         input-parameter: 'carbon'
         coefficient: 3
         output-parameter: 'carbon-product'
-       parameter-metadata:
+      parameter-metadata:
         inputs:
           carbon:
-            description: "an amount of carbon emitted into the atmosphere"
-            unit: "gCO2e"
+            description: 'an amount of carbon emitted into the atmosphere'
+            unit: 'gCO2e'
+            aggregation-method:
+              time: sum
+              component: sum
         outputs:
           carbon-product:
-            description: "a product of cabon property and the coefficient"
-            unit: "gCO2e"
+            description: 'a product of cabon property and the coefficient'
+            unit: 'gCO2e'
+            aggregation-method:
+              time: sum
+              component: sum
 tree:
   children:
     child:
@@ -117,9 +141,9 @@ The results will be saved to a new `yaml` file in `./examples/outputs`
 
 `Coefficient` exposes one of the IF error classes.
 
-### GlobalConfigError
+### ConfigError
 
-You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+You will receive an error starting `ConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
 
 The required parameters are:
 

package/src/if-run/builtins/copy-param/README.md

@@ -43,16 +43,32 @@ Three parameters are required in config: `from` and `to` and `keep-existing`.
 
 The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method` of the parameters of the inputs and outputs
 
-- `inputs`: describe the parameter of the `from` of the global config. The parameter has the following attributes:
+- `inputs`: describe the parameter of the `from` of the config. The parameter has the following attributes:
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
-- `outputs`: describe the parameters of the `to` of the global config. The parameter has the following attributes:
+- `outputs`: describe the parameters of the `to` of the config. The parameter has the following attributes:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+
+### Mapping
+
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
+
+```yaml
+copy-param:
+  path: builtin
+  method: Copy
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
 ### Inputs
 
@@ -69,13 +85,17 @@ To run the plugin, you must first create an instance of `Copy`. Then, you can ca
 ```typescript
 import {Copy} from '.';
 
-const plugin = Copy({
+const config = {
   'keep-existing': true,
   from: 'from-param',
   to: 'to-param',
-});
+};
+const parametersMetadata = {inputs: {}, outputs: {}};
+const mapping = {};
+
+const plugin = Copy(config, parametersMetadata, mapping);
 
-const result = plugin.execute([
+const result = await plugin.execute([
   {
     timestamp: '2023-12-12T00:00:13.000Z',
     duration: 30,
@@ -99,7 +119,7 @@ initialize:
     copy-param:
       path: builtin
       method: Copy
-      global-config:
+      config:
         keep-existing: true
         from: original
         to: copy

package/src/if-run/builtins/csv-lookup/README.md

@@ -61,12 +61,28 @@ The `parameter-metadata` section contains information about `description`, `unit
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
 - `outputs`: describe the parameters in the `output` of the config block. The parameter has the following attributes:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+
+### Mapping
+
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
+
+```yaml
+cloud-metadata:
+  method: CSVLookup
+  path: 'builtin'
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
 ### Inputs
 
@@ -78,7 +94,7 @@ The input data with the requested csv content appended to it.
 
 ## Plugin logic
 
-1. Validates global config which contains `filepath`, `query` and `output`.
+1. Validates config which contains `filepath`, `query` and `output`.
 2. Tries to retrieve given file (with url or local path).
 3. Parses given CSV.
 4. Filters requested information from CSV.
@@ -90,7 +106,7 @@ The input data with the requested csv content appended to it.
 To run the plugin, you must first create an instance of `CSVLookup`. Then, you can call `execute()`.
 
 ```typescript
-const globalConfig = {
+const config = {
   filepath: 'https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/cloud-metdata-aws-instances.csv',
   query: {
     'cloud-provider': 'cloud/provider'
@@ -99,9 +115,11 @@ const globalConfig = {
   },
   output: ['cpu-tdp', 'tdp'],
 };
-const csvLookup = CSVLookup(globalConfig);
+const parametersMetadata = {inputs: {}, outputs: {}};
+const mapping = {};
+const csvLookup = CSVLookup(config, parametersMetadata, mapping);
 
-const input = [
+const result = await csvLookup.execute([
   {
     timestamp: '2023-08-06T00:00'
     duration: 3600
@@ -109,7 +127,7 @@ const input = [
     'cloud/provider': gcp
     'cloud/region': asia-east
   },
-];
+]);
 ```
 
 ## Example manifest
@@ -125,12 +143,14 @@ initialize:
     cloud-metadata:
       method: CSVLookup
       path: 'builtin'
-      global-config:
+      config:
         filepath: https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/region-metadata.csv
         query:
           cloud-provider: 'cloud/provider'
           cloud-region: 'cloud/region'
         output: '*'
+      mapping:
+        cloud/region: cloud/area
 tree:
   children:
     child:
@@ -141,7 +161,7 @@ tree:
         - timestamp: 2023-08-06T00:00
           duration: 3600
           cloud/provider: Google Cloud
-          cloud/region: europe-north1
+          cloud/area: europe-north1
 ```
 
 You can run this example by saving it as `./examples/manifests/csv-lookup.yml` and executing the following command from the project root:
@@ -177,9 +197,9 @@ This error is caused by the `CsvLookup` plugin failing to find data that matches
 
 This error arises due to problems parsing CSV data into IF. This can occur when the CSV data is incorrectly formatted or contains unexpected characters that IF does not recognize. These errors are expected to be unusual edge cases as incorrectly formatted data will usually be identified during file loading and cause a `ReadFileError`. To debug, check your CSV file for any unexpected formatting or unusual characters.
 
-### GlobalConfigError
+### ConfigError
 
-You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+You will receive an error starting `ConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
 
 The required parameters are:
 

package/src/if-run/builtins/divide/README.md

@@ -16,16 +16,32 @@ You provide the names of the values you want to divide, and a name to use to add
 
 The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method` of the parameters of the inputs and outputs
 
-- `inputs`: describe the parameter of the `numerator` of the global config. The parameter has the following attributes:
+- `inputs`: describe the parameter of the `numerator` of the config. The parameter has the following attributes:
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
 - `outputs`: describe the parameter of the `denominator` of the global config. The parameter has the following attributes:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+
+### Mapping
+
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
+
+```yaml
+divide:
+  method: Divide
+  path: 'builtin'
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
 ### Inputs
 
@@ -35,7 +51,7 @@ The `parameter-metadata` section contains information about `description`, `unit
 
 ## Returns
 
-- `output`: the division of `numerator` with the parameter name into `denominator` with the parameter name defined by `output` in global config.
+- `output`: the division of `numerator` with the parameter name into `denominator` with the parameter name defined by `output` in config.
 
 The plugin throws an exception if the division result is not a number.
 
@@ -52,20 +68,24 @@ output = input0 / input1
 To run the plugin, you must first create an instance of `Divide`. Then, you can call `execute()`.
 
 ```typescript
-const globalConfig = {
+const config = {
   numerator: 'vcpus-allocated',
   denominator: 2,
   output: 'cpu/number-cores',
 };
-const divide = Divide(globalConfig, parametersMetadata);
+const parametersMetadata = {inputs: {}, outputs: {}};
+const mapping = {
+  'vcpus-allocated': 'vcpus-distributed',
+};
+const divide = Divide(config, parametersMetadata, mapping);
 
-const input = [
+const result = await divide.execute([
   {
     timestamp: '2021-01-01T00:00:00Z',
     duration: 3600,
     'vcpus-allocated': 24,
   },
-];
+]);
 ```
 
 ## Example manifest
@@ -81,10 +101,12 @@ initialize:
     divide:
       method: Divide
       path: 'builtin'
-      global-config:
+      config:
         numerator: vcpus-allocated
         denominator: 2
         output: cpu/number-cores
+      mapping:
+        vcpus-allocated: vcpus-distributed
 tree:
   children:
     child:
@@ -94,7 +116,7 @@ tree:
       inputs:
         - timestamp: 2023-08-06T00:00
           duration: 3600
-          vcpus-allocated: 24
+          vcpus-distributed: 24
 ```
 
 You can run this example by saving it as `./examples/manifests/divide.yml` and executing the following command from the project root:
@@ -110,9 +132,9 @@ The results will be saved to a new `yaml` file in `./examples/outputs`.
 
 `Divide` exposes two of IF's error classes.
 
-### GlobalConfigError
+### ConfigError
 
-You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+You will receive an error starting `ConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
 
 The required parameters are: