How to annotate the type of a streamed file response

[Isaac-Leonard]

I'm looking at moving my apis over to use express-zod-api however one endpoint returns large zipped files using res.sendFile() .
The example says that this is possible but doesn't explain what sort of output validation / typing information I should give for streamed responses.
Do I just use string or is there a better option?

[RobinTail]

Hello @Utopianii , thank you for the question.

Short answer: please use string for now.

I was also researching the similar question and here I'm ready to share my results with you.

1. The schema validation library (Zod) does not have a special type for describing a stream. At least yet. So the easiest way to do it right now is to use z.string() (ZodString type). In theory, it's possible to create a custom type by inheriting from ZodType<> generic inferring ReadableStream, and implementing own _parse() method for validation, but I decided that this is an unnecessary complication at this stage.
2. At the same time talking about creating a specification and a documentation of an API, according to the OpenAPI 3.0 standard, there is no specific type for a file. They suggest to use string with an additional format property, that can be binary or byte for base64-encoded files. At the moment, the ZodString schema itself does not allow storing such information, but perhaps in the future I can determine this through the MIME type of the response.

Additional clarifications

The Endpoint's handler does not have an access to res (Response) itself. And it's only capable for returning z.object(). File serving in this regard becomes the functionality of ResultHandler. You can find an example implementation here.
In your case, since we are talking about streams, the Endpoint should most likely return the file name within the output, and the ResultHandler should open it and stream it into the response using the .pipe(response).

I hope that I was able to provide you with useful information for your project.

[RobinTail]

P.S. The given example is a part of the v2, which is currently beta and available for installation using tag beta:

yarn add express-zod-api@beta

Stable release scheduled in a week.

[RobinTail]

@Utopianii , I made the file streaming implementation example for you in this PR: #76

[Isaac-Leonard]

Thank you, yes that answers my question.

[RobinTail]

I've added z.file() schema in version 2.1.0 with two optional refinements: .binary() and .base64().

// before
const fileStreamingEndpointsFactoryBefore = new EndpointsFactory(createResultHandler({
  getPositiveResponse: () => createApiResponse(z.string(), 'image/*'),
  ...
}));

// after
const fileStreamingEndpointsFactoryAfter = new EndpointsFactory(createResultHandler({
  getPositiveResponse: () => createApiResponse(z.file().binary(), 'image/*'),
  ...
}));

CC @Utopianii