@skyleague/therefore
v6.0.0
Published
Therefore the JSON TypeScript toolkit.
Downloads
2,912
Readme
∴ Therefore @skyleague/therefore
Such is the advantage of a well-constructed language that its simplified notation often becomes the source of profound theories.
- Pierre-Simon de Laplace
Therefore empowers you to generate JSON Schemas and typescript types.
It is hard to keep JSON Schemas and types aligned, especially in a world of growing api complexity. Therefore, we want to simplify the most frustrating problems associated with JSON validation and typing.
Therefore is:
- clean schema definition that reads similar to typescript interfaces
- handwritten types look very similar to the generated schemas
- easily (re)generate schemas with a simple CLI command
- no runtime dependencies; Therefore is designed such that it only has to be a development package
- strict by default; less api-surface, less confusion, happier code
Documentation
The documentation can be found here.
Security
Therefore internally uses Ajv
for its validation. That means that the security considerations of using Therefore become a superset of those of Ajv
. By default Therefore tries to implement the strictest interface and validation given a schema.
Background
Having runtime validation of your typescript types is not supported out of the box. More than one has tried to solve this problem. However, many of those implementations - we felt - are too complex. We wanted to separate the validation (a challenging situation in itself) and the schema part. And thus, we looked at the different schema validation implementations, where only one stood out: JSON Schema.
The usage of JSON Schema has grown incredibly over the last few years. Most languages now have a stable validator implementation, and OpenAPI (the successor of swagger) fully adopted the JSON Schema specification. As a result, we now have good tools to define and validate API interfaces.
So why not take advantage? As we found out, there is a problem with successful schema validation in typescript - keeping your schemas synchronized with your code can be incredibly hard without proper tooling. Writing JSON Schema is verbose, but reading it requires more effort than just glancing at a typescript definition. That is not the most significant problem, but we firmly believe schema definitions should be strict, readable and concise.
This is where Therefore comes in. Therefore itself does not do any validation. At all. Therefore allows you to write very concise JSON Schemas supported by excellent tooling to help you wherever it can—creating a reference to another variable? No problem. You don't want to export that particular object? Consider it done. Do you want to reuse the JSON Schema in an OpenAPI specification? Of course, go ahead!
In a nutshell:
- You define your schema definitions in files with a specific extension (
.schema.ts
by default) - You run Therefore on the folder
npx therefore -f src
- Therefore will generate a type file with extension
.type.ts
for you with helper functions of all exported symbols, and in a subfolderschemas
you will find all generated JSON Schemas waiting for you. - No runtime dependency on Therefore :)
Install
Install Therefore using npm
:
$ npm install --save-dev @skyleague/therefore
Usage
Let's get started with a simple JSON Schema taken as an example:
example.schema.ts
import { $number, $object, $string, $validator } from '@skyleague/therefore'
export const person = $validator(
$object({
firstName: $string({
description: "The person's first name.",
}),
lastName: $string,
age: $number,
})
)
With this schema defined, we can generate the typescript types and JSON schema file:
$ therefore -f examples/json-schema/
scanning examples/json-schema/example.schema.ts
- found Person
$ prettier --write examples/json-schema/example.type.ts examples/json-schema/schemas/person.schema.json
examples/json-schema/example.type.ts 149ms
examples/json-schema/schemas/person.schema.json 17ms
Done in 0.41s.
example.type.ts
export interface Person {
/**
* The person's first name.
*/
firstName: string
lastName: string
age: number
}
export const Person = {
validate: require('./schemas/person.schema.js') as ValidateFunction<Person>,
get schema() {
return Person.validate.schema
},
source: `${__dirname}example.schema`,
sourceSymbol: 'person',
is: (o: unknown): o is Person => Person.validate(o) === true,
} as const
schemas/person.schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "The person's first name."
},
"lastName": {
"type": "string"
},
"age": {
"type": "number"
}
},
"required": ["firstName", "lastName", "age"],
"additionalProperties": false
}
Examples
CLI
You can run Therefore directly from the CLI
USAGE
$ therefore
Options:
--version Show version number [boolean]
--help Show help [boolean]
-f, --files globs to scan for schemas [array] [required]
-i, --ignore-pattern globs to exclude
[array] [required] [default: ["**/*.d.ts","node_modules"]]
--compile [boolean] [default: true]
--ext [string] [default: ".schema.ts"]
--out-ext [string] [default: ".type.ts"]
API
Alternative projects
In no particular order, the following libraries try to solve similar problems (albeit very different):
Zod
Runtypes
; similar interface, but completely runtime defined.TypeBox
io-ts
joi
json-schema-to-typescript
typescript-json-schema
- The list goes on....
PR's are very welcome if you think your project is missing here.
When not to use Therefore?
- By default, we create as strict a JSON Schema/type as possible. We are aware that this doesn't suit everyone's needs.
- additional properties will result in validation errors without extra work
- indexable types are always explicitly nullable, i.e.
Record<string, string | undefined>
instead ofRecord<string, string>
- We only support JSON Schema validation through Ajv. If you do not want to/can't use Ajv, Therefore probably isn't for you.
- Therefore is an insanely opinionated implementation of runtime validation of types; It will not fit everyone's needs.
This open source library package is part of the SkyLeague modern application delivery stack.
Support
SkyLeague provides Enterprise Support on this open-source library package at clients across industries. Please get in touch via https://skyleague.io
.
If you are not under Enterprise Support, feel free to raise an issue and we'll take a look at it on a best-effort basis!
License & Copyright
This library is licensed under the MIT License (see LICENSE.md for details).
If you using this SDK without Enterprise Support, please note this (partial) MIT license clause:
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND
Copyright (c) 2022, SkyLeague Technologies B.V.. 'SkyLeague' and the astronaut logo are trademarks of SkyLeague Technologies, registered at Chamber of Commerce in The Netherlands under number 86650564.
All product names, logos, brands, trademarks and registered trademarks are property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, trademarks and brands does not imply endorsement.