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

* 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

Author: dreamorosi

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}`);
+  }
+};

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);
+};

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);
+};

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);
+};

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);
+};

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);
+};

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);
+};

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);
+};

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}`);
+  }
+};

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);
+};