Skip to content

Latest commit

 

History

History
59 lines (41 loc) · 2.6 KB

Parser-not-validator.md

File metadata and controls

59 lines (41 loc) · 2.6 KB
Raw

Parser, not validator

While this package provides API for generating both parsers and validators, parser should be preferred if that fits your use case.

Why?

Using the parser API ensures that the object is never present in your code in parsed but not validated form, significantly reducing the number of mistakes that can come from using unvalidated raw objects.

Apart from that, it allows some checks in the validation to be fast-tracked for clarity and performance if the input is known to be from JSON.parse and can not contain, e.g. undefined variables. That fast-tracking could be also enabled via the isJSON option of the validator, but it should be used only when the input is definitely coming from a JSON.parse without a reviver.

Differences between parser and validator

validator(schema, options) creates a validate(object) function which accepts input after it has been parsed from JSON. It will return either true or false and errors would be reported as a property of validate function: validate.errors (if includeErrors option is enabled).

parser(schema, options) creates a similar parse(string) function, which accepts a raw string containing JSON-encoded input, and returns a parse result as an object { valid, error, errors, value }.

  1. valid is a boolean flag indicating if parsing and validation succeeded (true) or not (false).

  2. error is the first error message in a human-readable form. Included if includeErrors option is enabled.

  3. errors is a list of the original validation errors, included only if includeErrors option is enabled. Will be undefined if validation succeeded (even if JSON.parse failed).

    Has the same form as errors produced by the validator(schema, options) API.

    Will be limited to at most one error unless allErrors option is enabled (in addition to includeErrors).

    See also Error handling documentation on the exact format of the errors property.

  4. value is the result of parsing and validation. If either parsing or validation failed, value is undefined.

    It is affected by the post-processing via removeAdditional and useDefaults options, if enabled (both disabled by default).

This naming is designed to be compatible with upstream spec conventions for equivalent properties.

Parser operates in strong mode by default. To override it, use mode: 'default' option.

Parsers can be likewise exported to js code by using parser.toModule().