feat(logger): JSDOCS support

packages/logger/src/config/ConfigService.ts

@@ -1,21 +1,62 @@
 import { ConfigServiceInterface } from '.';
 
+/**
+ * Abstract class ConfigService
+ *
+ * This class defines common methods and variables that can be set by the developer
+ * in the runtime.
+ *
+ * @class
+ * @abstract
+ * @implements {ConfigServiceInterface}
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime
+ * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#environment-variables
+ */
 abstract class ConfigService implements ConfigServiceInterface {
 
-  // Custom environment variables
+  /**
+   * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#environment-variables
+   * @protected
+   */
   protected currentEnvironmentVariable = 'ENVIRONMENT';
   protected logLevelVariable = 'LOG_LEVEL';
   protected sampleRateValueVariable = 'POWERTOOLS_LOGGER_SAMPLE_RATE';
   protected serviceNameVariable = 'POWERTOOLS_SERVICE_NAME';
 
+  /**
+   * It returns the value of an environment variable that has given name.
+   *
+   * @param {string} name
+   * @returns {string}
+   */
   public abstract get(name: string): string;
 
+  /**
+   * It returns the value of the ENVIRONMENT environment variable.
+   *
+   * @returns {string}
+   */
   public abstract getCurrentEnvironment(): string;
 
+  /**
+   * It returns the value of the LOG_LEVEL environment variable.
+   *
+   * @returns {string}
+   */
   public abstract getLogLevel(): string;
 
+  /**
+   * It returns the value of the POWERTOOLS_LOGGER_SAMPLE_RATE environment variable.
+   *
+   * @returns {string|undefined}
+   */
   public abstract getSampleRateValue(): number | undefined;
 
+  /**
+   * It returns the value of the POWERTOOLS_SERVICE_NAME environment variable.
+   *
+   * @returns {string}
+   */
   public abstract getServiceName(): string;
 
 }

packages/logger/src/config/ConfigServiceInterface.ts

@@ -1,13 +1,46 @@
+/**
+ * Interface ConfigServiceInterface
+ *
+ * @interface
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime
+ * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#environment-variables
+ */
 interface ConfigServiceInterface {
 
+  /**
+   * It returns the value of an environment variable that has given name.
+   *
+   * @param {string} name
+   * @returns {string}
+   */
   get(name: string): string
 
+  /**
+   * It returns the value of the ENVIRONMENT environment variable.
+   *
+   * @returns {string}
+   */
   getCurrentEnvironment(): string
 
+  /**
+   * It returns the value of the LOG_LEVEL environment variable.
+   *
+   * @returns {string}
+   */
   getLogLevel(): string
 
+  /**
+   * It returns the value of the POWERTOOLS_LOGGER_SAMPLE_RATE environment variable.
+   *
+   * @returns {string|undefined}
+   */
   getSampleRateValue(): number | undefined
 
+  /**
+   * It returns the value of the POWERTOOLS_SERVICE_NAME environment variable.
+   *
+   * @returns {string}
+   */
   getServiceName(): string
 
 }

packages/logger/src/config/EnvironmentVariablesService.ts

@@ -1,5 +1,18 @@
 import { ConfigService } from '.';
 
