A library for reflectable runtime validation of json values. A mix of io-ts and JSON Schema. This library is still in its early development. The API is not yet final.
yarn add @hediet/semantic-json
The most important concept of this library is the serializer.
A serializer can deserialize JSON to a typed value and serialize the value back to JSON.
All functions to construct serializers start with an s
.
Serializers can be composed, as the following example demonstrates:
// All serializers start with an `s`.
import {
sObject,
sString,
sArrayOf,
optionalProp,
} from "@hediet/semantic-json";
import { expect } from "chai";
const contactBook = sArrayOf(
sObject({
firstName: sString(),
lastName: sString(),
city: optionalProp(sString(), {
description: "The city where the contact lives in.",
}),
}),
{ minLength: 1 }
);
expect(() => {
const value = contactBook
.deserialize([{ firstName: "Test" }])
// getValidValue throws and complains that "lastName" is missing.
.getValidValue();
// value is of type { firstName: string, lastName: string, city?: string }[]
console.log(value[0].firstName, value[0].lastName);
}).to.throw();
To generate typescript declaration types, it is recommended to name the serializers.
The TypeScriptTypeGenerator
will be moved to its own package at some later point.
import {
sObject,
sString,
sArrayOf,
namespace,
TypeScriptTypeGenerator,
} from "@hediet/semantic-json";
const myNs = namespace("demo.org");
class Contact {
constructor(private firstName: string, private lastName: string) {}
public toString() {
return `${this.firstName} ${this.lastName}`;
}
}
const contact = sObject({
firstName: sString(),
lastName: sString(),
});
const contactBook = sArrayOf(contact.defineAs(myNs("Contact"))).defineAs(
myNs("ContactBook")
);
const g = new TypeScriptTypeGenerator();
const tsType = g.getType(contactBook);
equal(tsType, "ContactBook");
equal(
g.getDefinitionSource(),
`type ContactBook = (Contact)[];
type Contact = {
firstName: string;
lastName: string;
/**
* The city where the contact lives in.
*/
city?: string;
};`
);