Feature request: infer ParsedResult types from inputs of parse function

[dreamorosi]

Use case

When using the Parser with the safeParse option enabled, the result is a ParsedResult type that can contain either the parsed payload or an error depending on the result of the parsing.

Today, customers need to specify two types: one for the input type, usually the one of the envelope, and an output type, either the schema or the transformed type.

This is ok when using envelopes, but when parsing a schema directly the two types can be redundant and/or confusing.

I don't know if it's possible, but we could explore the possibility of making the second type optional when typing the ParsedResult or even making it optional and infer the types from the decorator usage.

Solution/User Experience

Before

import { parser } from '@aws-lambda-powertools/parser';
import { APIGatewayProxyEventV2Schema } from '@aws-lambda-powertools/parser/schemas/api-gatewayv2';
import type {
  ParsedResult,
  APIGatewayProxyEventV2,
} from '@aws-lambda-powertools/parser/types';
import type { Context } from 'aws-lambda';

class Lambda {
  @parser({ schema: APIGatewayProxyEventV2Schema, safeParse: true })
  public async handler(
    event: ParsedResult<APIGatewayProxyEventV2, APIGatewayProxyEventV2>,
    _context: Context
  ) {
    if (event.success) {
      console.log(event.data); // this is APIGatewayProxyEventV2
    } else {
      // event.error is now strongly typed
      console.error(event.error);
      // event.originalEvent is now strongly typed
      console.error(event.originalEvent);
    }
  }
}

export const handler = new Lambda().handler;

After

class Lambda {
  @parser({ schema: APIGatewayProxyEventV2Schema, safeParse: true })
  public async handler(
-    event: ParsedResult<unknown, APIGatewayProxyEventV2>,
+    event: ParsedResult<APIGatewayProxyEventV2>,
    _context: Context
  ) {
    if (event.success) {
      console.log(event.data); // this is APIGatewayProxyEventV2
    } else {
      // event.error is now strongly typed
      console.error(event.error);
      // event.originalEvent is now strongly typed
      console.error(event.originalEvent);
    }
  }
}

Especially in cases where we don't use an envelope, the Output type is always the z.infer<typeof XXXSchema>.

Alternative solutions

If this is not feasible, I would suggest refactoring the `ParsedResult` type which today looks like this:


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


To switch the order and make it more obvious what is what, i.e.

```ts
type ParsedResult<PayloadSchema = unknown, EnvelopeSchema = unknown> =
  | ParsedResultSuccess<PayloadSchema>
  | ParsedResultError< EnvelopeSchema>;

So that one can just specify the first one when not using envelopes.

This solution however might be counterintuitive because we are now reverting the order of the parameters. The good thing about the current solution is that logically input comes before the output.

### Acknowledgment

- [X] This feature request meets [Powertools for AWS Lambda (TypeScript) Tenets](https://docs.powertools.aws.dev/lambda/typescript/latest/#tenets)
- [ ] Should this be considered in other Powertools for AWS Lambda languages? i.e. [Python](https://github.com/aws-powertools/powertools-lambda-python/), [Java](https://github.com/aws-powertools/powertools-lambda-java/), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet/)

### Future readers

Please react with 👍 and your use case to help us understand customer demand.

[dreamorosi]

I also noticed that the API docs of the feature are incorrect and don't mention the fact that you need two types.

I have started a branch to fix this, if we decide to fix this we can continue working on it.