type-level-schema

This library's goal

This library tries to minimize the amount of duplication of runtime type assertions, and compile time interfaces. This library will generate the appropriate interfaces for JSON schema objects. This library will not ship a runtime JSON schema validator, there are many of these already and most are quite good.

Example: ajv

import { Schema, Schematize } from 'type-level-schema';
import * as ajv from 'ajv';

const validate = <S extends Schema>(schema: S, thing: any): thing is Schematize<S> => {
    return (new ajv()).validate(schema, thing) as boolean;
};

// this helper assures that the schema you are specifying is a valid schema using compile-time types
// it also helps eliminate TS type widening: 'object' as 'object', 'string' as 'string', etc.
const asSchema = <S extends Schema>(schema: S) => schema;

const schema = asSchema({
    type: 'object',
    parameters: {
        id: { type: 'string' },
        page: { type: 'number' },
    },
});

const getData = async () => {
    const fetchedData = await fetch('/some/api/call').then(data => data.json()) as any;

    if (validate(schema, fetchedData)) return schema;
    throw new Error('oops');
}

const x = await getData(); // => { id: string, page: number };

This library is tested using both ajv and jsonschema as these are two of the more popular JSON Schema validators. This library should work with any JSON Schema validator that adheres to the JSON Schema standard.

Why?

Typescript adds static type safety to the internals of javascript libraries. Unfortunately, because typescript cannot control the type and shape of data being sent into a well-typed system, type level bugs can still occur. One way to deal with this is checking types at runtime. For instance:

const doThing = (x: number, y: string) => {
    if (typeof x !== 'number') throw new Error('expected a number');
    return parseInt(y) + x;
};

This example checks types of variables passed in by some consumer of this code (who apparently isn't using typescript).

Another (perhaps more common) example is:

interface ApiData {
    id: string;
    page: number;
    nextUri: string;
    data: string[];
}
const getDataFromSomeoneElsesAPI = (): Promise<ApiData> => {
    return fetch('/some/api/call').then(data => data.json()) as any;
};

Let's just hope that someoneElsesApi doesn't decide to change their contracts..

A runtime solution could look like:

const schema = {
    type: 'object',
    parameters: {
        id: { type: 'string' },
        page: { type: 'number' },
    },
};

interface ApiData {
    id: string;
    page: number;
};

const getData = async (): Promise<ApiData> => {
    const fetchedData = await fetch('/some/api/call').then(data => data.json()) as any;

    if (jsonSchemaValidator(schema, fetchedData)) return fetchedData;
    throw new Error("Expected fetched data to match schema, but it didn't :(");
};

Unfortunately, here we are specifying the expected shape of the data twice. This means twice as many places to change our contract when the api call changes. Twice as much code. Twice as many places to screw up.