feat(metrics): return metrics instance from metrics functions (#4930)

dothomson · svozza · web-flow · commit e7aa2e2b5efb · 2026-01-16T12:34:54.000Z
Co-authored-by: Stefano Vozza &lt;svozza@amazon.com&gt;
diff --git a/packages/metrics/src/Metrics.ts b/packages/metrics/src/Metrics.ts
@@ -71,9 +71,10 @@ import type {
  * });
  *
  * export const handler = async (event: { requestId: string }) => {
- *   metrics.addMetadata('request_id', event.requestId);
- *   metrics.addMetric('successfulBooking', MetricUnit.Count, 1);
- *   metrics.publishStoredMetrics();
+ *   metrics
+ *     .addMetadata('request_id', event.requestId)
+ *     .addMetric('successfulBooking', MetricUnit.Count, 1)
+ *     .publishStoredMetrics();
  * };
  * ```
  *
@@ -110,7 +111,7 @@ import type {
  * ```
  *
  * Note that decorators are a Stage 3 proposal for JavaScript and are not yet part of the ECMAScript standard.
- * The current implmementation in this library is based on the legacy TypeScript decorator syntax enabled by the [`experimentalDecorators` flag](https://www.typescriptlang.org/tsconfig/#experimentalDecorators)
+ * The current implementation in this library is based on the legacy TypeScript decorator syntax enabled by the [`experimentalDecorators` flag](https://www.typescriptlang.org/tsconfig/#experimentalDecorators)
  * set to `true` in the `tsconfig.json` file.
  *
  * **Middy.js middleware**
@@ -239,12 +240,12 @@ class Metrics extends Utility implements MetricsInterface {
    * @param name - The name of the dimension
    * @param value - The value of the dimension
    */
-  public addDimension(name: string, value: string): void {
+  public addDimension(name: string, value: string): this {
     if (isStringUndefinedNullEmpty(name) || isStringUndefinedNullEmpty(value)) {
       this.#logger.warn(
         `The dimension ${name} doesn't meet the requirements and won't be added. Ensure the dimension name and value are non empty strings`
       );
-      return;
+      return this;
     }
     if (MAX_DIMENSION_COUNT <= this.#dimensionsStore.getDimensionCount()) {
       throw new RangeError(
@@ -262,6 +263,7 @@ class Metrics extends Utility implements MetricsInterface {
       );
     }
     this.#dimensionsStore.addDimension(name, value);
+    return this;
   }
 
   /**
@@ -276,7 +278,7 @@ class Metrics extends Utility implements MetricsInterface {
    *
    * @param dimensions - An object with key-value pairs of dimensions
    */
-  public addDimensions(dimensions: Dimensions): void {
+  public addDimensions(dimensions: Dimensions): this {
     const newDimensions = this.#sanitizeDimensions(dimensions);
     const currentCount = this.#dimensionsStore.getDimensionCount();
     const newSetCount = Object.keys(newDimensions).length;
@@ -287,6 +289,7 @@ class Metrics extends Utility implements MetricsInterface {
     }
 
     this.#dimensionsStore.addDimensionSet(newDimensions);
+    return this;
   }
 
   /**
@@ -316,8 +319,9 @@ class Metrics extends Utility implements MetricsInterface {
    * @param key - The key of the metadata
    * @param value - The value of the metadata
    */
-  public addMetadata(key: string, value: string): void {
+  public addMetadata(key: string, value: string): this {
     this.#metadataStore.set(key, value);
+    return this;
   }
 
   /**
@@ -359,9 +363,10 @@ class Metrics extends Utility implements MetricsInterface {
     unit: MetricUnit,
     value: number,
     resolution: MetricResolution = MetricResolutions.Standard
-  ): void {
+  ): this {
     this.storeMetric(name, unit, value, resolution);
     if (this.isSingleMetric) this.publishStoredMetrics();
+    return this;
   }
 
   /**
@@ -450,7 +455,7 @@ class Metrics extends Utility implements MetricsInterface {
    *
    *   // ...
    *
-   *   metrics.clearDimensions(); // olnly the region dimension is removed
+   *   metrics.clearDimensions(); // only the region dimension is removed
    * };
    * ```
    *
@@ -595,7 +600,7 @@ class Metrics extends Utility implements MetricsInterface {
    * };
    * ```
    */
-  public publishStoredMetrics(): void {
+  public publishStoredMetrics(): this {
     const hasMetrics = this.hasStoredMetrics();
     if (!this.shouldThrowOnEmptyMetrics && !hasMetrics) {
       this.#logger.warn(
@@ -613,6 +618,7 @@ class Metrics extends Utility implements MetricsInterface {
     this.clearMetrics();
     this.clearDimensions();
     this.clearMetadata();
+    return this;
   }
 
   /**
@@ -645,14 +651,15 @@ class Metrics extends Utility implements MetricsInterface {
    * ```
    * @param timestamp - The timestamp to set, which can be a number or a Date object.
    */
-  public setTimestamp(timestamp: number | Date): void {
+  public setTimestamp(timestamp: number | Date): this {
     if (!this.#validateEmfTimestamp(timestamp)) {
       this.#logger.warn(
         "This metric doesn't meet the requirements and will be skipped by Amazon CloudWatch. " +
           'Ensure the timestamp is within 14 days in the past or up to 2 hours in the future and is also a valid number or Date object.'
       );
     }
     this.#metricsStore.setTimestamp(timestamp);
+    return this;
   }
 
   /**
@@ -786,7 +793,7 @@ class Metrics extends Utility implements MetricsInterface {
    *
    * @param dimensions - The dimensions to be added to the default dimensions object
    */
-  public setDefaultDimensions(dimensions: Dimensions): void {
+  public setDefaultDimensions(dimensions: Dimensions): this {
     const newDimensions = this.#sanitizeDimensions(dimensions);
     const currentDefaultDimensions =
       this.#dimensionsStore.getDefaultDimensions();
@@ -802,6 +809,7 @@ class Metrics extends Utility implements MetricsInterface {
       ...currentDefaultDimensions,
       ...newDimensions,
     });
+    return this;
   }
 
   /**
@@ -823,8 +831,9 @@ class Metrics extends Utility implements MetricsInterface {
    *
    * @param enabled - Whether to throw an error if no metrics are emitted
    */
-  public setThrowOnEmptyMetrics(enabled: boolean): void {
+  public setThrowOnEmptyMetrics(enabled: boolean): this {
     this.shouldThrowOnEmptyMetrics = enabled;
+    return this;
   }
 
   /**
@@ -1042,11 +1051,15 @@ class Metrics extends Utility implements MetricsInterface {
       throw new RangeError(`${value} is not a valid number`);
     if (!Object.values(MetricUnits).includes(unit))
       throw new RangeError(
-        `Invalid metric unit '${unit}', expected either option: ${Object.values(MetricUnits).join(',')}`
+        `Invalid metric unit '${unit}', expected either option: ${Object.values(
+          MetricUnits
+        ).join(',')}`
       );
     if (!Object.values(MetricResolutions).includes(resolution))
       throw new RangeError(
-        `Invalid metric resolution '${resolution}', expected either option: ${Object.values(MetricResolutions).join(',')}`
+        `Invalid metric resolution '${resolution}', expected either option: ${Object.values(
+          MetricResolutions
+        ).join(',')}`
       );
 
     if (this.#metricsStore.getMetricsCount() >= MAX_METRICS_SIZE) {
diff --git a/packages/metrics/src/types/Metrics.ts b/packages/metrics/src/types/Metrics.ts
@@ -179,7 +179,7 @@ interface MetricsInterface {
    * @param name - The name of the dimension
    * @param value - The value of the dimension
    */
-  addDimension(name: string, value: string): void;
+  addDimension(name: string, value: string): MetricsInterface;
   /**
    * Add multiple dimensions to the metrics.
    *
@@ -191,7 +191,7 @@ interface MetricsInterface {
    *
    * @param dimensions - An object with key-value pairs of dimensions
    */
-  addDimensions(dimensions: Dimensions): void;
+  addDimensions(dimensions: Dimensions): MetricsInterface;
   /**
    * A metadata key-value pair to be included with metrics.
    *
@@ -219,7 +219,7 @@ interface MetricsInterface {
    * @param key - The key of the metadata
    * @param value - The value of the metadata
    */
-  addMetadata(key: string, value: string): void;
+  addMetadata(key: string, value: string): MetricsInterface;
   /**
    * Add a metric to the metrics buffer.
    *
@@ -260,7 +260,7 @@ interface MetricsInterface {
     unit: MetricUnit,
     value: number,
     resolution?: MetricResolution
-  ): void;
+  ): MetricsInterface;
   /**
    * Immediately emit a `ColdStart` metric if this is a cold start invocation.
    *
@@ -335,7 +335,7 @@ interface MetricsInterface {
    *
    *   // ...
    *
-   *   metrics.clearDimensions(); // olnly the region dimension is removed
+   *   metrics.clearDimensions(); // only the region dimension is removed
    * };
    * ```
    *
@@ -506,7 +506,7 @@ interface MetricsInterface {
    * ```
    * @param timestamp - The timestamp to set, which can be a number or a Date object.
    */
-  setTimestamp(timestamp: number | Date): void;
+  setTimestamp(timestamp: number | Date): MetricsInterface;
   /**
    * Create a new Metrics instance configured to immediately flush a single metric.
    *
@@ -539,14 +539,14 @@ interface MetricsInterface {
 }
 
 export type {
-  MetricsOptions,
   Dimensions,
   EmfOutput,
   ExtraOptions,
-  StoredMetrics,
-  StoredMetric,
   MetricDefinition,
   MetricResolution,
-  MetricUnit,
   MetricsInterface,
+  MetricsOptions,
+  MetricUnit,
+  StoredMetric,
+  StoredMetrics,
 };
diff --git a/packages/metrics/tests/e2e/basicFeatures.manual.test.functionCode.ts b/packages/metrics/tests/e2e/basicFeatures.manual.test.functionCode.ts
@@ -27,13 +27,17 @@ const metrics = new Metrics({ namespace: namespace, serviceName: serviceName });
 
 export const handler = (_event: unknown, _context: Context) => {
   metrics.captureColdStartMetric();
-  metrics.throwOnEmptyMetrics();
-  metrics.setDefaultDimensions(JSON.parse(defaultDimensions));
-  metrics.addMetric(metricName, metricUnit, Number.parseInt(metricValue, 10));
-  metrics.addDimension(
-    Object.entries(JSON.parse(extraDimension))[0][0],
-    Object.entries(JSON.parse(extraDimension))[0][1] as string
-  );
+
+  metrics
+    .setThrowOnEmptyMetrics(true)
+    .setDefaultDimensions(JSON.parse(defaultDimensions));
+
+  metrics
+    .addMetric(metricName, metricUnit, Number.parseInt(metricValue, 10))
+    .addDimension(
+      Object.entries(JSON.parse(extraDimension))[0][0],
+      Object.entries(JSON.parse(extraDimension))[0][1] as string
+    );
 
   const metricWithItsOwnDimensions = metrics.singleMetric();
   metricWithItsOwnDimensions.addDimension(
diff --git a/packages/metrics/tests/unit/concurrency/metrics.test.ts b/packages/metrics/tests/unit/concurrency/metrics.test.ts
@@ -53,9 +53,10 @@ describe('Metrics concurrent invocation isolation', () => {
           () => {
             // Metrics must be created inside ALS context because reset() clears InvokeStore
             metrics = new Metrics({ singleMetric: false });
-            metrics.addDimension('env', 'prod');
-            metrics.addMetric('count', MetricUnit.Count, 1);
-            metrics.addMetadata('key', 'value1');
+            metrics
+              .addDimension('env', 'prod')
+              .addMetric('count', MetricUnit.Count, 1)
+              .addMetadata('key', 'value1');
           },
         ],
         return: () => metrics.publishStoredMetrics(),
@@ -132,8 +133,9 @@ describe('Metrics concurrent invocation isolation', () => {
         sideEffects: [
           () => {},
           () => {
-            metrics.setTimestamp(timestamp2);
-            metrics.addMetric('count', MetricUnit.Count, 2);
+            metrics
+              .setTimestamp(timestamp2)
+              .addMetric('count', MetricUnit.Count, 2);
           },
           () => metrics.publishStoredMetrics(),
         ],
diff --git a/packages/metrics/tests/unit/creatingMetrics.test.ts b/packages/metrics/tests/unit/creatingMetrics.test.ts
@@ -61,10 +61,11 @@ describe('Creating metrics', () => {
     const metrics = new Metrics({ singleMetric: false });
 
     // Act
-    metrics.addMetric('test', MetricUnit.Count, 1);
-    metrics.addMetric('test', MetricUnit.Count, 2);
-    metrics.addMetric('another', MetricUnit.Bytes, 3);
-    metrics.publishStoredMetrics();
+    metrics
+      .addMetric('test', MetricUnit.Count, 1)
+      .addMetric('test', MetricUnit.Count, 2)
+      .addMetric('another', MetricUnit.Bytes, 3)
+      .publishStoredMetrics();
 
     // Assess
     expect(console.log).toHaveBeenCalledTimes(1);
@@ -101,8 +102,7 @@ describe('Creating metrics', () => {
     metrics.addMetric('test', MetricUnit.Count, 1);
     metrics.addMetric('test', MetricUnit.Count, 2);
     metrics.clearMetrics();
-    metrics.addMetric('another', MetricUnit.Count, 3);
-    metrics.publishStoredMetrics();
+    metrics.addMetric('another', MetricUnit.Count, 3).publishStoredMetrics();
 
     // Assess
     expect(console.log).toHaveBeenCalledTimes(1);
@@ -126,11 +126,11 @@ describe('Creating metrics', () => {
     const metrics = new Metrics({ singleMetric: false });
 
     // Act
-    metrics.addMetric('test', MetricUnit.Count, 1);
-    metrics.addMetric('test', MetricUnit.Count, 2);
-    metrics.publishStoredMetrics();
-    metrics.addMetric('another', MetricUnit.Count, 3);
-    metrics.publishStoredMetrics();
+    metrics
+      .addMetric('test', MetricUnit.Count, 1)
+      .addMetric('test', MetricUnit.Count, 2)
+      .publishStoredMetrics();
+    metrics.addMetric('another', MetricUnit.Count, 3).publishStoredMetrics();
 
     // Assess
     expect(console.log).toHaveBeenCalledTimes(2);
@@ -328,7 +328,9 @@ describe('Creating metrics', () => {
     // @ts-expect-error - Testing runtime behavior with invalid metric unit
     expect(() => metrics.addMetric('test', 'invalid-unit', 1)).toThrowError(
       new RangeError(
-        `Invalid metric unit 'invalid-unit', expected either option: ${Object.values(MetricUnit).join(',')}`
+        `Invalid metric unit 'invalid-unit', expected either option: ${Object.values(
+          MetricUnit
+        ).join(',')}`
       )
     );
   });
@@ -343,7 +345,9 @@ describe('Creating metrics', () => {
       metrics.addMetric('test', MetricUnit.Count, 1, 'invalid-resolution')
     ).toThrowError(
       new RangeError(
-        `Invalid metric resolution 'invalid-resolution', expected either option: ${Object.values(MetricResolution).join(',')}`
+        `Invalid metric resolution 'invalid-resolution', expected either option: ${Object.values(
+          MetricResolution
+        ).join(',')}`
       )
     );
   });
diff --git a/packages/metrics/tests/unit/customTimestamp.test.ts b/packages/metrics/tests/unit/customTimestamp.test.ts
@@ -84,8 +84,7 @@ describe('Setting custom timestamp', () => {
     });
 
     // Act
-    metrics.setTimestamp(Number.NaN);
-    metrics.addMetric('test', MetricUnit.Count, 1);
+    metrics.setTimestamp(Number.NaN).addMetric('test', MetricUnit.Count, 1);
 
     // Assess
     expect(console.warn).toHaveBeenCalledTimes(1);
@@ -111,8 +110,9 @@ describe('Setting custom timestamp', () => {
     });
 
     // Act
-    metrics.setTimestamp(Date.now() + 0.5);
-    metrics.addMetric('test', MetricUnit.Count, 1);
+    metrics
+      .setTimestamp(Date.now() + 0.5)
+      .addMetric('test', MetricUnit.Count, 1);
 
     // Assess
     expect(console.warn).toHaveBeenCalledTimes(1);
diff --git a/packages/metrics/tests/unit/dimensions.test.ts b/packages/metrics/tests/unit/dimensions.test.ts
diff --git a/packages/metrics/tests/unit/metadata.test.ts b/packages/metrics/tests/unit/metadata.test.ts
