feat: implement File type

[jgradzki]

#814

z.file().type(["image/png", "image/jpeg"]).min(2000).max(4000);
z.file().type("image/png");

For Node.js:

import { File } from "@web-std/file";

z.file({}, File);

Getters:

z.file().min(1).minSize;
z.file().max(5).maxSize;
z.file().type("image/png").allowedTypes

[andresgutgon]

We could use something like @web-std/file

[jgradzki]

@JacobWeisenburger ☝️

[andresgutgon]

If we want to support custom errors I think you need to pass RawCreateParams like in ZodString right?

[andresgutgon]

I'm talking about this:

[andresgutgon]

I think is the zod way to allow translated errors

[andresgutgon]

I'm playing with your PR in my code. Looking nice at least the errors.

I'll check how it feels the validations : )

[jgradzki]

Ok, so no problem? :D
I have removed some extra " in "File not supported ..." error message, also changed separator in issue.expected.join from , to or

[jgradzki]

nvm, i see what you talking about, will update

[jgradzki]

i wonder which parameter should be first, for now file constructor is second

[andresgutgon]

Ok, this is my real problem. Let's see if you have an idea 😄

When a Node request occur. Let's say a POST request multipart the user submit a form with text fields and file fields.

Then the request is processed and and validated. In the case of files what I had seen in other codes is that they write into Disk the data of that file and chunk by chunk they check if the current size of the file is lower than maxBytes.

If it's bigger they throw an Error and stop the stream.

I put a piece of code here that is kind of what's I'm talking

Now my question is how I use z.file(File).size and this flow?

[andresgutgon]

I would switch the order here. It's more common to set the constructor than the params I think. Feel free to ignore, just an opinion

[jgradzki]

maybe, I will wait for one more opinion maybe and then we will decide

[jgradzki]

Ok, this is my real problem. Let's see if you have an idea smile

When a Node request occur. Let's say a POST request multipart the user submit a form with text fields and file fields.

Then the request is processed and and validated. In the case of files what I had seen in other codes is that they write into Disk the data of that file and chunk by chunk they check if the current size of the file is lower than maxBytes.

If it's bigger they throw an Error and stop the stream.

I put a piece of code here that is kind of what's I'm talking

Now my question is how I use z.file(File).size and this flow?

Unfortunately I don't have an answer, I would have to dive in and research about it but I don't have that much time right now :(

[andresgutgon]

It would be nice to have a getter like string isEmail to get the expected types, min and max.

Would be something like this:

const myFile = z.file().min(2).max(39).type(["application/pdf", "image/png"])

// The getters
myFile.type // ["application/pdf", "image/png"]]
myFile.min // 2
myFile.max // 39

I would need this to use in a code like this one

[jgradzki]

It would be nice to have a getter like string isEmail to get the expected types, min and max.

Would be something like this:

const myFile = z.file().min(2).max(39).type(["application/pdf", "image/png"])

// The getters
myFile.type // ["application/pdf", "image/png"]]
myFile.min // 2
myFile.max // 39

I would need this to use in a code like this one

added, had to use different names ;)

[andresgutgon]

Ok I think current implementation is flexible enough. For my use case I don't want to build a real File object while doing validation. But this code allow me to pass a class that looks like a File

export class FileShape { constructor(public type: string, public size: number) {}}

// Then I can use normal:
const myFile = z.file({}, FileShape).max(34033).type(["images/jpeg"])

The reason for not wanting to use a real File implementation is because I don't know the size of the file in advance on the server. So I can't build a real file and pass to zod.
What I do is to stream the contents on the file + write to disk those contents and measure if they are less than the .max attribute on the zod file validation.

When I know that the size of the file submitted is too big I set that size in my ShapeFile like this

const file = new FileShape("image/jpeg", 0)
const myValidation = z.file({}, FileShape).max(34033).type(["images/jpeg"])
// ...
// Do some work with Node streams + write to disk + measure bytes
// If I detect the the file is too big set that size in my FileShape like this:
file.setSize(23232323) // Too big
myValidation.parse(file) // Now that I know the actual file size I want to get the errors.

Do you thing is a reasonable way of using this or it's fragile?

I like your PR 👍

[andresgutgon]

Missing here messages for too_big and too_small. Without it for file the error goes to the generic:

[andresgutgon]

I can do these changes if you give me push permission to your branch. If not is fine I'll wait :)

