✅ Frontend client generation

[McMerph]

First of all, https://github.com/RobinTail/express-zod-api#generating-a-frontend-client is a great feature! Thanks for this!

But I manually edit the generated code due to:

1. It generates types as the intersection of Record<string, unknown> and the actual endpoint input/response. So, I just remove the Record<string, unknown> part of the intersections.
2. In addition, an empty endpoint input/response is also generated as Record<string, unknown>. So I change it to Record<PropertyKey, never>.
3. Optional input fields are generated with an undefined type and the specifier ?, e.g. optionalField?: string | undefined;. So, I remove the undefined type from those fields, e.g. optional field?: string.
4. Unfortunately, the ExpressZodAPIClient code produces a lot of tsc errors. That is why I do not use it and remove this part (MethodPath, jsonEndpoints, Provider, Implementation, ExpressZodAPIClient) of the generated code manually. I would like to have more options in Client.print() so that I don't generate code that I don't use.

Can we discuss the points above?

[RobinTail]

Yes, @McMerph
I'd like to know more details.

[McMerph]

Unfortunately, the ExpressZodAPIClient code produces a lot of tsc errors

These are actually eslint errors, not tsc errors

[McMerph]

Let's break it apart because it seems like some issues are specific to my use cases.

Issues 1 and 2 are hard to reproduce. Let's deal with issues 3 and 4 first.
I created a sample repository to show my problems.
This commit has issues 3 and 4.

---

Issue 3 in details
Generated client code is:

type GetV1HelloInput = {
  name?: string | undefined;
};
...

So, it looks like | undefined part of name type is redundant.
Moreover npm run lint outputs an error:

express-zod-api-client-generation-sample/src/client/api.ts
  2:7  error  {"message":"Consider removing 'undefined' type or '?' specifier, one of them is redundant.","secondaryLocations":[{"column":18,"line":2,"endColumn":27,"endLine":2}]}  sonar/no-redundant-optional

Is it an issue or expected behaviour?

---

Issue 4 in details
Generated code is:

type GetV1HelloInput = {
    name?: string | undefined;
};

type GetV1HelloResponse = {
    status: "success";
    data: {
        greetings: string;
    };
} | {
    status: "error";
    error: {
        message: string;
    };
};

export type Path = "/v1/hello";

export type Method = "get" | "post" | "put" | "delete" | "patch";

export type MethodPath = `${Method} ${Path}`;

export interface Input extends Record<MethodPath, any> {
    "get /v1/hello": GetV1HelloInput;
}

export interface Response extends Record<MethodPath, any> {
    "get /v1/hello": GetV1HelloResponse;
}

export const jsonEndpoints = { "get /v1/hello": true };

export type Provider = <M extends Method, P extends Path>(method: M, path: P, params: Input[`${M} ${P}`]) => Promise<Response[`${M} ${P}`]>;

export type Implementation = (method: Method, path: string, params: Record<string, any>) => Promise<any>;

export class ExpressZodAPIClient {
    constructor(protected readonly implementation: Implementation) { }
    public readonly provide: Provider = (method, path, params) => this.implementation(method, Object.keys(params).reduce((acc, key) => acc.replace(`:${key}`, params[key]), path), Object.keys(params).reduce((acc, key) => path.indexOf(`:${key}`) >= 0 ? acc : { ...acc, [key]: params[key] }, {}));
}

BTW, ESLint complains:

  37:14   error  Class name `ExpressZodAPIClient` must match one of the following formats: StrictPascalCase                                                                             @typescript-eslint/naming-convention
  39:41   error  Functions that return promises must be async                                                                                                                           @typescript-eslint/promise-function-async
  39:67   error  Unsafe return of type `Promise<any>` from function with return type `Promise<Response[`${M} ${P}`]>`                                                                   @typescript-eslint/no-unsafe-return
  39:159  error  Unsafe argument of type `any` assigned to a parameter of type `string`                                                                                                 @typescript-eslint/no-unsafe-argument
  39:221  error  Use 'includes()' method instead                                                                                                                                        @typescript-eslint/prefer-includes
  39:268  error  Unsafe assignment of an `any` value                                                                                                                                    @typescript-eslint/no-unsafe-assignment

I'd like to exclude MethodPath, jsonEndpoints, Provider, Implementation, ExpressZodAPIClient from generated code.
How can I achieve this? It looks like Client.print does not have such options.

[RobinTail]

@McMerph ,

