diff --git a/packages/parameters/src/appconfig/AppConfigProvider.ts b/packages/parameters/src/appconfig/AppConfigProvider.ts index 1975968c99..c78bdadf26 100644 --- a/packages/parameters/src/appconfig/AppConfigProvider.ts +++ b/packages/parameters/src/appconfig/AppConfigProvider.ts @@ -14,15 +14,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 +38,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 +77,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 +113,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 +139,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. * @@ -192,21 +187,20 @@ class AppConfigProvider extends BaseProvider { private readonly application?: string; private readonly environment: string; - /** - * It initializes the AppConfigProvider class. - * * - * @param {AppConfigProviderOptions} options - The configuration object. - */ - 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( @@ -235,26 +229,23 @@ 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 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 async get< + public get< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | AppConfigGetOptions | undefined = AppConfigGetOptions, >( name: string, - options?: InferredFromOptionsType & AppConfigGetOptions + options?: NonNullable ): Promise< | AppConfigGetOutput | undefined @@ -287,12 +278,16 @@ 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, - options?: AppConfigGetOptions + options?: NonNullable ): Promise { if ( !this.configurationTokenStore.has(name) || @@ -339,7 +334,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 +353,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/appconfig/getAppConfig.ts b/packages/parameters/src/appconfig/getAppConfig.ts index aa73d49741..0a3e11996a 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 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 - 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, @@ -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 2678d31113..a35127e2e4 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. * @@ -239,11 +234,6 @@ class DynamoDBProvider extends BaseProvider { protected tableName: string; protected valueAttr = 'value'; - /** - * It initializes the DynamoDBProvider class. - * - * @param {DynamoDBProviderOptions} config - The configuration object. - */ public constructor(config: DynamoDBProviderOptions) { super({ awsSdkV3ClientPrototype: DynamoDBClient as new ( @@ -276,26 +266,23 @@ 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 (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 async get< + public get< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | DynamoDBGetOptions | undefined = DynamoDBGetOptions, >( name: string, - options?: InferredFromOptionsType & DynamoDBGetOptions + options?: NonNullable ): Promise< | DynamoDBGetOutput | undefined @@ -323,27 +310,24 @@ 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 (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 async getMultiple< + public getMultiple< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | DynamoDBGetMultipleOptions | undefined = DynamoDBGetMultipleOptions, >( path: string, - options?: InferredFromOptionsType & DynamoDBGetMultipleOptions + options?: NonNullable ): Promise< | DynamoDBGetMultipleOutput< ExplicitUserProvidedType, @@ -363,12 +347,16 @@ 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 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 || {}), @@ -387,12 +375,17 @@ 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, - 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 134e788536..f247a7aca8 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,18 +135,12 @@ 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. - * - * @param {SecretsProviderOptions} config - The configuration object. - */ - public constructor(config?: SecretsProviderOptions) { + public constructor(config?: NonNullable) { super({ awsSdkV3ClientPrototype: SecretsManagerClient as new ( config?: unknown @@ -175,26 +164,23 @@ 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 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 async get< + public get< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SecretsGetOptions | undefined = SecretsGetOptions, >( name: string, - options?: InferredFromOptionsType & SecretsGetOptions + options?: NonNullable ): Promise< | SecretsGetOutput | undefined @@ -206,7 +192,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,14 +202,15 @@ 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, - options?: SecretsGetOptions + options?: NonNullable ): Promise { const sdkOptions: GetSecretValueCommandInput = { ...(options?.sdkOptions || {}), @@ -240,11 +227,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..f1d04849e2 100644 --- a/packages/parameters/src/secrets/getSecret.ts +++ b/packages/parameters/src/secrets/getSecret.ts @@ -6,21 +6,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 +23,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 +50,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 +64,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,25 +84,27 @@ 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 - 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 = async < +const getSecret = < ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SecretsGetOptions | 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 d905ab2681..36a2097992 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. * @@ -272,11 +267,6 @@ class SSMProvider extends BaseProvider { protected errorsKey = '_errors'; protected maxGetParametersItems = 10; - /** - * It initializes the SSMProvider class. - * - * @param {SSMProviderOptions} config - The configuration object. - */ public constructor(config?: SSMProviderOptions) { super({ awsSdkV3ClientPrototype: SSMClient as new (config?: unknown) => SSMClient, @@ -298,26 +288,23 @@ 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 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 async get< + public get< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends SSMGetOptions | undefined = SSMGetOptions, >( name: string, - options?: InferredFromOptionsType & SSMGetOptions + options?: NonNullable ): Promise< SSMGetOutput | undefined > { @@ -343,19 +330,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,29 +385,28 @@ 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 - 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 async getMultiple< + public getMultiple< ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SSMGetMultipleOptions | undefined = undefined, >( path: string, - options?: InferredFromOptionsType & SSMGetMultipleOptions + options?: NonNullable ): Promise< | SSMGetMultipleOutput | undefined @@ -450,15 +434,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,13 +456,18 @@ 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.transform - Whether to transform the value before returning it. Supported values: `json`, `binary` + * @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 = { ...{ @@ -554,12 +536,15 @@ 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, - options?: SSMGetOptions + options?: NonNullable ): Promise { const sdkOptions: GetParameterCommandInput = { ...(options?.sdkOptions || {}), @@ -577,12 +562,19 @@ 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, - options?: SSMGetMultipleOptions + options?: NonNullable ): Promise> { const sdkOptions: GetParametersByPathCommandInput = { ...(options?.sdkOptions || {}), @@ -613,7 +605,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 +622,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 +658,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 +697,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 +729,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 +773,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 +806,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 +848,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 +889,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 +908,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..359caebf7d 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,31 +107,26 @@ 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 - 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 = async < +const getParameter = < ExplicitUserProvidedType = undefined, 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 a00caee550..b8aca01a0d 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,34 +110,27 @@ 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 - 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 = async < +const getParameters = < ExplicitUserProvidedType = undefined, InferredFromOptionsType extends | SSMGetMultipleOptions | 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 b609871b0f..57c5043c08 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,15 +133,18 @@ 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.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 = async ( +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/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..d9768f49ee 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 - 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`. */ 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')); diff --git a/packages/parameters/typedoc.json b/packages/parameters/typedoc.json index 90daedca0b..20ae20e204 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": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-secrets-manager/Interface/GetSecretValueCommandInput/" + }, + "@aws-sdk/client-dynamodb": { + "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": "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": "#" } + } }