feat(parser): implement safeParse option

[am29d]

Description of your changes

This PR implements safeParse option for decorator and middy middleware. The safeParse is necessary to allow users to have a catch mechanism and recover from any parsing errors manually. The option improves the DX compared to manual parsing, even with provided envelopes and schemas. Here is the difference.

With the new options the example code will be:

const TestSchema = z.object({
   name: z.string(),
   age: z.string()
});

type TestEvent = z.infer<typeof TestSchema>;

@parser({ schema: TestSchema, envelope: EventBridgeEnvelope, safeParse: true })
public async handler(event: ParsedResult<EventBridgeEvent, TestEvent>,  _context: Context): Promise<unknown> {
  if(event.success) {
     event.data: TestEvent .... // event is parsed and is a TestEvent type derived from TestSchema
  } else {
    event.error // inspect error, log it, add metric
    event.originalEvent: EventBridgeEvent // this is the structure of the original event
  }
}

The based on the parse outcome the event object will be changed to ParsedResult with the structure:

export type ParsedResultSuccess<Output> = {
  success: true;
  data: Output;
};

export type ParsedResultError<Input> = {
  success: false;
  error: ZodError | Error;
  originalEvent: Input;
};

export type ParsedResult<Input = unknown, Output = unknown> =
  | ParsedResultSuccess<Output>
  | ParsedResultError<Input>

In case of success we return data, otherwise error and originalEvent, which allows user to anything they want for troubleshooting, observability and recovery. The Input and Output parameters are optional and should provide better DX during development, so TS understand what to expect.

The implementation became more complex than expected, which is a signal that Powertools takes care of complexity, but also a smell that there might be a better solution and we need to simplify in the future. I have explored one approach but hit few blockers.

You will notices that we often unwrap the inner part of the event, the actual payload we are interested in. It looks simple for API gateway events where we only have one level, the body. With more nested fields, arrays and additional transformations like decompression, json parse, base64 encoding, the chain becomes more complex and we have to do more manual work.

This leads to an assumption, that we could extend the built-in schema in the envelope and let the parse do the jobs, so we don't need to, for instance, here is an example of a potential ApiGatewayEnvelope

export class ApiGatewayEnvelope extends Envelope {
  public static parse<T extends ZodSchema>(
    data: unknown,
    schema: T
  ): z.infer<T> {
    const customisedParsedEnvelope = APIGatewayProxyEventSchema.extend({
      body: schema,
    });
    
    return customisedParsedEnvelope.parse(data);
}

It does look much simpler, especially if we apply it any other schema with arrays, we don't have to loop through the events and call the parser for each of them.

But there is a huge limitation with many cases, which does not allow us to uniformly apply this solution. In case of deeply nested events with more than one level we have to transform the payload and apply the parser afterwards, i.e. decompress bytes to string -> parse string to object -> apply parser schema. Zod does not provide a capability where we can apply transformation before parsing, only afterwards.

There might be an option to do it in zod, which I am not aware of yet.

While it might look like this could potentially impact performance, it does not change the underlying complexity and runtime overhead customers would have if they used zod on their own. We only provide built-in schemas and decorators to improve the DX.

Related issues, RFCs

Issue number: closes #2204

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.

[dreamorosi]

Left some suggestions/comments almost exclusively on types/imports and documentation.

I really like the implementation and think this will add much value to users.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarCloud

[dreamorosi]

Great work on this PR, really like how this is going!