Regarding "issue 3"

The message you get comes from ESLint rule sonar/no-redundant-optional you have installed and enabled on the generated file.

There are different opinions on presence of | undefined for optional properties.
If I remember correctly, in some cases it was required to be enable you to assign undefined value to such property.
Perhaps it's currently fixed in modern Typescript.

But anyway, it's probably more like a code style redundancy.
Does this rule have an auto-fix? Does it fix it when running yarn eslint --fix?

[RobinTail]

🚀 The feature for "issue 3" released in version 10.3.0, @McMerph

[RobinTail]

@McMerph , For your case the code should look this way:

new Client({
  routing,
  optionalPropStyle: { withQuestionMark: true }, // no `| undefined`
}).print();

[McMerph]

"issue 3" is fixed. Thank you, @RobinTail

What about "issue 4"?
Is there a point to exclude MethodPath, jsonEndpoints, Provider, Implementation, ExpressZodAPIClient from generated code?

[RobinTail]

"issue 3" is fixed. Thank you, @RobinTail

Great. Thank you for checking it, @McMerph

What about "issue 4"?

I'm thinking on a better way of implementing it. I'll share more details a bit later.

[RobinTail]

Well. More details for you, @McMerph .

Without entities you mentioned, the rest would not be a Client. It would be just a collection of depicted I/O types of your API endpoints. Even without their relationship to its routing.

Therefore, it's a problem of semantics. I can not add an option withoutClient: boolean to the Client::constructor, it would make a confusion.

Instead, I need a layer of abstraction here. So far, I wanna call that entity Integration giving it configurable options or variations that it can produce.

Still thinking on it, but I decided to inform you why it might take some time.

[McMerph]

Regarding "issue 1"

I believe is works as expected because according to Index signature is missing in type (only on interfaces, not on type alias) :

interfaces should declare an explicit index signature if they intend to be indexed.

---

In my particular usecase, these interfaces are converted to types after eslint --fix but the Record<string, unknown> part remains.
@RobinTail Why do you prefer interfaces over types here?

[RobinTail]

I'm sorry, I missed this part since we've been focused on issues "3" and "4".
However, Record<string, unknown> required an investigation.
I believe I didn't encountered this. Need to check your example repo.

[RobinTail]

@McMerph , could you please help me with pointing to the endpoint that causes Record<string, unknown> in Typescript generation.
Can not find the exact place in your repo.

[McMerph]

I added the commit regarding "Issue 2"
Record<string, unknown> is here

[RobinTail]

I found the reason for that, @McMerph .

If I stop you script execution right after the client generation:

npm run-script run-ts -- scripts/client-generator.ts
exit

that line looks the following way:

type GetV1SampleYamlInput = {};

however, then you run eslint --fix on it, which by some rule replaces it to Record<string, unknown>.

I'd suggest to disable eslint for the genrated code or disable its certain rules on it.

[RobinTail]

The PR for "issue 4" is #974

[RobinTail]

Is it safe to delete & Record<MethodPath, any> in Input and Response types?

Not really, it ensures that the keys of the interface comply the MethodPath type.

It's similar to satisfies keyword in TS 4.9.

[RobinTail]

I use Path, Method, Input, Response in my DIY solution, so I do not want them to be deleted.

Ok. I will restore them.

But the MethodPath will be restored as well, since it's needed for Input and Response.

So far I don't clearly understand what's the issue with MethodPath. But if you could clarify it, I could make its presence configurable.
@McMerph

[RobinTail]

It's interesting that in your repo the dictionary type looks this way:

export type Input = {
  "get /v1/hello": GetV1HelloInput;
  "get /v1/sample-yaml": GetV1SampleYamlInput;
} & Record<MethodPath, any>;

while in mine it looks this way:

export interface Input extends Record<MethodPath, any> {
  "get /v1/user/retrieve": GetV1UserRetrieveInput;
  "post /v1/user/:id": PostV1UserIdInput;
  "get /v1/avatar/send": GetV1AvatarSendInput;
  "get /v1/avatar/stream": GetV1AvatarStreamInput;
  "post /v1/avatar/upload": PostV1AvatarUploadInput;
}

there is no & and no type.

[RobinTail]

Ah, I found — you wrote it's the result of some ESLint rule.

eslint --fix

[RobinTail]

Consider disabling eslint on the generated code or disabling its certain rules on it.
It seems that those rules make more confusion than benefits, @McMerph