Getting started

How does Validatem work?

As validation libraries go, Validatem is a little different. For example, unlike Joi (where every validator is a chained method) or checkit (where every validator is a string name), a validator in Validatem is just a function that receives the to-be-validated value as an argument. That function can do a few different things:

• Return with nothing: Consider the value valid, and don't transform it.
• Return with a new value: Consider the value valid, but transform it to something else (eg. a parsed version).
• Throw or return a ValidationError: Consider the value invalid; the message of the error is what shows up in the validation results.
• Throw with a different kind of error: Indicate that something is wrong (eg. there is a bug in the code); this error will be passed through as-is, and validation will be aborted.
• Return a validationResult object: This can be done to return multiple errors, or a combination of errors and a new value. Unless you're writing a combinator, you probably don't need this.

Importantly, you can write these functions yourself, and custom validators - whether written by you or by someone else - are on equal footing with the 'official' validators. They are just as easy to use, and just as easy to combine. In fact, all of the official validators are packaged as if they were third-party packages!

Validating a value or a function's arguments, then, is just a matter of calling one of the validation functions with the desired validation schema. Either it will pass (and return the validated value, optionally transformed), or it will fail and throw an AggregrateValidationError with a clear description of what's wrong:

TODO: Insert error example here

There are a number of different validation functions included in @validatem/core:

• validateArguments: This validates a function's arguments against a validation schema. The schema describes the complete set of arguments, and the validation rules for each of them.
• validateOptions: Like validateArguments, but specifically for functions which only take a single options argument. You can directly specify the allowable options as the schema. Note that this does not work for React components; see validate-props below.
• validateValue: This validates an arbitrary value against a validation schema. The schema is directly applied to the value.
• testValue: Like validateValue, but instead of throwing an error, it returns a boolean that indicates whether the value matched the schema. This should not be used for actual validation; it's meant to be used for cases like "this function allows a few different kinds of input, and I need to execute different logic for each". You'd then use testValue to reuse the same validators in your conditional logic.

Additionally, some more validation utility functions are available as separate packages:

• validate-form: This validates incoming form data, and specially formats error metadata so that it's easy to eg. highlight the failing fields.
• validate-props: This validates the props for a functional React component. Because those components actually receive more than one argument, even if you usually only interact with the first one, the usual validateOptions doesn't work here.

Transforming values

TODO: explain why defaultTo etc. are useful, self-documenting

Combining (composing) validators

TODO: show array syntax TODO: show why wrapError can be useful

TODO: explain how linters can interfere? TODO: explain how either can be used like a match statement, like is done in raqb with wrapping