improv(parameters): include cause in set parameter error (#3047)

Author: dreamorosi

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';
   }
 }

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;
   }
 
   /**

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<void> => {
- *  // 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.
  *
@@ -50,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.
  *
@@ -67,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
@@ -88,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 <