docs(parameters): main docs for the utility (#1215)

dreamorosi · web-flow · commit 0d68f5904363 · 2023-01-10T16:56:47.000+01:00
* docs: added main section, SSMProvider, transform, and config

* chore: added missing new in front of constructor

* docs: added SecretsProvider sections

* docs: fixes

* docs: added DynamoDBProvider

* docs: completed first version of docs

* docs: extract code snippets

* docs: review comments
diff --git a/docs/snippets/parameters/adjustingCacheTTL.ts b/docs/snippets/parameters/adjustingCacheTTL.ts
@@ -0,0 +1,15 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+
+const parametersProvider = new SSMProvider();
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single parameter
+  const parameter = await parametersProvider.get('/my/parameter', { maxAge: 60 }); // 1 minute
+  console.log(parameter);
+
+  // Retrieve multiple parameters from a path prefix
+  const parameters = await parametersProvider.getMultiple('/my/path/prefix', { maxAge: 120 }); // 2 minutes
+  for (const [ key, value ] of Object.entries(parameters || {})) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/appConfigProvider.ts b/docs/snippets/parameters/appConfigProvider.ts
@@ -0,0 +1,15 @@
+import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
+import type { AppConfigDataClientConfig } from '@aws-sdk/client-appconfigdata';
+
+const clientConfig: AppConfigDataClientConfig = { region: 'us-east-1' };
+const configsProvider = new AppConfigProvider({
+  application: 'my-app',
+  environment: 'my-env',
+  clientConfig,
+});
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a config
+  const config = await configsProvider.get('my-config');
+  console.log(config);
+};
diff --git a/docs/snippets/parameters/appConfigProviderCustomClient.ts b/docs/snippets/parameters/appConfigProviderCustomClient.ts
@@ -0,0 +1,12 @@
+import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
+import { AppConfigDataClient } from '@aws-sdk/client-appconfigdata';
+
+// construct your clients with any custom configuration
+const appConfigClient = new AppConfigDataClient({ region: 'us-east-1' });
+// pass the client to the provider
+const configsProvider = new AppConfigProvider({ awsSdkV3Client: appConfigClient });
+
+export const handler = async (): Promise<void> => {
+  const config = await configsProvider.get('my-config');
+  console.log(config);
+};
diff --git a/docs/snippets/parameters/clientConfig.ts b/docs/snippets/parameters/clientConfig.ts
@@ -0,0 +1,11 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+import type { SSMClientConfig } from '@aws-sdk/client-ssm';
+
+const clientConfig: SSMClientConfig = { region: 'us-east-1' };
+const parametersProvider = new SSMProvider({ clientConfig });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single parameter
+  const value = await parametersProvider.get('/my/parameter');
+  console.log(value);
+};
diff --git a/docs/snippets/parameters/dynamoDBProvider.ts b/docs/snippets/parameters/dynamoDBProvider.ts
@@ -0,0 +1,9 @@
+import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
+
+const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a value from DynamoDB
+  const value = await dynamoDBProvider.get('my-parameter');
+  console.log(value);
+};
diff --git a/docs/snippets/parameters/dynamoDBProviderCustomClient.ts b/docs/snippets/parameters/dynamoDBProviderCustomClient.ts
@@ -0,0 +1,13 @@
+import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+// construct your clients with any custom configuration
+const dynamoDBClient = new DynamoDBClient({ region: 'us-east-1' });
+// pass the client to the provider
+const valuesProvider = new DynamoDBProvider({ awsSdkV3Client: dynamoDBClient });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single value
+  const value = await valuesProvider.get('my-value');
+  console.log(value);
+};
diff --git a/docs/snippets/parameters/dynamoDBProviderCustomizeTable.ts b/docs/snippets/parameters/dynamoDBProviderCustomizeTable.ts
@@ -0,0 +1,13 @@
+import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
+
+const dynamoDBProvider = new DynamoDBProvider({
+  tableName:'my-table',
+  keyAttr:'key',
+  sortAttr:'sort',
+  valueAttr:'val'
+});
+
+export const handler = async (): Promise<void> => {
+  const value = await dynamoDBProvider.get('my-parameter');
+  console.log(value);
+};
diff --git a/docs/snippets/parameters/dynamoDBProviderLocal.ts b/docs/snippets/parameters/dynamoDBProviderLocal.ts
@@ -0,0 +1,14 @@
+import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
+
+const dynamoDBProvider = new DynamoDBProvider({
+	  tableName: 'my-table',
+	  clientConfig: {
+	    endpoint: 'http://localhost:8000'
+	  },
+});
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a value from DynamoDB
+  const value = await dynamoDBProvider.get('my-parameter');
+  console.log(value);
+};
diff --git a/docs/snippets/parameters/dynamoDBProviderMultiple.ts b/docs/snippets/parameters/dynamoDBProviderMultiple.ts
@@ -0,0 +1,16 @@
+import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
+
+const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' });
+
+export const handler = async (): Promise<void> => {
+  /**
+	 * Retrieve multiple values by performing a Query on the DynamoDB table.
+	 * This returns a dict with the sort key attribute as dict key.
+	 */
+  const values = await dynamoDBProvider.getMultiple('my-hash-key');
+  for (const [ key, value ] of Object.entries(values || {})) {
+    // key: param-a
+    // value: my-value-a
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/forceFetch.ts b/docs/snippets/parameters/forceFetch.ts
@@ -0,0 +1,7 @@
+import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single parameter
+  const parameter = await getParameter('/my/parameter', { forceFetch: true });
+  console.log(parameter);
+};
diff --git a/docs/snippets/parameters/getAppConfig.ts b/docs/snippets/parameters/getAppConfig.ts
@@ -0,0 +1,10 @@
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a configuration, latest version
+  const config = await getAppConfig('my-configuration', {
+    environment: 'my-env',
+    application: 'my-app'
+  });
+  console.log(config);
+};
diff --git a/docs/snippets/parameters/getParameter.ts b/docs/snippets/parameters/getParameter.ts
@@ -0,0 +1,7 @@
+import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single parameter
+  const parameter = await getParameter('/my/parameter');
+  console.log(parameter);
+};
diff --git a/docs/snippets/parameters/getParameters.ts b/docs/snippets/parameters/getParameters.ts
@@ -0,0 +1,12 @@
+import { getParameters } from '@aws-lambda-powertools/parameters/ssm';
+
+export const handler = async (): Promise<void> => {
+  /**
+   * Retrieve multiple parameters from a path prefix recursively.
+   * This returns an object with the parameter name as key
+   */ 
+  const parameters = await getParameters('/my/path/prefix');
+  for (const [ key, value ] of Object.entries(parameters || {})) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/getParametersByName.ts b/docs/snippets/parameters/getParametersByName.ts
@@ -0,0 +1,18 @@
+import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
+import type {
+  SSMGetParametersByNameOptionsInterface
+} from '@aws-lambda-powertools/parameters/ssm';
+
+const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
+  '/develop/service/commons/telemetry/config': { maxAge: 300, transform: 'json' },
+  '/no_cache_param': { maxAge: 0 },
+  '/develop/service/payment/api/capture/url': {}, // When empty or undefined, it uses default values
+};
+
+export const handler = async (): Promise<void> => {
+  // This returns an object with the parameter name as key
+  const parameters = await getParametersByName(props, { maxAge: 60 });
+  for (const [ key, value ] of Object.entries(parameters)) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts b/docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts
@@ -0,0 +1,25 @@
+import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
+import type {
+  SSMGetParametersByNameOptionsInterface
+} from '@aws-lambda-powertools/parameters/ssm';
+
+const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
+  '/develop/service/commons/telemetry/config': { maxAge: 300, transform: 'json' },
+  '/this/param/does/not/exist': {}, // <- Example of non-existent parameter
+};
+
+export const handler = async (): Promise<void> => {
+  const {
+    _errors: errors,
+    ...parameters
+  } = await getParametersByName(props, { throwOnError: false });
+	
+  // Handle gracefully, since `/this/param/does/not/exist` will only be available in `_errors`
+  if (errors && errors.length) {
+    console.error(`Unable to retrieve parameters: ${errors.join(',')}`);
+  }
+
+  for (const [ key, value ] of Object.entries(parameters)) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/getSecret.ts b/docs/snippets/parameters/getSecret.ts
@@ -0,0 +1,7 @@
+import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single secret
+  const secret = await getSecret('my-secret');
+  console.log(secret);
+};
diff --git a/docs/snippets/parameters/sdkOptions.ts b/docs/snippets/parameters/sdkOptions.ts
@@ -0,0 +1,16 @@
+import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
+import type { GetSecretValueCommandInput } from '@aws-sdk/client-secrets-manager';
+
+const secretsProvider = new SecretsProvider();
+
+export const handler = async (): Promise<void> => {
+  const sdkOptions: Partial<GetSecretValueCommandInput> = {
+    VersionId: 'e62ec170-6b01-48c7-94f3-d7497851a8d2'
+  };
+  /**
+   * The 'VersionId' argument will be passed to the underlying
+   * `GetSecretValueCommand` call.
+   */
+  const secret = await secretsProvider.get('my-secret', { sdkOptions });
+  console.log(secret);
+};
diff --git a/docs/snippets/parameters/secretsProvider.ts b/docs/snippets/parameters/secretsProvider.ts
@@ -0,0 +1,11 @@
+import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
+import type { SecretsManagerClientConfig } from '@aws-sdk/client-secretsmanager';
+
+const clientConfig: SecretsManagerClientConfig = { region: 'us-east-1' };
+const secretsProvider = new SecretsProvider({ clientConfig });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single secret
+  const secret = await secretsProvider.get('my-secret');
+  console.log(secret);
+};
diff --git a/docs/snippets/parameters/secretsProviderCustomClient.ts b/docs/snippets/parameters/secretsProviderCustomClient.ts
@@ -0,0 +1,13 @@
+import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+
+// construct your clients with any custom configuration
+const secretsManagerClient = new SecretsManagerClient({ region: 'us-east-1' });
+// pass the client to the provider
+const secretsProvider = new SecretsProvider({ awsSdkV3Client: secretsManagerClient });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single secret
+  const secret = await secretsProvider.get('my-secret');
+  console.log(secret);
+};
diff --git a/docs/snippets/parameters/ssmProvider.ts b/docs/snippets/parameters/ssmProvider.ts
@@ -0,0 +1,17 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+import type { SSMClientConfig } from '@aws-sdk/client-ssm';
+
+const clientConfig: SSMClientConfig = { region: 'us-east-1' };
+const parametersProvider = new SSMProvider({ clientConfig });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single parameter
+  const parameter = await parametersProvider.get('/my/parameter');
+  console.log(parameter);
+
+  // Retrieve multiple parameters from a path prefix
+  const parameters = await parametersProvider.getMultiple('/my/path/prefix');
+  for (const [ key, value ] of Object.entries(parameters || {})) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/ssmProviderCustomClient.ts b/docs/snippets/parameters/ssmProviderCustomClient.ts
@@ -0,0 +1,13 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+import { SSMClient } from '@aws-sdk/client-ssm';
+
+// construct your clients with any custom configuration
+const ssmClient = new SSMClient({ region: 'us-east-1' });
+// pass the client to the provider
+const parametersProvider = new SSMProvider({ awsSdkV3Client: ssmClient });
+
+export const handler = async (): Promise<void> => {
+  // Retrieve a single parameter
+  const parameter = await parametersProvider.get('/my/parameter');
+  console.log(parameter);
+};
diff --git a/docs/snippets/parameters/ssmProviderDecryptAndRecursive.ts b/docs/snippets/parameters/ssmProviderDecryptAndRecursive.ts
@@ -0,0 +1,13 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+
+const parametersProvider = new SSMProvider();
+
+export const handler = async (): Promise<void> => {
+  const decryptedValue = await parametersProvider.get('/my/encrypted/parameter', { decrypt: true });
+  console.log(decryptedValue);
+
+  const noRecursiveValues = await parametersProvider.getMultiple('/my/path/prefix', { recursive: false });
+  for (const [ key, value ] of Object.entries(noRecursiveValues || {})) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/transform.ts b/docs/snippets/parameters/transform.ts
@@ -0,0 +1,6 @@
+import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
+
+export const handler = async (): Promise<void> => {
+  const valueFromJson = await getParameter('/my/json/parameter', { transform: 'json' });
+  console.log(valueFromJson);
+};
diff --git a/docs/snippets/parameters/transformAuto.ts b/docs/snippets/parameters/transformAuto.ts
@@ -0,0 +1,10 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+
+const parametersProvider = new SSMProvider();
+
+export const handler = async (): Promise<void> => {
+  const values = await parametersProvider.getMultiple('/param', { transform: 'auto' });
+  for (const [ key, value ] of Object.entries(values || {})) {
+    console.log(`${key}: ${value}`);
+  }
+};
diff --git a/docs/snippets/parameters/transformPartialFailures.ts b/docs/snippets/parameters/transformPartialFailures.ts
@@ -0,0 +1,29 @@
+import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
+
+const parametersProvider = new SSMProvider();
+
+export const handler = async (): Promise<void> => {
+  /**
+   * This will display:
+   * /param/a: [some value]
+   * /param/b: [some value]
+   * /param/c: undefined
+   */
+  const parameters = await parametersProvider.getMultiple('/param', { transform: 'json' });
+  for (const [ key, value ] of Object.entries(parameters || {})) {
+    console.log(`${key}: ${value}`);
+  }
+
+  try {
+    // This will throw a TransformParameterError
+    const parameters2 = await parametersProvider.getMultiple('/param', {
+      transform: 'json',
+      throwOnTransformError: true
+    });
+    for (const [ key, value ] of Object.entries(parameters2 || {})) {
+      console.log(`${key}: ${value}`);
+    }
+  } catch (err) {
+    console.error(err);
+  }
+};
diff --git a/docs/snippets/parameters/transformProvider.ts b/docs/snippets/parameters/transformProvider.ts
@@ -0,0 +1,13 @@
+import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
+
+const secretsProvider = new SecretsProvider();
+
+export const handler = async (): Promise<void> => {
+  // Transform a JSON string
+  const json = await secretsProvider.get('my-secret-json', { transform: 'json' });
+  console.log(json);
+
+  // Transform a Base64 encoded string (e.g. binary)
+  const binary = await secretsProvider.getMultiple('my-secret-binary', { transform: 'binary' });
+  console.log(binary);
+};
diff --git a/docs/snippets/parameters/tsconfig.json b/docs/snippets/parameters/tsconfig.json
diff --git a/docs/utilities/parameters.md b/docs/utilities/parameters.md
