docs: add parser example for built-in extension using transform and pipe

[am29d]

Summary

This PR add an example how to extend a built-in schema with transform and pipe zod functions. This allows more complex transformations and schema chaining.

I have removed the missing examples in api-gateway.md, otherwise you can't build docs.

Changes

Please provide a summary of what's being changed

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

Issue number: closes #2891

---

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]

Great addition to the docs!

I think we should also add this helper to our utility and export it, so that customers can just use it right away and have less boilerplate code.

For example, we could create a new file under packages/parser/src/helpers.ts and add a new schema helper like:

import { z, type ZodSchema } from 'zod';

const JSONStringified = (schema: ZodSchema) =>
    z
      .string()
      .transform((str, ctx) => {
        try {
          return JSON.parse(str);
        } catch (err) {
          ctx.addIssue({
            code: 'custom',
            message: 'Invalid JSON',
          });
        }
      })
      .pipe(schema);

export { JSONStringified };

so that later, customers could import it in their code and use it like:

import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';
import { APIGatewayProxyEventSchema } from '@aws-lambda-powertools/parser/schemas/api-gateway';

const orderSchema = z.object({
  orderId: z.number(),
  order: z.object({
    amount: z.number()
  })
});

const orderEventSchema = APIGatewayProxyEventSchema.extend({
  body: JSONStringified(orderSchema)
});

Putting myself into this situation, I would find it very useful to do this rather than going back to the docs every time, also in the future we could add more of these helpers if they come up. But for now at least we have it documented!

I leave it to you if you want to do it now, or open an issue so that someone can pick it up before the next release.

[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 SonarCloud

[am29d]

You are right, having a small helper function is much better than pointing to the docs. I will create a separate issue for that

[am29d]

Closing in favour of new helper function and docs.