From 7f0971806f2266425549fa30845bba2a6f8737c4 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 24 Sep 2025 18:23:47 +0200 Subject: [PATCH 1/3] style(parser): apply stricter linting & improve docstrings --- .../src/appconfig/AppConfigProvider.ts | 64 +++--- .../src/dynamodb/DynamoDBProvider.ts | 86 ++++---- .../parameters/src/secrets/SecretsProvider.ts | 56 +++--- packages/parameters/src/secrets/getSecret.ts | 39 ++-- packages/parameters/src/ssm/SSMProvider.ts | 185 +++++++++--------- packages/parameters/src/ssm/getParameter.ts | 48 ++--- packages/parameters/src/ssm/getParameters.ts | 50 ++--- .../parameters/src/ssm/getParametersByName.ts | 48 ++--- packages/parameters/src/ssm/setParameter.ts | 27 +-- .../parameters/src/types/AppConfigProvider.ts | 77 +++++--- packages/parameters/src/types/BaseProvider.ts | 20 +- .../parameters/src/types/DynamoDBProvider.ts | 106 ++++++---- packages/parameters/src/types/SSMProvider.ts | 51 +++-- .../parameters/src/types/SecretsProvider.ts | 42 ++-- .../tests/e2e/appConfigProvider.class.test.ts | 14 +- .../tests/e2e/dynamoDBProvider.class.test.ts | 18 +- .../tests/e2e/secretsProvider.class.test.ts | 10 +- .../tests/e2e/ssmProvider.class.test.ts | 20 +- .../tests/unit/AppConfigProvider.test.ts | 10 +- .../tests/unit/DynamoDBProvider.test.ts | 6 +- .../parameters/tests/unit/SSMProvider.test.ts | 12 +- .../tests/unit/SecretsProvider.test.ts | 6 +- .../tests/unit/setParameter.test.ts | 2 +- 23 files changed, 480 insertions(+), 517 deletions(-) diff --git a/packages/parameters/src/appconfig/AppConfigProvider.ts b/packages/parameters/src/appconfig/AppConfigProvider.ts index 1975968c99..49aa1b9c5c 100644 --- a/packages/parameters/src/appconfig/AppConfigProvider.ts +++ b/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 | undefined> { diff --git a/packages/parameters/src/dynamodb/DynamoDBProvider.ts b/packages/parameters/src/dynamodb/DynamoDBProvider.ts index 2678d31113..1b096f8893 100644 --- a/packages/parameters/src/dynamodb/DynamoDBProvider.ts +++ b/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, diff --git a/packages/parameters/src/secrets/SecretsProvider.ts b/packages/parameters/src/secrets/SecretsProvider.ts index 134e788536..a04521f37a 100644 --- a/packages/parameters/src/secrets/SecretsProvider.ts +++ b/packages/parameters/src/secrets/SecretsProvider.ts @@ -11,15 +11,12 @@ import type { } from '../types/SecretsProvider.js'; /** - * ## Intro - * The Parameters utility provides a SecretsProvider that allows to retrieve secrets from AWS Secrets Manager. - * - * ## Getting started + * The Parameters utility provides a `SecretsProvider` that allows to retrieve secrets from AWS Secrets Manager. * * This utility supports AWS SDK v3 for JavaScript only (`@aws-sdk/client-secrets-manager`). 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 @@ -35,9 +32,7 @@ import type { * * If you want to retrieve secrets without customizing the provider, you can use the {@link getSecret} 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. @@ -68,7 +63,7 @@ import type { * }; * ``` * - * ### Transformations + * **Transformations** * * For parameters stored in JSON or Base64 format, you can use the transform argument for deserialization. * @@ -84,7 +79,7 @@ import type { * }; * ``` * - * ### Extra SDK options + * **Extra SDK options** * * When retrieving a secret, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter. * @@ -106,7 +101,7 @@ import type { * * This object accepts the same options as the [AWS SDK v3 for JavaScript Secrets Manager client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-secrets-manager/interfaces/getsecretvaluecommandinput.html). * - * ### Customize AWS SDK v3 for JavaScript client + * **Customize AWS SDK v3 for JavaScript client** * * By default, the provider will create a new Secrets Manager client using the default configuration. * @@ -140,16 +135,17 @@ import type { * * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). * - * @class * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ */ class SecretsProvider extends BaseProvider { public declare client: SecretsManagerClient; /** - * It initializes the SecretsProvider class. + * Initialize a `SecretsProvider` class. * - * @param {SecretsProviderOptions} config - The configuration object. + * @param config - The configuration object. + * @param config.clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with `awsSdkV3Client`. + * @param config.awsSdkV3Client - Optional AWS SDK v3 client to pass during {@link SecretsProvider | `SecretsProvider`} class instantiation. Mutually exclusive with `clientConfig`. */ public constructor(config?: SecretsProviderOptions) { super({ @@ -175,19 +171,16 @@ class SecretsProvider extends BaseProvider { * }; * ``` * - * You can customize the retrieval of the secret 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 SecretsProvider}. - * - * @param {string} name - The name of the secret - * @param {SecretsGetOptions} options - Options to customize the retrieval of the secret * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param name - The name of the secret + * @param options - Options to customize the retrieval of the secret + * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client */ - public async get< + public get< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SecretsGetOptions @@ -206,7 +199,7 @@ class SecretsProvider extends BaseProvider { } /** - * Retrieving multiple parameter values is not supported with AWS Secrets Manager. + * Retrieving multiple secrets is not supported with AWS Secrets Manager. */ /* v8 ignore start */ public async getMultiple( path: string, @@ -216,10 +209,11 @@ class SecretsProvider extends BaseProvider { } /* v8 ignore stop */ /** - * Retrieve a configuration from AWS Secrets Manager. + * Retrieve a secret from AWS Secrets Manager. * - * @param {string} name - Name of the configuration or its ID - * @param {SecretsGetOptions} options - SDK options to propagate to the AWS SDK v3 for JavaScript client + * @param name - Name of the secret or its ID + * @param options - SDK options to propagate to the AWS SDK v3 for JavaScript client + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client, accepts the same options as {@link GetSecretValueCommandInput | `GetSecretValueCommandInput`} except `SecretId`. */ protected async _get( name: string, @@ -240,11 +234,11 @@ class SecretsProvider extends BaseProvider { } /** - * Retrieving multiple parameter values is not supported with AWS Secrets Manager. + * Retrieving multiple secrets is not supported with AWS Secrets Manager. * * @throws Not Implemented Error. */ - protected async _getMultiple( + protected _getMultiple( _path: string, _options?: unknown ): Promise | undefined> { diff --git a/packages/parameters/src/secrets/getSecret.ts b/packages/parameters/src/secrets/getSecret.ts index 6b47a3cc75..2d3987542f 100644 --- a/packages/parameters/src/secrets/getSecret.ts +++ b/packages/parameters/src/secrets/getSecret.ts @@ -1,3 +1,4 @@ +import type { SecretsManagerClientConfig } from '@aws-sdk/client-secrets-manager'; import { DEFAULT_PROVIDERS } from '../base/DefaultProviders.js'; import type { SecretsGetOptions, @@ -6,21 +7,12 @@ import type { import { SecretsProvider } from './SecretsProvider.js'; /** - * ## Intro - * The Parameters utility provides a SecretsProvider that allows to retrieve secrets from AWS Secrets Manager. - * - * ## Getting started + * The Parameters utility provides a `SecretsProvider` that allows to retrieve secrets from AWS Secrets Manager. * * This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only * the SDK packages you need and keep your bundle size small. * - * To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for Secrets Manager: - * - * ```sh - * npm install @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager - * ``` - * - * ## Basic usage + * **Basic usage** * * @example * ```typescript @@ -32,9 +24,7 @@ import { SecretsProvider } from './SecretsProvider.js'; * }; * ``` * - * ## 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. @@ -61,7 +51,7 @@ import { SecretsProvider } from './SecretsProvider.js'; * }; * ``` * - * ### Transformations + * **Transformations** * * For parameters stored as JSON or base64-encoded strings, you can use the transform argument set to `json` or `binary` for deserialization. * @@ -75,7 +65,7 @@ import { SecretsProvider } from './SecretsProvider.js'; * }; * ``` * - * ### Extra SDK options + * **Extra SDK options** * * When retrieving a secret, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter. * @@ -95,18 +85,21 @@ import { SecretsProvider } from './SecretsProvider.js'; * * This object accepts the same options as the [AWS SDK v3 for JavaScript Secrets Manager client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-secrets-manager/interfaces/getsecretvaluecommandinput.html). * - * ### Built-in provider class + * **Built-in provider class** * * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SecretsProvider} class. * - * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). - * - * - * @param {string} name - The name of the secret to retrieve - * @param {SecretsGetOptions} options - Options to configure the provider * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param name - The name of the secret to retrieve + * @param options - Options to configure the provider + * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: `5`) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client, accepts the same configuration object as the AWS SDK v3 client ({@link SecretsManagerClientConfig | `SecretsManagerClientConfig`}). + * @param options.decrypt - Whether to decrypt the value before returning it. (default: `false`) */ -const getSecret = async < +const getSecret = < ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SecretsGetOptions diff --git a/packages/parameters/src/ssm/SSMProvider.ts b/packages/parameters/src/ssm/SSMProvider.ts index d905ab2681..30b7ee6b9f 100644 --- a/packages/parameters/src/ssm/SSMProvider.ts +++ b/packages/parameters/src/ssm/SSMProvider.ts @@ -35,15 +35,12 @@ import type { } from '../types/SSMProvider.js'; /** - * ## Intro - * The Parameters utility provides a SSMProvider that allows to retrieve parameters from AWS Systems Manager. - * - * ## Getting started + * The Parameters utility provides a `SSMProvider` that allows to retrieve parameters from AWS Systems Manager. * * This utility supports AWS SDK v3 for JavaScript only (`@aws-sdk/client-ssm`). 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 parameter from SSM: * @@ -96,9 +93,7 @@ import type { * * If you don't need to customize the provider, you can also use the {@link getParametersByName} 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. @@ -157,7 +152,7 @@ import type { * * Likewise, you can use the `forceFetch` parameter with the `getParametersByName` method both for individual parameters and for all parameters. * - * ### Decryption + * **Decryption** * * If you want to retrieve a parameter that is encrypted, you can use the `decrypt` parameter. This parameter is compatible with `get`, `getMultiple` and `getParametersByName`. * @@ -175,7 +170,7 @@ import type { * }; * ``` * - * ### Transformations + * **Transformations** * * For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string. * @@ -211,7 +206,7 @@ import type { * * Both type of transformations are compatible also with the `getParametersByName` method. * - * ### Extra SDK options + * **Extra SDK options** * * When retrieving parameters, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter. * @@ -233,7 +228,7 @@ import type { * * The objects accept the same options as respectively the [AWS SDK v3 for JavaScript GetParameter command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/classes/getparametercommand.html) and the [AWS SDK v3 for JavaScript GetParametersByPath command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/classes/getparametersbypathcommand.html). * - * ### Customize AWS SDK v3 for JavaScript client + * **Customize AWS SDK v3 for JavaScript client** * * By default, the provider will create a new SSM client using the default configuration. * @@ -275,7 +270,7 @@ class SSMProvider extends BaseProvider { /** * It initializes the SSMProvider class. * - * @param {SSMProviderOptions} config - The configuration object. + * @param config - The configuration object. */ public constructor(config?: SSMProviderOptions) { super({ @@ -298,21 +293,18 @@ class SSMProvider extends BaseProvider { * const parameter = await parametersProvider.get('/my-parameter'); * }; * ``` - * - * 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 - * * `decrypt` - Whether to decrypt the value before returning it. - * - * For usage examples check {@link SSMProvider}. - * - * @param {string} name - The name of the value to retrieve (i.e. the partition key) - * @param {SSMGetOptions} 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 - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache (default: false) + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client + * @param options.decrypt - Whether to decrypt the value before returning it. (default: false) */ - public async get< + public get< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends SSMGetOptions | undefined = SSMGetOptions, >( @@ -343,19 +335,17 @@ class SSMProvider extends BaseProvider { * }; * ``` * - * You can customize the storage of the value by passing options to the function: - * * `value` - The value of the parameter, which is a mandatory option. - * * `overwrite` - Whether to overwrite the value if it already exists (default: `false`) - * * `description` - The description of the parameter - * * `parameterType` - The type of the parameter, can be one of `String`, `StringList`, or `SecureString` (default: `String`) - * * `tier` - The parameter tier to use, can be one of `Standard`, `Advanced`, and `Intelligent-Tiering` (default: `Standard`) - * * `kmsKeyId` - The KMS key id to use to encrypt the parameter - * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client - * - * @param {string} name - The name of the parameter - * @param {SSMSetOptions} options - Options to configure the parameter - * @returns {Promise} The version of the parameter * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param name - The name of the parameter + * @param options - Options to configure the parameter + * @param options.value - The value of the parameter + * @param options.overwrite - Whether to overwrite the value if it already exists (default: `false`) + * @param options.description - The description of the parameter + * @param options.parameterType - The type of the parameter, can be one of `String`, `StringList`, or `SecureString` (default: `String`) + * @param options.tier - The parameter tier to use, can be one of `Standard`, `Advanced`, and `Intelligent-Tiering` (default: `Standard`) + * @param options.kmsKeyId - The KMS key id to use to encrypt the parameter + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client */ public async set< InferredFromOptionsType extends SSMSetOptions | undefined = SSMSetOptions, @@ -400,22 +390,21 @@ class SSMProvider 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`) - * * `decrypt` - Whether to decrypt the value before returning it. - * * `recursive` - Whether to recursively retrieve all parameters under the given path (default: `false`) - * - * For usage examples check {@link SSMProvider}. + * For usage examples check {@link SSMProvider | `SSMProvider`}. * - * @param {string} path - The path of the parameters to retrieve - * @param {SSMGetMultipleOptions} options - Options to configure the retrieval * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param path - The path of the parameters to retrieve + * @param options - Options to configure the retrieval + * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client + * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) + * @param options.decrypt - Whether to decrypt the value before returning it. + * @param options.recursive - Whether to recursively retrieve all parameters under the given path (default: `false`) */ - public async getMultiple< + public getMultiple< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SSMGetMultipleOptions @@ -450,15 +439,8 @@ class SSMProvider extends BaseProvider { * }); * }; * ``` - * You can customize the retrieval of the values by passing options to **both the function and the parameter**: - * * `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`) - * * `decrypt` - Whether to decrypt the value before returning it - * - * `throwOnError` decides whether to throw an error if a parameter is not found: + * + * The `throwOnError` option decides whether to throw an error if a parameter is not found: * - A) Default fail-fast behavior: Throws a `GetParameterError` error upon any failure. * - B) Gracefully aggregate all parameters that failed under "_errors" key. * @@ -479,9 +461,17 @@ class SSMProvider extends BaseProvider { * └────────────────────┘ * ``` * - * @param {Record} parameters - Object containing parameter names and any optional overrides - * @param {SSMGetParametersByNameOptions} options - Options to configure the retrieval * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param parameters - Object containing parameter names and any optional overrides + * @param options - Options to configure the retrieval + * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client + * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) + * @param options.decrypt - Whether to decrypt the value before returning it. + * @param options.throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error (default: `true`) */ public async getParametersByName( parameters: Record, @@ -554,8 +544,11 @@ class SSMProvider extends BaseProvider { /** * Retrieve a parameter from AWS Systems Manager. * - * @param {string} name - Name of the parameter to retrieve - * @param {SSMGetOptions} options - Options to customize the retrieval + * @param name - Name of the parameter to retrieve + * @param options - Options to customize the retrieval + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client + * @param options.decrypt - Whether to decrypt the value before returning it. + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary`, or `auto` (default: `undefined`) */ protected async _get( name: string, @@ -577,8 +570,15 @@ class SSMProvider extends BaseProvider { /** * Retrieve multiple items from AWS Systems Manager. * - * @param {string} path - The path of the parameters to retrieve - * @param {SSMGetMultipleOptions} options - Options to configure the provider + * @param path - The path of the parameters to retrieve + * @param options - Options to configure the provider + * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client + * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) + * @param options.decrypt - Whether to decrypt the value before returning it. + * @param options.recursive - Whether to recursively retrieve all parameters under the given path (default: `false`) */ protected async _getMultiple( path: string, @@ -613,7 +613,7 @@ class SSMProvider extends BaseProvider { * * The parameter name returned by SSM will contain the full path. * However, for readability, we should return only the part after the path. - **/ + */ // biome-ignore lint/style/noNonNullAssertion: If the parameter is present in the response, then it has a Name let name = parameter.Name!; name = name.replace(path, ''); @@ -630,9 +630,9 @@ class SSMProvider extends BaseProvider { /** * Retrieve multiple items by name from AWS Systems Manager. * - * @param {Record} parameters - An object of parameter names and their options - * @param {throwOnError} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully - * @param {boolean} decrypt - Whether to decrypt the parameters or not + * @param parameters - An object of parameter names and their options + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully + * @param decrypt - Whether to decrypt the parameters or not */ protected async _getParametersByName( parameters: Record, @@ -666,9 +666,9 @@ class SSMProvider extends BaseProvider { /** * Slice batch and fetch parameters using GetPrameters API by max permissible batch size * - * @param {Record} parameters - An object of parameter names and their options - * @param {throwOnError} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully - * @param {boolean} decrypt - Whether to decrypt the parameters or not + * @param parameters - An object of parameter names and their options + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully + * @param decrypt - Whether to decrypt the parameters or not */ protected async getParametersBatchByName( parameters: Record, @@ -705,11 +705,11 @@ class SSMProvider extends BaseProvider { /** * Fetch each parameter from batch that hasn't expired from cache * - * @param {Record} parameters - An object of parameter names and their options + * @param parameters - An object of parameter names and their options */ - protected async getParametersByNameFromCache( + protected getParametersByNameFromCache( parameters: Record - ): Promise { + ): SSMGetParametersByNameFromCacheOutputType { const cached: Record> = {}; const toFetch: Record = {}; @@ -737,9 +737,9 @@ class SSMProvider extends BaseProvider { /** * Slice object into chunks of max permissible batch size and fetch parameters * - * @param {Record} parameters - An object of parameter names and their options - * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully - * @param {boolean} decrypt - Whether to decrypt the parameters or not + * @param parameters - An object of parameter names and their options + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully + * @param decrypt - Whether to decrypt the parameters or not */ protected async getParametersByNameInChunks( parameters: Record, @@ -781,8 +781,8 @@ class SSMProvider extends BaseProvider { /** * Fetch parameters by name while also decrypting them * - * @param {Record} parameters - An object of parameter names and their options - * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully + * @param parameters - An object of parameter names and their options + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully */ protected async getParametersByNameWithDecryptOption( parameters: Record, @@ -814,11 +814,12 @@ class SSMProvider extends BaseProvider { } /** - * Handle any invalid parameters returned by GetParameters API + * Handle any invalid parameters returned by GetParameters API. + * * GetParameters is non-atomic. Failures don't always reflect in exceptions so we need to collect. * - * @param {GetParametersCommandOutput} result - The result of the GetParameters API call - * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully + * @param result - The result of the GetParameters API call + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully */ protected static handleAnyInvalidGetParameterErrors( result: Partial, @@ -855,8 +856,8 @@ class SSMProvider extends BaseProvider { /** * Split parameters that can be fetched by GetParameters vs GetParameter. * - * @param {Record} parameters - An object of parameter names and their options - * @param {SSMGetParametersByNameOptions} configs - The configs passed down + * @param parameters - An object of parameter names and their options + * @param configs - The configs passed down */ protected static splitBatchAndDecryptParameters( parameters: Record, @@ -896,9 +897,9 @@ class SSMProvider extends BaseProvider { /** * Throw a GetParameterError if fail-fast is disabled and `_errors` key is in parameters list. * - * @param {Record} parameters - * @param {string} reservedParameter - * @param {boolean} throwOnError + * @param parameters - An object of parameter names and their options + * @param reservedParameter - The reserved parameter name that cannot be used when fail-fast is disabled + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully */ protected static throwIfErrorsKeyIsPresent( parameters: Record, @@ -915,9 +916,9 @@ class SSMProvider extends BaseProvider { /** * Transform and cache the response from GetParameters API call * - * @param {GetParametersCommandOutput} response - The response from the GetParameters API call - * @param {Record} parameters - An object of parameter names and their options - * @param {boolean} throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully + * @param response - The response from the GetParameters API call + * @param parameters - An object of parameter names and their options + * @param throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error or handle them gracefully */ protected transformAndCacheGetParametersResponse( response: Partial, diff --git a/packages/parameters/src/ssm/getParameter.ts b/packages/parameters/src/ssm/getParameter.ts index 50a4ab93f3..6468e1d2de 100644 --- a/packages/parameters/src/ssm/getParameter.ts +++ b/packages/parameters/src/ssm/getParameter.ts @@ -3,21 +3,12 @@ import type { SSMGetOptions, SSMGetOutput } from '../types/SSMProvider.js'; import { SSMProvider } from './SSMProvider.js'; /** - * ## Intro - * The Parameters utility provides an SSMProvider that allows to retrieve parameters from AWS Systems Manager. - * - * ## Getting started + * The Parameters utility provides an `SSMProvider` that allows to retrieve parameters from AWS Systems Manager. * * This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only * the SDK packages you need and keep your bundle size small. * - * To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for AppConfig: - * - * ```sh - * npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm - * ``` - * - * ## Basic usage + * **Basic usage** * * @example * ```typescript @@ -29,9 +20,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ## Advanced usage - * - * ### Decryption + * **Decryption** * * If you have encrypted parameters, you can use the `decrypt` option to automatically decrypt them. * @@ -45,7 +34,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### 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. @@ -72,7 +61,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### Transformations + * **Transformations** * * For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string. * @@ -98,7 +87,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### Extra SDK options + * **Extra SDK options** * * When retrieving a parameter, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter. * @@ -118,26 +107,21 @@ import { SSMProvider } from './SSMProvider.js'; * * This object accepts the same options as the [AWS SDK v3 for JavaScript SSM GetParameter command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/interfaces/getparametercommandinput.html). * - * ### Built-in provider class + * **Built-in provider class** * * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SSMProvider} class. * - * ### Options - * - * * 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 - * * `decrypt` - Whether to decrypt the value before returning it. - * - * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). - * - * @param {string} name - The name of the parameter to retrieve - * @param {SSMGetOptions} options - Options to configure the provider * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param name - The name of the parameter to retrieve + * @param options - Options to configure the provider + * @param options.maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. + * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @param options.transform - Optional transform to be applied, can be 'json' or 'binary'. + * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 for JavaScript client. Supports all options from {@link GetParameterCommandInput | `GetParameterCommandInput`} except `Name`. + * @param options.decrypt - Whether to decrypt the value before returning it. Defaults to `false`. */ -const getParameter = async < +const getParameter = < ExplicitUserProvidedType = undefined, InferredFromOptionsType extends SSMGetOptions | undefined = SSMGetOptions, >( diff --git a/packages/parameters/src/ssm/getParameters.ts b/packages/parameters/src/ssm/getParameters.ts index a00caee550..bcd438f0f0 100644 --- a/packages/parameters/src/ssm/getParameters.ts +++ b/packages/parameters/src/ssm/getParameters.ts @@ -6,21 +6,12 @@ import type { import { SSMProvider } from './SSMProvider.js'; /** - * ## Intro - * The Parameters utility provides an SSMProvider that allows to retrieve parameters from AWS Systems Manager. - * - * ## Getting started + * The Parameters utility provides an `SSMProvider` that allows to retrieve parameters from AWS Systems Manager. * * This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only * the SDK packages you need and keep your bundle size small. * - * To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for AppConfig: - * - * ```sh - * npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm - * ``` - * - * ## Basic usage + * **Basic usage** * * @example * ```typescript @@ -32,9 +23,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ## Advanced usage - * - * ### Decryption + * **Decryption** * * If you have encrypted parameters, you can use the `decrypt` option to automatically decrypt them. * @@ -48,7 +37,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### 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. @@ -75,7 +64,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### Transformations + * **Transformations** * * For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript objects instead of a strings. * @@ -101,7 +90,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### Extra SDK options + * **Extra SDK options** * * When retrieving a parameter, you can pass extra options to the AWS SDK v3 for JavaScript client by using the `sdkOptions` parameter. * @@ -121,27 +110,20 @@ import { SSMProvider } from './SSMProvider.js'; * * This object accepts the same options as the [AWS SDK v3 for JavaScript SSM getParametersByPath command](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ssm/interfaces/getParameterssbypathcommandinput.html). * - * ### Built-in provider class - * * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SSMProvider} class. * - * ### Options - * - * * 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 - * * `decrypt` - Whether to decrypt the value before returning it. - * * `recursive` - Whether to recursively retrieve all parameters within the path. - * - * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). - * - * @param {string} path - The path of the parameters to retrieve - * @param {SSMGetMultipleOptions} options - Options to configure the provider * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param path - The path of the parameters to retrieve + * @param options - Options to configure the provider + * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) + * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client, accepts the same options as {@link GetParametersByPathCommandInput | `GetParametersByPathCommandInput`}. + * @param options.decrypt - Whether to decrypt the value before returning it. + * @param options.recursive - Whether to recursively retrieve all parameters within the path. */ -const getParameters = async < +const getParameters = < ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SSMGetMultipleOptions diff --git a/packages/parameters/src/ssm/getParametersByName.ts b/packages/parameters/src/ssm/getParametersByName.ts index b609871b0f..ef67f28ab7 100644 --- a/packages/parameters/src/ssm/getParametersByName.ts +++ b/packages/parameters/src/ssm/getParametersByName.ts @@ -6,21 +6,12 @@ import type { import { SSMProvider } from './SSMProvider.js'; /** - * ## Intro - * The Parameters utility provides an SSMProvider that allows to retrieve parameters from AWS Systems Manager. - * - * ## Getting started + * The Parameters utility provides an `SSMProvider` that allows to retrieve parameters from AWS Systems Manager. * * This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only * the SDK packages you need and keep your bundle size small. * - * To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for AppConfig: - * - * ```sh - * npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm - * ``` - * - * ## Basic usage + * **Basic usage** * * @example * ```typescript @@ -35,9 +26,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ## Advanced usage - * - * ### Decryption + * **Decryption** * * If you have encrypted parameters, you can use the `decrypt` option to automatically decrypt them. * @@ -54,7 +43,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### 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. @@ -102,7 +91,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### Transformations + * **Transformations** * * For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript objects instead of a strings. * For parameters that are instead stored as base64-encoded binary data, you can use the transform argument set to `binary` for decoding. This will return decoded strings for each parameter. @@ -121,21 +110,9 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * - * ### Built-in provider class - * * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SSMProvider} class. * - * ### Options - * - * * You can customize the retrieval of the value by passing options to **both the function and the parameter**: - * * `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 - * * `decrypt` - Whether to decrypt the value before returning it - * - * `throwOnError` decides whether to throw an error if a parameter is not found: + * The `throwOnError` parameter decides whether to throw an error if a parameter is not found: * - A) Default fail-fast behavior: Throws a `GetParameterError` error upon any failure. * - B) Gracefully aggregate all parameters that failed under "_errors" key. * @@ -156,13 +133,16 @@ import { SSMProvider } from './SSMProvider.js'; * └────────────────────┘ * ``` * - * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). - * - * @param {Record} parameters - The path of the parameters to retrieve - * @param {SSMGetParametersByNameOptions} options - Options to configure the provider * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param parameters - The path of the parameters to retrieve + * @param options - Options to configure the provider + * @param options.maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. + * @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 GetParametersByNameCommandInput | `GetParametersByNameCommandInput`} except `Names`. + * @param options.decrypt - Whether to decrypt the values before returning them. If true, will use `GetParameter` API for each parameter. If false (default), will use `GetParametersByName` API. */ -const getParametersByName = async ( +const getParametersByName = ( parameters: Record, options?: SSMGetParametersByNameOptions ): Promise> => { diff --git a/packages/parameters/src/ssm/setParameter.ts b/packages/parameters/src/ssm/setParameter.ts index a059d11dc5..21adbefff6 100644 --- a/packages/parameters/src/ssm/setParameter.ts +++ b/packages/parameters/src/ssm/setParameter.ts @@ -58,24 +58,17 @@ import { SSMProvider } from './SSMProvider.js'; * * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SSMProvider} utility. * - * **Options** - * - * You can customize the storage of the value by passing options to the function: - * * `value` - The value of the parameter, which is a mandatory option. - * * `overwrite` - Whether to overwrite the value if it already exists (default: `false`) - * * `description` - The description of the parameter - * * `parameterType` - The type of the parameter, can be one of `String`, `StringList`, or `SecureString` (default: `String`) - * * `tier` - The parameter tier to use, can be one of `Standard`, `Advanced`, and `Intelligent-Tiering` (default: `Standard`) - * * `kmsKeyId` - The KMS key id to use to encrypt the parameter - * * `sdkOptions` - Extra options to pass to the AWS SDK v3 for JavaScript client - * - * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). - * - * @param name - Name of the parameter - * @param options - Options to configure the parameter - * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ + * + * @param name - Name of the parameter + * @param options - Options to configure the parameter + * @param options.value - The value of the parameter + * @param options.overwrite - Whether to overwrite the value if it already exists (default: `false`) + * @param options.description - The description of the parameter + * @param options.parameterType - The type of the parameter, can be one of `String`, `StringList`, or `SecureString` (default: `String`) + * @param options.tier - The parameter tier to use, can be one of `Standard`, `Advanced`, and `Intelligent-Tiering` (default: `Standard`) */ -const setParameter = async < +const setParameter = < InferredFromOptionsType extends SSMSetOptions | undefined = SSMSetOptions, >( name: string, diff --git a/packages/parameters/src/types/AppConfigProvider.ts b/packages/parameters/src/types/AppConfigProvider.ts index 64dc4ee170..134b26b403 100644 --- a/packages/parameters/src/types/AppConfigProvider.ts +++ b/packages/parameters/src/types/AppConfigProvider.ts @@ -4,80 +4,85 @@ import type { AppConfigDataClientConfig, StartConfigurationSessionCommandInput, } from '@aws-sdk/client-appconfigdata'; +import type { AppConfigProvider } from '../appconfig/AppConfigProvider.js'; +import type { getAppConfig } from '../appconfig/getAppConfig.js'; import type { GetOptionsInterface } from './BaseProvider.js'; /** - * Base interface for AppConfigProviderOptions. + * Base interface for {@link AppConfigProviderOptions | `AppConfigProviderOptions`}. * - * @interface - * @property {string} environment - The environment ID or the environment name. - * @property {string} [application] - The application ID or the application name. + * @property environment - The environment ID or the environment name. + * @property application - The optional application ID or the application name. */ interface AppConfigProviderOptionsBaseInterface { + /** + * The environment ID or the environment name. + */ environment: string; + /** The optional application ID or the application name. + */ application?: string; } /** - * Interface for AppConfigProviderOptions with clientConfig property. + * Interface for {@link AppConfigProviderOptions | `AppConfigProviderOptions`} with `clientConfig` property. * - * @interface - * @extends AppConfigProviderOptionsBaseInterface - * @property {AppConfigDataClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. - * @property {never} [awsSdkV3Client] - This property should never be passed. + * @property clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. + * @property awsSdkV3Client - This property should never be passed when using `clientConfig`. */ interface AppConfigProviderOptionsWithClientConfig extends AppConfigProviderOptionsBaseInterface { /** - * Optional configuration to pass during client initialization, e.g. AWS region. It accepts the same configuration object as the AWS SDK v3 client (`AppConfigDataClient`). + * Optional configuration to pass during client initialization, e.g. AWS region. Accepts the same configuration object as the AWS SDK v3 client ({@link AppConfigDataClientConfig | `AppConfigDataClientConfig`}). */ clientConfig?: AppConfigDataClientConfig; + /** + * This property should never be passed when using `clientConfig`. + */ awsSdkV3Client?: never; } /** - * Interface for AppConfigProviderOptions with awsSdkV3Client property. + * Interface for {@link AppConfigProviderOptions | `AppConfigProviderOptions`} with awsSdkV3Client property. * - * @interface - * @extends AppConfigProviderOptionsBaseInterface - * @property {AppConfigDataClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during AppConfigProvider class instantiation - * @property {never} [clientConfig] - This property should never be passed. + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during the `AppConfigProvider` class instantiation, should be an instance of {@link AppConfigDataClient | `AppConfigDataClient`}. + * @property clientConfig - This property should never be passed when using `awsSdkV3Client`. */ interface AppConfigProviderOptionsWithClientInstance extends AppConfigProviderOptionsBaseInterface { /** - * Optional AWS SDK v3 client instance (`AppConfigDataClient`) to use for AppConfig operations. If not provided, we will create a new instance of `AppConfigDataClient`. + * Optional AWS SDK v3 client instance ({@link AppConfigDataClient | `AppConfigDataClient`}) to use for AppConfig operations. If not provided, we will create a new instance of the client. */ awsSdkV3Client?: AppConfigDataClient; + /** + * This property should never be passed when using `awsSdkV3Client`. + */ clientConfig?: never; } /** - * Options for the AppConfigProvider class constructor. + * Options for the `AppConfigProvider` class constructor. * - * @type AppConfigProviderOptions - * @property {string} environment - The environment ID or the environment name. - * @property {string} [application] - The application ID or the application name. - * @property {AppConfigDataClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with awsSdkV3Client. - * @property {AppConfigDataClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during AppConfigProvider class instantiation. Mutually exclusive with clientConfig. + * @property environment - The environment ID or the environment name. + * @property application - The optional application ID or the application name. + * @property 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`}). + * @property awsSdkV3Client - Optional ({@link AppConfigDataClient | `AppConfigDataClient`}) instance to pass during `AppConfigProvider` class instantiation. Mutually exclusive with `clientConfig`. */ type AppConfigProviderOptions = | AppConfigProviderOptionsWithClientConfig | AppConfigProviderOptionsWithClientInstance; /** - * Options for the AppConfigProvider get method. + * Options for the {@link AppConfigProvider.get | `AppConfigProvider.get()`} method. * - * @interface AppConfigGetOptionsBase - * @extends {GetOptionsInterface} - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {StartConfigurationSessionCommandInput} [sdkOptions] - Additional options to pass to the AWS SDK v3 client. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Additional options to pass to the AWS SDK v3 client. Supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier`. + * @property transform - Optional transform to be applied, can be 'json' or 'binary'. */ interface AppConfigGetOptionsBase extends GetOptionsInterface { /** - * Additional options to pass to the AWS SDK v3 client. Supports all options from `StartConfigurationSessionCommandInput` except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier`. + * Additional options to pass to the AWS SDK v3 client. Supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier`. */ sdkOptions?: Omit< Partial, @@ -99,6 +104,14 @@ interface AppConfigGetOptionsTransformNone extends AppConfigGetOptionsBase { transform?: never; } +/** + * Options for the {@link AppConfigProvider.get | `AppConfigProvider.get()`} method. + * + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Additional options to pass to the AWS SDK v3 client. Supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier`. + * @property transform - Optional transform to be applied, can be 'json' or 'binary'. + */ type AppConfigGetOptions = | AppConfigGetOptionsTransformNone | AppConfigGetOptionsTransformJson @@ -106,7 +119,7 @@ type AppConfigGetOptions = | undefined; /** - * Generic output type for the AppConfigProvider get method. + * Generic output type for the {@link AppConfigProvider.get | `AppConfigProvider.get()` } get method. */ type AppConfigGetOutput< ExplicitUserProvidedType = undefined, @@ -124,7 +137,7 @@ type AppConfigGetOutput< : ExplicitUserProvidedType; /** - * Combined options for the getAppConfig utility function. + * Combined options for the {@link getAppConfig | `getAppConfig()`} utility function. */ type GetAppConfigOptions = Omit< AppConfigProviderOptions, diff --git a/packages/parameters/src/types/BaseProvider.ts b/packages/parameters/src/types/BaseProvider.ts index 3154bb0893..d4ec626c9c 100644 --- a/packages/parameters/src/types/BaseProvider.ts +++ b/packages/parameters/src/types/BaseProvider.ts @@ -1,7 +1,7 @@ import type { Transform } from '../constants.js'; /** - * Options for the BaseProvider class constructor. + * Options for the `BaseProvider` class constructor. */ type BaseProviderConstructorOptions = { /** @@ -30,10 +30,10 @@ type TransformOptions = (typeof Transform)[keyof typeof Transform]; /** * Options for the `get` method. * - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {unknown} sdkOptions - Options to pass to the underlying SDK. - * @property {TransformOptions} transform - Transform to be applied, can be 'json', 'binary', or 'auto'. + * @property maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Options to pass to the underlying SDK. + * @property transform - Optional transform to be applied, can be 'json', 'binary', or 'auto'. */ interface GetOptionsInterface { /** @@ -57,11 +57,11 @@ interface GetOptionsInterface { /** * Options for the `getMultiple` method. * - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {unknown} sdkOptions - Options to pass to the underlying SDK. - * @property {TransformOptions} transform - Transform to be applied, can be 'json', 'binary', or 'auto'. - * @property {boolean} throwOnTransformError - Whether to throw an error if a value cannot be transformed. + * @property maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Options to pass to the underlying SDK. + * @property transform - Transform to be applied, can be 'json', 'binary', or 'auto'. + * @property throwOnTransformError - Whether to throw an error if a value cannot be transformed. */ interface GetMultipleOptionsInterface extends GetOptionsInterface { /** diff --git a/packages/parameters/src/types/DynamoDBProvider.ts b/packages/parameters/src/types/DynamoDBProvider.ts index 97b6241636..664e0dbac7 100644 --- a/packages/parameters/src/types/DynamoDBProvider.ts +++ b/packages/parameters/src/types/DynamoDBProvider.ts @@ -5,87 +5,101 @@ import type { GetItemCommandInput, QueryCommandInput, } from '@aws-sdk/client-dynamodb'; +import type { DynamoDBProvider } from '../dynamodb/DynamoDBProvider.js'; import type { GetMultipleOptionsInterface, GetOptionsInterface, } from './BaseProvider.js'; /** - * Base interface for DynamoDBProviderOptions. + * Base interface for {@link DynamoDBProviderOptions | `DynamoDBProviderOptions`}. * - * @interface - * @property {string} tableName - The DynamoDB table name. - * @property {string} [keyAttr] - The DynamoDB table key attribute name. Defaults to 'id'. - * @property {string} [sortAttr] - The DynamoDB table sort attribute name. Defaults to 'sk'. - * @property {string} [valueAttr] - The DynamoDB table value attribute name. Defaults to 'value'. + * @property tableName - The DynamoDB table name. + * @property keyAttr - Optional DynamoDB table key attribute name. Defaults to 'id'. + * @property sortAttr - Optional DynamoDB table sort attribute name. Defaults to 'sk'. + * @property valueAttr - Optional DynamoDB table value attribute name. Defaults to 'value'. */ interface DynamoDBProviderOptionsBase { + /** + * The DynamoDB table name. + */ tableName: string; + /** + * Optional DynamoDB table key attribute name. Defaults to 'id'. + */ keyAttr?: string; + /** + * Optional DynamoDB table sort attribute name. Defaults to 'sk'. + */ sortAttr?: string; + /** + * Optional DynamoDB table value attribute name. Defaults to 'value'. + */ valueAttr?: string; } /** - * Interface for DynamoDBProviderOptions with clientConfig property. + * Interface for {@link DynamoDBProviderOptions | `DynamoDBProviderOptions`} with `clientConfig` property. * - * @interface - * @extends DynamoDBProviderOptionsBase - * @property {DynamoDBClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. - * @property {never} [awsSdkV3Client] - This property should never be passed. + * @property clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Accepts the same options as the AWS SDK v3 client ({@link DynamoDBClient | `DynamoDBClient`}). + * @property awsSdkV3Client - This property should never be passed when using `clientConfig`. */ interface DynamoDBProviderOptionsWithClientConfig extends DynamoDBProviderOptionsBase { /** - * Optional configuration to pass during client initialization, e.g. AWS region. It accepts the same configuration object as the AWS SDK v3 client (`DynamoDBClient`). + * Optional configuration to pass during client initialization, e.g. AWS region. Accepts the same options as the AWS SDK v3 client ({@link DynamoDBClient | `DynamoDBClient`}). */ clientConfig?: DynamoDBClientConfig; + /** + * This property should never be passed when using `clientConfig`. + */ awsSdkV3Client?: never; } /** - * Interface for DynamoDBProviderOptions with awsSdkV3Client property. + * Interface for {@link DynamoDBProviderOptions | `DynamoDBProviderOptions`} with `awsSdkV3Client` property. * - * @interface - * @extends DynamoDBProviderOptionsBase - * @property {DynamoDBClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during DynamoDBProvider class instantiation - * @property {never} [clientConfig] - This property should never be passed. + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during `DynamoDBProvider` class instantiation, should be an instance of {@link DynamoDBClient | `DynamoDBClient`}. + * @property clientConfig - This property should never be passed when using `awsSdkV3Client`. */ interface DynamoDBProviderOptionsWithClientInstance extends DynamoDBProviderOptionsBase { /** - * Optional AWS SDK v3 client instance (`DynamoDBClient`) to use for DynamoDB operations. If not provided, we will create a new instance of `DynamoDBClient`. + * Optional AWS SDK v3 client instance ({@link DynamoDBClient | `DynamoDBClient`}) to use for DynamoDB operations. If not provided, we will create a new instance of the client. */ awsSdkV3Client?: DynamoDBClient; + /** + * This property should never be passed when using `awsSdkV3Client`. + */ clientConfig?: never; } /** - * Options for the DynamoDBProvider class constructor. + * Options for the {@link DynamoDBProvider | `DynamoDBProvider`} class constructor. * - * @type DynamoDBProviderOptions - * @property {string} tableName - The DynamoDB table name. - * @property {string} [keyAttr] - The DynamoDB table key attribute name. Defaults to 'id'. - * @property {string} [sortAttr] - The DynamoDB table sort attribute name. Defaults to 'sk'. - * @property {string} [valueAttr] - The DynamoDB table value attribute name. Defaults to 'value'. - * @property {DynamoDBClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with awsSdkV3Client. - * @property {DynamoDBClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during DynamoDBProvider class instantiation. Mutually exclusive with clientConfig. + * @property tableName - The DynamoDB table name. + * @property keyAttr - Optional DynamoDB table key attribute name. Defaults to 'id'. + * @property sortAttr - Optional DynamoDB table sort attribute name. Defaults to 'sk'. + * @property valueAttr - Optional DynamoDB table value attribute name. Defaults to 'value'. + * @property 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`}). + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during DynamoDBProvider class instantiation. Mutually exclusive with `clientConfig`, should be an instance of {@link DynamoDBClient | `DynamoDBClient`}. */ type DynamoDBProviderOptions = | DynamoDBProviderOptionsWithClientConfig | DynamoDBProviderOptionsWithClientInstance; /** - * Options for the DynamoDBProvider get method. + * Options for the {@link DynamoDBProvider.get | `DynamoDBProvider.get()`} get method. * - * @interface DynamoDBGetOptionsBase - * @extends {GetOptionsInterface} - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {GetItemCommandInput} [sdkOptions] - Additional options to pass to the AWS SDK v3 client. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link GetItemCommandInput | `GetItemCommandInput`} except `Key`, `TableName`, and `ProjectionExpression`. + * @property transform - Transform to be applied, can be 'json' or 'binary'. */ interface DynamoDBGetOptionsBase extends GetOptionsInterface { + /** + * Additional options to pass to the AWS SDK v3 client, supports all options from {@link GetItemCommandInput | `GetItemCommandInput`} except `Key`, `TableName`, and `ProjectionExpression`. + */ sdkOptions?: Omit< Partial, 'Key' | 'TableName' | 'ProjectionExpression' @@ -104,6 +118,14 @@ interface DynamoDBGetOptionsTransformNone extends DynamoDBGetOptionsBase { transform?: never; } +/** + * Options for the {@link DynamoDBProvider.get | `DynamoDBProvider.get()`} get method. + * + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link GetItemCommandInput | `GetItemCommandInput`} except `Key`, `TableName`, and `ProjectionExpression`. + * @property transform - Transform to be applied, can be 'json' or 'binary'. + */ type DynamoDBGetOptions = | DynamoDBGetOptionsTransformNone | DynamoDBGetOptionsTransformJson @@ -111,7 +133,7 @@ type DynamoDBGetOptions = | undefined; /** - * Generic output type for DynamoDBProvider get method. + * Generic output type for {@link DynamoDBProvider.get | `DynamoDBProvider.get()`} method. */ type DynamoDBGetOutput< ExplicitUserProvidedType = undefined, @@ -129,15 +151,13 @@ type DynamoDBGetOutput< : ExplicitUserProvidedType; /** - * Options for the DynamoDBProvider getMultiple method. + * Options for the {@link DynamoDBProvider.getMultiple | `DynamoDBProvider.getMultiple()`} method. * - * @interface DynamoDBGetMultipleOptions - * @extends {GetMultipleOptionsInterface} - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {QueryCommandInput} [sdkOptions] - Additional options to pass to the AWS SDK v3 client. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. - * @property {boolean} throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Additional options to pass to the AWS SDK v3 client, supports all options from {@link QueryCommandInput | `QueryCommandInput`} except `TableName` and `KeyConditionExpression`. + * @property transform - Transform to be applied, can be 'json' or 'binary'. + * @property throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) */ interface DynamoDBGetMultipleOptionsBase extends GetMultipleOptionsInterface { sdkOptions?: Partial; @@ -170,7 +190,7 @@ type DynamoDBGetMultipleOptions = | DynamoDBGetMultipleOptionsTransformNone; /** - * Generic output type for DynamoDBProvider getMultiple method. + * Generic output type for {@link DynamoDBProvider.getMultiple | `DynamoDBProvider.getMultiple()`} method. */ type DynamoDBGetMultipleOutput< ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/types/SSMProvider.ts b/packages/parameters/src/types/SSMProvider.ts index 889438db7e..547f5ffa04 100644 --- a/packages/parameters/src/types/SSMProvider.ts +++ b/packages/parameters/src/types/SSMProvider.ts @@ -15,9 +15,8 @@ import type { /** * Interface for SSMProvider with clientConfig property. * - * @interface - * @property {SSMClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. - * @property {never} [awsSdkV3Client] - This property should never be passed. + * @property clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. + * @property awsSdkV3Client - This property should never be passed. */ interface SSMProviderOptionsWithClientConfig { /** @@ -30,9 +29,8 @@ interface SSMProviderOptionsWithClientConfig { /** * Interface for SSMProvider with awsSdkV3Client property. * - * @interface - * @property {SSMClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during SSMProvider class instantiation - * @property {never} [clientConfig] - This property should never be passed. + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during SSMProvider class instantiation + * @property clientConfig - This property should never be passed. */ interface SSMProviderOptionsWithClientInstance { /** @@ -45,9 +43,8 @@ interface SSMProviderOptionsWithClientInstance { /** * Options for the SSMProvider class constructor. * - * @type SSMProviderOptions - * @property {SSMClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with awsSdkV3Client. - * @property {SSMClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during DynamoDBProvider class instantiation. Mutually exclusive with clientConfig. + * @property clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with awsSdkV3Client. + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during DynamoDBProvider class instantiation. Mutually exclusive with clientConfig. */ type SSMProviderOptions = | SSMProviderOptionsWithClientConfig @@ -58,11 +55,12 @@ type SSMProviderOptions = * * @interface SSMGetOptionsBase * @extends {GetOptionsInterface} - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {GetItemCommandInput} [sdkOptions] - Additional options to pass to the AWS SDK v3 client. Supports all options from `GetParameterCommandInput`. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. - * @property {boolean} decrypt - If true, the parameter will be decrypted. Defaults to `false`. + * + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Optional options to pass to the AWS SDK v3 client. Supports all options from {@link GetParameterCommandInput | `GetParameterCommandInput`}. + * @property transform - Transform to be applied, can be 'json' or 'binary'. + * @property decrypt - If true, the parameter will be decrypted. Defaults to `false`. */ interface SSMGetOptionsBase extends GetOptionsInterface { /** @@ -154,15 +152,15 @@ type SSMGetOutput< /** * Options for the SSMProvider getMultiple method. * - * @interface SSMGetMultipleOptionsBase * @extends {GetMultipleOptionsInterface} - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {GetItemCommandInput} [sdkOptions] - Additional options to pass to the AWS SDK v3 client. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. - * @property {boolean} decrypt - If true, the parameter will be decrypted. - * @property {boolean} recursive - If true, the parameter will be fetched recursively. - * @property {boolean} throwOnTransformError - If true, the method will throw an error if the transform fails. + * + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property [sdkOptions] - Additional options to pass to the AWS SDK v3 client. + * @property transform - Transform to be applied, can be 'json' or 'binary'. + * @property decrypt - If true, the parameter will be decrypted. + * @property recursive - If true, the parameter will be fetched recursively. + * @property throwOnTransformError - If true, the method will throw an error if the transform fails. */ interface SSMGetMultipleOptionsBase extends GetMultipleOptionsInterface { /** @@ -230,11 +228,10 @@ type SSMGetMultipleOutput< /** * Options for the SSMProvider getParametersByName method. * - * @interface SSMGetParametersByNameOptions - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. - * @property {boolean} decrypt - If true, the parameter will be decrypted. - * @property {boolean} throwOnError - If true, the method will throw an error if one of the parameters cannot be fetched. Otherwise it will aggregate the errors under an _errors key in the response. + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property transform - Transform to be applied, can be 'json' or 'binary'. + * @property decrypt - If `true`, the parameter will be decrypted. + * @property throwOnError - If `true`, the method will throw an error if one of the parameters cannot be fetched. Otherwise it will aggregate the errors under an `_errors` key in the response. */ interface SSMGetParametersByNameOptions { maxAge?: number; diff --git a/packages/parameters/src/types/SecretsProvider.ts b/packages/parameters/src/types/SecretsProvider.ts index 0d31a66192..5db8d9ef7d 100644 --- a/packages/parameters/src/types/SecretsProvider.ts +++ b/packages/parameters/src/types/SecretsProvider.ts @@ -4,34 +4,32 @@ import type { SecretsManagerClient, SecretsManagerClientConfig, } from '@aws-sdk/client-secrets-manager'; +import type { SecretsProvider } from '../secrets/SecretsProvider.js'; import type { GetOptionsInterface, TransformOptions } from './BaseProvider.js'; /** - * Base interface for SecretsProviderOptions. + * Base interface for {@link SecretsProviderOptions | SecretsProviderOptions}. * - * @interface - * @property {SecretsManagerClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. - * @property {never} [awsSdkV3Client] - This property should never be passed. + * @property clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. + * @property awsSdkV3Client - This property should never be passed. */ interface SecretsProviderOptionsWithClientConfig { /** - * Optional configuration to pass during client initialization, e.g. AWS region. It accepts the same configuration object as the AWS SDK v3 client (`SecretsManagerClient`). + * Optional configuration to pass during client initialization, e.g. AWS region. Accepts the same configuration object as the AWS SDK v3 client ({@link SecretsManagerClientConfig | `SecretsManagerClientConfig`}). */ clientConfig?: SecretsManagerClientConfig; awsSdkV3Client?: never; } /** - * Interface for SecretsProviderOptions with awsSdkV3Client property. + * Interface for {@link SecretsProviderOptions | SecretsProviderOptions} with `awsSdkV3Client` property. * - * @interface - * @extends SecretsProviderOptionsWithClientConfig - * @property {SecretsManagerClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during SecretsProvider class instantiation - * @property {never} [clientConfig] - This property should never be passed. + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during {@link SecretsProvider | `SecretsProvider`} class instantiation + * @property clientConfig - This property should never be passed. */ interface SecretsProviderOptionsWithClientInstance { /** - * Optional AWS SDK v3 client instance (`SecretsManagerClient`) to use for Secrets Manager operations. If not provided, we will create a new instance of `SecretsManagerClient`. + * Optional AWS SDK v3 client instance ({@link SecretsManagerClient | `SecretsManagerClient`}) to use for Secrets Manager operations. If not provided, we will create a new instance of the client. */ awsSdkV3Client?: SecretsManagerClient; clientConfig?: never; @@ -40,9 +38,8 @@ interface SecretsProviderOptionsWithClientInstance { /** * Options for the SecretsProvider class constructor. * - * @type SecretsProviderOptions - * @property {SecretsManagerClientConfig} [clientConfig] - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with awsSdkV3Client. - * @property {SecretsManagerClient} [awsSdkV3Client] - Optional AWS SDK v3 client to pass during SecretsProvider class instantiation. Mutually exclusive with clientConfig. + * @property clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with `awsSdkV3Client`. + * @property awsSdkV3Client - Optional AWS SDK v3 client to pass during {@link SecretsProvider | `SecretsProvider`} class instantiation. Mutually exclusive with `clientConfig`. */ type SecretsProviderOptions = | SecretsProviderOptionsWithClientConfig @@ -51,18 +48,19 @@ type SecretsProviderOptions = /** * Options to configure the retrieval of a secret. * - * @interface SecretsGetOptionsBase - * @extends {GetOptionsInterface} - * @property {number} maxAge - Maximum age of the value in the cache, in seconds. - * @property {boolean} forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @property {GetSecretValueCommandInput} sdkOptions - Options to pass to the underlying SDK. - * @property {TransformOptions} transform - Transform to be applied, can be 'json' or 'binary'. + * @property maxAge - Maximum age of the value in the cache, in seconds. + * @property forceFetch - Force fetch the value from the parameter store, ignoring the cache. + * @property sdkOptions - Options to pass to the underlying SDK, supports all options from {@link GetSecretValueCommandInput | `GetSecretValueCommandInput`} except `SecretId`. + * @property transform - Transform to be applied, can be 'json' or 'binary'. */ interface SecretsGetOptionsBase extends GetOptionsInterface { /** - * Additional options to pass to the AWS SDK v3 client. Supports all options from `GetSecretValueCommandInput` except `SecretId`. + * Additional options to pass to the AWS SDK v3 client. Supports all options from {@link GetSecretValueCommandInput | `GetSecretValueCommandInput`} except `SecretId`. */ sdkOptions?: Omit, 'SecretId'>; + /** + * Transform to be applied, can be `json` or `binary`. + */ transform?: Exclude; } @@ -85,7 +83,7 @@ type SecretsGetOptions = | undefined; /** - * Generic output type for the SecretsProvider get method. + * Generic output type for the {@link SecretsProvider.get | `SecretsProvider.get()`} method. */ type SecretsGetOutput< ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/tests/e2e/appConfigProvider.class.test.ts b/packages/parameters/tests/e2e/appConfigProvider.class.test.ts index af28e69110..938ae423e1 100644 --- a/packages/parameters/tests/e2e/appConfigProvider.class.test.ts +++ b/packages/parameters/tests/e2e/appConfigProvider.class.test.ts @@ -171,7 +171,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { describe('AppConfigProvider usage', () => { // Test 1 - get a single parameter as-is (no transformation - should return an Uint8Array) - it('should retrieve single parameter as-is', () => { + it('retrieves single parameter as-is', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[0]); @@ -182,7 +182,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { }); // Test 2 - get a free-form JSON and apply json transformation (should return an object) - it('should retrieve a free-form JSON parameter with JSON transformation', () => { + it('retrieves a free-form JSON parameter with JSON transformation', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[1]); @@ -194,7 +194,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { // Test 3 - get a free-form base64-encoded plain text and apply binary transformation // (should return a decoded string) - it('should retrieve a base64-encoded plain text parameter with binary transformation', () => { + it('retrieves a base64-encoded plain text parameter with binary transformation', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[2]); @@ -205,7 +205,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { }); // Test 4 - get a feature flag and apply json transformation (should return an object) - it('should retrieve a feature flag parameter with JSON transformation', () => { + it('retrieves a feature flag parameter with JSON transformation', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[3]); @@ -217,7 +217,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { // Test 5 - get parameter twice with middleware, which counts the number // of requests, we check later if we only called AppConfig API once - it('should retrieve single parameter cached', () => { + it('retrieves single parameter cached', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[4]); @@ -229,7 +229,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { // Test 6 - get parameter twice, but force fetch 2nd time, // we count number of SDK requests and check that we made two API calls - it('should retrieve single parameter twice without caching', async () => { + it('retrieves single parameter twice without caching', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[5]); @@ -242,7 +242,7 @@ describe('Parameters E2E tests, AppConfig provider', () => { // Test 7 - get parameter twice, using maxAge to avoid primary cache // we count number of SDK requests and check that we made two API calls // and check that the values match - it('should retrieve single parameter twice, with expiration between and matching values', async () => { + it('retrieves single parameter twice, with expiration between and matching values', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[6]); const result = freeFormPlainTextValue; diff --git a/packages/parameters/tests/e2e/dynamoDBProvider.class.test.ts b/packages/parameters/tests/e2e/dynamoDBProvider.class.test.ts index f4fa7c4ba4..9c3ac74cc6 100644 --- a/packages/parameters/tests/e2e/dynamoDBProvider.class.test.ts +++ b/packages/parameters/tests/e2e/dynamoDBProvider.class.test.ts @@ -263,7 +263,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { describe('DynamoDBProvider usage', () => { // Test 1 - get a single parameter with default options (keyAttr: 'id', valueAttr: 'value') - it('should retrieve a single parameter', async () => { + it('retrieves a single parameter', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[0]); @@ -274,7 +274,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 2 - get multiple parameters with default options (keyAttr: 'id', sortAttr: 'sk', valueAttr: 'value') - it('should retrieve multiple parameters', async () => { + it('retrieves multiple parameters', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[1]); @@ -285,7 +285,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 3 - get a single parameter with custom options (keyAttr: 'key', valueAttr: 'val') - it('should retrieve a single parameter', async () => { + it('retrieves a single parameter', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[2]); @@ -296,7 +296,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 4 - get multiple parameters with custom options (keyAttr: 'key', sortAttr: 'sort', valueAttr: 'val') - it('should retrieve multiple parameters', async () => { + it('retrieves multiple parameters', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[3]); @@ -307,7 +307,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 5 - get a single parameter with json transform - it('should retrieve a single parameter with json transform', async () => { + it('retrieves a single parameter with json transform', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[4]); @@ -318,7 +318,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 6 - get a single parameter with binary transform - it('should retrieve a single parameter with binary transform', async () => { + it('retrieves a single parameter with binary transform', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[5]); @@ -329,7 +329,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 7 - get multiple parameters with auto transforms (json and binary) - it('should retrieve multiple parameters with auto transforms', async () => { + it('retrieves multiple parameters with auto transforms', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[6]); @@ -343,7 +343,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 8 - Get a parameter twice and check that the value is cached. - it('should retrieve multiple parameters with auto transforms', async () => { + it('retrieves multiple parameters with auto transforms', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[7]); @@ -354,7 +354,7 @@ describe('Parameters E2E tests, dynamoDB provider', () => { }); // Test 9 - Get a cached parameter and force retrieval. - it('should retrieve multiple parameters with auto transforms', async () => { + it('retrieves multiple parameters with auto transforms', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[8]); diff --git a/packages/parameters/tests/e2e/secretsProvider.class.test.ts b/packages/parameters/tests/e2e/secretsProvider.class.test.ts index b52481cbed..2899b1ac2d 100644 --- a/packages/parameters/tests/e2e/secretsProvider.class.test.ts +++ b/packages/parameters/tests/e2e/secretsProvider.class.test.ts @@ -136,7 +136,7 @@ describe('Parameters E2E tests, Secrets Manager provider', () => { }); describe('SecretsProvider usage', () => { - it('should retrieve a secret as plain string', async () => { + it('retrieves a secret as plain string', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[0]); @@ -146,7 +146,7 @@ describe('Parameters E2E tests, Secrets Manager provider', () => { }); }); - it('should retrieve a secret using transform json option', async () => { + it('retrieves a secret using transform json option', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[1]); @@ -156,7 +156,7 @@ describe('Parameters E2E tests, Secrets Manager provider', () => { }); }); - it('should retrieve a secret using transform binary option', async () => { + it('retrieves a secret using transform binary option', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[2]); @@ -167,7 +167,7 @@ describe('Parameters E2E tests, Secrets Manager provider', () => { }); }); - it('should retrieve a secret twice with cached value', async () => { + it('retrieves a secret twice with cached value', () => { const logs = invocationLogs.getFunctionLogs(); const testLogFirst = TestInvocationLogs.parseFunctionLog(logs[3]); @@ -178,7 +178,7 @@ describe('Parameters E2E tests, Secrets Manager provider', () => { }); }); - it('should retrieve a secret twice with forceFetch second time', async () => { + it('retrieves a secret twice with forceFetch second time', () => { const logs = invocationLogs.getFunctionLogs(); const testLogFirst = TestInvocationLogs.parseFunctionLog(logs[4]); diff --git a/packages/parameters/tests/e2e/ssmProvider.class.test.ts b/packages/parameters/tests/e2e/ssmProvider.class.test.ts index c5a28619fc..f65fb0c88f 100644 --- a/packages/parameters/tests/e2e/ssmProvider.class.test.ts +++ b/packages/parameters/tests/e2e/ssmProvider.class.test.ts @@ -188,7 +188,7 @@ describe('Parameters E2E tests, SSM provider', () => { describe('SSMProvider usage', () => { // Test 1 - get a single parameter by name with default options - it('should retrieve a single parameter', async () => { + it('retrieves a single parameter', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[0]); @@ -199,7 +199,7 @@ describe('Parameters E2E tests, SSM provider', () => { }); // Test 2 - get a single parameter by name with decrypt - it('should retrieve a single parameter with decryption', async () => { + it('retrieves a single parameter with decryption', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[1]); @@ -210,7 +210,7 @@ describe('Parameters E2E tests, SSM provider', () => { }); // Test 3 - get multiple parameters by path with default options - it('should retrieve multiple parameters', async () => { + it('retrieves multiple parameters', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[2]); const expectedParameterNameA = paramA.substring( @@ -232,7 +232,7 @@ describe('Parameters E2E tests, SSM provider', () => { // Test 4 - get multiple parameters by path recursively // (aka. get all parameters under a path recursively) i.e. // given /param, retrieve /param/get/a and /param/get/b (note path depth) - it('should retrieve multiple parameters recursively', async () => { + it('retrieves multiple parameters recursively', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[3]); const expectedParameterNameA = paramA.substring( @@ -251,7 +251,7 @@ describe('Parameters E2E tests, SSM provider', () => { }); }); - it('should retrieve multiple parameters with decryption', async () => { + it('retrieves multiple parameters with decryption', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[4]); const expectedParameterNameA = paramEncryptedA.substring( @@ -271,7 +271,7 @@ describe('Parameters E2E tests, SSM provider', () => { }); // Test 6 - get multiple parameters by name with default options - it('should retrieve multiple parameters by name', async () => { + it('retrieves multiple parameters by name', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[5]); @@ -285,7 +285,7 @@ describe('Parameters E2E tests, SSM provider', () => { }); // Test 7 - get multiple parameters by name, some of them encrypted and some not - it('should retrieve multiple parameters by name with mixed decryption', async () => { + it('retrieves multiple parameters by name with mixed decryption', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[6]); @@ -301,7 +301,7 @@ describe('Parameters E2E tests, SSM provider', () => { // Test 8 - get parameter twice with middleware, which counts the number // of requests, we check later if we only called SSM API once - it('should retrieve single parameter cached', async () => { + it('retrieves single parameter cached', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[7]); @@ -313,7 +313,7 @@ describe('Parameters E2E tests, SSM provider', () => { // Test 9 - get parameter twice, but force fetch 2nd time, // we count number of SDK requests and check that we made two API calls - it('should retrieve single parameter twice without caching', async () => { + it('retrieves single parameter twice without caching', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[8]); @@ -324,7 +324,7 @@ describe('Parameters E2E tests, SSM provider', () => { }); // Test 10 - store and overwrite single parameter - it('should store and overwrite single parameter', async () => { + it('stores and overwrite single parameter', () => { const logs = invocationLogs.getFunctionLogs(); const testLog = TestInvocationLogs.parseFunctionLog(logs[9]); diff --git a/packages/parameters/tests/unit/AppConfigProvider.test.ts b/packages/parameters/tests/unit/AppConfigProvider.test.ts index 5bfb01ace3..2112bcdf45 100644 --- a/packages/parameters/tests/unit/AppConfigProvider.test.ts +++ b/packages/parameters/tests/unit/AppConfigProvider.test.ts @@ -9,7 +9,7 @@ import { mockClient } from 'aws-sdk-client-mock'; import { beforeEach, describe, expect, it, vi } from 'vitest'; import { AppConfigProvider } from '../../src/appconfig/index.js'; import { ExpirableValue } from '../../src/base/ExpirableValue.js'; -import { APPCONFIG_TOKEN_EXPIRATION } from '../../src/constants'; +import { APPCONFIG_TOKEN_EXPIRATION } from '../../src/constants.js'; import type { AppConfigProviderOptions } from '../../src/types/AppConfigProvider.js'; vi.mock('@aws-lambda-powertools/commons', async (importOriginal) => ({ @@ -27,7 +27,7 @@ describe('Class: AppConfigProvider', () => { }); describe('Method: constructor', () => { - it('instantiates a new AWS SDK and adds a middleware to it', async () => { + it('instantiates a new AWS SDK and adds a middleware to it', () => { // Prepare const options: AppConfigProviderOptions = { application: 'MyApp', @@ -66,7 +66,7 @@ describe('Class: AppConfigProvider', () => { expect(addUserAgentMiddleware).toHaveBeenCalled(); }); - it('uses the provided AWS SDK client', async () => { + it('uses the provided AWS SDK client', () => { // Prepare const awsSdkV3Client = new AppConfigDataClient({ endpoint: 'http://localhost:8000', @@ -90,7 +90,7 @@ describe('Class: AppConfigProvider', () => { ); }); - it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', async () => { + it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', () => { // Prepare const awsSdkV3Client = {}; const options: AppConfigProviderOptions = { @@ -179,7 +179,7 @@ describe('Class: AppConfigProvider', () => { expect(result).toBe(mockData); }); - it('throws when no application is set', async () => { + it('throws when no application is set', () => { // Prepare process.env.POWERTOOLS_SERVICE_NAME = ''; const options = { diff --git a/packages/parameters/tests/unit/DynamoDBProvider.test.ts b/packages/parameters/tests/unit/DynamoDBProvider.test.ts index 195a766d3d..7b7018d889 100644 --- a/packages/parameters/tests/unit/DynamoDBProvider.test.ts +++ b/packages/parameters/tests/unit/DynamoDBProvider.test.ts @@ -27,7 +27,7 @@ describe('Class: DynamoDBProvider', () => { }); describe('Method: constructor', () => { - it('instantiates a new AWS SDK with default options', async () => { + it('instantiates a new AWS SDK with default options', () => { // Prepare const options: DynamoDBProviderOptions = { tableName: 'test-table', @@ -64,7 +64,7 @@ describe('Class: DynamoDBProvider', () => { expect(addUserAgentMiddleware).toHaveBeenCalled(); }); - it('uses the provided AWS SDK client', async () => { + it('uses the provided AWS SDK client', () => { // Prepare const awsSdkV3Client = new DynamoDBClient({ endpoint: 'http://localhost:8000', @@ -87,7 +87,7 @@ describe('Class: DynamoDBProvider', () => { ); }); - it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', async () => { + it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', () => { // Prepare const awsSdkV3Client = {}; const options: DynamoDBProviderOptions = { diff --git a/packages/parameters/tests/unit/SSMProvider.test.ts b/packages/parameters/tests/unit/SSMProvider.test.ts index 0b28f6863a..b0ab95c17b 100644 --- a/packages/parameters/tests/unit/SSMProvider.test.ts +++ b/packages/parameters/tests/unit/SSMProvider.test.ts @@ -36,7 +36,7 @@ describe('Class: SSMProvider', () => { }); describe('Method: constructor', () => { - it('adds the middleware to the created AWS SDK', async () => { + it('adds the middleware to the created AWS SDK', () => { // Prepare const options: SSMProviderOptions = {}; @@ -70,7 +70,7 @@ describe('Class: SSMProvider', () => { expect(addUserAgentMiddleware).toHaveBeenCalled(); }); - it('uses the provided AWS SDK client', async () => { + it('uses the provided AWS SDK client', () => { // Prepare const awsSdkV3Client = new SSMClient({ endpoint: 'http://localhost:3000', @@ -92,7 +92,7 @@ describe('Class: SSMProvider', () => { ); }); - it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', async () => { + it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', () => { // Prepare const awsSdkV3Client = {}; const options: SSMProviderOptions = { @@ -790,7 +790,7 @@ describe('Class: SSMProvider', () => { this.store.set(key, value); } - public async getParametersByNameFromCache( + public getParametersByNameFromCache( parameters: Record ): Promise { return super.getParametersByNameFromCache(parameters); @@ -828,7 +828,7 @@ describe('Class: SSMProvider', () => { public _getParametersByName = vi.fn(); public maxGetParametersItems = 1; - public async getParametersByNameInChunks( + public getParametersByNameInChunks( parameters: Record, throwOnError: boolean, decrypt: boolean @@ -933,7 +933,7 @@ describe('Class: SSMProvider', () => { class SSMProviderMock extends SSMProvider { public _get = vi.fn(); - public async getParametersByNameWithDecryptOption( + public getParametersByNameWithDecryptOption( parameters: Record, throwOnError: boolean ): Promise { diff --git a/packages/parameters/tests/unit/SecretsProvider.test.ts b/packages/parameters/tests/unit/SecretsProvider.test.ts index 7a9bc71a4f..b79c46b6af 100644 --- a/packages/parameters/tests/unit/SecretsProvider.test.ts +++ b/packages/parameters/tests/unit/SecretsProvider.test.ts @@ -23,7 +23,7 @@ describe('Class: SecretsProvider', () => { }); describe('Method: constructor', () => { - it('instantiates a new AWS SDK with default options', async () => { + it('instantiates a new AWS SDK with default options', () => { // Prepare const options: SecretsProviderOptions = {}; @@ -57,7 +57,7 @@ describe('Class: SecretsProvider', () => { expect(addUserAgentMiddleware).toHaveBeenCalled(); }); - it('uses the provided AWS SDK client', async () => { + it('uses the provided AWS SDK client', () => { // Prepare const awsSdkV3Client = new SecretsManagerClient({ endpoint: 'http://localhost:3000', @@ -79,7 +79,7 @@ describe('Class: SecretsProvider', () => { ); }); - it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', async () => { + it('falls back on a new SDK client and logs a warning when an unknown object is provided instead of a client', () => { // Prepare const awsSdkV3Client = {}; const options: SecretsProviderOptions = { diff --git a/packages/parameters/tests/unit/setParameter.test.ts b/packages/parameters/tests/unit/setParameter.test.ts index b9a0ebf01d..fa03b2ed58 100644 --- a/packages/parameters/tests/unit/setParameter.test.ts +++ b/packages/parameters/tests/unit/setParameter.test.ts @@ -49,7 +49,7 @@ describe('Function: setParameter', () => { expect(DEFAULT_PROVIDERS.ssm).toBe(provider); }); - it('rethrows the error thrown by the underlying sdk client', async () => { + it('rethrows the error thrown by the underlying sdk client', () => { // Prepare const options: SSMSetOptions = { value: 'my-value' }; client.on(PutParameterCommand).rejects(new Error('Could not send command')); From 7777163cf32533bfc7c36930b8f390dd62071182 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 25 Sep 2025 19:34:19 +0200 Subject: [PATCH 2/3] style(parameters): apply stricter linting --- .../src/appconfig/AppConfigProvider.ts | 31 ++---- .../parameters/src/appconfig/getAppConfig.ts | 101 +++++++++--------- .../src/dynamodb/DynamoDBProvider.ts | 21 +--- .../parameters/src/secrets/SecretsProvider.ts | 13 +-- packages/parameters/src/secrets/getSecret.ts | 3 +- packages/parameters/src/ssm/SSMProvider.ts | 18 +--- packages/parameters/src/ssm/getParameter.ts | 2 +- packages/parameters/src/ssm/getParameters.ts | 2 +- .../parameters/src/ssm/getParametersByName.ts | 6 +- .../parameters/src/types/AppConfigProvider.ts | 2 +- packages/parameters/typedoc.json | 17 ++- 11 files changed, 98 insertions(+), 118 deletions(-) diff --git a/packages/parameters/src/appconfig/AppConfigProvider.ts b/packages/parameters/src/appconfig/AppConfigProvider.ts index 49aa1b9c5c..f95dc9d2cd 100644 --- a/packages/parameters/src/appconfig/AppConfigProvider.ts +++ b/packages/parameters/src/appconfig/AppConfigProvider.ts @@ -1,8 +1,5 @@ import { getServiceName } from '@aws-lambda-powertools/commons/utils/env'; -import type { - AppConfigDataClientConfig, - StartConfigurationSessionCommandInput, -} from '@aws-sdk/client-appconfigdata'; +import type { StartConfigurationSessionCommandInput } from '@aws-sdk/client-appconfigdata'; import { AppConfigDataClient, GetLatestConfigurationCommand, @@ -190,26 +187,20 @@ class AppConfigProvider extends BaseProvider { private readonly application?: string; private readonly environment: string; - /** - * 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) { + public constructor({ + application, + environment, + clientConfig, + awsSdkV3Client, + }: AppConfigProviderOptions) { super({ awsSdkV3ClientPrototype: AppConfigDataClient as new ( config?: unknown ) => AppConfigDataClient, - clientConfig: options.clientConfig, - awsSdkV3Client: options.awsSdkV3Client, + clientConfig, + awsSdkV3Client, }); - const { application, environment } = options; this.application = application ?? getServiceName(); if (!this.application || this.application.trim().length === 0) { throw new Error( @@ -254,7 +245,7 @@ class AppConfigProvider extends BaseProvider { | undefined = AppConfigGetOptions, >( name: string, - options?: InferredFromOptionsType & AppConfigGetOptions + options?: NonNullable ): Promise< | AppConfigGetOutput | undefined @@ -296,7 +287,7 @@ class AppConfigProvider extends BaseProvider { */ protected async _get( name: string, - options?: AppConfigGetOptions + options?: NonNullable ): Promise { if ( !this.configurationTokenStore.has(name) || diff --git a/packages/parameters/src/appconfig/getAppConfig.ts b/packages/parameters/src/appconfig/getAppConfig.ts index aa73d49741..a6e31dced7 100644 --- a/packages/parameters/src/appconfig/getAppConfig.ts +++ b/packages/parameters/src/appconfig/getAppConfig.ts @@ -6,39 +6,30 @@ import type { import { AppConfigProvider } from './AppConfigProvider.js'; /** - * ## Intro - * The Parameters utility provides an AppConfigProvider that allows to retrieve configuration profiles from AWS AppConfig. + * The Parameters utility provides an `AppConfigProvider` that allows to retrieve configuration profiles from AWS AppConfig. * - * ## Getting started - * - * This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only + * 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. * - * To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for AppConfig: - * - * ```sh - * npm install @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata - * ``` - * - * ## Basic usage + * **Basic usage** * * @example * ```typescript * import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig'; * + * const encodedConfig = await getAppConfig('my-config', { + * application: 'my-app', + * environment: 'prod', + * }); + * const config = new TextDecoder('utf-8').decode(encodedConfig); + * * export const handler = async (): Promise => { - * // Retrieve a configuration profile - * const encodedConfig = await getAppConfig('my-config', { - * application: 'my-app', - * environment: 'prod', - * }); - * const config = new TextDecoder('utf-8').decode(encodedConfig); + * // Use the config variable as needed + * console.log(config); * }; * ``` * - * ## 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. @@ -47,13 +38,15 @@ import { AppConfigProvider } from './AppConfigProvider.js'; * ```typescript * import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig'; * + * const encodedConfig = await getAppConfig('my-config', { + * application: 'my-app', + * environment: 'prod', + * maxAge: 10, // Cache for 10 seconds + * }); + * const config = new TextDecoder('utf-8').decode(encodedConfig); + * * export const handler = async (): Promise => { - * // Retrieve a configuration profile and cache it for 10 seconds - * const encodedConfig = await getAppConfig('my-config', { - * application: 'my-app', - * environment: 'prod', - * }); - * const config = new TextDecoder('utf-8').decode(encodedConfig); + * // Use the config variable as needed * }; * ``` * @@ -63,18 +56,20 @@ import { AppConfigProvider } from './AppConfigProvider.js'; * ```typescript * import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig'; * + * const encodedConfig = await getAppConfig('my-config', { + * application: 'my-app', + * environment: 'prod', + * forceFetch: true, // Always fetch the latest value + * }); + * const config = new TextDecoder('utf-8').decode(encodedConfig); + * * export const handler = async (): Promise => { - * // Retrieve a config and always fetch the latest value - * const config = await getAppConfig('my-config', { - * application: 'my-app', - * environment: 'prod', - * forceFetch: true, - * }); - * const config = new TextDecoder('utf-8').decode(encodedConfig); + * // Use the config variable as needed + * console.log * }; * ``` * - * ### 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. * @@ -82,13 +77,16 @@ import { AppConfigProvider } from './AppConfigProvider.js'; * ```typescript * import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig'; * + * // Retrieve a JSON config and parse it as JSON + * const encodedConfig = await getAppConfig('my-config', { + * application: 'my-app', + * environment: 'prod', + * transform: 'json' + * }); + * * export const handler = async (): Promise => { - * // Retrieve a JSON config or Feature Flag and parse it as JSON - * const config = await getAppConfig('my-config', { - * application: 'my-app', - * environment: 'prod', - * transform: 'json' - * }); + * // Use the config variable as needed + * console.log(config); * }; * ``` * @@ -108,7 +106,7 @@ import { AppConfigProvider } from './AppConfigProvider.js'; * }; * ``` * - * ### 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. * @@ -131,15 +129,18 @@ import { AppConfigProvider } from './AppConfigProvider.js'; * * 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). * - * ### Built-in provider class + * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link AppConfigProvider | `AppConfigProvider`} class. * - * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link AppConfigProvider} class. - * - * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/). - * - * @param {string} name - The name of the configuration profile or its ID - * @param {GetAppConfigOptions} 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.application - The application ID or the application name. + * @param options.environment - The environment ID or the environment name. + * @param options.maxAge - The maximum age (in seconds) to keep values in cache. Default: 5 seconds. + * @param options.forceFetch - Whether to skip the cache and always fetch the latest value from the store. Default: `false`. + * @param options.transform - Optional transformation to apply to the retrieved value. Supported options are: 'json' and 'binary'. + * @param options.sdkOptions - Optional extra options to pass to the AWS SDK v3 for JavaScript client when retrieving the configuration profile. */ const getAppConfig = < ExplicitUserProvidedType = undefined, @@ -148,7 +149,7 @@ const getAppConfig = < | undefined = GetAppConfigOptions, >( name: string, - options: InferredFromOptionsType & GetAppConfigOptions + options: NonNullable ): Promise< | AppConfigGetOutput | undefined diff --git a/packages/parameters/src/dynamodb/DynamoDBProvider.ts b/packages/parameters/src/dynamodb/DynamoDBProvider.ts index 1b096f8893..c55ec4e55b 100644 --- a/packages/parameters/src/dynamodb/DynamoDBProvider.ts +++ b/packages/parameters/src/dynamodb/DynamoDBProvider.ts @@ -234,17 +234,6 @@ class DynamoDBProvider extends BaseProvider { protected tableName: string; protected valueAttr = 'value'; - /** - * Initialize a DynamoDBProvider class instance. - * - * @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({ awsSdkV3ClientPrototype: DynamoDBClient as new ( @@ -293,7 +282,7 @@ class DynamoDBProvider extends BaseProvider { | undefined = DynamoDBGetOptions, >( name: string, - options?: InferredFromOptionsType & DynamoDBGetOptions + options?: NonNullable ): Promise< | DynamoDBGetOutput | undefined @@ -338,7 +327,7 @@ class DynamoDBProvider extends BaseProvider { | undefined = DynamoDBGetMultipleOptions, >( path: string, - options?: InferredFromOptionsType & DynamoDBGetMultipleOptions + options?: NonNullable ): Promise< | DynamoDBGetMultipleOutput< ExplicitUserProvidedType, @@ -362,12 +351,12 @@ class DynamoDBProvider extends BaseProvider { * @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.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, - options?: DynamoDBGetOptions + options?: NonNullable ): Promise { const sdkOptions: GetItemCommandInput = { ...(options?.sdkOptions || {}), @@ -396,7 +385,7 @@ class DynamoDBProvider extends BaseProvider { */ protected async _getMultiple( path: string, - options?: DynamoDBGetMultipleOptions + options?: NonNullable ): Promise> { const sdkOptions: QueryCommandInput = { ...(options?.sdkOptions || {}), diff --git a/packages/parameters/src/secrets/SecretsProvider.ts b/packages/parameters/src/secrets/SecretsProvider.ts index a04521f37a..f42c9a4920 100644 --- a/packages/parameters/src/secrets/SecretsProvider.ts +++ b/packages/parameters/src/secrets/SecretsProvider.ts @@ -140,14 +140,7 @@ import type { class SecretsProvider extends BaseProvider { public declare client: SecretsManagerClient; - /** - * Initialize a `SecretsProvider` class. - * - * @param config - The configuration object. - * @param config.clientConfig - Optional configuration to pass during client initialization, e.g. AWS region. Mutually exclusive with `awsSdkV3Client`. - * @param config.awsSdkV3Client - Optional AWS SDK v3 client to pass during {@link SecretsProvider | `SecretsProvider`} class instantiation. Mutually exclusive with `clientConfig`. - */ - public constructor(config?: SecretsProviderOptions) { + public constructor(config?: NonNullable) { super({ awsSdkV3ClientPrototype: SecretsManagerClient as new ( config?: unknown @@ -187,7 +180,7 @@ class SecretsProvider extends BaseProvider { | undefined = SecretsGetOptions, >( name: string, - options?: InferredFromOptionsType & SecretsGetOptions + options?: NonNullable ): Promise< | SecretsGetOutput | undefined @@ -217,7 +210,7 @@ class SecretsProvider extends BaseProvider { */ protected async _get( name: string, - options?: SecretsGetOptions + options?: NonNullable ): Promise { const sdkOptions: GetSecretValueCommandInput = { ...(options?.sdkOptions || {}), diff --git a/packages/parameters/src/secrets/getSecret.ts b/packages/parameters/src/secrets/getSecret.ts index 2d3987542f..0a31450167 100644 --- a/packages/parameters/src/secrets/getSecret.ts +++ b/packages/parameters/src/secrets/getSecret.ts @@ -97,7 +97,6 @@ import { SecretsProvider } from './SecretsProvider.js'; * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache (default: `false`) * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client, accepts the same configuration object as the AWS SDK v3 client ({@link SecretsManagerClientConfig | `SecretsManagerClientConfig`}). - * @param options.decrypt - Whether to decrypt the value before returning it. (default: `false`) */ const getSecret = < ExplicitUserProvidedType = undefined, @@ -106,7 +105,7 @@ const getSecret = < | undefined = SecretsGetOptions, >( name: string, - options?: InferredFromOptionsType & SecretsGetOptions + options?: NonNullable ): Promise< | SecretsGetOutput | undefined diff --git a/packages/parameters/src/ssm/SSMProvider.ts b/packages/parameters/src/ssm/SSMProvider.ts index 30b7ee6b9f..66be3e52be 100644 --- a/packages/parameters/src/ssm/SSMProvider.ts +++ b/packages/parameters/src/ssm/SSMProvider.ts @@ -267,11 +267,6 @@ class SSMProvider extends BaseProvider { protected errorsKey = '_errors'; protected maxGetParametersItems = 10; - /** - * It initializes the SSMProvider class. - * - * @param config - The configuration object. - */ public constructor(config?: SSMProviderOptions) { super({ awsSdkV3ClientPrototype: SSMClient as new (config?: unknown) => SSMClient, @@ -309,7 +304,7 @@ class SSMProvider extends BaseProvider { InferredFromOptionsType extends SSMGetOptions | undefined = SSMGetOptions, >( name: string, - options?: InferredFromOptionsType & SSMGetOptions + options?: NonNullable ): Promise< SSMGetOutput | undefined > { @@ -411,7 +406,7 @@ class SSMProvider extends BaseProvider { | undefined = undefined, >( path: string, - options?: InferredFromOptionsType & SSMGetMultipleOptions + options?: NonNullable ): Promise< | SSMGetMultipleOutput | undefined @@ -466,16 +461,13 @@ class SSMProvider extends BaseProvider { * @param parameters - Object containing parameter names and any optional overrides * @param options - Options to configure the retrieval * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) - * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` - * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client - * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) * @param options.decrypt - Whether to decrypt the value before returning it. * @param options.throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error (default: `true`) */ public async getParametersByName( parameters: Record, - options?: SSMGetParametersByNameOptions + options?: NonNullable ): Promise> { const configs = { ...{ @@ -552,7 +544,7 @@ class SSMProvider extends BaseProvider { */ protected async _get( name: string, - options?: SSMGetOptions + options?: NonNullable ): Promise { const sdkOptions: GetParameterCommandInput = { ...(options?.sdkOptions || {}), @@ -582,7 +574,7 @@ class SSMProvider extends BaseProvider { */ protected async _getMultiple( path: string, - options?: SSMGetMultipleOptions + options?: NonNullable ): Promise> { const sdkOptions: GetParametersByPathCommandInput = { ...(options?.sdkOptions || {}), diff --git a/packages/parameters/src/ssm/getParameter.ts b/packages/parameters/src/ssm/getParameter.ts index 6468e1d2de..32e969be21 100644 --- a/packages/parameters/src/ssm/getParameter.ts +++ b/packages/parameters/src/ssm/getParameter.ts @@ -126,7 +126,7 @@ const getParameter = < InferredFromOptionsType extends SSMGetOptions | undefined = SSMGetOptions, >( name: string, - options?: InferredFromOptionsType & SSMGetOptions + options?: NonNullable ): Promise< SSMGetOutput | undefined > => { diff --git a/packages/parameters/src/ssm/getParameters.ts b/packages/parameters/src/ssm/getParameters.ts index bcd438f0f0..6691ed0f9e 100644 --- a/packages/parameters/src/ssm/getParameters.ts +++ b/packages/parameters/src/ssm/getParameters.ts @@ -130,7 +130,7 @@ const getParameters = < | undefined = SSMGetMultipleOptions, >( path: string, - options?: InferredFromOptionsType & SSMGetMultipleOptions + options?: NonNullable ): Promise< | SSMGetMultipleOutput | undefined diff --git a/packages/parameters/src/ssm/getParametersByName.ts b/packages/parameters/src/ssm/getParametersByName.ts index ef67f28ab7..57c5043c08 100644 --- a/packages/parameters/src/ssm/getParametersByName.ts +++ b/packages/parameters/src/ssm/getParametersByName.ts @@ -138,13 +138,13 @@ import { SSMProvider } from './SSMProvider.js'; * @param parameters - The path of the parameters to retrieve * @param options - Options to configure the provider * @param options.maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. - * @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 GetParametersByNameCommandInput | `GetParametersByNameCommandInput`} except `Names`. + * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` * @param options.decrypt - Whether to decrypt the values before returning them. If true, will use `GetParameter` API for each parameter. If false (default), will use `GetParametersByName` API. + * @param options.throwOnError - Whether to throw an error if any of the parameters' retrieval throws an error (default: `true`) */ const getParametersByName = ( parameters: Record, - options?: SSMGetParametersByNameOptions + options?: NonNullable ): Promise> => { if (!Object.hasOwn(DEFAULT_PROVIDERS, 'ssm')) { DEFAULT_PROVIDERS.ssm = new SSMProvider(); diff --git a/packages/parameters/src/types/AppConfigProvider.ts b/packages/parameters/src/types/AppConfigProvider.ts index 134b26b403..d9768f49ee 100644 --- a/packages/parameters/src/types/AppConfigProvider.ts +++ b/packages/parameters/src/types/AppConfigProvider.ts @@ -64,7 +64,7 @@ interface AppConfigProviderOptionsWithClientInstance * Options for the `AppConfigProvider` class constructor. * * @property environment - The environment ID or the environment name. - * @property application - The optional application ID or the application name. + * @property application - Optional application ID or the application name, if not provided it will be inferred from the service name in the environment. * @property 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`}). * @property awsSdkV3Client - Optional ({@link AppConfigDataClient | `AppConfigDataClient`}) instance to pass during `AppConfigProvider` class instantiation. Mutually exclusive with `clientConfig`. */ diff --git a/packages/parameters/typedoc.json b/packages/parameters/typedoc.json index 90daedca0b..2eac7c6cfe 100644 --- a/packages/parameters/typedoc.json +++ b/packages/parameters/typedoc.json @@ -13,5 +13,20 @@ "./src/errors.ts", "./src/constants.ts" ], - "readme": "README.md" + "readme": "README.md", + "externalSymbolLinkMappings": { + "@aws-sdk/client-secrets-manager": { + "GetSecretValueCommandInput": "#" + }, + "@aws-sdk/client-dynamodb": { + "DynamoDBClient": "#", + "GetItemCommandInput": "#", + "QueryCommandInput": "#" + }, + "@aws-sdk/client-appconfigdata": { + "AppConfigDataClient": "#", + "StartConfigurationSessionCommandInput": "#" + }, + "@aws-sdk/client-ssm": { "GetParameterCommandInput": "#" } + } } From 074d644be774b9d4c1af7ff035f7db67c61b78b1 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 25 Sep 2025 19:47:29 +0200 Subject: [PATCH 3/3] style(parameters): apply stricter linting --- .../src/appconfig/AppConfigProvider.ts | 12 ++++---- .../parameters/src/appconfig/getAppConfig.ts | 14 ++++----- .../src/dynamodb/DynamoDBProvider.ts | 26 ++++++++-------- .../parameters/src/secrets/SecretsProvider.ts | 12 ++++---- packages/parameters/src/secrets/getSecret.ts | 11 ++++--- packages/parameters/src/ssm/SSMProvider.ts | 30 +++++++++---------- packages/parameters/src/ssm/getParameter.ts | 12 ++++---- packages/parameters/src/ssm/getParameters.ts | 14 ++++----- packages/parameters/typedoc.json | 12 ++++---- 9 files changed, 71 insertions(+), 72 deletions(-) diff --git a/packages/parameters/src/appconfig/AppConfigProvider.ts b/packages/parameters/src/appconfig/AppConfigProvider.ts index f95dc9d2cd..c78bdadf26 100644 --- a/packages/parameters/src/appconfig/AppConfigProvider.ts +++ b/packages/parameters/src/appconfig/AppConfigProvider.ts @@ -231,12 +231,12 @@ class AppConfigProvider extends BaseProvider { * * @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'. + * @param name - The name of the configuration profile to retrieve + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier` */ public get< ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/appconfig/getAppConfig.ts b/packages/parameters/src/appconfig/getAppConfig.ts index a6e31dced7..0a3e11996a 100644 --- a/packages/parameters/src/appconfig/getAppConfig.ts +++ b/packages/parameters/src/appconfig/getAppConfig.ts @@ -133,14 +133,14 @@ import { AppConfigProvider } from './AppConfigProvider.js'; * * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ * - * @param name - The name of the configuration profile or its ID + * @param name - The name of the configuration profile to retrieve * @param options - Options to configure the provider - * @param options.application - The application ID or the application name. - * @param options.environment - The environment ID or the environment name. - * @param options.maxAge - The maximum age (in seconds) to keep values in cache. Default: 5 seconds. - * @param options.forceFetch - Whether to skip the cache and always fetch the latest value from the store. Default: `false`. - * @param options.transform - Optional transformation to apply to the retrieved value. Supported options are: 'json' and 'binary'. - * @param options.sdkOptions - Optional extra options to pass to the AWS SDK v3 for JavaScript client when retrieving the configuration profile. + * @param options.application - The application ID or the application name + * @param options.environment - The environment ID or the environment name + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link StartConfigurationSessionCommandInput | `StartConfigurationSessionCommandInput`} except `ApplicationIdentifier`, `EnvironmentIdentifier`, and `ConfigurationProfileIdentifier` */ const getAppConfig = < ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/dynamodb/DynamoDBProvider.ts b/packages/parameters/src/dynamodb/DynamoDBProvider.ts index c55ec4e55b..a35127e2e4 100644 --- a/packages/parameters/src/dynamodb/DynamoDBProvider.ts +++ b/packages/parameters/src/dynamodb/DynamoDBProvider.ts @@ -268,12 +268,12 @@ class DynamoDBProvider extends BaseProvider { * * @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'. + * @param name - The name of the value to retrieve (partition key) + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetItemCommandInput | `GetItemCommandInput`} except `Key`, `TableName`, and `ProjectionExpression` */ public get< ExplicitUserProvidedType = undefined, @@ -312,13 +312,13 @@ class DynamoDBProvider extends BaseProvider { * * @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`) + * @param path - The path of the values to retrieve (partition key) + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link QueryCommandInput | `QueryCommandInput`} except `TableName` and `KeyConditionExpression` + * @param options.throwOnTransformError - Optional flag to throw an error if the transform fails (default: `true`) */ public getMultiple< ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/secrets/SecretsProvider.ts b/packages/parameters/src/secrets/SecretsProvider.ts index f42c9a4920..f247a7aca8 100644 --- a/packages/parameters/src/secrets/SecretsProvider.ts +++ b/packages/parameters/src/secrets/SecretsProvider.ts @@ -166,12 +166,12 @@ class SecretsProvider extends BaseProvider { * * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ * - * @param name - The name of the secret - * @param options - Options to customize the retrieval of the secret - * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) - * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache - * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` - * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client + * @param name - The name of the secret to retrieve + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetSecretValueCommandInput | `GetSecretValueCommandInput`} except `SecretId` */ public get< ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/secrets/getSecret.ts b/packages/parameters/src/secrets/getSecret.ts index 0a31450167..f1d04849e2 100644 --- a/packages/parameters/src/secrets/getSecret.ts +++ b/packages/parameters/src/secrets/getSecret.ts @@ -1,4 +1,3 @@ -import type { SecretsManagerClientConfig } from '@aws-sdk/client-secrets-manager'; import { DEFAULT_PROVIDERS } from '../base/DefaultProviders.js'; import type { SecretsGetOptions, @@ -92,11 +91,11 @@ import { SecretsProvider } from './SecretsProvider.js'; * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ * * @param name - The name of the secret to retrieve - * @param options - Options to configure the provider - * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: `5`) - * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache (default: `false`) - * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` - * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client, accepts the same configuration object as the AWS SDK v3 client ({@link SecretsManagerClientConfig | `SecretsManagerClientConfig`}). + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetSecretValueCommandInput | `GetSecretValueCommandInput`} except `SecretId` */ const getSecret = < ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/ssm/SSMProvider.ts b/packages/parameters/src/ssm/SSMProvider.ts index 66be3e52be..36a2097992 100644 --- a/packages/parameters/src/ssm/SSMProvider.ts +++ b/packages/parameters/src/ssm/SSMProvider.ts @@ -291,13 +291,13 @@ class SSMProvider extends BaseProvider { * @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 - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) - * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache (default: false) - * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` - * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client - * @param options.decrypt - Whether to decrypt the value before returning it. (default: false) + * @param name - The name of the parameter to retrieve + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetParameterCommandInput | `GetParameterCommandInput`} except `Name` + * @param options.decrypt - Optional flag to decrypt the value before returning it (default: `false`) */ public get< ExplicitUserProvidedType = undefined, @@ -390,14 +390,14 @@ class SSMProvider extends BaseProvider { * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ * * @param path - The path of the parameters to retrieve - * @param options - Options to configure the retrieval - * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) - * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache - * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` - * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client - * @param options.throwOnTransformError - Whether to throw an error if the transform fails (default: `true`) - * @param options.decrypt - Whether to decrypt the value before returning it. - * @param options.recursive - Whether to recursively retrieve all parameters under the given path (default: `false`) + * @param options - Optional options to configure the retrieval + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetParametersByPathCommandInput | `GetParametersByPathCommandInput`} except `Path` + * @param options.throwOnTransformError - Optional flag to throw an error if the transform fails (default: `true`) + * @param options.decrypt - Optional flag to decrypt the value before returning it (default: `false`) + * @param options.recursive - Optional flag to recursively retrieve all parameters under the given path (default: `false`) */ public getMultiple< ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/ssm/getParameter.ts b/packages/parameters/src/ssm/getParameter.ts index 32e969be21..359caebf7d 100644 --- a/packages/parameters/src/ssm/getParameter.ts +++ b/packages/parameters/src/ssm/getParameter.ts @@ -114,12 +114,12 @@ import { SSMProvider } from './SSMProvider.js'; * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ * * @param name - The name of the parameter to retrieve - * @param options - Options to configure the provider - * @param options.maxAge - Maximum age of the value in the cache, in seconds. Will be applied after the first API call. - * @param options.forceFetch - Force fetch the value from the parameter store, ignoring the cache. - * @param options.transform - Optional transform to be applied, can be 'json' or 'binary'. - * @param options.sdkOptions - Additional options to pass to the AWS SDK v3 for JavaScript client. Supports all options from {@link GetParameterCommandInput | `GetParameterCommandInput`} except `Name`. - * @param options.decrypt - Whether to decrypt the value before returning it. Defaults to `false`. + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetParameterCommandInput | `GetParameterCommandInput`} except `Name` + * @param options.decrypt - Optional flag to decrypt the value before returning it (default: `false`) */ const getParameter = < ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/src/ssm/getParameters.ts b/packages/parameters/src/ssm/getParameters.ts index 6691ed0f9e..b8aca01a0d 100644 --- a/packages/parameters/src/ssm/getParameters.ts +++ b/packages/parameters/src/ssm/getParameters.ts @@ -115,13 +115,13 @@ import { SSMProvider } from './SSMProvider.js'; * @see https://docs.powertools.aws.dev/lambda/typescript/latest/features/parameters/ * * @param path - The path of the parameters to retrieve - * @param options - Options to configure the provider - * @param options.maxAge - The maximum age of the value in cache before fetching a new one (in seconds) (default: 5) - * @param options.forceFetch - Whether to always fetch a new value from the store regardless if already available in cache - * @param options.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` - * @param options.sdkOptions - Extra options to pass to the AWS SDK v3 for JavaScript client, accepts the same options as {@link GetParametersByPathCommandInput | `GetParametersByPathCommandInput`}. - * @param options.decrypt - Whether to decrypt the value before returning it. - * @param options.recursive - Whether to recursively retrieve all parameters within the path. + * @param options - Optional options to configure the provider + * @param options.maxAge - Optional maximum age of the value in the cache, in seconds (default: `5`) + * @param options.forceFetch - Optional flag to always fetch a new value from the store regardless if already available in cache (default: `false`) + * @param options.transform - Optional transform to be applied, can be `json` or `binary` + * @param options.sdkOptions - Optional additional options to pass to the AWS SDK v3 client, supports all options from {@link GetParametersByPathCommandInput | `GetParametersByPathCommandInput`} except `Path` + * @param options.decrypt - Optional flag to decrypt the value before returning it (default: `false`) + * @param options.recursive - Optional flag to recursively retrieve all parameters within the path (default: `false`) */ const getParameters = < ExplicitUserProvidedType = undefined, diff --git a/packages/parameters/typedoc.json b/packages/parameters/typedoc.json index 2eac7c6cfe..20ae20e204 100644 --- a/packages/parameters/typedoc.json +++ b/packages/parameters/typedoc.json @@ -16,16 +16,16 @@ "readme": "README.md", "externalSymbolLinkMappings": { "@aws-sdk/client-secrets-manager": { - "GetSecretValueCommandInput": "#" + "GetSecretValueCommandInput": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-secrets-manager/Interface/GetSecretValueCommandInput/" }, "@aws-sdk/client-dynamodb": { - "DynamoDBClient": "#", - "GetItemCommandInput": "#", - "QueryCommandInput": "#" + "DynamoDBClient": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/", + "GetItemCommandInput": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-dynamodb/Interface/GetItemCommandInput/", + "QueryCommandInput": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-dynamodb/Interface/QueryCommandInput/" }, "@aws-sdk/client-appconfigdata": { - "AppConfigDataClient": "#", - "StartConfigurationSessionCommandInput": "#" + "AppConfigDataClient": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/appconfigdata/", + "StartConfigurationSessionCommandInput": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-appconfigdata/Interface/StartConfigurationSessionCommandInput/" }, "@aws-sdk/client-ssm": { "GetParameterCommandInput": "#" } }