From cc73aa97e205e65cb35544adee6d495eee4b88c7 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 22 Jun 2023 16:10:40 +0000 Subject: [PATCH 1/2] docs(parameters): refresh README file with usage examples --- packages/parameters/README.md | 211 ++++++++++++++++++++++++++++------ 1 file changed, 173 insertions(+), 38 deletions(-) diff --git a/packages/parameters/README.md b/packages/parameters/README.md index 89c4f70157..79a7984964 100644 --- a/packages/parameters/README.md +++ b/packages/parameters/README.md @@ -6,19 +6,16 @@ Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serverless [best practices and increase developer velocity](https://docs.powertools.aws.dev/lambda-typescript/latest/#features). -You can use the library in both TypeScript and JavaScript code bases. - -> Also available in [Python](https://github.com/aws-powertools/powertools-lambda-python), [Java](https://github.com/aws-powertools/powertools-lambda-java), and [.NET](https://docs.powertools.aws.dev/lambda-dotnet/). - -**[Documentation](https://docs.powertools.aws.dev/lambda-typescript/)** | **[npm](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://docs.powertools.aws.dev/lambda-typescript/latest/roadmap)** | **[Examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** - -## Table of contents - -- [Features](#features) -- [Getting started](#getting-started) - - [Installation](#installation) - - [Examples](#examples) - - [Serverless TypeScript Demo application](#serverless-typescript-demo-application) +You can use the package in both TypeScript and JavaScript code bases. + +- [Intro](#intro) +- [Key features](#key-features) +- [Usage](#usage) + - [SSMProvider](#ssmprovider) + - [Fetching parameters](#fetching-parameters) + - [SecretsProvider](#secretsprovider) + - [DynamoDBProvider](#dynamodbprovider) + - [AppConfigProvider](#appconfigprovider) - [Contribute](#contribute) - [Roadmap](#roadmap) - [Connect](#connect) @@ -29,47 +26,185 @@ You can use the library in both TypeScript and JavaScript code bases. - [Credits](#credits) - [License](#license) -## Features +## Intro + +The Parameters utility provides high-level functions to retrieve one or multiple parameter values from [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html), [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html), [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html), [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html), or your own parameter store. + +## Key features + +* Retrieve one or multiple parameters from the underlying provider +* Cache parameter values for a given amount of time (defaults to 5 seconds) +* Transform parameter values from JSON or base64 encoded strings +* Bring Your Own Parameter Store Provider + +## Usage + +### SSMProvider + +To get started, install the library and the corresponding AWS SDK for JavaScript v3: + +```sh +npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm +``` + +Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the [actions detailed](https://docs.powertools.aws.dev/lambda-typescript/1.9.0/utilities/parameters/#iam-permissions) in the documentation of the utility. + +#### Fetching parameters + +You can retrieve a single parameter using the `getParameter` high-level function. + +```ts +import { getParameter } from '@aws-lambda-powertools/parameters/ssm'; + +export const handler = async (): Promise => { + // Retrieve a single parameter + const parameter = await getParameter('/my/parameter'); + console.log(parameter); +}; +``` + +For multiple parameters, you can use `getParameters` to recursively fetch all parameters under a path: + +```ts +import { getParameters } from '@aws-lambda-powertools/parameters/ssm'; + +export const handler = async (): Promise => { + /** + * 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}`); + } +}; +``` + +To fetch disctinct parameters using their full name, you can use the `getParametersByName` function: + +```ts +import { Transform } from '@aws-lambda-powertools/parameters'; +import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm'; +import type { SSMGetParametersByNameOptions } from '@aws-lambda-powertools/parameters/ssm/types'; + +const props: Record = { + '/develop/service/commons/telemetry/config': { + maxAge: 300, + transform: 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 => { + // 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}`); + } +}; +``` + +Check the [docs](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#fetching-parameters) for more examples, and [the advanced section](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#advanced) for details about caching, transforms, customizing the underlying SDK, and more. + +### SecretsProvider + +To get started, install the library and the corresponding AWS SDK for JavaScript v3: + +```sh +npm install @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager +``` + +Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the [actions detailed](https://docs.powertools.aws.dev/lambda-typescript/1.9.0/utilities/parameters/#iam-permissions) in the documentation of the utility. + +You can fetch secrets stored in Secrets Manager using the `getSecret` function: + +```ts +import { getSecret } from '@aws-lambda-powertools/parameters/secrets'; -* **[Tracer](https://docs.powertools.aws.dev/lambda-typescript/latest/core/tracer/)** - Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions -* **[Logger](https://docs.powertools.aws.dev/lambda-typescript/latest/core/logger/)** - Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context -* **[Metrics](https://docs.powertools.aws.dev/lambda-typescript/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) -* **[Parameters (beta)](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/)** - High-level functions to retrieve one or more parameters from AWS SSM, Secrets Manager, AppConfig, and DynamoDB +export const handler = async (): Promise => { + // Retrieve a single secret + const secret = await getSecret('my-secret'); + console.log(secret); +}; +``` + +Check the [docs](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#fetching-secrets) for more examples, and [the advanced section](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#advanced) for details about caching, transforms, customizing the underlying SDK, and more. + +### DynamoDBProvider + +To get started, install the library and the corresponding AWS SDK for JavaScript v3: + +```sh +npm install @aws-lambda-powertools/parameters @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb +``` -## Getting started +Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the [actions detailed](https://docs.powertools.aws.dev/lambda-typescript/1.9.0/utilities/parameters/#iam-permissions) in the documentation of the utility. -Find the complete project's [documentation here](https://docs.powertools.aws.dev/lambda-typescript). +You can retrieve a single parameter from DynamoDB using the `DynamoDBProvider.get()` method: -### Installation +```ts +import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb'; -The Powertools for AWS Lambda (TypeScript) utilities follow a modular approach, similar to the official [AWS SDK v3 for JavaScript](https://github.com/aws/aws-sdk-js-v3). -Each TypeScript utility is installed as standalone NPM package. +const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' }); -Install all three core utilities at once with this single command: +export const handler = async (): Promise => { + // Retrieve a value from DynamoDB + const value = await dynamoDBProvider.get('my-parameter'); + console.log(value); +}; +``` -```shell -npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics +For retrieving multiple parameters, you can use the `DynamoDBProvider.getMultiple()` method instead: + +```ts +import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb'; + +const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' }); + +export const handler = async (): Promise => { + /** + * 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}`); + } +}; ``` -Or refer to the installation guide of each utility: +Check the [docs](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#fetching-secrets) for more examples, and [the advanced section](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#advanced) for details about caching, transforms, customizing the underlying SDK, and more. -👉 [Installation guide for the **Tracer** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/core/tracer#getting-started) -👉 [Installation guide for the **Logger** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/core/logger#getting-started) +### AppConfigProvider -👉 [Installation guide for the **Metrics** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/core/metrics#getting-started) +To get started, install the library and the corresponding AWS SDK for JavaScript v3: -👉 [Installation guide for the **Parameters** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#getting-started) +```sh +npm install @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata +``` -### Examples +Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the [actions detailed](https://docs.powertools.aws.dev/lambda-typescript/1.9.0/utilities/parameters/#iam-permissions) in the documentation of the utility. -* [CDK](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/cdk) -* [SAM](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/sam) +You can fetch application configurations in AWS AppConfig using the `getAppConfig` function: -### Serverless TypeScript Demo application +```ts +import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig'; + +export const handler = async (): Promise => { + // Retrieve a configuration, latest version + const config = await getAppConfig('my-configuration', { + environment: 'my-env', + application: 'my-app', + }); + console.log(config); +}; +``` -The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Powertools for AWS Lambda (TypeScript). -You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo). +Check the [docs](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#fetching-app-configurations) for more examples, and [the advanced section](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#advanced) for details about caching, transforms, customizing the underlying SDK, and more. ## Contribute @@ -77,7 +212,7 @@ If you are interested in contributing to this project, please refer to our [Cont ## Roadmap -The roadmap of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand. +[The roadmap](https://docs.powertools.aws.dev/lambda-typescript/latest/roadmap/) of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand. Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/aws-powertools/powertools-lambda-typescript/issues), or [creating new ones](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), in this GitHub repository. ## Connect From 149936da3f89a2268d1215387338bb1c69b02135 Mon Sep 17 00:00:00 2001 From: Andrea Amorosi Date: Thu, 22 Jun 2023 16:11:09 +0000 Subject: [PATCH 2/2] docs: fix typos in dosc --- docs/snippets/parameters/getParametersByName.ts | 7 ++++--- .../parameters/getParametersByNameGracefulErrorHandling.ts | 4 ++-- docs/utilities/parameters.md | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/snippets/parameters/getParametersByName.ts b/docs/snippets/parameters/getParametersByName.ts index 17679aedfb..fb65cb8d9a 100644 --- a/docs/snippets/parameters/getParametersByName.ts +++ b/docs/snippets/parameters/getParametersByName.ts @@ -1,10 +1,11 @@ +import { Transform } from '@aws-lambda-powertools/parameters'; import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm'; -import type { SSMGetParametersByNameOptionsInterface } from '@aws-lambda-powertools/parameters/ssm'; +import type { SSMGetParametersByNameOptions } from '@aws-lambda-powertools/parameters/ssm/types'; -const props: Record = { +const props: Record = { '/develop/service/commons/telemetry/config': { maxAge: 300, - transform: 'json', + transform: Transform.JSON, }, '/no_cache_param': { maxAge: 0 }, '/develop/service/payment/api/capture/url': {}, // When empty or undefined, it uses default values diff --git a/docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts b/docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts index a44a4e1db8..ecafab2288 100644 --- a/docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts +++ b/docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts @@ -1,7 +1,7 @@ import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm'; -import type { SSMGetParametersByNameOptionsInterface } from '@aws-lambda-powertools/parameters/ssm'; +import type { SSMGetParametersByNameOptions } from '@aws-lambda-powertools/parameters/ssm/types'; -const props: Record = { +const props: Record = { '/develop/service/commons/telemetry/config': { maxAge: 300, transform: 'json', diff --git a/docs/utilities/parameters.md b/docs/utilities/parameters.md index e312c9aed9..79a3fb2cfe 100644 --- a/docs/utilities/parameters.md +++ b/docs/utilities/parameters.md @@ -107,7 +107,7 @@ For multiple parameters, you can use either: ### Fetching secrets -You can fetch secrets stored in Secrets Manager using `getSecrets`. +You can fetch secrets stored in Secrets Manager using `getSecret`. ```typescript hl_lines="1 5" title="Fetching secrets" --8<-- "docs/snippets/parameters/getSecret.ts"