Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/skyleague/therefore
Therefore, the JSON Schema toolkit for TypeScript.
https://github.com/skyleague/therefore
json-schema skyleague typescript
Last synced: about 1 month ago
JSON representation
Therefore, the JSON Schema toolkit for TypeScript.
- Host: GitHub
- URL: https://github.com/skyleague/therefore
- Owner: skyleague
- License: mit
- Created: 2022-08-12T08:16:25.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-21T18:48:47.000Z (7 months ago)
- Last Synced: 2024-05-22T11:52:23.747Z (7 months ago)
- Topics: json-schema, skyleague, typescript
- Language: TypeScript
- Homepage: https://skyleague.io
- Size: 3.13 MB
- Stars: 5
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# ∴ Therefore _[@skyleague/therefore](https://skyleague.github.io/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](https://skyleague.github.io/therefore/)
The documentation can be found [here](https://skyleague.github.io/therefore/).
## Security
Therefore internally uses [`Ajv`](https://github.com/ajv-validator/ajv) for its validation. That means that the security considerations of using Therefore become a superset of those of [`Ajv`](https://github.com/ajv-validator/ajv#security-considerations). 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](#alternative-projects) 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:
1. You define your schema definitions in files with a specific extension (`.schema.ts` by default)
2. You run Therefore on the folder `npx therefore -f src`
3. Therefore will generate a type file with extension `.type.ts` for you with helper functions of all exported symbols, and in a subfolder `schemas` you will find all generated JSON Schemas waiting for you.
4. No runtime dependency on Therefore :)
## Install
Install Therefore using [`npm`](https://www.npmjs.com/):
```console
$ npm install --save-dev @skyleague/therefore
```
## Usage
Let's get started with a simple JSON Schema taken as an example:
**example.schema.ts**
```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:
```console
$ 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.
```
Typescript (Output)
JSON Schema (Output)
**example.type.ts**
```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,
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**
```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
```console
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`](https://github.com/colinhacks/zod)
- [`Runtypes`](https://github.com/pelotom/runtypes); similar interface, but completely runtime defined.
- [`TypeBox`](https://github.com/sinclairzx81/typebox)
- [`io-ts`](https://github.com/gcanti/io-ts)
- [`joi`](https://github.com/sideway/joi)
- [`json-schema-to-typescript`](https://github.com/bcherny/json-schema-to-typescript)
- [`typescript-json-schema`](https://github.com/YousefED/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` instead of `Record`
- 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`](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](./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.