Tyrann IO

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:

1. The HTTP server doesn't generate the client (in TypeScript).
2. We don't have the backend API specs.
3. 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! 👋