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.

[dreamorosi]

@am29d - note that I might have been far off with this suggestion and this is simply how Zod types work.

Before moving onto an implementation I'd like us to discuss options if that's ok with you - I'd want to avoid us touching dozen files just to later throw it away.

Also, nobody seem to have engaged with this issue - so perhaps we could also just close it and revisit this if there's ever demand.

[dreamorosi]

As discussed during today's meeting @am29d has been looking into this and the change will require updating the type of the LambdaInterface in commons.

He's going to do a small PoC to see if it's worth changing, but if too big we'll just drop the request and close the issue as not planned by the end of the iteration.

[github-actions[bot]]

⚠️ COMMENT VISIBILITY WARNING ⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions[bot]]

This is now released under v2.14.0 version!