add `ZodURL` to validate parts of a url.

Hey 👋

Currently we got z.string().url(). It remains a string after the check. There are more things we could validate in a url, but it’ll feel really awkward to put url-specific methods on ZodString.

Now that we have z.coerce & z.pipe, might be a good idea to add the following options:

z.url(); // native `URL` instance.
z.coerce.url(); // coerce to native `URL` instance.
z.string().transform(value => new URL(value)).pipe(z.url());  // pipe to native `URL` instance for further checks.

and have checks like:

z.url().protocol('https');
z.url().port(1234);
z.url().search({
  age: z.coerce.number().int().min(1),
}); // alternatively could be called `searchParams`.
z.url().username('admin');
z.url().password('123456789');
z.url().pathname(/^\/users\/\d+\/settings$/);
// etc. etc..

---

I’d love to open a PR if this sounds good…

[kentcdodds]

I’ve got a pretty good working version of something that can handle searchParams in #1697.

I decided that if the schema is expecting an array then we’ll treat it like an array, but if it’s not it’ll be invalid if there’s more than one value. That seems reasonable to me.

[colinhacks]

I like a lot of these ideas, but this is a big API surface with a lot of potential headaches.

Some open questions:

Will .pathname(), .user(), .password() etc. support regexes? Arrays of strings? Zod schemas?

z.url().password(z.string().min(10))

If a method exists, people will eventually ask for all of these things. But the end result is a method with a ton of overloads, and the DX starts feeling a little chaotic. There aren’t a lot of methods like that in Zod (by design).

I like .protocol() but we may want to steer clear of .username/.password/.port/.pathname for that reason. Of course its a bit weird that only one property of URL would have its own method.

---

The search params stuff is a big can of worms. If the return type of z.url() is URL then how to we return the parsed/typed search params to the user?

const schema = z.url().search({
  names: z.string().transform(val => val.split(","))
});

const result = schema.parse("http://localhost?names=jim,bob");
result; // => URL
result.searchParams; // => URLSearchParams
// how to retrieve the post-parse search params as  { names: string[] }?

The result could just be URL & { params: <inferred search params type> }?

Other URLSearchParams things:

• Do we let users specify whether a field in the URLSearchParams should be considered a multi-value (.getAll()) or single value (.get())?
• Should there be an equivalent of .strict() and .passthrough() for the returned search params?

URLSearchParams and FormData (which are very similar in their API) may get a separate API entirely: https://github.com/colinhacks/zod/issues/1630

---

Sorry, brain dump. There’s a lot to think about here, and we should definitely hash out details before anyone starts on implementation.