Skip to content

Commit 21013f5

Browse files
dreamorosidreamorosi
authored
docs(parameters): refresh README for utility with usage examples (#1547)
* docs(parameters): refresh README file with usage examples * docs: fix typos in dosc
1 parent 67f5f14 commit 21013f5

File tree

4 files changed

+180
-44
lines changed

4 files changed

+180
-44
lines changed

Diff for: ‎docs/snippets/parameters/getParametersByName.ts

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1+
import { Transform } from '@aws-lambda-powertools/parameters';
12
import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
2-
import type { SSMGetParametersByNameOptionsInterface } from '@aws-lambda-powertools/parameters/ssm';
3+
import type { SSMGetParametersByNameOptions } from '@aws-lambda-powertools/parameters/ssm/types';
34

4-
const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
5+
const props: Record<string, SSMGetParametersByNameOptions> = {
56
'/develop/service/commons/telemetry/config': {
67
maxAge: 300,
7-
transform: 'json',
8+
transform: Transform.JSON,
89
},
910
'/no_cache_param': { maxAge: 0 },
1011
'/develop/service/payment/api/capture/url': {}, // When empty or undefined, it uses default values

Diff for: ‎docs/snippets/parameters/getParametersByNameGracefulErrorHandling.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
2-
import type { SSMGetParametersByNameOptionsInterface } from '@aws-lambda-powertools/parameters/ssm';
2+
import type { SSMGetParametersByNameOptions } from '@aws-lambda-powertools/parameters/ssm/types';
33

4-
const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
4+
const props: Record<string, SSMGetParametersByNameOptions> = {
55
'/develop/service/commons/telemetry/config': {
66
maxAge: 300,
77
transform: 'json',

Diff for: ‎docs/utilities/parameters.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ For multiple parameters, you can use either:
107107

108108
### Fetching secrets
109109

110-
You can fetch secrets stored in Secrets Manager using `getSecrets`.
110+
You can fetch secrets stored in Secrets Manager using `getSecret`.
111111

112112
```typescript hl_lines="1 5" title="Fetching secrets"
113113
--8<-- "docs/snippets/parameters/getSecret.ts"

Diff for: ‎packages/parameters/README.md

+173-38
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,16 @@
66

77
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).
88

9-
You can use the library in both TypeScript and JavaScript code bases.
10-
11-
> 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/).
12-
13-
**[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)**
14-
15-
## Table of contents <!-- omit in toc -->
16-
17-
- [Features](#features)
18-
- [Getting started](#getting-started)
19-
- [Installation](#installation)
20-
- [Examples](#examples)
21-
- [Serverless TypeScript Demo application](#serverless-typescript-demo-application)
9+
You can use the package in both TypeScript and JavaScript code bases.
10+
11+
- [Intro](#intro)
12+
- [Key features](#key-features)
13+
- [Usage](#usage)
14+
- [SSMProvider](#ssmprovider)
15+
- [Fetching parameters](#fetching-parameters)
16+
- [SecretsProvider](#secretsprovider)
17+
- [DynamoDBProvider](#dynamodbprovider)
18+
- [AppConfigProvider](#appconfigprovider)
2219
- [Contribute](#contribute)
2320
- [Roadmap](#roadmap)
2421
- [Connect](#connect)
@@ -29,55 +26,193 @@ You can use the library in both TypeScript and JavaScript code bases.
2926
- [Credits](#credits)
3027
- [License](#license)
3128

32-
## Features
29+
## Intro
30+
31+
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.
32+
33+
## Key features
34+
35+
* Retrieve one or multiple parameters from the underlying provider
36+
* Cache parameter values for a given amount of time (defaults to 5 seconds)
37+
* Transform parameter values from JSON or base64 encoded strings
38+
* Bring Your Own Parameter Store Provider
39+
40+
## Usage
41+
42+
### SSMProvider
43+
44+
To get started, install the library and the corresponding AWS SDK for JavaScript v3:
45+
46+
```sh
47+
npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm
48+
```
49+
50+
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.
51+
52+
#### Fetching parameters
53+
54+
You can retrieve a single parameter using the `getParameter` high-level function.
55+
56+
```ts
57+
import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
58+
59+
export const handler = async (): Promise<void> => {
60+
// Retrieve a single parameter
61+
const parameter = await getParameter('/my/parameter');
62+
console.log(parameter);
63+
};
64+
```
65+
66+
For multiple parameters, you can use `getParameters` to recursively fetch all parameters under a path:
67+
68+
```ts
69+
import { getParameters } from '@aws-lambda-powertools/parameters/ssm';
70+
71+
export const handler = async (): Promise<void> => {
72+
/**
73+
* Retrieve multiple parameters from a path prefix recursively.
74+
* This returns an object with the parameter name as key
75+
*/
76+
const parameters = await getParameters('/my/path/prefix');
77+
for (const [key, value] of Object.entries(parameters || {})) {
78+
console.log(`${key}: ${value}`);
79+
}
80+
};
81+
```
82+
83+
To fetch disctinct parameters using their full name, you can use the `getParametersByName` function:
84+
85+
```ts
86+
import { Transform } from '@aws-lambda-powertools/parameters';
87+
import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
88+
import type { SSMGetParametersByNameOptions } from '@aws-lambda-powertools/parameters/ssm/types';
89+
90+
const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
91+
'/develop/service/commons/telemetry/config': {
92+
maxAge: 300,
93+
transform: Transform.JSON,
94+
},
95+
'/no_cache_param': { maxAge: 0 },
96+
'/develop/service/payment/api/capture/url': {}, // When empty or undefined, it uses default values
97+
};
98+
99+
export const handler = async (): Promise<void> => {
100+
// This returns an object with the parameter name as key
101+
const parameters = await getParametersByName(props, { maxAge: 60 });
102+
for (const [key, value] of Object.entries(parameters)) {
103+
console.log(`${key}: ${value}`);
104+
}
105+
};
106+
```
107+
108+
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.
109+
110+
### SecretsProvider
111+
112+
To get started, install the library and the corresponding AWS SDK for JavaScript v3:
113+
114+
```sh
115+
npm install @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager
116+
```
117+
118+
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.
119+
120+
You can fetch secrets stored in Secrets Manager using the `getSecret` function:
121+
122+
```ts
123+
import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
33124

34-
* **[Tracer](https://docs.powertools.aws.dev/lambda-typescript/latest/core/tracer/)** - Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
35-
* **[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
36-
* **[Metrics](https://docs.powertools.aws.dev/lambda-typescript/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
37-
* **[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
125+
export const handler = async (): Promise<void> => {
126+
// Retrieve a single secret
127+
const secret = await getSecret('my-secret');
128+
console.log(secret);
129+
};
130+
```
131+
132+
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.
133+
134+
### DynamoDBProvider
135+
136+
To get started, install the library and the corresponding AWS SDK for JavaScript v3:
137+
138+
```sh
139+
npm install @aws-lambda-powertools/parameters @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb
140+
```
38141

39-
## Getting started
142+
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.
40143

41-
Find the complete project's [documentation here](https://docs.powertools.aws.dev/lambda-typescript).
144+
You can retrieve a single parameter from DynamoDB using the `DynamoDBProvider.get()` method:
42145

43-
### Installation
146+
```ts
147+
import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
44148

45-
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).
46-
Each TypeScript utility is installed as standalone NPM package.
149+
const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' });
47150

48-
Install all three core utilities at once with this single command:
151+
export const handler = async (): Promise<void> => {
152+
// Retrieve a value from DynamoDB
153+
const value = await dynamoDBProvider.get('my-parameter');
154+
console.log(value);
155+
};
156+
```
49157

50-
```shell
51-
npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
158+
For retrieving multiple parameters, you can use the `DynamoDBProvider.getMultiple()` method instead:
159+
160+
```ts
161+
import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';
162+
163+
const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' });
164+
165+
export const handler = async (): Promise<void> => {
166+
/**
167+
* Retrieve multiple values by performing a Query on the DynamoDB table.
168+
* This returns a dict with the sort key attribute as dict key.
169+
*/
170+
const values = await dynamoDBProvider.getMultiple('my-hash-key');
171+
for (const [key, value] of Object.entries(values || {})) {
172+
// key: param-a
173+
// value: my-value-a
174+
console.log(`${key}: ${value}`);
175+
}
176+
};
52177
```
53178

54-
Or refer to the installation guide of each utility:
179+
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.
55180

56-
👉 [Installation guide for the **Tracer** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/core/tracer#getting-started)
57181

58-
👉 [Installation guide for the **Logger** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/core/logger#getting-started)
182+
### AppConfigProvider
59183

60-
👉 [Installation guide for the **Metrics** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/core/metrics#getting-started)
184+
To get started, install the library and the corresponding AWS SDK for JavaScript v3:
61185

62-
👉 [Installation guide for the **Parameters** utility](https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/#getting-started)
186+
```sh
187+
npm install @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata
188+
```
63189

64-
### Examples
190+
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.
65191

66-
* [CDK](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/cdk)
67-
* [SAM](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/sam)
192+
You can fetch application configurations in AWS AppConfig using the `getAppConfig` function:
68193

69-
### Serverless TypeScript Demo application
194+
```ts
195+
import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
196+
197+
export const handler = async (): Promise<void> => {
198+
// Retrieve a configuration, latest version
199+
const config = await getAppConfig('my-configuration', {
200+
environment: 'my-env',
201+
application: 'my-app',
202+
});
203+
console.log(config);
204+
};
205+
```
70206

71-
The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Powertools for AWS Lambda (TypeScript).
72-
You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo).
207+
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.
73208

74209
## Contribute
75210

76211
If you are interested in contributing to this project, please refer to our [Contributing Guidelines](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md).
77212

78213
## Roadmap
79214

80-
The roadmap of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand.
215+
[The roadmap](https://docs.powertools.aws.dev/lambda-typescript/latest/roadmap/) of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand.
81216
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.
82217

83218
## Connect

0 commit comments

Comments
 (0)