Getting started

⚠️

Please read all documentation. These docs are not complete and although almost all of the features of Kaito are described least somewhere on this website, it might not be where you would expect it to be. I don’t have infinite time to work on Kaito and its docs, so if you would like to help you can sponsor me on GitHub, or submit documentation PRs yourself. Thank you!

Installation

Kaito depends on zod for schema validation, make sure you install it too.

yarn add @kaito-http/core zod

Or with npm:

npm install @kaito-http/core zod

Concepts

Kaito is very simple to use, it revolves around a few basic concepts. Let’s go through the key principles.

Routes

A route is a function that processes HTTP requests and returns either a value (which will be JSON encoded) or a Response object. For example:

export const app = router().get('/users', async ({ctx}) => {
	return ctx.db.getUsers();
});

Router

The Kaito router is a class that holds all of our routes and their type information. Every app will have at least one router and they can be merged together so you can separate your routes into different files.

Context

Context is a variable that is generated on every single request. It is up to developers what to place inside their context, but it will be available to access in every single route. For example, you could include the req and res objects, a method to get the current session, etc.

Quickstart

Firstly, we need to setup our context. You can put this in a context.ts file, for example.

import {createUtilities} from '@kaito-http/core';
 
// Define the time that we started the server at
const serverStarted = Date.now();
 
// Context is generated on every request, and is available in every route.
// We can choose to pass in the request and response objects, as well as
// any other utilities (perhaps a database connection, ORM, other utils, etc).
export const {router, getContext} = createUtilities(async (req, res) => ({
	req,
	res,
	uptime: Date.now() - serverStarted,
}));

Secondly, we’ll need to create a router, a server, and our first route.

import {createServer} from '@kaito-http/core';
import {router, getContext} from './context';
 
const app = router().get('/', async ({ctx}) => {
	return {
		uptime: ctx.uptime,
		time_now: Date.now(),
	};
});
 
const server = createServer({
	// Pass our getContext function to the root server options
	getContext,
 
	// And pass our root router
	router: app,
 
	// Define an async `onError` handler, in case something goes wrong inside of the route.
	// More on that that later.
	onError: async ({error}) => {
		console.log(error);
 
		return {
			status: 500,
			message: error.message,
		};
	},
});
 
server.listen(8080);

Awesome! So we now have a server that can be accessed at http://localhost:8080/ that mounts a GET route to / which will respond with the server’s uptime, and the time now. If you run this file and navigate to http://localhost:8080/, you’ll see that result.

Introduction Help