+/**
+ * Class EnvironmentVariablesService
+ *
+ * This class is used to return environment variables that are available in the runtime of
+ * the current Lambda invocation.
+ * These variables can be a mix of runtime environment variables set by AWS and
+ * variables that can be set by the developer additionally.
+ *
+ * @class
+ * @extends {ConfigService}
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime
+ * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#environment-variables
+ */
 class EnvironmentVariablesService extends ConfigService {
 
   // Reserved environment variables
@@ -9,46 +22,97 @@ class EnvironmentVariablesService extends ConfigService {
   private memoryLimitInMBVariable = 'AWS_LAMBDA_FUNCTION_MEMORY_SIZE';
   private xRayTraceIdVariable = '_X_AMZN_TRACE_ID';
 
+  /**
+   * It returns a the value of an environment variable that has given name.
+   *
+   * @param {string} name
+   * @returns {string}
+   */
   public get(name: string): string {
     return process.env[name]?.trim() || '';
   }
 
+  /**
+   * It returns the value of the AWS_REGION environment variable.
+   *
+   * @returns {string}
+   */
   public getAwsRegion(): string {
     return this.get(this.awsRegionVariable);
   }
 
+  /**
+   * It returns the value of the ENVIRONMENT environment variable.
+   *
+   * @returns {string}
+   */
   public getCurrentEnvironment(): string {
     return this.get(this.currentEnvironmentVariable);
   }
 
+  /**
+   * It returns the value of the AWS_LAMBDA_FUNCTION_MEMORY_SIZE environment variable.
+   *
+   * @returns {string}
+   */
   public getFunctionMemory(): number {
     const value = this.get(this.memoryLimitInMBVariable);
 
     return Number(value);
   }
 
+  /**
+   * It returns the value of the AWS_LAMBDA_FUNCTION_NAME environment variable.
+   *
+   * @returns {string}
+   */
   public getFunctionName(): string {
     return this.get(this.functionNameVariable);
   }
 
+  /**
+   * It returns the value of the AWS_LAMBDA_FUNCTION_VERSION environment variable.
+   *
+   * @returns {string}
+   */
   public getFunctionVersion(): string {
     return this.get(this.functionVersionVariable);
   }
 
+  /**
+   * It returns the value of the LOG_LEVEL environment variable.
+   *
+   * @returns {string}
+   */
   public getLogLevel(): string {
     return this.get(this.logLevelVariable);
   }
 
+  /**
+   * It returns the value of the POWERTOOLS_LOGGER_SAMPLE_RATE environment variable.
+   *
+   * @returns {string|undefined}
+   */
   public getSampleRateValue(): number | undefined {
     const value = this.get(this.sampleRateValueVariable);
 
     return (value && value.length > 0) ? Number(value) : undefined;
   }
 
+  /**
+   * It returns the value of the POWERTOOLS_SERVICE_NAME environment variable.
+   *
+   * @returns {string}
+   */
   public getServiceName(): string {
     return this.get(this.serviceNameVariable);
   }
 
+  /**
+   * It returns the value of the _X_AMZN_TRACE_ID environment variable.
+   *
+   * @returns {string}
+   */
   public getXrayTraceId(): string {
     return this.get(this.xRayTraceIdVariable);
   }

packages/logger/src/formatter/LogFormatter.ts

@@ -1,10 +1,31 @@
 import { LogFormatterInterface } from '.';
 import { LogAttributes, UnformattedAttributes } from '../types';
 
+/**
+ * Abstract class LogFormatter
+ *
+ * This class defines and implements common methods for the formatting of log attributes.
+ *
+ * @class
+ * @abstract
+ * @implements {LogFormatterInterface}
+ */
 abstract class LogFormatter implements LogFormatterInterface {
 
+  /**
+   * It formats key-value pairs of log attributes.
+   *
+   * @param {UnformattedAttributes} attributes
+   * @returns {LogAttributes}
+   */
   public abstract formatAttributes(attributes: UnformattedAttributes): LogAttributes;
 
+  /**
+   * It formats a given Error parameter.
+   *
+   * @param {Error} error
+   * @returns {LogAttributes}
+   */
   public formatError(error: Error): LogAttributes {
     return {
       name: error.name,
@@ -14,10 +35,22 @@ abstract class LogFormatter implements LogFormatterInterface {
     };
   }
 
+  /**
+   * It formats a date into a string in simplified extended ISO format (ISO 8601).
+   *
+   * @param {Date} now
+   * @returns {string}
+   */
   public formatTimestamp(now: Date): string {
     return now.toISOString();
   }
 
+  /**
+   * It returns a string containing the location of an error, given a particular stack trace.
+   *
+   * @param stack
+   * @returns {string}
+   */
   public getCodeLocation(stack?: string): string {
     if (!stack) {
       return '';

packages/logger/src/formatter/LogFormatterInterface.ts

@@ -1,9 +1,26 @@
 import { LogAttributes, UnformattedAttributes } from '../types';
 
+/**
+ * Interface LogFormatterInterface
+ *
+ * @interface
+ */
 interface LogFormatterInterface {
 
+  /**
+   * It formats key-value pairs of log attributes.
+   *
+   * @param {UnformattedAttributes} attributes
+   * @returns {PowertoolLog}
+   */
   formatAttributes(attributes: UnformattedAttributes): LogAttributes
 
+  /**
+   * It formats a given Error parameter.
+   *
+   * @param {Error} error
+   * @returns {LogAttributes}
+   */
   formatError(error: Error): LogAttributes
 
 }

packages/logger/src/formatter/PowertoolLogFormatter.ts

@@ -2,8 +2,21 @@ import { LogFormatter } from '.';
 import { UnformattedAttributes } from '../types';
 import { PowertoolLog } from '../types/formats';
 
+/**
+ * This class is used to transform a set of log key-value pairs
+ * in the AWS Lambda Powertools' default structure log format.
+ *
+ * @class
+ * @extends {LogFormatter}
+ */
 class PowertoolLogFormatter extends LogFormatter {
 
+  /**
+   * It formats key-value pairs of log attributes.
+   *
+   * @param {UnformattedAttributes} attributes
+   * @returns {PowertoolLog}
+   */
   public formatAttributes(attributes: UnformattedAttributes): PowertoolLog {
     return {
       cold_start: attributes.lambdaContext?.coldStart,

packages/logger/src/middleware/middy.ts

@@ -1,6 +1,13 @@
 import type { Logger } from '../Logger';
 import middy from '@middy/core';
 
+/**
+ * Middy middleware that adds the current Lambda invocation's context
+ * inside all log items.
+ *
+ * @param {Logger|Logger[]} target
+ * @returns middy.MiddlewareObj
+ */
 const injectLambdaContext = (target: Logger | Logger[]): middy.MiddlewareObj => {
   const injectLambdaContextBefore = async (request: middy.Request): Promise<void> => {
     const loggers = target instanceof Array ? target : [target];