JSON Type Validation

A TypeScript library to perform type checking and validation on untyped JSON data at runtime.

This library owes thanks to:

- JsonDecoder by Daniel van den Eijkel
- Type-safe JSON Decoder by Wesley Merkel
- The Elm Json.Decode API

Installation

``
npm i @mojotech/json-type-validation
`
Projects using < typescript@3.0.1 will need a polyfill for the unknown
type, such as unknown-ts.

Motivation

Let's say we're creating a web app for our pet sitting business, and we've
picked TypeScript as one of our core technologies. This is a great choice
because the extra stability and type safety that TypeScript provides is really
going to help us market our business.

We've defined the data we need to track about each client's pet:

`typescript
interface Pet {
name: string;
species: string;
age?: number;
isCute?: boolean;
}
`

And we've got some data about current client's pets which is stored as JSON:

`typescript
const croc: Pet = JSON.parse('{"name":"Lyle","species":"Crocodile","isCute":true}')
const moose: Pet = JSON.parse('{"name":"Bullwinkle","age":59}')
`

But that can't be right -- our data for moose is missing information required
for the Pet interface, but TypeScript compiles the code just fine!

Of course this isn't an issue with TypeScript, but with our own type
annotations. In TypeScript JSON.parse has a return type of any, which pushes
the responsibility of verifying the type of data onto the user. By assuming that
all of our data is correctly formed, we've left ourselves open to unexpected
errors at runtime.

Unfortunately TypeScript doesn't provide a good built-in way to deal with this
issue. Providing run-time type information is one of TypeScript's
non-goals,
and our web app is too important to risk using a forked version of TypeScript
with that added functionality.
Type guards
work, but are limited in that they circumvent type inference instead of working
with it, and can be cumbersome to write.

With json-type-validation we can define decoders that validate untyped json
input. Decoders are concise, composable, and typecheck against our defined types
and interfaces.

`typescript
import {Decoder, object, string, optional, number, boolean} from 'json-type-validation'

const petDecoder: Decoder = object({
name: string(),
species: string(),
age: optional(number()),
isCute: optional(boolean())
})
`

Finally, we can choose from a number of decoding methods to validate json and
report success or failure. When some json input fails validation the decoder
clearly shows how the data was malformed.

`typescript
const lyle: Pet = petDecoder.runWithException(croc)

const bullwinkle: Pet = petDecoder.runWithException(moose)
// Throws the exception:
// Input: {"name":"Bullwinkle","age":59}
// Failed at input: the key 'species' is required but was not present
`

Documentation

Documentation.

Building

$3

There exists some Nix infrastructure that can be used
to reproduce a build environment exactly. A helper shell script lives at
bin/jtv that you can use to enter environments for multiple uses.
You'll need to follow the directions on the Nix website to install and use the
Nix package manager.

* To enter a shell suitable for building the library run ./bin/jtv
build-shell. This will leave you in the root of the project and automatically
install any project and npm dependencies. You can run further yarn commands
here.
* To build the library for distribution and exit you can run ./bin/jtv distribute.
* To enter a build shell and run the build process, watching for changes, run
./bin/jtv build-watch.
* To run an arbitrary command in a build environment use ./bin/jtv run
COMMAND. For example, ./bin/jtv run yarn test` will run the tests and exit.