feat(validation): Add @validator decorator for JSON Schema validation

[VatsalGoel3]

Summary

Changes

Please provide a summary of what's being changed

This PR introduces a @validator method decorator that enables JSON Schema validation for both input (inbound) and output (outbound) parameters of class methods. It is built using the existing validate function and follows the Powertools for AWS Lambda (TypeScript) validation utility standards.

Key Features
✅ Validates method arguments using inbound schemas
✅ Validates method return values using outbound schemas
✅ Supports optional parameters like envelope, formats, and external references
✅ Allows custom AJV instances for extended schema validation
✅ Includes unit tests with 100% coverage

Implementation
Created validator.ts, a TypeScript decorator that validates the input and output of methods based on JSON Schema definitions.
Integrated the decorator with the existing validate function to ensure consistency.
Added unit tests to verify:
Successful validation for both inbound and outbound payloads.
Errors for invalid inbound and outbound payloads.
Proper handling when no schema is provided (no-op behavior).
Coverage for edge cases such as undefined method descriptors.

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

Issue number: closes #3608

---

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.

[github-actions]

No related issues found. Please ensure there is an open issue related to this change to avoid significant delays or closure.

[github-actions]

No acknowledgement section found. Please make sure you used the template to open a PR and didn't remove the acknowledgment section. Check the template here: https://github.com/aws-powertools/powertools-lambda-typescript/blob/develop/.github/PULL_REQUEST_TEMPLATE.md#acknowledgment

[dreamorosi]

Hi @VatsalGoel3 - thank you for opening the PR.

You have modified the PR body and our automation fails because of it. Not sure why this keeps happening, but if you're using some kind of git client, please set it up so it keeps the PR body intact and just fills in the required fields.

[dreamorosi]

Left a couple comments on the implementation - mainly refactoring for types, the flow is good.

[dreamorosi]

Thanks for the review, before merging we need to make a few more changes:

• In packages/validation/src/validate.ts change the import from import Ajv, { type ValidateFunction } from 'ajv'; to import { Ajv, type ValidateFunction } from 'ajv';
• In packages/validation/src/validate.ts change the function signature from export function validate<T = unknown>(params: ValidateParams<T>): T { to export function validate<T = unknown>(params: ValidateParams): T {
• In packages/validation/src/index.ts change the first import from export { validate } from './validate'; to export { validate } from './validate.js';
• In packages/validation/src/index.ts add a new import export { validator } from './decorator.js';

I checked out the branch and tried to build it, and unless we make these changes it won't work.

[VatsalGoel3]

@dreamorosi Just updated with the suggested changes.

[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

[dreamorosi]

Thank you for addressing all the review comments!

Let's ship it 🚢 !