add jsdoc on new functions

Author: flochaz

packages/metrics/src/Metrics.ts

@@ -88,7 +88,7 @@ class Metrics implements MetricsInterface {
   private isSingleMetric: boolean = false;
   private metadata: { [key: string]: string } = {};
   private namespace?: string;
-  private raiseOnEmptyMetrics: boolean = false;
+  private shouldRaiseOnEmptyMetrics: boolean = false;
   private storedMetrics: StoredMetrics = {};
 
   public constructor(options: MetricsOptions = {}) {
@@ -165,6 +165,28 @@ class Metrics implements MetricsInterface {
     this.storedMetrics = {};
   }
 
+
+  /**
+   * Throw an Error if the metrics buffer is empty.
+   *
+   * @example
+   *
+   * ```typescript
+   * import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+   * import { Context } from 'aws-lambda';
+   *
+   * const metrics = new Metrics({namespace:"ServerlessAirline", service:"orders"});
+   *
+   * export const handler = async (event: any, context: Context) => {
+   *     metrics.raiseOnEmptyMetrics();
+   *     metrics.purgeStoredMetrics(); // will throw since no metrics added.
+   * }
+   * ```
+   */
+  public raiseOnEmptyMetrics(): void {
+    this.shouldRaiseOnEmptyMetrics = true;
+  }
+
   /**
    * A decorator automating coldstart capture, raise on empty metrics and publishing metrics on handler exit.
    *
@@ -192,7 +214,9 @@ class Metrics implements MetricsInterface {
    */
   public logMetrics(options: DecoratorOptions = {}): HandlerMethodDecorator {
     const { raiseOnEmptyMetrics, defaultDimensions, captureColdStartMetric } = options;
-    this.raiseOnEmptyMetrics = raiseOnEmptyMetrics || false;
+    if (raiseOnEmptyMetrics) {
+      this.raiseOnEmptyMetrics();
+    }
     if (defaultDimensions !== undefined) {
       this.setDefaultDimensions(defaultDimensions);
     }
@@ -202,7 +226,7 @@ class Metrics implements MetricsInterface {
       descriptor.value = (event, context, callback) => {
         this.functionName = context.functionName;
 
-        if (captureColdStartMetric) this.captureColdStart();
+        if (captureColdStartMetric) this.captureColdStartMetric();
         try {
           const result = originalMethod?.apply(this, [event, context, callback]);
           return result;
@@ -245,7 +269,7 @@ class Metrics implements MetricsInterface {
       Name: metricDefinition.name,
       Unit: metricDefinition.unit,
     }));
-    if (metricDefinitions.length === 0 && this.raiseOnEmptyMetrics) {
+    if (metricDefinitions.length === 0 && this.shouldRaiseOnEmptyMetrics) {
       throw new RangeError('The number of metrics recorded must be higher than zero');
     }
 
@@ -321,8 +345,21 @@ class Metrics implements MetricsInterface {
    *   * Add function_name and service dimensions
    *
    * This has the advantage of keeping cold start metric separate from your application metrics, where you might have unrelated dimensions.
+   *
+   * @example
+   *
+   * ```typescript
+   * import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
+   * import { Context } from 'aws-lambda';
+   *
+   * const metrics = new Metrics({namespace:"ServerlessAirline", service:"orders"});
+   *
+   * export const handler = async (event: any, context: Context) => {
+   *     metrics.captureColdStartMetric();
+   * }
+   * ```
    */
-  public captureColdStart(): void {
+  public captureColdStartMetric(): void {
     if (!this.isColdStart) return;
     this.isColdStart = false;
     const singleMetric = this.singleMetric();

packages/metrics/tests/unit/Metrics.test.ts

@@ -225,6 +225,25 @@ describe('Class: Metrics', () => {
   });
 
   describe('Feature: Cold Start', () => {
+    test('Cold start metric should only be written out once and flushed automatically', async () => {
+      const metrics = new Metrics({ namespace: 'test' });
+
+      const handler = async (event: any, context: Context) => {
+        // Should generate only one log
+        metrics.captureColdStartMetric();
+      };
+
+      await handler(dummyEvent, dummyContext);
+      await handler(dummyEvent, dummyContext);
+      const loggedData = [JSON.parse(consoleSpy.mock.calls[0][0])];
+
+      expect(console.log).toBeCalledTimes(1);
+      expect(loggedData[0]._aws.CloudWatchMetrics[0].Metrics.length).toBe(1);
+      expect(loggedData[0]._aws.CloudWatchMetrics[0].Metrics[0].Name).toBe('ColdStart');
+      expect(loggedData[0]._aws.CloudWatchMetrics[0].Metrics[0].Unit).toBe('Count');
+      expect(loggedData[0].ColdStart).toBe(1);
+    });
+
     test('Cold start metric should only be written out once', async () => {
       const metrics = new Metrics({ namespace: 'test' });
 
@@ -338,6 +357,23 @@ describe('Class: Metrics', () => {
         expect((<Error>e).message).toBe('The number of metrics recorded must be higher than zero');
       }
     });
+
+    test('Error should be thrown on empty metrics when raiseOnEmptyMetrics() is callse', async () => {
+      expect.assertions(1);
+
+      const metrics = new Metrics({ namespace: 'test' });
+      const handler = async (event: any, context: Context) => {
+        metrics.raiseOnEmptyMetrics();
+        // Logic goes here
+        metrics.purgeStoredMetrics();
+      };
+
+      try {
+        await handler(dummyEvent, dummyContext);
+      } catch (e) {
+        expect((<Error>e).message).toBe('The number of metrics recorded must be higher than zero');
+      }
+    });
   });
 
   describe('Feature: Auto log at limit', () => {