# @codenhub/validation

> Validation for TypeScript where each validator is a small standalone function, so a package or app ships only the checks it uses. Works for a single value such as an email or a port, and for whole objects such as forms. The package is experimental.

A validator takes any input and returns `{ ok: true, value }` or `{ ok: false, error: { issues } }`; it never throws for invalid input. Create one by calling a factory, then call it with the value: `email()(input)`, `number({ int: true, min: 0 })(input)`. Every factory takes its own arguments, then options, then checks, which are rules for rarer cases: `string({ min: 3 }, startsWith("a"))`. Every validator that reports an issue takes a `message` option. Ready-made validators cover strings, numbers, bigints, booleans, symbols, dates, functions, literals and enums, and formats such as email, url, domain, ip, cidr, phone, uuid, datetime, time, duration, semver, slug, jwt, creditCard and port. `url` and `email` take validators for their parts (`url({ host: hostname() })`), and `searchParams` reads a query string into typed values. Collections (`array`, `tuple`, `record`, `set`, `map`), `union`, `tagged`, `intersection`, `optional` (with an optional default), `nullable`, `transform` and `lazy` combine them. Build objects with `object`, add rules with `check`, build your own with `format` and `guard`, chain with `pipe`, and read the type with `Infer`. Text input is converted with the `coerce*` validators, and `standard` exposes a validator as a Standard Schema. Issues carry a code, a path and params, never the input; `formatIssue` and `flatten` turn them into text from a message map you pass, `englishMessages` for the built-in English, or your own to reword or localize. A validator with an asynchronous check is an `AsyncValidator` and must be awaited.

## Documentation

- [Documentation overview](docs/index.md): The idea, results, objects, combining validators, and sync versus async.
- [Validator reference](docs/validators.md): Every validator, check and combinator with its options and the issue it reports, and the parts of `url` and `email`.
- [Custom validators](docs/custom-validators.md): Rules with `check`, validators with `format` and `guard`, asynchronous rules and testing.
- [Coercion](docs/coercion.md): `coerceString`, `coerceNumber`, `coerceBoolean`, `coerceBigint` and `coerceDate` for text input such as environment variables and form fields.
- [Standard Schema](docs/standard-schema.md): `standard(validator, messages)` for libraries that accept a Standard Schema.
- [Issues and messages](docs/errors.md): The shape of an issue, built-in codes and params, message text, the `message` option, localization and form errors.
- [API reference](docs/reference/index.md): Every export with its signature and documentation, generated from the source.
- [Changelog](docs/changelog/index.md): Release notes, and the migrations from 0.1.0 and from 0.0.1.
