@lucania/schema v2.0.2

Schema

This library allows you to specify the schema for your data, and get compile time typings (help from your IDE) and runtime validation (throw errors if your data isn't in the right format).

With this library, you create objects that serve as a blueprint for what your data should look like. These objects are called Schemas.

Validation

The simplest possible validation:

import { $ } from "@lucania/schema";

// Create a Schema to represent a number.
const numberSchema = $.Number();

// Some data with an unknown type, likely coming from a file, network or untyped library.
const dataOfUnknownType: any = 123;

// Using our number Schema to validate that our untyped data is what we expect it to be, a number. "dataOfNumberType" now has the "number" type.
const dataOfNumberType = numberSchema.validate(dataOfUnknownType);

With this collection of Schemas, we can now start building more complex data structures. There are multiple way to represent different scenarios. This is done with the following constructs.

Creating Hierarchical Schema

These schemas can come together to allow you to define a blueprint for more complex data structures.

import { $ } from "@lucania/schema";

const WeaponSchema = $.Object({
    damage: $.Number(true).clamp(0, 100),
    forged: $.Date(false),
    affixtures: $.DynamicObject($.String())
});

const PersonSchema = $.Object({
    name: $.Object({
        first: $.String(true),
        middle: $.String(false),
        last: $.String(true)
    }),
    favoriteNumber: $.Number(true).ensure((data, pass) => data % 2 === 0, "Your favorite number must be a multiple of 2!"),
    age: $.Number(true).min(16, "You must be at least 16 years old!").max(100, "You must be at most 100 years old!"),
    weapon: WeaponSchema
});

Using Schema

With the schema definitions created, they can be used to validate data where the types are unknown. This data might come from fetch requests, information read from disk, or even JavaScript libraries that don't export their own type definitions, just to name a few examples.

import fs from "fs";

const personData = JSON.parse(fs.readFileSync("person.json", "utf8"));
const person = PersonSchema.validate(personData);

person now has the following compile-time type annotation based on PersonSchema.

At runtime, the object parsed from the person.json file will be validated to match this generated typing. If it does not match, a Schema.ValidationError will be thrown.