Skip to content

Releases: aws-powertools/powertools-lambda-typescript

v1.14.2

03 Nov 11:16
@github-actions github-actions
v1.14.2
1944156
Compare
Choose a tag to compare
v1.14.2

Summary

In this patch release we are fixing a bug that affected the Metrics utility.

When using the utility you can set default dimensions that will be added to every metric emitted by your application.

carbon

Before this release, when setting a dimension using an existing key, the emitted EMF blob would contain duplicate keys. This release fixes the bug and makes sure that keys are deduplicated correctly.

Additionally we have also improved our Gitpod configuration which should make it easier for contributors to get up and running.

Changes

📜 Documentation updates

  • docs(maintenance): add clarification about async decorators (#1778) by @dreamorosi

🐛 Bug and hot fixes

  • fix(metrics): deduplicate dimensions when serialising (#1780) by @am29d

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi

Contributors

am29d and dreamorosi
Loading

v1.14.1

01 Nov 01:19
@github-actions github-actions
v1.14.1
1805a34
Compare
Choose a tag to compare
v1.14.1

Summary

In this patch release we have improved the logic around creating AWS SDK clients in the Parameters & Idempotency utility, as well as improving our documentation to include sections dedicated to how to contribute and how we manage the project.

Idempotency & Parameters

Both the Idempotency utility and the Parameters one allow you to bring your own AWS SDK to interact with AWS APIs. This is useful when there's a need to customize the SDK client or share an existing one already used in other parts of the function. Prior to this release, both utilities were instantiating a new AWS SDK client by default, only to then replace it with the customer provided one. In these cases, we were needlessly instantiating a client leading to wasted cycles.

Starting from this version both utilities include a refactored logic that instantiate a new SDK client only when a valid one is not provided by the customer. This way customers bringing their own client don't have to pay the performance hit of instantiating multiple clients.

Documentation

As part of this release we have also added a new section to our documentation dedicated to explain our processes. The section includes our roadmap, the maintainers' handbook, and a few sections dedicated to contributing. These sections are designed to be a companion to the contributing guidelines, which we also refreshed to make them more focused, and provide a deeper look around specific areas like setting your development environment, finding you first contribution, project's conventions, and testing.

Changes

  • chore(idempotency): refactor aws sdk init logic (#1768) by @dreamorosi
  • chore(commons): update Powertools UA middleware detection (#1762) by @dreamorosi
  • chore(parameters): refactor provider constructor to init client as needed (#1757) by @dreamorosi
  • chore(ci): add workflow to publish v2 docs on merge (#1756) by @dreamorosi
  • chore(docs): add invisible unicode char to decorator docstrings (#1755) by @dreamorosi
  • chore(maintenance): set removeComments to false in tsconfig.json (#1754) by @dreamorosi
  • chore(tracer): update warning to better format segment name (#1750) by @dreamorosi
  • chore(ci): update v2 release workflow (#1745) by @dreamorosi

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@dreamorosi

Contributors

dreamorosi and dependabot
Loading

v1.14.0

29 Sep 07:27
@github-actions github-actions
v1.14.0
1dc1805
Compare
Choose a tag to compare
v1.14.0

Summary

This release brings all the generally available utilities to the Lambda Layers, improves the Idempotency utility with the addition of a new @idempotent class method decorator, and makes Tracer more reliable.

Lambda Layers

Starting from version 21, which corresponds to this release, of our Lambda Layer includes the Idempotency, Parameters, and Batch Processing utilities. The layer comes with its own reduced copy of AWS SDK v3 for JavaScript clients so you can easily attach it to Lambda functions running on Node.js 16 without having to bundle the SDK.

The layers are available in most commercial AWS Regions, go here to learn more about how to use them and find the ARN for your region.

Idempotency

If you use decorators you can now make your class methods idempotent thanks to the new @idempotent decorator.

idempotent

You can use the decorator on your Lambda handler, like shown in the image above, or on any method that returns a response. This is useful when you want to make a specific part of your code idempotent, for example when your Lambda handler performs multiple side effects and you only want to make part of it safe to retry.

Tracer

When segments generated by your code are about to be sent to the AWS X-Ray daemon, the AWS X-Ray SDK for Node.js serializes them into a JSON string. If the segment contains exotic objects like BigInt, Set, or Map in the metadata the serialization can throw an error because the native JSON.stringify() function doesn't know how to handle these objects.

To guard against this type of runtime errors we have wrapped within try/catch logic the branches of code in Tracer where this issue could happen. Now, when an error gets thrown during the serialization of a segment within Tracer, we will catch it and log a warning instead.

We are also working with the X-Ray team to add a replacer function to the serialization logic directly in the X-Ray SDK so that the issue can be better mitigated.

Acknowledgements

Congratulations to @HaaLeo and @KhurramJalil for having your first contribution to the project, thank you for helping make Powertools better for everyone 🎉

Note
We have officially started working on the next major version of Powertools for AWS (TypeScript) 🔥 We have published a Request For Comment (RFC) that details most of the changes that we have planned and in the coming weeks we'll work on an upgrade guide. We would love to hear what you think about our plan and hear any concern you might have.

Changes

  • chore(ci): create v2 alpha release workflow (#1719) by @dreamorosi
  • chore(layers): add Idempotency, Batch, and Parameters to layer (#1712) by @am29d

🌟New features and non-breaking changes

  • feat(idempotency): add idempotency decorator (#1723) by @am29d
  • feat(tracer): add try/catch logic to decorator and middleware close (#1716) by @dreamorosi
  • feat(layers): add arm64 to integration test matrix (#1720) by @dreamorosi

🌟 Minor Changes

📜 Documentation updates

  • docs(idempotency): address comments (#1724) by @am29d
  • feat(idempotency): add idempotency decorator (#1723) by @am29d
  • docs: typo for serverless framework (#1701) by @HaaLeo

🔧 Maintenance

This release was made possible by the following contributors:

@HaaLeo, @KhurramJalil, @am29d, @dreamorosi

Contributors

am29d, dreamorosi, and 2 other contributors
Loading

v1.13.1

21 Sep 11:18
@github-actions github-actions
v1.13.1
1c7a169
Compare
Choose a tag to compare
v1.13.1

Summary

In this minor release we have removed the upper bound for middy/core 4.x in our peerDependency. We only support middy 3.x and in the last release we added peerDependency section to make it explicit. But some of Powertools user had already middy 4.x in their dependencies and the recent change broke their builds. We have now removed the upper bound to give you the freedom to use middy/core 4.x though we do not support it yet. With more recent requests we will address this issue soon to bring middy 4.x support earlier than we anticipated.

Changes

  • chore: bump version in commons for user agent (#1698) by @am29d
  • chore(tracer): mark createTracer helper function as deprecated (#1692) by @dreamorosi

📜 Documentation updates

  • docs(tracer): update annotation & metadata docs to include full code (#1704) by @dreamorosi
  • docs: remove beta warning from batch and idempotency readme (#1696) by @am29d
  • docs: upgrade mkdocs to fix dark mode custom highlight style (#1695) by @am29d

🐛 Bug and hot fixes

🔧 Maintenance

  • fix(maintenance): remove upper peer dependency Middy (#1705) by @dreamorosi
  • docs: remove beta warning from batch and idempotency readme (#1696) by @am29d

This release was made possible by the following contributors:

@am29d, @dreamorosi, Alexander Melnyk, Alexander Schueren and Release bot[bot]

Contributors

am29d and dreamorosi
Loading

v1.13.0

18 Sep 16:27
@github-actions github-actions
v1.13.0
ed969f3
Compare
Choose a tag to compare
v1.13.0

Summary

In this release we are excited to announce the General Availability of two utilities: Idempotency and Batch.

Batch

Warning
Breaking Change

We have introduced a breaking change in the batch utility. We have initially followed the python implementation for this utility and after multiple reviews we have realised that the choice of async/sync processors is different in NodeJS ecosystem compared to Python. Async functions are often the preferred choice of synchronous functions and thus we renamed AsyncBatchProcessor to BatchProcessor, making it also a default choice. When you need to process a batch synchronously (i.e. SQS Fifo) use the explicit BatchProcessorSync processor. We have added a dedicated section in the documentation to clarify the implications and when to pick the right processor.

Idempotency

We have improved the docs on the customer feedback we have received over the month. You have now more details how to implement your own persistence store. In addition, Batch and Idempotency are often used together, so we added a section how to integrate Batch into Idempotency, here is an example:

import {
  BatchProcessor,
  EventType,
  processPartialResponse,
} from '@aws-lambda-powertools/batch';
import type {
  Context,
  SQSBatchResponse,
  SQSEvent,
  SQSRecord,
} from 'aws-lambda';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
import {
  IdempotencyConfig,
  makeIdempotent,
} from '@aws-lambda-powertools/idempotency';

const processor = new BatchProcessor(EventType.SQS);

const dynamoDBPersistence = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTable',
});
const idempotencyConfig = new IdempotencyConfig({
  eventKeyJmesPath: 'messageId',
});

const processIdempotently = makeIdempotent(
  async (_record: SQSRecord) => {
    // process your event
  },
  {
    persistenceStore: dynamoDBPersistence,
    config: idempotencyConfig,
  }
);

export const handler = async (
  event: SQSEvent,
  context: Context
): Promise<SQSBatchResponse> => {
  idempotencyConfig.registerLambdaContext(context);

  return processPartialResponse(event, processIdempotently, processor, {
    context,
  });
};

Layers

Welcome TelAviv! We have added il-central-1 to our regions and the layer is now available in this region. Of course, we bumped the version to the same number, so you only have to change the region in your ARN:

arn:aws:lambda:il-central-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:19

Acknowledgements

A big thanks again to @erikayao93 for the work on the Batch Processing utility that goes GA in this release, we appreciate your work 🎉

Changes

🌟New features and breaking changes

  • feat(batch): rename AsyncBatchProcessor to default BatchProcessor (#1683) by @am29d

🌟 Minor Changes

📜 Documentation updates

  • feat(batch): rename AsyncBatchProcessor to default BatchProcessor (#1683) by @am29d
  • chore(maintenance): bump dependencies + apply peerDependencies (#1685) by @dreamorosi
  • docs(idempotency): bring your own persistent store (#1681) by @dreamorosi
  • improv(idempotency): expose record status & expiry config + make DynamoDB Client optional (#1679) by @dreamorosi
  • docs(idempotency): add batch integration to idempotency docs (#1676) by @am29d
  • docs(batch): add section on how to trace batch processing (#1673) by @dreamorosi
  • chore(maintenance): adopt TypeScript 5.x (#1672) by @dreamorosi
  • chore(internal): revisit tsconfig files (#1667) by @dreamorosi
  • chore(docs): improve idempotency documentation (#1655) by @am29d
  • chore(ci): add il-central-1 to layer deployment pipeline (#1656) by @am29d
  • chore(docs): added tecRacer GmbH & Co. KG to project supporters (#1653) by @dreamorosi
  • docs(batch): added flow charts (#1640) by @dreamorosi
  • chore(docs): update roadmap, labels, and issue templates (#1632) by @dreamorosi

🐛 Bug and hot fixes

  • fix(parameters): return type when options without transform is used (#1671) by @dreamorosi
  • fix(batch): Update processor to pass only context to handler (#1637) by @erikayao93

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi, @erikayao93, @sthulb and Release bot[bot]

Contributors

sthulb, am29d, and 2 other contributors
Loading

v1.12.1

25 Jul 13:20
@github-actions github-actions
v1.12.1
2aa1d88
Compare
Choose a tag to compare
v1.12.1

Summary

This release brings another new utility to Powertools for AWS Lambda (TypeScript): introducing the Batch Processing utility ✨ The release also improves the Logger utility, which can now include the cause field in error logs.

Batch Processing Beta

Warning
This utility is currently released as beta developer preview and is intended strictly for feedback and testing purposes and not for production workloads. The version and all future versions tagged with the -beta suffix should be treated as not stable. Up until before the General Availability release we might introduce significant breaking changes and improvements in response to customers feedback.

The batch processing utility handles partial failures when processing batches from Amazon SQS, Amazon Kinesis Data Streams, and Amazon DynamoDB Streams.

Key Features

  • Reports batch item failures to reduce number of retries for a record upon errors
  • Simple interface to process each batch record
  • Build your own batch processor by extending primitives

Problem Statement

When using SQS, Kinesis Data Streams, or DynamoDB Streams as a Lambda event source, your Lambda functions are triggered with a batch of messages.

If your function fails to process any message from the batch, the entire batch returns to your queue or stream. This same batch is then retried until either condition happens first: a) your Lambda function returns a successful response, b) record reaches maximum retry attempts, or c) when records expire.

With this utility, batch records are processed individually – only messages that failed to be processed return to the queue or stream for a further retry.

Getting Started

To get started, install the utility by running:

npm install @aws-lambda-powertools/batch

Then, define a record handler function:

record handler

This function will be called by the Batch Processing utility for each record in the batch. If the function throws an error, the record will be marked as failed and reported once the main handler returns.

Record handlers can be both synchronous and asynchronous, in the latter case the utility will process all the records of your batch in concurrently. To learn more about when it's safe to use async handlers, check the dedicated section in our docs.

SQS Processor

When using SQS as a Lambda event source, you can specify the EventType.SQS to process the records. The response will be a SQSBatchResponse which contains a list of items that failed to be processed.

sqs processing

To learn more about this mode, as well as how to process SQS FIFO queues, check the docs.

Kinesis Processor

When using Kinesis Data Streams as a Lambda event source, you can specify the EventType.KinesisDataStreams to process the records. The response will be a KinesisStreamBatchResponse which contains a list of items that failed to be processed.

kinesis processing

Learn more on the docs.

DynamoDB Stream Processor

When using DynamoDB Streams as a Lambda event source, you can use the BatchProcessor with the EventType.DynamoDBStreams to process the records. The response will be a DynamoDBBatchResponse which contains a list of items that failed to be processed.

dynamodb stream processing

Check the docs to learn more about this processor.

Logger

Starting from this release, when logging an error with the logger.error() method, the Logger utility will include the cause field as part of the JSON-formatted log entry:

log error cause

The cause field is available in the Error class starting from Node.js v16.9.0 and allows to specify the error that caused the one being thrown. This is useful when you are catching an error and throwing your own, but still want to preserve the original cause of the error.

Acknowledgements

Congratulations and a big thank you to @erikayao93 for the work on the new Batch Processing utility 🎉

Changes

🌟New features and non-breaking changes

📜 Documentation updates

  • docs(parameters): add parameters examples cdk and sam (#1622) by @am29d
  • feat(batch): add batch processing utility (#1625) by @dreamorosi
  • feat(batch): Implementation of base batch processing classes (#1588) by @erikayao93

🔧 Maintenance

  • docs(parameters): add parameters examples cdk and sam (#1622) by @am29d
  • chore(maintenance): bump word-wrap from 1.2.3 to 1.2.4 (#1618) by @dependabot
  • chore(ci): restore dependencies & fix e2e tests (#1615) by @dreamorosi
  • chore(maintenance): remove vm2 from package-lock.json (#1613) by @am29d
  • chore(maintenance): remove proxy-agent from dependencies (#1611) by @am29d
  • feat(batch): Implementation of base batch processing classes (#1588) by @erikayao93

This release was made possible by the following contributors:

@am29d, @dreamorosi, @erikayao93

Contributors

am29d, dreamorosi, and 2 other contributors
Loading

v1.11.1

11 Jul 15:27
@github-actions github-actions
v1.11.1
3f03c5c
Compare
Choose a tag to compare
v1.11.1

Summary

In this release we are excited to announce the developer beta for the new idempotency utility 🎉. This new utility allows you to make your functions idempotent so that multiple invocations will return the same result without side effects.

Idempotency Beta

Warning
This utility is currently released as beta developer preview and is intended strictly for feedback and testing purposes and not for production workloads. The version and all future versions tagged with the -beta suffix should be treated as not stable. Up until before the General Availability release we might introduce significant breaking changes and improvements in response to customers feedback.

Key features

  • Prevent Lambda handler from executing more than once on the same event payload during a time window
  • Ensure Lambda handler returns the same result when called with the same payload
  • Select a subset of the event as the idempotency key using JMESPath expressions
  • Set a time window in which records with the same payload should be considered duplicates
  • Expires in-progress executions if the Lambda function times out halfway through

Persistence store

Before getting started, you need to create a persistent storage layer where the idempotency utility can store its state - your lambda functions will need read and write access to it. As of now, Amazon DynamoDB is the only supported persistent storage layer, so you'll need to create a table first. Check the documentation for more information on Persistence layer. Then you configure the persistence layer with your table:

import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName', // <-- create this table before 
});

MakeIdempotent function wrapper

You can quickly start by initializing the DynamoDBPersistenceLayer class and using it with the makeIdempotent function wrapper on your Lambda handler.

import { randomUUID } from 'node:crypto';
import { makeIdempotent } from '@aws-lambda-powertools/idempotency';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
import type { Context } from 'aws-lambda';
import type { Request, Response, SubscriptionResult } from './types';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const createSubscriptionPayment = async (
  event: Request
): Promise<SubscriptionResult> => {
  // ... create payment
  return {
    id: randomUUID(),
    productId: event.productId,
  };
};

export const handler = makeIdempotent(
  async (event: Request, _context: Context): Promise<Response> => {
    try {
      const payment = await createSubscriptionPayment(event);

      return {
        paymentId: payment.id,
        message: 'success',
        statusCode: 200,
      };
    } catch (error) {
      throw new Error('Error creating payment');
    }
  },
  {
    persistenceStore,
  }
);

Middy middleware

If you are using Middy as your middleware engine, you can use the makeHandlerIdempotent middleware to make your Lambda handler idempotent.

import { randomUUID } from 'node:crypto';
import { makeHandlerIdempotent } from '@aws-lambda-powertools/idempotency/middleware';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';
import middy from '@middy/core';
import type { Context } from 'aws-lambda';
import type { Request, Response, SubscriptionResult } from './types';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const createSubscriptionPayment = async (
  event: Request
): Promise<SubscriptionResult> => {
  // ... create payment
  return {
    id: randomUUID(),
    productId: event.productId,
  };
};

export const handler = middy(
  async (event: Request, _context: Context): Promise<Response> => {
    try {
      const payment = await createSubscriptionPayment(event);

      return {
        paymentId: payment.id,
        message: 'success',
        statusCode: 200,
      };
    } catch (error) {
      throw new Error('Error creating payment');
    }
  }
).use(
  makeHandlerIdempotent({
    persistenceStore,
  })
);

Customization

Similar to the Powertools for AWS Lambda (Python) implementation we have created many options for you to customize the persistence store and the idempotency behavior, such as idempotency key, record expiration, hash function, table attributes, local cache, payload validation and more). You can also bring your own Javascript SDK v3 client or pass only client options for the utility to use. See the our documentation for more information.

Changes

  • chore(ci): fix canary deploy in ci with correct workspace name (#1601) by @am29d
  • chore(maintenance): remove parameters utility from layer bundling and layers e2e tests (#1599) by @am29d
  • chore(ci): add canary to layer deployment (#1593) by @am29d
  • chore(maintenance): avoid attaching two middlewares to ua (#1583) by @am29d
  • chore(parameters): apply UA to AWS SDK clients used by Parameters (#1577) by @am29d
  • chore(tracer): apply UA to AWS SDK clients used by Tracer (#1575) by @am29d

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(idempotency): types, docs, and makeIdempotent function wrapper (#1579) by @dreamorosi
  • fix(docs): fix alias in versions.json (#1576) by @sthulb
  • fix(ci): remove old release tag version for layer (#1570) by @am29d

🔧 Maintenance

  • chore(idempotency): mark the utility ready public beta (#1595) by @dreamorosi
  • build(internal): bump semver from 5.7.1 to 5.7.2 (#1594) by @dependabot
  • docs(idempotency): write utility docs (#1592) by @dreamorosi
  • test(idempotency): improve integration tests for utility (#1591) by @dreamorosi
  • fix(idempotency): types, docs, and makeIdempotent function wrapper (#1579) by @dreamorosi
  • chore(maintenance): add powertools to user-agent in SDK clients (#1567) by @am29d

This release was made possible by the following contributors:

@am29d, @dependabot, @dependabot[bot], @dreamorosi, @github-actions[bot], @sthulb and Release bot[bot]

Contributors

sthulb, am29d, and 2 other contributors
Loading

v1.11.0

29 Jun 15:26
@github-actions github-actions
v1.11.0
71f1892
Compare
Choose a tag to compare
v1.11.0

Summary

In this release we are excited to announce the General Availability of the Parameters utility 🎉 After almost three months of beta period we consider the utility ready for production workloads and consider the API stable.

Parameters

The Parameters utility provides high-level functions to retrieve one or multiple parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, AWS AppConfig, Amazon DynamoDB, 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
Fetching parameters from AWS SSM Parameter Store

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

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 in the documentation of the utility.

You can retrieve a single parameter using the getParameter() high-level function.

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

For multiple parameters, you can use getParameters() to recursively fetch all parameters under a path:

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

Alternatively, you can also fetch multiple parameters using their full name by using the getParametersByName() function.

Getting secrets from Amazon Secrets Manager

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

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 in the documentation of the utility.

You can fetch secrets stored in Secrets Manager using the getSecret() function:

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);
};
Fetching configs from AWS AppConfig

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata

Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.

You can fetch application configurations in AWS AppConfig using the getAppConfig() function:

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);
};
Retrieving values from Amazon DynamoDB

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.

You can retrieve a single parameter from DynamoDB using the DynamoDBProvider.get() method:

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

For retrieving multiple parameters, you can use the DynamoDBProvider.getMultiple() method instead.

Learn More

If you want to learn more, check the post we have just published on the AWS Compute Blog: Retrieving parameters and secrets with Powertools for AWS Lambda (TypeScript)

Acknowledgements

A big thank you to all the people who contributed to this utility with PRs, questions, feedback, and bug reports.

Changes

🌟New features and non-breaking changes

  • feat(idempotency): preserve original error when wrapping into IdempotencyPersistenceLayerError (#1552) by @am29d

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi, @hjgraca and Release bot[bot]

Contributors

hjgraca, am29d, and dreamorosi
Loading

v1.10.0

23 Jun 14:33
@github-actions github-actions
v1.10.0
40b1b68
Compare
Choose a tag to compare
v1.10.0

Summary

This release brings the Release Candidate (RC) for the Parameters utility as well as a bug fix for the Metrics utility and improvements to the Middy middlewares of all three core utilities. Starting from this release we are also adding provenance and publish attestation to our packages, and we have a new documentation domain.

Parameters

Note
This release of the Parameters utility is expected to be the last release before the utility goes GA (General Availability) in the next one.

In this new version we have completed the work on the input and return types of all providers. Now, when retrieving a value the utility will modify its return type based on the intersection between the transform being applied and the actual data types returned by the AWS APIs.

For example, when retrieving a Secret from Amazon Secrets Manager, the default return type would be a string or undefined in case the value is not found. When applying a json transform however, the return type can be any JSON primitive that can be parsed by the JSON.parse() function.

getSecret

To support this feature we have added new types for JSON primitives and have applied them to all the Parameters providers.

Additionally, we have also finalized the exports for the utility that should be scoped and allow you to tree-shake all the providers that you are not using and avoid shipping unnecessary code.

Metrics

Prior to this release the Metrics utility allowed to add a number of data points greater than the current limit of 100 data points set by the EMF specification.

With this release we are releasing a fix that ensures that when a new data point is added, and the limit is reached, all the stored metrics are flushed right away.

If you are using Metrics in your workloads and are dealing with a large number of datapoints, we encourage to update to the latest version of the package at your earliest convenience.

Middy middlewares

As part of this release we have fully rolled out the cleanup hooks in all the Middy middlewares offered by Powertools for AWS.

This feature is intended for those who write their own custom middlewares, and specifically for those middlewares that might need to stop the whole execution flow and return a response immediately.

In these cases, to prevent data loss for data, you should make sure to call the cleanupMiddlewares() function before returning. In doing so all Powertools core utilities will make sure to flush any data they might have stored.

This function doesn't require you to know which or how many Powertools middlewares are in the Middy stack, and in case no other middleware has registered its cleanup function it will result in a no-op.

cleanupMiddlewares

📚 Additionally, we now have a page dedicated to Powertools for AWS on the Middy documentation where you can find information about its middlewares as well as best practices for users and middleware authors.

Provenance

Starting from this release, all the npm packages under the @aws-lambda-powertools/scope are published together with publish and provenance attestations (example transparency log and scorecard on npmjs.com below).

This allows you to publicly establish that our packages was built and published by us, which can increase your supply-chain security.

image

Click here to learn more about the definition of each attestation and how the feature works.

Governance

As you might have noticed, we have moved the project to a new GitHub Organization dedicated to Powertools for AWS Lambda (new name, who this?). The migration is still ongoing behind the scenes and we'll share more in the coming weeks.

With the new name, ✨ Powertools for AWS Lambda (TypeScript) ✨, we also have a new domain for our documentation: docs.powertools.aws.dev/lambda/typescript. Links to the previous domain (and repository) should be redirected for the most part, however if you are a content creator and have links to the project, we encourage you to update them if possible.

Finally, we have updated our public roadmap and our public Project Board, together with corresponding Milestones. This should give you visibility over the areas we plan on focusing for the rest of the year.

Acknowledgements

Congratulations to @kitsunde for landing your first merged PR, and special thanks to @am29d and @sthulb for making this release possible.

Changes

🌟New features and non-breaking changes

  • feat(metrics): publish metrics when other middlewares return early (#1546) by @dreamorosi
  • feat(tracer): close & restore segments when other middlewares return (#1545) by @dreamorosi
  • feat(logger): clear state when other middlewares return early (#1544) by @dreamorosi
  • feat(parameters): review types and exports (#1528) by @dreamorosi

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(metrics): flush metrics when data points array reaches max size (#1548) by @dreamorosi
  • fix(docs/ci): change how versions and aliases are inserted into versions.json (#1549) by @sthulb
  • fix(idempotency): pass lambda context remaining time to save inprogress (#1540) by @am29d
  • fix(docs): aliases in versions.json (#1522) by @sthulb
  • fix(docs): upload versions.json (#1521) by @sthulb
  • fix: update reference in workflow (#1518) by @sthulb
  • fix(idempotency): skip persistence for optional idempotency key (#1507) by @am29d
  • fix(idempotency): record validation not using hash (#1502) by @dreamorosi
  • chore(docs): Fix docs upload to s3 (#1494) by @sthulb

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @dreamorosi, @kitsunde, @sthulb

Contributors

kitsunde, sthulb, and 3 other contributors
Loading

v1.9.0

09 Jun 17:58
@github-actions github-actions
v1.9.0
8d62a62
Compare
Choose a tag to compare
v1.9.0

Summary

This release includes the ability to modify and retrieve the log level at runtime in Logger, as well as the ability to know whether your AWS Lambda function invocation is being sampled by AWS X-Ray. The release also includes additional improvements to the types of the Parameters utility and the introduction of two deprecation notices for minor undocumented helper functions that will be removed in the next major release.

Logger

Starting with this release you can set the Logger level at runtime as well as retrieving the current level both in string (i.e. DEBUG) and numeric (i.e. 8) notations.

Prior to this version, you could only set the log level when creating a new Logger instance. There are however cases (see #1265) in which you might want to change the log level of an existing Logger instance at runtime.

To support this type of feature we have added three new methods to the Logger utility:

Set a new log level

The first one is the Logger.setLogLevel() method. This method accepts a string (both lower and uppercase) and sets the corresponding log level.

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

logger.setLogLevel('DEBUG');

If you pass invalid value, the method will throw an error.

Get current log level

The second one is Logger.getLevelName(), which returns the current log level as string:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

logger.getLevelName(); // returns "INFO"

Get current log level number value

The third, and last one, is a new class property called level, which holds the numeric value of the current log level:

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();

logger.level; // returns 12

Tracer

Thanks to @icholy's feature request and contribution we have added a new method to Tracer that allows you to know whether a specific Lambda invocation is being sampled in X-Ray or not.

The new Tracer.isTraceSampled() method reads the value of the _X_AMZN_TRACE_ID environment variable and returns a boolean value reflecting whether the function invocation is being traced or not.

You can use this value to further enrich your JSON-structured logs together with the existing Tracer.getRootXrayTraceId():

import { Logger } from '@aws-lambda-powertools/logger'; 
import { Tracer } from '@aws-lambda-powertools/tracer'; 

const tracer = new Tracer();
const logger = new Logger();

export const handler = async () => {
  try {  
    throw new Error('something went wrong');
  } catch (error) {
    logger.error('something went wrong', {
      trace_id: tracer.getRootXrayTraceId(),
      trace_sampled: tracer.isTraceSampled(),
      error,
   });

   throw error;
  }
};

Parameters

We continued the work started in the previous release and improved the return types for the Parameters utility by applying adaptive types to the SecretsProvider.

The new types use generics and modify the return type of the functions/methods based on the arguments passed to them or based on an explicitly set type.

For instance, if users pass transform: json, then we can assume that the return type should be an object (Record<K, V>). Conversely, if no transform or a binary (base64) transform is applied, the result will be a string.

import { getSecret } from '@aws-lambda-powertools/parameters/secrets';

const jsonValue = getSecret('my-secret', { transform: 'json' }); // type is `Record<string, unknown>`
const binaryValue = getSecret('my-other-secret', { transform: 'binary' }); // type is `string`

Finally, if the user doesn't specify any transform then, given that Amazon Secrets Manager is able to store both SecretString and SecretBinary data types, then we can only narrow down the return type to one of string or Uint8Array.

There are however also cases in which users might know more about the values they are retrieving than the compiler does, and for those instances this PR introduces the ability to specify the return type while using either the function or method like so:

import { getSecret } from '@aws-lambda-powertools/parameters/secrets';

const value = getSecret<number>('my-secret', { transform: 'json' });

In the example above the value constant will have type number, this is because the user has specified a type and so this will take precedence over any type-heuristic we do behind the scenes.

Deprecation Notices

We have started laying the groundwork for the next major release and as first item we have marked both the createLogger and createTracer helper functions as deprecated. Both functions were undocumented and were only used in tests, however since they were part of the exported modules we are marking them as deprecated and leaving them intact until the next major release.

If you are using them in your code, we encourage you to move to instantiating the utilities directly as we will remove these functions in the next major release:

-- import { createLogger } from '@aws-lambda-powertools/logger';
-- import { createTracer } from '@aws-lambda-powertools/tracer';
++ import { Logger } from '@aws-lambda-powertools/logger'; 
++ import { Tracer } from '@aws-lambda-powertools/tracer'; 

-- const logger = createLogger();
-- const tracer = createTracer();
++ const logger = new Logger();
++ const tracer = new Tracer();

Acknowledgements

Finally, a big thank you to both @icholy and @arnabrahman for landing their first merged PRs 🎉 🎉

Finally

Changes

🌟New features and non-breaking changes

  • feat(idempotency): idempotency middleware & types exports (#1487) by @dreamorosi
  • feat(idempotency): makeHandlerIdempotent middy middleware (#1474) by @dreamorosi
  • feat(idempotency): add package exports (#1483) by @dreamorosi
  • feat(logger): enhance log level handling (#1476) by @dreamorosi
  • feat(commons): add cleanupPowertools function (#1473) by @dreamorosi
  • feat(tracer): add isTraceSampled method (#1435) by @icholy
  • feat(idempotency): implement IdempotencyHandler (#1416) by @am29d
  • refactor(metrics): unit tests for Metrics are written to follow similar convention as Logger/Tracer (#1414) by @arnabrahman
  • feat(parameters): add adaptive types to SecretsProvider (#1411) by @dreamorosi

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@am29d, @...

Read more

Contributors

rubenfonseca, sthulb, and 6 other contributors
Loading