Introduction
Overview
Tyrann is a TypeScript HTTP API manager. It enables us to define HTTP APIs in the following fashion. 🎉
import { tyrann } from 'tyrann-io';
import * as t from 'io-ts';
const apis = tyrann({
'/user/{id}': {
get: {
path: t.type({
id: t.number,
}),
response: {
200: t.type({
name: t.string,
address: t.string,
}),
},
}
},
});
To explain a little, the above code defines an API /user/{id}
. It takes an id: number
as input, and should returns with an object in the following shape:
{
name: string;
address: string;
}
Why Tyrann IO
Tyrann IO is useful when we are not allowed to automatically generate a fully-typed HTTP client. A typed HTTP client is useful because a simple JSON.parse(response) as UserResponse
doesn't check the type of response, which lets landmine into your typing. We do have ways to automatically generate a correctly typed HTTP client, such as gRPC, OpenAPI tools and GraphQL. However, sometimes the tech-stack of the serverside doesn't support sound type definition, so we have to handcode the client by ourselves.
In reality, these problems happen:
- The HTTP server doesn't generate the client (in TypeScript).
- We don't have the backend API specs.
- Simple methods like
JSON.parse(response) as UserResponse
does not guarantee runtime type safety. The server can update or change, or error, making unchecked data into the system, leading to hard-to-trace problems.
Our developers have tested tyrann-io
in production for a few projects, proving its usefulness. The typed client created with tyrann-io
proves to be a vigilant sentinel to avoid errors propagating in our app.
Installation
yarn add tyrann-io
# OR
npm i tyrann-io
Documentation
User Guide
Please refer to README.md#user-guide
API Reference
Please refer to README.md#api-definition
Source Code
The code lives on GitHub wopal-dev/tyrann-io. Issues and contributions are welcome! 👋