z.date documentation needed

[JacobWeisenburger]

Discussed in #879

^{Originally posted by blocka January 24, 2022}
Very surprised that I could not find anything on this.

If I have a date schema const schema = z.date() and I pass it a date string schema.parse('2022-01-12T00:00:00.000Z')
I would expect to get back a JS Date object. Instead I get an exception that I've passed a string instead of a date. ...

There really should be some documentation in the README about how z.date works.

[scotttrinh]

I think documentation in general needs some more attention, so would welcome some stop-gap PRs in this regard for sure!

Furthermore, there is a general expectation from new users that Zod will somehow coerce values which I think is equally important to address beyond this. The fact that anyone expects to pass an arbitrary value into a schema that isn't the type specified by the schema is both surprising to me and telling about how we're missing the mark in communicating the goal and utility of Zod. I think as we continue to grow and more people are looking to Zod as a simple form validator (or JSON parser, etc), we'll continue to get confused or frustrated potential users, so better docs seem like a really important thing to put effort into.

[JacobWeisenburger]

I agree completely.

I think the "parse, don't validate" thing is confusing. I have been using Zod for awhile now and so I get how it works. But I still don't get the reasoning behind "parse, don't validate". To me, leaving the implementation of parse and safeParse the way they are is fine, but renaming them to validate and safeValidate or something would help with some of the confusion. But that's just me....

[scotttrinh]

I think the "parse, don't validate" thing is confusing.

Yeah, definitely confusing if one hasn't already read the linked article (and if you haven't it's absolutely a banger and worth reading immediately) or had trouble following the idea due to the Haskell, but I absolutely get that "parse" means something specific to people and in a web context has a very strong connotation of String -> T.

The TL;DR of "parse, don't validate" is that instead of writing "validators" which do not return a value but simply check that a value has a certain shape, you should prefer to write a "parser" which takes a value and returns a new value of a more constrained type. That keeps you from having to add validation steps all over your code since you can just parse it at the boundary and know with full confidence the runtime characteristics of the returned values.

A succinct passage (roughly translated into TypeScript) from that article:

declare function validateNonEmpty<T>(input: unknown): asserts input is NonEmptyArray<T>
declare function parseNonEmpty<T>(input: unknown): NonEmptyArray<T>

These two functions are nearly identical: they check if the provided list is empty, and if it is, they abort the program with an error message. The difference lies entirely in the return type: validateNonEmpty always returns void, the type that contains no information, but parseNonEmpty returns NonEmptyArray<T>, a refinement of the input type that preserves the knowledge gained in the type system. Both of these functions check the same thing, but parseNonEmpty gives the caller access to the information it learned, while validateNonEmpty just throws it away.
[...]
Under this flexible definition, parsers are an incredibly powerful tool: they allow discharging checks on input up-front, right on the boundary between a program and the outside world, and once those checks have been performed, they never need to be checked again!

Furthermore, with transform, we further stray from "validation" since now the data is substantially and actually different after passing through the parser, which is even more parser-like.

All of this context and philosophy can and should absolutely be more explicit and I'm very open to finding a good way to structure and improve the documentation. I think we need multiple levels of documentation help, so maybe it's worth making some separate issues around this and discussing what documentation infrastructure looks like. Could just be fleshing out the docs directory and restructuring a bit, or could be something like GitBook or Github Pages? Would love to hear @colinhacks 's thoughts.

[JacobWeisenburger]

ok, I understand what it means much better now. Thanks

To me, when I think of validation, I think of what parse does, and when I think of parse, I think of what transform does. So I would imagine there are a lot of others out there that think the same way.

[scotttrinh]

To me, when I think of validation, I think of what parse does [...] So I would imagine there are a lot of others out there that think the same way.

Yeah, that's fair. I think a lot of people assume that validation is easy with Zod, but I think it's actually quite tricky to do it idiomatically. Lack of type guards and assertion functions are surprising to people and some find needing to use the return value to be strange or unergonomic, but all of that flows from the "parse, don't validate" idea. Definitely a further proof that the documentation and onboarding needs some focus and effort put in. I'll try to figure out a good way to get a documentation effort started so we can start to make some progress on this front.

[scotttrinh]

@JacobWeisenburger

Started a discussion to talk about forming a documentation working group if you're interested: #911