File Upload & Client implementation

[Alexandregirbal]

Hi guys,
First of all, thanks for building this package, it's 99% amazing.
About the 1% left:

• I just wanted to talk quickly about the way the default implementation is made and how one could make it better. It would be great to pass a baseURL to the Client instead of having to create a custom Implementation. At the same time, we could even consider adding some headers to pass to every request (like a jwt for example). What do you think ? I am keen to work on this to contribute to the project if you agree on.

• I also wanted to say that this sentence in the Upload section made me run mad because I was adding the content type manually instead of letting my browser handling this for me. I could be great to add a note about it in the documentation:

  The request content type must be multipart/form-data:

  Could become:

  The request content type must be multipart/form-data, but no need to manually add this content-type to you request as it is handled by most browsers.

• About the transformations in GET params, it's losing my generated client as it creates types undefined | undefined. it would be great to find a way to handle this natively and avoir transforms. I don't if this is in the todos.

[RobinTail]

Thank you for appreciation and your feedback, @Alexandregirbal .

It would be great to pass a baseURL to the Client

express-zod-api/express-zod-api/src/integration.ts

Lines 39 to 43 in 7b92ff0

	/**
	* @desc The API URL to use in the generated code
	* @default https://example.com
	* */
	serverUrl?: string;

consider adding some headers to pass to every request
What do you think ? I am keen to work on this to contribute to the project if you agree on.

💡 nice idea. If it's static, then it could be an option for Integration.
But JWT is temporary token, so it might be better to pass it over ctx to a custom implementation.
Not sure how to make with default one in a non-breaking way.
But if you have an idea I welcome your PR.

must be multipart/form-data

but no need to manually add this content-type to you request as it is handled by most browsers.

Well, it's awesome that they do that for you.
But most !== all, and the API could be requested by other kind of program, such as CURL.
Therefore, I meant that the header must be there, no matter who'd place it: you or your client program.
Perhaps there is way to express this thought more clear in the documentation.
I'm welcome your suggestions.

GET params, it's losing my generated client as it creates types undefined | undefined.

Not sure what you mean. I don't have such issue with input transformations.

Endpoint:

express-zod-api/example/endpoints/retrieve-user.ts

Lines 21 to 26 in 7b92ff0

	input: z.object({
	id: z
	.string()
	.trim()
	.regex(/\d+/)
	.transform((id) => parseInt(id, 10))

Client types:

express-zod-api/example/example.client.ts

Lines 8 to 12 in 7b92ff0

	/** get /v1/user/retrieve */
	type GetV1UserRetrieveInput = {
	/** a numeric string containing the id of the user */
	id: string;
	};

Let me know more details about this case.
Perhaps you meant the output ones?

[Alexandregirbal]

About the baseUrl / serverUrl

💡 nice idea. If it's static, then it could be an option for Integration.

I understand it is possible to pass a serverUrl (let's call it this way).
But my problem is that the client is not customizable on demand. It is a very opinionated way of printing/building the client.
I love the fact that it's writable into a file, and I use this in a monorepo to seperate the backend client from the actual backend in order to expose only types and client to my frontend in this kind of architecture :

.
├── apps
│   ├── backend/
│   │   ├── routes/
│   │   ├── routing.ts
│   │   ├── main.ts
│   │   └── scripts/
│   │       └── generate-client.ts -> ../../libs/api-client/
│   └── frontend/
├── libs/
│   ├── api-client/
│   ├── common/
│   ├── front-common/
│   └── back-common/
...

In the end, I wrote my own Implementation, but It would be a nice shortcut to avoid doing this "only" because I want to use a different serverUrl from the written file.

About the upload

You are right, most !== all, but the default implementation does not take this into account as having a body always adds application/json in the content type header.

express-zod-api/express-zod-api/src/integration-base.ts

Lines 373 to 382 in 6346e26

	makeTernary(
	this.#ids.hasBodyConst,
	f.createObjectLiteralExpression([
	f.createPropertyAssignment(
	literally("Content-Type"),
	literally(contentTypes.json),
	),
	]),
	this.#ids.undefinedValue,
	),

This is another reason why I write my own implementation.
I don't know what is doable about this ? In the end, is the defaultImplementation a good idea inside the client ? it could be a util function exposed in the package ?
Here is my customImplementation derived from the default one, partially solving the upload issue, even though it could be optimized a lot it works:

import { Client, Implementation } from './generatedClient';

export const buildAPIClient = ({
  baseUrl,
  token,
}: {
  baseUrl: string;
  token: string | null;
}) => {
  const customImplementation: Implementation = async (method, path, params) => {
    const url = new URL(path, baseUrl);

    const hasBody = !['get', 'delete'].includes(method);
    const hasParams = Object.keys(params).length > 0;
    const hasFile = Object.values(params).some(
      (value) => value instanceof File || value instanceof Blob
    );

    if (hasFile && !hasBody) {
      throw new Error('Files cannot be sent without a body');
    }

    const searchParams =
      hasBody && hasParams ? '' : `?${new URLSearchParams(params)}`;

    const contentType = hasBody && !hasFile ? 'application/json' : undefined;

    const formData = new FormData();
    if (hasFile) {
      Object.entries(params).forEach(([key, value]) => {
        formData.append(key, value);
      });
    }

    const body = hasFile
      ? formData
      : hasBody
      ? JSON.stringify(params)
      : undefined;

    const response = await fetch(`${url}${searchParams}`, {
      method: method.toUpperCase(),
      headers: {
        ...(token ? { Authorization: token } : {}),
        ...(contentType ? { 'Content-Type': contentType } : {}),
      },
      body,
    });

    const responseContentType = response.headers.get('content-type');
    if (!responseContentType) return;

    const isJSON = responseContentType.startsWith('application/json');
    return response[isJSON ? 'json' : 'text']();
  };

  return new Client(customImplementation);
};

About the type issues

I will create another discussion as it is not related to the Implementation, Integration and generated Client.

Thanks for your response, hoping I can help make this project 1% better 😄

[RobinTail]

In the end, I wrote my own Implementation

I expect you to write your own implementation — it's absolutely fine.
The default one is not supposed to suit all needs, it's just for basic ones.
Integration is designed to be customizable on several levels:

• pluggable Implementation to the Client
• ctx argument of Implementation (check this out btw, you could pass your baseUrl and token to it)
• variant: "types" to make a fully DIY solution.

So my goal is to keep the Client rather flexible than comprehensive.

Here is my customImplementation

Thank you, I will review what I could take from it to the default one, @Alexandregirbal
In case you already have an idea, you are welcome to file a PR.