From 4573bf6dbe62552b9bc1701e9b320e8af9391670 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 11 Sep 2024 19:51:53 +0200 Subject: [PATCH 1/3] improv(parameters): include cause in set parameter error --- packages/parameters/src/errors.ts | 12 +++++--- packages/parameters/src/ssm/SSMProvider.ts | 7 +++-- packages/parameters/src/ssm/setParameter.ts | 31 ++++++--------------- 3 files changed, 20 insertions(+), 30 deletions(-) diff --git a/packages/parameters/src/errors.ts b/packages/parameters/src/errors.ts index 5f5325c141..722cc52580 100644 --- a/packages/parameters/src/errors.ts +++ b/packages/parameters/src/errors.ts @@ -1,19 +1,23 @@ /** * Error thrown when a parameter cannot be retrieved. + * + * You can use this error to catch and handle errors when getting a parameter, the `cause` property will contain the original error. */ class GetParameterError extends Error { - public constructor(message?: string) { - super(message); + public constructor(message?: string, options?: ErrorOptions) { + super(message, options); this.name = 'GetParameterError'; } } /** * Error thrown when a parameter cannot be set. + * + * You can use this error to catch and handle errors when setting a parameter, the `cause` property will contain the original error. */ class SetParameterError extends Error { - public constructor(message?: string) { - super(message); + public constructor(message?: string, options?: ErrorOptions) { + super(message, options); this.name = 'SetParameterError'; } } diff --git a/packages/parameters/src/ssm/SSMProvider.ts b/packages/parameters/src/ssm/SSMProvider.ts index e3a0413475..86c1e571c6 100644 --- a/packages/parameters/src/ssm/SSMProvider.ts +++ b/packages/parameters/src/ssm/SSMProvider.ts @@ -376,11 +376,12 @@ class SSMProvider extends BaseProvider { try { result = await this.client.send(new PutParameterCommand(sdkOptions)); } catch (error) { - throw new SetParameterError(`Unable to set parameter with name ${name}`); + throw new SetParameterError(`Unable to set parameter with name ${name}`, { + cause: error, + }); } - // biome-ignore lint/style/noNonNullAssertion: The API for PutParameter states that there will always be a value returned when the request was successful. - return result.Version!; + return result.Version as number; } /** diff --git a/packages/parameters/src/ssm/setParameter.ts b/packages/parameters/src/ssm/setParameter.ts index 08d64b4c24..ed8eb317fd 100644 --- a/packages/parameters/src/ssm/setParameter.ts +++ b/packages/parameters/src/ssm/setParameter.ts @@ -3,36 +3,21 @@ import type { SSMSetOptions } from '../types/SSMProvider.js'; import { SSMProvider } from './SSMProvider.js'; /** - * ## Intro - * The Parameters utility provides an SSMProvider that allows setting parameters in AWS Systems Manager. + * Set a parameter in AWS Systems Manager Parameter Store. * - * ## Getting started - * - * 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 SSM: - * - * ```sh - * npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm - *``` - * - * ## Basic Usage + * **Basic Usage** * * @example * ```typescript * import { setParameter } from '@aws-lambda-powertools/parameters/ssm'; * - * export const handler = async (): Promise => { - * // Set a parameter - * const version = await setParameter('/my-parameter', { value: 'my-value' }); - * console.log(Parameter version: ${version}); + * export const handler = async () => { + * // Set a parameter + * const version = await setParameter('/my-parameter', { value: 'my-value' }); * }; * ``` * - * ## Advanced Usage - * - * ### Overwriting a parameter + * **Overwriting a parameter** * * By default, the provider will not overwrite a parameter if it already exists. You can force the provider to overwrite the parameter by using the `overwrite` option. * @@ -71,11 +56,11 @@ import { SSMProvider } from './SSMProvider.js'; * * This object accepts the same options as the AWS SDK v3 for JavaScript `PutParameterCommandInput` interface. * - * ### 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 + * **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. From 776c9c2c0f7f93c8c8d8c5bdb2c12a3a5c695fcb Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 11 Sep 2024 20:08:50 +0200 Subject: [PATCH 2/3] docs: improve api docs --- packages/parameters/src/ssm/setParameter.ts | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/packages/parameters/src/ssm/setParameter.ts b/packages/parameters/src/ssm/setParameter.ts index ed8eb317fd..fbdf9dce8d 100644 --- a/packages/parameters/src/ssm/setParameter.ts +++ b/packages/parameters/src/ssm/setParameter.ts @@ -35,7 +35,7 @@ import { SSMProvider } from './SSMProvider.js'; * }; * ``` * - * ### Extra SDK options + * **Extra SDK options** * * When setting a parameter, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter. * @@ -52,17 +52,15 @@ import { SSMProvider } from './SSMProvider.js'; * }, * }); * }; - * ``` - * - * This object accepts the same options as the AWS SDK v3 for JavaScript `PutParameterCommandInput` interface. + * ``` * - * **Built-in provider class** + * This object accepts the same options as the AWS SDK v3 for JavaScript `PutParameterCommandInput` interface. * - * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SSMProvider} class. + * For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the {@link SSMProvider} utility. * - * **Options** + * **Options** * - * You can customize the storage of the value by passing options to the function: + * 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 From 8e9ad98d9727cdae00eaf4a1da69d366b048684c Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Wed, 11 Sep 2024 20:09:23 +0200 Subject: [PATCH 3/3] docs: improve api docs --- packages/parameters/src/ssm/setParameter.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/parameters/src/ssm/setParameter.ts b/packages/parameters/src/ssm/setParameter.ts index fbdf9dce8d..01fc937bee 100644 --- a/packages/parameters/src/ssm/setParameter.ts +++ b/packages/parameters/src/ssm/setParameter.ts @@ -71,8 +71,8 @@ import { SSMProvider } from './SSMProvider.js'; * * For more usage examples, see [our documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/). * - * @param {string} name - Name of the parameter - * @param {SSMSetOptions} options - Options to configure the parameter + * @param name - Name of the parameter + * @param options - Options to configure the parameter * @see https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/ */ const setParameter = async <