style(parser): apply stricter linting & improve docstrings

Author: dreamorosi

packages/parameters/src/appconfig/AppConfigProvider.ts

@@ -1,5 +1,8 @@
 import { getServiceName } from '@aws-lambda-powertools/commons/utils/env';
-import type { StartConfigurationSessionCommandInput } from '@aws-sdk/client-appconfigdata';
+import type {
+  AppConfigDataClientConfig,
+  StartConfigurationSessionCommandInput,
+} from '@aws-sdk/client-appconfigdata';
 import {
   AppConfigDataClient,
   GetLatestConfigurationCommand,
@@ -14,15 +17,12 @@ import type {
 } from '../types/AppConfigProvider.js';
 
 /**
- * ## Intro
- * The Parameters utility provides an AppConfigProvider that allows to retrieve configuration profiles from AWS AppConfig.
- *
- * ## Getting started
+ * The Parameters utility provides an `AppConfigProvider` that allows to retrieve configuration profiles from AWS AppConfig.
  *
  * This utility supports AWS SDK v3 for JavaScript only (`@aws-sdk/client-appconfigdata`). This allows the utility to be modular, and you to install only
  * the SDK packages you need and keep your bundle size small.
  *
- * ## Basic usage
+ * **Basic usage**
  *
  * @example
  * ```typescript
@@ -41,9 +41,7 @@ import type {
  * ```
  * If you want to retrieve configs without customizing the provider, you can use the {@link getAppConfig} function instead.
  *
- * ## Advanced usage
- *
- * ### Caching
+ * **Caching**
  *
  * By default, the provider will cache parameters retrieved in-memory for 5 seconds.
  * You can adjust how long values should be kept in cache by using the `maxAge` parameter.
@@ -82,7 +80,7 @@ import type {
  * };
  * ```
  *
- * ### Transformations
+ * **Transformations**
  *
  * For configurations stored as freeform JSON, Freature Flag, you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.
  *
@@ -118,7 +116,7 @@ import type {
  * };
  * ```
  *
- * ### Extra SDK options
+ * **Extra SDK options**
  *
  * When retrieving a configuration profile, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter.
  *
@@ -144,7 +142,7 @@ import type {
  *
  * This object accepts the same options as the [AWS SDK v3 for JavaScript AppConfigData client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-appconfigdata/interfaces/startconfigurationsessioncommandinput.html).
  *
- * ### Customize AWS SDK v3 for JavaScript client
+ * **Customize AWS SDK v3 for JavaScript client**
  *
  * By default, the provider will create a new AppConfigData client using the default configuration.
  *
@@ -193,9 +191,14 @@ class AppConfigProvider extends BaseProvider {
   private readonly environment: string;
 
   /**
-   * It initializes the AppConfigProvider class.
-   * *
-   * @param {AppConfigProviderOptions} options - The configuration object.
+   * initializes an `AppConfigProvider` class instance.
+   *
+   * @param options - The configuration object.
+   * @param options.environment - The environment ID or the environment name.
+   * @param options.application - Optional application ID or the application name.
+   * @param options.clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with `awsSdkV3Client`. Accepts the same configuration object as the AWS SDK v3 client ({@link AppConfigDataClientConfig | `AppConfigDataClientConfig`}).
+   * @param options.awsSdkV3Client - Optional ({@link AppConfigDataClient | `AppConfigDataClient`}) instance to pass during `AppConfigProvider` class instantiation. Mutually exclusive with `clientConfig`.
+   *
    */
   public constructor(options: AppConfigProviderOptions) {
     super({
@@ -235,19 +238,16 @@ class AppConfigProvider extends BaseProvider {
    * };
    * ```
    *
-   * You can customize the retrieval of the configuration profile by passing options to the function:
-   * * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
-   * * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
-   * * `transform` - Whether to transform the value before returning it. Supported values: `json`, `binary`
-   * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
-   *
-   * For usage examples check {@link AppConfigProvider}.
-   *
-   * @param {string} name - The name of the configuration profile or its ID
-   * @param {AppConfigGetOptions} options - Options to configure the provider
    * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/
+   *
+   * @param name - The name of the configuration profile or its ID
+   * @param options - Options to configure the provider
+   * @param options.maxAge - Maximum age of the value in the cache, in seconds.
+   * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache.
+   * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 client. Supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier`.
+   * @param options.transform - Optional transform to be applied, can be 'json' or 'binary'.
    */
-  public async get<
+  public get<
     ExplicitUserProvidedType = undefined,
     InferredFromOptionsType extends
       | AppConfigGetOptions
@@ -287,8 +287,12 @@ class AppConfigProvider extends BaseProvider {
    * polls the configuration multiple times, we return the most recent value by returning the cached
    * one if an empty response is returned by AppConfig.
    *
-   * @param {string} name - Name of the configuration or its ID
-   * @param {AppConfigGetOptions} options - SDK options to propagate to `StartConfigurationSession` API call
+   * @param name - Name of the configuration or its ID
+   * @param options - SDK options to propagate to `StartConfigurationSession` API call
+   * @param options.maxAge - Maximum age of the value in the cache, in seconds.
+   * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache.
+   * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 client. Supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier`.
+   * @param options.transform - Optional transform to be applied, can be 'json' or 'binary'.
    */
   protected async _get(
     name: string,
@@ -339,7 +343,7 @@ class AppConfigProvider extends BaseProvider {
     /** When the response is not empty, stash the result locally before returning
      * See AppConfig docs:
      * {@link https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-retrieving-the-configuration.html}
-     **/
+     */
     if (
       response.Configuration !== undefined &&
       response.Configuration?.length > 0
@@ -358,7 +362,7 @@ class AppConfigProvider extends BaseProvider {
    *
    * @throws Not Implemented Error.
    */
-  protected async _getMultiple(
+  protected _getMultiple(
     _path: string,
     _sdkOptions?: unknown
   ): Promise<Record<string, unknown> | undefined> {

packages/parameters/src/dynamodb/DynamoDBProvider.ts

@@ -18,15 +18,12 @@ import type {
 } from '../types/DynamoDBProvider.js';
 
 /**
- * ## Intro
- * The Parameters utility provides a DynamoDBProvider that allows to retrieve values from Amazon DynamoDB.
- *
- * ## Getting started
+ * The Parameters utility provides a `DynamoDBProvider` that allows to retrieve values from Amazon DynamoDB.
  *
  * This utility supports AWS SDK v3 for JavaScript only (`@aws-sdk/client-dynamodb` and `@aws-sdk/util-dynamodb`). This allows the utility to be modular, and you to install only
  * the SDK packages you need and keep your bundle size small.
  *
- * ## Basic usage
+ * **Basic usage**
  *
  * Retrieve a value from DynamoDB:
  *
@@ -60,9 +57,7 @@ import type {
  * };
  * ```
  *
- * ## Advanced usage
- *
- * ### Caching
+ * **Caching**
  *
  * By default, the provider will cache parameters retrieved in-memory for 5 seconds.
  * You can adjust how long values should be kept in cache by using the `maxAge` parameter.
@@ -101,7 +96,7 @@ import type {
  * };
  * ```
  *
- * ### Transformations
+ * **Transformations**
  *
  * For values stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.
  *
@@ -157,7 +152,7 @@ import type {
  * };
  * ```
  *
- * ### Custom key names
+ * **Custom key names**
  *
  * By default, the provider will use the following key names: `id` for the partition key, `sk` for the sort key, and `value` for the value.
  * You can adjust the key names by using the `keyAttr`, `sortAttr`, and `valueAttr` parameters.
@@ -174,7 +169,7 @@ import type {
  * });
  * ```
  *
- * ### Extra SDK options
+ * **Extra SDK options**
  *
  * When retrieving values, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter.
  *
@@ -198,7 +193,7 @@ import type {
  *
  * The objects accept the same options as respectively the [AWS SDK v3 for JavaScript PutItem command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb/classes/putitemcommand.html) and the [AWS SDK v3 for JavaScript DynamoDB client Query command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb/classes/querycommand.html).
  *
- * ### Customize AWS SDK v3 for JavaScript client
+ * **Customize AWS SDK v3 for JavaScript client**
  *
  * By default, the provider will create a new DynamoDB client using the default configuration.
  *
@@ -240,9 +235,15 @@ class DynamoDBProvider extends BaseProvider {
   protected valueAttr = 'value';
 
   /**
-   * It initializes the DynamoDBProvider class.
+   * Initialize a DynamoDBProvider class instance.
    *
-   * @param {DynamoDBProviderOptions} config - The configuration object.
+   * @param config - The configuration object.
+   * @param config.tableName - The DynamoDB table name.
+   * @param config.keyAttr - Optional DynamoDB table key attribute name. Defaults to 'id'.
+   * @param config.sortAttr - Optional DynamoDB table sort attribute name. Defaults to 'sk'.
+   * @param config.valueAttr - Optional DynamoDB table value attribute name. Defaults to 'value'.
+   * @param config.clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with `awsSdkV3Client`, accepts the same options as the AWS SDK v3 client ({@link DynamoDBClient | `DynamoDBClient`}).
+   * @param config.awsSdkV3Client - Optional AWS SDK v3 client to pass during DynamoDBProvider class instantiation. Mutually exclusive with `clientConfig`, should be an instance of {@link DynamoDBClient | `DynamoDBClient`}.
    */
   public constructor(config: DynamoDBProviderOptions) {
     super({
@@ -276,19 +277,16 @@ class DynamoDBProvider extends BaseProvider {
    * };
    * ```
    *
-   * You can customize the retrieval of the value by passing options to the function:
-   * * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
-   * * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
-   * * `transform` - Whether to transform the value before returning it. Supported values: `json`, `binary`
-   * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
-   *
-   * For usage examples check {@link DynamoDBProvider}.
-   *
-   * @param {string} name - The name of the value to retrieve (i.e. the partition key)
-   * @param {DynamoDBGetOptionsInterface} options - Options to configure the provider
    * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/
+   *
+   * @param name - The name of the value to retrieve (i.e. the partition key)
+   * @param options - Options to configure the provider
+   * @param options.maxAge - Maximum age of the value in the cache, in seconds.
+   * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache.
+   * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link GetItemCommandInput | `GetItemCommandInput`} except `Key`, `TableName`, and `ProjectionExpression`.
+   * @param options.transform - Transform to be applied, can be 'json' or 'binary'.
    */
-  public async get<
+  public get<
     ExplicitUserProvidedType = undefined,
     InferredFromOptionsType extends
       | DynamoDBGetOptions
@@ -323,20 +321,17 @@ class DynamoDBProvider extends BaseProvider {
    * };
    * ```
    *
-   * You can customize the retrieval of the values by passing options to the function:
-   * * `maxAge` - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5)
-   * * `forceFetch` - Whether to always fetch a new value from the store regardless if already available in cache
-   * * `transform` - Whether to transform the value before returning it. Supported values: `json`, `binary`
-   * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client
-   * * `throwOnTransformError` - Whether to throw an error if the transform fails (default: `true`)
-   *
-   * For usage examples check {@link DynamoDBProvider}.
-   *
-   * @param {string} path - The path of the values to retrieve (i.e. the partition key)
-   * @param {DynamoDBGetMultipleOptions} options - Options to configure the provider
    * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/
+   *
+   * @param path - The path of the values to retrieve (i.e. the partition key)
+   * @param options - Options to configure the provider
+   * @param options.maxAge - Maximum age of the value in the cache, in seconds.
+   * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache.
+   * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link QueryCommandInput | `QueryCommandInput`} except `TableName` and `KeyConditionExpression`.
+   * @param options.transform - Transform to be applied, can be 'json' or 'binary'.
+   * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`)
    */
-  public async getMultiple<
+  public getMultiple<
     ExplicitUserProvidedType = undefined,
     InferredFromOptionsType extends
       | DynamoDBGetMultipleOptions
@@ -363,8 +358,12 @@ class DynamoDBProvider extends BaseProvider {
   /**
    * Retrieve an item from Amazon DynamoDB.
    *
-   * @param {string} name - Key of the item to retrieve (i.e. the partition key)
-   * @param {DynamoDBGetOptions} options - Options to customize the retrieval
+   * @param name - Key of the item to retrieve (i.e. the partition key)
+   * @param options - Options to customize the retrieval
+   * @param options.maxAge - Maximum age of the value in the cache, in seconds.
+   * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link GetItemCommandInput | `GetItemCommandInput`} except `Key`, `TableName`, and `ProjectionExpression`.
+   * @param params.forceFetch - Force fetch the value from the parameter store, ignoring the cache.
+   * @param options.transform - Transform to be applied, can be 'json' or 'binary'.
    */
   protected async _get(
     name: string,
@@ -387,8 +386,13 @@ class DynamoDBProvider extends BaseProvider {
   /**
    * Retrieve multiple items from Amazon DynamoDB.
    *
-   * @param {string} path - The path of the values to retrieve (i.e. the partition key)
-   * @param {DynamoDBGetMultipleOptions} options - Options to customize the retrieval
+   * @param path - The path of the values to retrieve (i.e. the partition key)
+   * @param options - Options to customize the retrieval
+   * @param options.maxAge - Maximum age of the value in the cache, in seconds.
+   * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache.
+   * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link QueryCommandInput | `QueryCommandInput`} except `TableName` and `KeyConditionExpression`.
+   * @param options.transform - Transform to be applied, can be 'json' or 'binary'.
+   * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`)
    */
   protected async _getMultiple(
     path: string,