feat: improved types for getParameters

Author: dreamorosi

Diff for: packages/parameters/src/ssm/SSMProvider.ts

@@ -15,10 +15,12 @@ import type {
 } from '@aws-sdk/client-ssm';
 import type {
   SSMProviderOptions,
-  SSMGetMultipleOptionsInterface,
   SSMGetOptions,
   SSMGetOptionsUnion,
   SSMGetOutput,
+  SSMGetMultipleOptions,
+  SSMGetMultipleOptionsUnion,
+  SSMGetMultipleOutput,
   SSMGetParametersByNameOutputInterface,
   SSMGetParametersByNameOptionsInterface,
   SSMSplitBatchAndDecryptParametersOutputType,
@@ -314,7 +316,7 @@ class SSMProvider extends BaseProvider {
    * For usage examples check {@link SSMProvider}.
    *
    * @param {string} name - The name of the value to retrieve (i.e. the partition key)
-   * @param {SSMGetOptionsInterface} options - Options to configure the provider
+   * @param {SSMGetOptions} options - Options to configure the provider
    * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/
    */
   public async get<O extends SSMGetOptionsUnion | undefined = undefined>(
@@ -351,14 +353,14 @@ class SSMProvider extends BaseProvider {
    * For usage examples check {@link SSMProvider}.
    *
    * @param {string} path - The path of the parameters to retrieve
-   * @param {SSMGetMultipleOptionsInterface} options - Options to configure the retrieval
+   * @param {SSMGetMultipleOptions} options - Options to configure the retrieval
    * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/
    */
-  public async getMultiple(
+  public async getMultiple<O extends SSMGetMultipleOptionsUnion | undefined = undefined>(
     path: string,
-    options?: SSMGetMultipleOptionsInterface | undefined
-  ): Promise<undefined | Record<string, unknown>> {
-    return super.getMultiple(path, options);
+    options?: O & SSMGetMultipleOptions
+  ): Promise<SSMGetMultipleOutput<O> | undefined> {
+    return super.getMultiple(path, options) as Promise<SSMGetMultipleOutput<O> | undefined>;
   }
 
   /**
@@ -469,7 +471,7 @@ class SSMProvider extends BaseProvider {
    * Retrieve a parameter from AWS Systems Manager.
    *
    * @param {string} name - Name of the parameter to retrieve
-   * @param {SSMGetOptionsInterface} options - Options to customize the retrieval
+   * @param {SSMGetOptions} options - Options to customize the retrieval
    */
   protected async _get(
     name: string,
@@ -490,11 +492,11 @@ class SSMProvider extends BaseProvider {
    * Retrieve multiple items from AWS Systems Manager.
    *
    * @param {string} path - The path of the parameters to retrieve
-   * @param {SSMGetMultipleOptionsInterface} options - Options to configure the provider
+   * @param {SSMGetMultipleOptions} options - Options to configure the provider
    */
   protected async _getMultiple(
     path: string,
-    options?: SSMGetMultipleOptionsInterface
+    options?: SSMGetMultipleOptions
   ): Promise<Record<string, string | undefined>> {
     const sdkOptions: GetParametersByPathCommandInput = {
       ...(options?.sdkOptions || {}),

Diff for: packages/parameters/src/ssm/getParameter.ts

@@ -137,7 +137,7 @@ import type {
  * For more usage examples, see [our documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/).
  *
  * @param {string} name - The name of the parameter to retrieve
- * @param {SSMGetOptionsInterface} options - Options to configure the provider
+ * @param {SSMGetOptions} options - Options to configure the provider
  * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/
  */
 const getParameter = <O extends SSMGetOptionsUnion | undefined = undefined>(
@@ -148,7 +148,9 @@ const getParameter = <O extends SSMGetOptionsUnion | undefined = undefined>(
     DEFAULT_PROVIDERS.ssm = new SSMProvider();
   }
 
-  return (DEFAULT_PROVIDERS.ssm as SSMProvider).get(name, options) as Promise<SSMGetOutput<O> | undefined>;
+  return (
+    DEFAULT_PROVIDERS.ssm as SSMProvider
+  ).get(name, options) as Promise<SSMGetOutput<O> | undefined>;
 };
 
 export {

Diff for: packages/parameters/src/ssm/getParameters.ts

@@ -1,5 +1,9 @@
 import { SSMProvider, DEFAULT_PROVIDERS } from './SSMProvider';
-import type { SSMGetMultipleOptionsInterface } from '../types/SSMProvider';
+import type {
+  SSMGetMultipleOptions,
+  SSMGetMultipleOptionsUnion,
+  SSMGetMultipleOutput,
+} from '../types/SSMProvider';
 
 /**
  * ## Intro
@@ -134,18 +138,20 @@ import type { SSMGetMultipleOptionsInterface } from '../types/SSMProvider';
  * For more usage examples, see [our documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/).
  *
  * @param {string} path - The path of the parameters to retrieve
- * @param {SSMGetMultipleOptionsInterface} options - Options to configure the provider
+ * @param {SSMGetMultipleOptions} options - Options to configure the provider
  * @see https://awslabs.github.io/aws-lambda-powertools-typescript/latest/utilities/parameters/
  */
-const getParameters = (
+const getParameters = <O extends SSMGetMultipleOptionsUnion | undefined = undefined>(
   path: string,
-  options?: SSMGetMultipleOptionsInterface
-): Promise<undefined | Record<string, unknown>> => {
+  options?: O & SSMGetMultipleOptions
+): Promise<SSMGetMultipleOutput<O> | undefined> => {
   if (!DEFAULT_PROVIDERS.hasOwnProperty('ssm')) {
     DEFAULT_PROVIDERS.ssm = new SSMProvider();
   }
 
-  return (DEFAULT_PROVIDERS.ssm as SSMProvider).getMultiple(path, options);
+  return (
+    DEFAULT_PROVIDERS.ssm as SSMProvider
+  ).getMultiple(path, options) as Promise<SSMGetMultipleOutput<O> | undefined>;
 };
 
 export {

Diff for: packages/parameters/src/types/SSMProvider.ts

@@ -50,12 +50,18 @@ type SSMProviderOptions = SSMProviderOptionsWithClientConfig | SSMProviderOption
  * @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 {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.
+ * @property {boolean} decrypt - If true, the parameter will be decrypted. Defaults to `false`.
  */
 interface SSMGetOptions extends GetOptionsInterface {
+  /**
+   * If true, the parameter will be decrypted. Defaults to `false`.
+   */
   decrypt?: boolean
+  /**
+   * Additional options to pass to the AWS SDK v3 client. Supports all options from `GetParameterCommandInput`.
+   */
   sdkOptions?: Partial<GetParameterCommandInput>
 }
 
@@ -93,13 +99,46 @@ type SSMGetOutput<O = undefined> =
  * @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.
  */
-interface SSMGetMultipleOptionsInterface extends GetMultipleOptionsInterface {
+interface SSMGetMultipleOptions extends GetMultipleOptionsInterface {
+  /**
+   * Additional options to pass to the AWS SDK v3 client. Supports all options from `GetParametersByPathCommandInput`.
+   */
   sdkOptions?: Partial<GetParametersByPathCommandInput>
+  /**
+   * If true, the parameters will be decrypted. Defaults to `false`.
+   */
   decrypt?: boolean
+  /**
+   * If true, the parameters will be fetched recursively. Defaults to `false`.
+   */
   recursive?: boolean
+  /**
+   * If true, the method will throw an error if the transform fails.
+   */
   throwOnTransformError?: boolean
 }
 
+interface SSMGetMultipleOptionsTransformJson extends SSMGetMultipleOptions {
+  transform: 'json'
+}
+
+interface SSMGetMultipleOptionsTransformBinary extends SSMGetMultipleOptions {
+  transform: 'binary'
+}
+
+interface SSMGetMultipleOptionsTransformNone extends SSMGetMultipleOptions {
+  transform?: never
+}
+
+type SSMGetMultipleOptionsUnion = SSMGetMultipleOptionsTransformJson | SSMGetMultipleOptionsTransformBinary | SSMGetMultipleOptionsTransformNone | undefined;
+
+type SSMGetMultipleOutput<O = undefined> =
+    undefined extends O ? Record<string, string> :
+      O extends SSMGetMultipleOptionsTransformNone | SSMGetMultipleOptionsTransformBinary ? Record<string, string> :
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        O extends SSMGetMultipleOptionsTransformJson ? Record<string, Record<string, any>> :
+          never;
+
 /**
  * Options for the SSMProvider getParametersByName method.
  *
@@ -145,7 +184,9 @@ export type {
   SSMGetOptions,
   SSMGetOptionsUnion,
   SSMGetOutput,
-  SSMGetMultipleOptionsInterface,
+  SSMGetMultipleOptions,
+  SSMGetMultipleOptionsUnion,
+  SSMGetMultipleOutput,
   SSMGetParametersByNameOptionsInterface,
   SSMSplitBatchAndDecryptParametersOutputType,
   SSMGetParametersByNameOutputInterface,