[andresgutgon]

Would be possible to support an Array of Files?

The use case is if people use multiple=true in an <input type="file" multiple />

This way these upload can be processed in the server and use this validation like this:

const myRequest = z.object({
  gallery: z.file({}, File).array()
})

But for this to work we need to manage the case when the input is an array.

I would play with it in my dev environment with your fork : )

[andresgutgon]

Forget it. This works:

const myRequest = z.object({
  gallery: z.array(z.file({}, File))
})

Nothing to do here : )

[andresgutgon]

@jgradzki could you take a look to my comments? I would really love to have this in "zod" ❤️

@colinhacks what's your opinion here?

[andresgutgon]

I'm being thinking on the approach we're taking here of requiring a constructor. It has some issues.

The first issue is that you need to pass a constructor on Non-web environments or simulate a web file API in Node. This is annoying and I think we can avoid it.

The second issue is that what you see after parsing your ZodFile is typeof File

This is a problem because then Typescript doesn't know what properties should have the returned File | FileLike class.

My proposal

My proposal is to define a minimum common interface that ZodFile should require and any class that respect this interface can be returned.

interface IFile {
  name: string;
  size: number;
  type: string;
}

If we return an Interface then Typescript know what is that. Look how nice : )

Also here is clear what you have

Implementation

I'm still working on it. That interface is missing for example filename which is basic in a node environment. Also we should add all official web attributes and methods according to the spec

But not check that passed object is an instanceof File. Instead just check that it has what we need for this ZodFile which is size and type

    const hasSize = !!input.data?.size;
    const hasType = !!input.data?.type;
    if (!hasSize || !hasType) {
      const issue = makeIssue({ //... set the issue as you do })
    }

What do you think?

[andresgutgon]

Please take a look to THIS SANDBOX I put together both apprach fileInterface.ts and fileConstructor.ts

[andresgutgon]

Why only browser? At this point a lot of people is using Zod in browser and in Node. Why not a solution valid for both environments?

In my case it looks something like this:

const schema = z.object({
  name: z.string(),
  avatar: z.file() 
})

const requestHandler = (request, response) => {
  const result = parser.parse({ request, schema })

  if (!result.success) {
     // Handle error
  } 
  
  // At this point is a file in NodeJS. That can be a file in filesystem o an object in S3
  console.log("DATA", result.data.avatar)
}

All the implementation on how to create that file is inside the parser. But Zod is there to provide a nice validation system. Would be super nice if instead of file type be limited to a web File object would be a contract that can satisfy both web and Node.

I'm not thinking on adding any Node dependency here. Just have a file validator that accept a contract instead of a fixed File class. In the end the validator just want the file to respond to size and type properties right?

[jgradzki]

I started thinking that we cannot satisfy browser and node.js in one type. My intentions were strictly to validate for File instance. I think there should be completely different type for node.js/deno and I think you should make your own in your project as handling files on server can be done in few different ways I guess.

[andresgutgon]

I started thinking that we cannot satisfy browser and node.js in one type. My intentions were strictly to validate for File instance. I think there should be completely different type for node.js/deno and I think you should make your own in your project as handling files on server can be done in few different ways I guess.

That's the thing : )

1. In browser a File is checked for size and type
2. In Node/Deno a Something is checked for size and type

The only job of this validator is to check if the Thing passed respond to type and size

And then in the return part could be something like this:

interface IFile {
  public name: string
  public size: number
  public filepath: string
}

As inspiration this what AdonisJS does for handling Disk, S3, GCP, Azure implementations. That is their common File interface. I understand maybe this is not Zod business so please feel free to ignore. I just want to expose what I'm seing in the Node side and what would be the best way to integrate Zod as a validation layer for a Node request.

I like about this proposal that is flexible enough to serve browser and Node.

Cons

In browser you would have to wrap your File with an IFile like interface

class WebFile implements IFile {
  filepath: string = ""
  constructor(file: File) {
     this.name = file.name
     this.size = file.size
  }
}

[andresgutgon]

Totally fine with implementing my own file for Node 😄

But I think Zod is awesome and people is already using it in the server. file should handle both platforms somehow. But as I said totally happy if this doesn't happen inside Zod

[jgradzki]

z.file I guess :D

[jgradzki]

@colinhacks what next :)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ricardo-valero]

What happened to this?