feat(jmespath): add JMESPath utility

[dreamorosi]

Description of your changes

This PR introduces a new Powertools utility for JMESPath which will be published under @aws-lambda-powertools/jmespath.

The utility is primarily aimed at being a dependency of the Idempotency utility but can be used as standalone as well as in future utilities that revolve around JSON like the Validation utility (#508).

As discussed in one of the linked issues (#1645) the official JMESPath module does not support custom functions (example in Powertools Python) and all other existing versions and forks are largely unmaintained or owned by individuals.

To tackle the concerns and limitations above, as well as providing a modern implementations fully written in TypeScript we decided to implement our own version based of the Python jmespath module which is MIT licensed.

The JMESPath specification offers a compliance test suite that is used by all libraries who want to offer spec-compliance, the utility we are introducing in this PR adopts that same suite and thus can be considered fully spec compliant.

In addition to the utility and corresponding documentation, this PR also introduces a new helper function that allows to extract data from envelopes when using JSON. Together with this, it introduces also a series of envelopes from common data sources similar to what found in Powertools Python.

import {
  extractDataFromEnvelope,
  SQS,
} from '@aws-lambda-powertools/jmespath/envelopes';
import { Logger } from '@aws-lambda-powertools/logger';
import type { SQSEvent } from 'aws-lambda';

const logger = new Logger();

type MessageBody = {
  customerId: string;
};

export const handler = async (event: SQSEvent): Promise<void> => {
  const records = extractDataFromEnvelope<Array<MessageBody>>(event, SQS);
  for (const record of records) {
    // records is now a list containing the deserialized body of each message
    const { customerId } = record;
    logger.appendKeys({ customerId });
  }
};

Note that while there are similarities with the Parser utility being implemented in parallel with this utility, the main difference is the way the problem is approached. While the Parser utility uses Zod to validate and parse a payload using Zod schemas, the extractDataFromEnvelope() function and its envelopes is instead used to simply extract a subset of data from a JSON payload while also not applying any kind of validation.

Together with these utilities we also provide some custom JMESPath functions that complement the existing JMESPath built-in functions. Using these functions customers can reach into encoded data structures within their JSON payload.

For example, when dealing with an event coming to API Gateway or SQS, the body of the message is a stringified version of a JSON. To access it customers have to apply their own parsing, but with these custom functions they do so within the same JMESPath expression, and potentially even extract data from within the parsed object.

import type { APIGatewayEvent } from 'aws-lambda';
import { randomUUID } from 'node:crypto';
import {
  makeIdempotent,
  IdempotencyConfig,
} from '@aws-lambda-powertools/idempotency';
import { DynamoDBPersistenceLayer } from '@aws-lambda-powertools/idempotency/dynamodb';

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

export const handler = makeIdempotent(
  async (event: APIGatewayEvent) => {
    const body = JSON.parse(event.body || '{}');
    const { user, productId } = body;

    const result = await createSubscriptionPayment(user, productId);

    return {
      statusCode: 200,
      body: JSON.stringify({
        paymentId: result.id,
        message: 'success',
      }),
    };
  },
  {
    persistenceStore,
    config: new IdempotencyConfig({
      eventKeyJmesPath: 'powertools_json(body)',
    }),
  }
);

declare function createSubscriptionPayment(
  user: string,
  productId: string
): Promise<{ id: string; message: string }>;

Finally, to support this utility I have made some small addition to the commons utility. Some of these, like the utilities to parse to and from base64 encoding can and will be adopted by the Parameters utility as well, allowing us to drop a dependency on a deprecated AWS SDK package.

This utility will be adopted by the Idempotency utility in a future PR. Some of the features mentioned above will allow customers to select parts of payloads to be used for idempotency that were not accessible before, like the SQS example mentioned above.

Related issues, RFCs

Issue number: #1645

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
27.9% Duplication on New Code

See analysis details on SonarCloud

[dreamorosi]

I closed this PR in favor of: #2187, #2189, #2192, #2212, #2213, #2214, #2259, #2264, #2266, #2265, #2271