fix(parser): DynamoDBStream schema & envelope

[dreamorosi]

Summary

Changes

Please provide a summary of what's being changed

This PR updates the logic of the DynamoDBStreamSchema and DynamoDBStreamEnvelope built-in schemas so that they automatically handle DynamoDB attribute values for the customer and convert them to JavaScript native objects during the parsing and validation.

As part of the PR, I have also improved the error messages in the parser to include the index of the record being processed as well as the full path of the issue when parsing fails. For example, now the error would be something like:

new ParseError('Failed to parse DynamoDB Stream envelope', {
  cause: new ZodError([
    {
      code: 'invalid_type',
      expected: 'object',
      received: 'undefined',
      path: ['Records', 0, 'dynamodb'],
      message: 'Required',
    }
  ]),
})

and like this for failed parsing of Keys, NewImage, and OldImage:

new ParseError('Failed to parse DynamoDB Stream envelope', {
  cause: new ZodError([
    {
      code: 'invalid_type',
      expected: 'number',
      received: 'object',
      path: ['Records', 0, 'dynamodb', 'NewImage'],
      message: 'Expected number, received object',
    }
  ]),
})

Likewise, when parsing an envelope using safeParse, the errors can also be combined when multiple records have issues:

new ParseError('Failed to parse records at indexes 0, 1', {
    cause: new ZodError([
      {
        code: 'invalid_type',
        expected: 'string',
        received: 'undefined',
        path: ['Records', 0, 'dynamodb', 'NewImage', 'Message'],
        message: 'Required',
      },
      {
        code: 'invalid_type',
        expected: 'string',
        received: 'number',
        path: ['Records', 1, 'dynamodb', 'NewImage', 'Message'],
        message: 'Expected string, received number',
      },
    ]),
  }),
  originalEvent: event,
})

Note that in all cases the full path of the object is preserved even though we are performing multiple Zod validations under the hood.

While working on this PR, I also brought into the commons package an implementation of the unmarshall function inspired by the one in the AWS SDK. This is similar to what Powertools for AWS Lambda (Python) does, and allows us to provide this behavior without forcing an extra dependency. Our implementation also differs from the reference one in a couple minor ways since we don't have to support old Node.js versions.

This new behavior is compatible with the DynamoDBHelper introduced in the previous release. This is because in order for customers to use the helper they will have to extend & replace the schema, thus bypassing the transform introduced in this PR.

Finally, we're treating this change as a fix because this should've been the default behavior all along.

Please add the issue number below, if no issue is present the PR might get blocked and not be reviewed

Issue number: fixes #3481

---

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.

[am29d]

Great PR, thanks for the work bringing the unmarschalling into envelope and schema!

Just a minor code duplication we'd need to fix, otherwise ready to go.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[am29d]

Beautiful!