✅ Client: requesting unlisted paths and methods

[HenriJ]

Description

In the current implementation MethodPath is the combination of all possible methods with all possible paths.

What it means is that I am able to call
client.provide("delete", "/v1/user/retrieve", { id: "10" });

even if there is no delete method linked with this path.

Expected

I should get a typescript error when calling a path that does not provide the requested method.

As a workaround, I implemented my own client that instead of taking a method and a path separately directly takes the full endpoint "get /v1/user/retrieve" (I'm using keyof type endpointTags to get the list of available endpoints which is not perfect though).

Reproduction

Try to call an endpoint with a method that does not exists.

Context

• Node.js version: 22
  • express-zod-api version: 20.21.0

[RobinTail]

I am able to call

well, this is a conceptual problem, because technically you do actually can, but the request might be handled by "not found (404)" handler which is a part of the API. It also can be handled by something besides the routing established by the framework itself, which is possible when using attachRouting() to an existing app, or by using beforeRouting feature in config. Thus, when you type client.provide() you may notice that the return type is any instead of something particular. So, what I mean is that the ability to request an unlisted path/method might be not a bug generally, but a property of the API, @HenriJ

However, I understand the confusion.

my own client ... takes ... "get /v1/user/retrieve"

this is similar to the interface of OctoKit Request.
I deliberately wanted to separate them.

Here is what I can do:

1. Stop extending Response from combinations and treat it as limited dictionary with literal keys

- interface Response extends Record<MethodPath, any>
+ interface Response

2. Change the Provider return type

- Promise<Response[`${M} ${P}`]>
+ Promise<`${M} ${P}` extends keyof Response ? Response[`${M} ${P}`] : never>

And probably this never should be configurable or at least opt-in feature.
Maybe it should be the config.errorHandler negative schema instead of never, depicting what 404 response actually look like.

[RobinTail]

I checked how OctoKit behaves in a similar scenario, @HenriJ , which I'd consider an etalon of REST API client, and it turned out that it does not prohibit unknown methods and undeclared routes. It acts exactly the same way as I implemented here — it returns any

Taking this finding into account, I'd consider the desired behaviour as a feature, not a bug of missing it.

[HenriJ]

Interesting, maybe octokit was written before unknown existed ?

I am trying to understand the trade-off between using the included frontend client generation versus using any other "openapi to client" lib that exist (for example to have react-query hooks auto-generated). Do you have any insight to share ?

Also while reading the source code regarding the openapi schema generation, I wondered if using a lib like https://github.com/samchungy/zod-openapi might make it easier ?

[RobinTail]

Interesting, maybe octokit was written before unknown existed ?

It's not difficult to make it return Promise<unknown> for invalid combination of method and path.

But I came to conclusion that in order to make this:

I should get a typescript error

provide() should require combined method + path similar to OctoKit, which might be a breaking change.
And so far, I'm still thinking on how to approach it better.

the trade-off between using the included frontend client generation versus using any other "openapi to client" lib

You can do that. It's just a longer path to make OpenAPI generated first and then based on it to generate a Typescript client.
Additionally, it may be discrepancies due to such a double conversions.
On contrary, making Typescript code in first place implies generating from Zod schema directly, without intermediate interpretation, @HenriJ

[RobinTail]

I wanna try making an overload, so that provider() could handle either 3 or 2 arguments, so that the 2 arguments variant could have the strict behaviour with method+path concatenated argument.

[RobinTail]

Dear @HenriJ ,
I made a new version 21.2.0-beta.1 that solves the problem you found.
The desired constraints and Typescript error is available when using the featured overload of the client's provide() method having 2 arguments, similar to what you made yourself.

Could you please install it, try it and let me know if it worked well for you?

[RobinTail]

@HenriJ , please confirm receiving the message

I made a new version 21.2.0-beta.1 that solves the problem you found.
The desired constraints and Typescript error is available when using the featured overload of the client's provide() method having 2 arguments, similar to what you made yourself.

Could you please install it, try it and let me know if it worked well for you?

[HenriJ]

Hi @RobinTail , just had some time to test and it is working great! I replaced my custom implementation with the generated code and everything is still working :)

FYI, the way I am using express-zod-api right now is:

• I am using the generated client for backend-to-backend communication as the generated client does the job well
• I am using openapi (heygen) client generation for the react frontend to have the react-query hooks generated for me (it also handles string to Date transform automatically)

Both are working really well which shows the quality of your library!

[RobinTail]

Awesome, I'm really glad to read this.
Then I'm going to release that feature.
Thank you for letting me know, @HenriJ !

[RobinTail]

🚀 21.2.0