Typescript or docs error in openapi() hook argument

[lucafaggianelli]

Which middleware has the bug?

@hono/zod-openapi

What version of the middleware?

1.1.3

What version of Hono are you using?

4.9.8

What runtime/platform is your app running on? (with version if possible)

Bun

What steps can reproduce the bug?

The hook argument in the app.openapi() function has a wrong type or at least is not well documented.

This is my code taken from the official docs:

app.openapi(
  clientsSyncRoute,
  async (c) => {
    const data = c.req.valid('json')

    await saveClientsDelta(JSON.stringify(data))

    return c.json({ success: true }, 202)
  },
  async (result, c) => { // This is throwing a TS error
    if (!result.success) {
      return c.json(
        {
          success: false,
          message: 'Validation error',
          errors: result.error.issues,
        },
        422
      )
    }
  }
)

The code works well but it's throwing a TS error, so I'd like to understand if the code is really OK or not. How should the hook function behave? Is it correct that I don't return anything in case of success? So the route handler function is not run if the hook returns something and it runs only if the hook returns undefined?

What is the expected behavior?

To not throw a type error

What do you see instead?

From my understanding the hook function can't return undefined, though the code is working so it appears to be only a type issue.

This is the Typescript error:

Argument of type '(result: { target: keyof ValidationTargets; } & ({ success: false; error: ZodError<unknown>; } | { success: true; data: { in: { json: { customer?: { customerName: string; customerSap: string; ... 6 more ...; Address?: string | ... 1 more ... | undefined; }[] | undefined; cardAccount?: { ...; }[] | undefined; card?: ...' is not assignable to parameter of type 'Hook<{ in: { json: { customer?: { customerName: string; customerSap: string; mainName: string; mainSap: string; VATcode: string; FiscalCode: string; IsoCode: string; action: "I" | "U" | "D"; Address?: string | ... 1 more ... | undefined; }[] | undefined; cardAccount?: { ...; }[] | undefined; card?: { ...; }[] | unde...'.
  Type 'Promise<JSONRespondReturn<{ success: false; message: string; errors: $ZodIssue[]; }, 422> | undefined>' is not assignable to type 'MaybePromise<RouteConfigToTypedResponse<{ description: string; method: "post"; path: "/clients/sync"; request: { body: { required: true; content: { 'application/json': { schema: ZodObject<{ customer: ZodOptional<ZodArray<ZodObject<{ customerName: ZodString; ... 7 more ...; action: ZodEnum<...>; }, $strip>>>; cardAcc...'.
    Type 'Promise<JSONRespondReturn<{ success: false; message: string; errors: $ZodIssue[]; }, 422> | undefined>' is not assignable to type 'Promise<RouteConfigToTypedResponse<{ description: string; method: "post"; path: "/clients/sync"; request: { body: { required: true; content: { 'application/json': { schema: ZodObject<{ customer: ZodOptional<ZodArray<ZodObject<{ customerName: ZodString; ... 7 more ...; action: ZodEnum<...>; }, $strip>>>; cardAccount:...'.
      Type 'JSONRespondReturn<{ success: false; message: string; errors: $ZodIssue[]; }, 422> | undefined' is not assignable to type 'RouteConfigToTypedResponse<{ description: string; method: "post"; path: "/clients/sync"; request: { body: { required: true; content: { 'application/json': { schema: ZodObject<{ customer: ZodOptional<ZodArray<ZodObject<{ customerName: ZodString; ... 7 more ...; action: ZodEnum<...>; }, $strip>>>; cardAccount: ZodOpti...'.
        Type 'undefined' is not assignable to type 'RouteConfigToTypedResponse<{ description: string; method: "post"; path: "/clients/sync"; request: { body: { required: true; content: { 'application/json': { schema: ZodObject<{ customer: ZodOptional<ZodArray<ZodObject<{ customerName: ZodString; ... 7 more ...; action: ZodEnum<...>; }, $strip>>>; cardAccount: ZodOpti...'.ts(2345)

Additional information

I'm happy to work on this issue, if you clarify what to do, i.e. improve the docs or the type