coerce

Type coercion for data that comes as strings: query parameters, FormData, environment variables, CSV.

Signature

coerce.string(msg?: Message): Schema<string>
coerce.number(msg?: Message): Schema<number>
coerce.boolean(msg?: Message): Schema<boolean>
coerce.date(msg?: Message): Schema<Date>

Parameters

Parameter	Type	Description
msg	Message	Custom message. Replaces the default messages for all errors of this schema

Conversions

Function	Conversion	Then validated as
coerce.string()	number, boolean, bigint → String(value)	string()
coerce.number()	string → trim → Number(value). An empty string stays empty	number()
coerce.boolean()	'true', '1', 'on', 'yes', 1 → true; 'false', '0', 'off', 'no', 0 → false. Case-insensitive	boolean()
coerce.date()	a non-empty string or a number → new Date(value)	date()

Values that already have the right type are not changed. Unsuitable values give a regular type error: coerce.number() on 'abc' → Must be a number.

Error codes

The same as the corresponding schema: required and string / number / boolean / date.

Examples

Query parameters

// GET /products?page=2&limit=20&inStock=1
const Query = object({
  page: optional(pipe(coerce.number(), integer(), min(1)), 1),
  limit: optional(pipe(coerce.number(), integer(), max(100)), 20),
  inStock: optional(coerce.boolean(), false),
});

parse(Query, req.query); // { page: 2, limit: 20, inStock: true }

FormData

const data = validate(Form, Object.fromEntries(new FormData(form)));

See also

• preprocess — custom coercion
• parse — environment variables example