@kaito-http/core 3.0.0-beta.16 → 3.0.0-beta.21

package/src/router/router.test.ts

@@ -0,0 +1,269 @@
+import assert from 'node:assert';
+import {describe, it} from 'node:test';
+import {z} from 'zod';
+import {KaitoError} from '../error.ts';
+import {Router} from './router.ts';
+
+type Context = {
+	userId: string;
+};
+
+type AuthContext = Context & {
+	isAdmin: boolean;
+};
+
+describe('Router', () => {
+	describe('create', () => {
+		it('should create an empty router', () => {
+			const router = Router.create<Context>();
+			assert.strictEqual(router.routes.size, 0);
+		});
+	});
+
+	describe('route handling', () => {
+		it('should handle GET requests', async () => {
+			const router = Router.create<Context>().get('/users', {
+				run: async () => ({users: []}),
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/users', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 200);
+			assert.deepStrictEqual(data, {
+				success: true,
+				data: {users: []},
+				message: 'OK',
+			});
+		});
+
+		it('should handle POST requests with body parsing', async () => {
+			const router = Router.create<Context>().post('/users', {
+				body: z.object({name: z.string()}),
+				run: async ({body}) => ({id: '1', name: body.name}),
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(
+				new Request('http://localhost/users', {
+					method: 'POST',
+					headers: {'Content-Type': 'application/json'},
+					body: JSON.stringify({name: 'John'}),
+				}),
+			);
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 200);
+			assert.deepStrictEqual(data, {
+				success: true,
+				data: {id: '1', name: 'John'},
+				message: 'OK',
+			});
+		});
+
+		it('should handle URL parameters', async () => {
+			const router = Router.create<Context>().get('/users/:id', {
+				run: async ({params}) => ({id: params.id}),
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/users/456', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 200);
+			assert.deepStrictEqual(data, {
+				success: true,
+				data: {id: '456'},
+				message: 'OK',
+			});
+		});
+
+		it('should handle query parameters', async () => {
+			const router = Router.create<Context>().get('/search', {
+				query: {
+					q: z.string(),
+					limit: z
+						.string()
+						.transform(value => Number(value))
+						.pipe(z.number()),
+				},
+				run: async ({query}) => ({
+					query: query.q,
+					limit: query.limit,
+				}),
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/search?q=test&limit=10', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 200);
+			assert.deepStrictEqual(data, {
+				success: true,
+				data: {query: 'test', limit: 10},
+				message: 'OK',
+			});
+		});
+	});
+
+	describe('middleware and context', () => {
+		it('should transform context through middleware', async () => {
+			const router = Router.create<Context>()
+				.through(async ctx => ({
+					...ctx,
+					isAdmin: ctx.userId === 'admin',
+				}))
+				.get('/admin', {
+					run: async ({ctx}) => ({
+						isAdmin: (ctx as AuthContext).isAdmin,
+					}),
+				});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: 'admin'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/admin', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 200);
+			assert.deepStrictEqual(data, {
+				success: true,
+				data: {isAdmin: true},
+				message: 'OK',
+			});
+		});
+	});
+
+	describe('error handling', () => {
+		it('should handle KaitoError with custom status', async () => {
+			const router = Router.create<Context>().get('/error', {
+				run: async () => {
+					throw new KaitoError(403, 'Forbidden');
+				},
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/error', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 403);
+			assert.deepStrictEqual(data, {
+				success: false,
+				data: null,
+				message: 'Forbidden',
+			});
+		});
+
+		it('should handle generic errors with server error handler', async () => {
+			const router = Router.create<Context>().get('/error', {
+				run: async () => {
+					throw new Error('Something went wrong');
+				},
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Custom Error Message'}),
+			});
+
+			const response = await handler(new Request('http://localhost/error', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 500);
+			assert.deepStrictEqual(data, {
+				success: false,
+				data: null,
+				message: 'Custom Error Message',
+			});
+		});
+	});
+
+	describe('router merging', () => {
+		it('should merge routers with prefix', async () => {
+			const userRouter = Router.create<Context>().get('/me', {
+				run: async ({ctx}) => ({id: ctx.userId}),
+			});
+
+			const mainRouter = Router.create<Context>().merge('/api', userRouter);
+
+			const handler = mainRouter.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/api/me', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 200);
+			assert.deepStrictEqual(data, {
+				success: true,
+				data: {id: '123'},
+				message: 'OK',
+			});
+		});
+	});
+
+	describe('404 handling', () => {
+		it('should return 404 for non-existent routes', async () => {
+			const router = Router.create<Context>();
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/not-found', {method: 'GET'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 404);
+			assert.deepStrictEqual(data, {
+				success: false,
+				data: null,
+				message: 'Cannot GET /not-found',
+			});
+		});
+
+		it('should return 404 for wrong method on existing path', async () => {
+			const router = Router.create<Context>().get('/users', {
+				run: async () => ({users: []}),
+			});
+
+			const handler = router.freeze({
+				getContext: async () => ({userId: '123'}),
+				onError: async () => ({status: 500, message: 'Internal Server Error'}),
+			});
+
+			const response = await handler(new Request('http://localhost/users', {method: 'POST'}));
+			const data = await response.json();
+
+			assert.strictEqual(response.status, 404);
+			assert.deepStrictEqual(data, {
+				success: false,
+				data: null,
+				message: 'Cannot POST /users',
+			});
+		});
+	});
+});

package/src/router/router.ts

@@ -0,0 +1,254 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import {KaitoError, WrappedError} from '../error.ts';
+import {KaitoRequest} from '../request.ts';
+import {KaitoResponse} from '../response.ts';
+import type {AnyQueryDefinition, AnyRoute, Route} from '../route.ts';
+import type {ServerConfig} from '../server.ts';
+import type {ErroredAPIResponse, Parsable} from '../util.ts';
+import type {KaitoMethod} from './types.ts';
+
+type PrefixRoutesPathInner<R extends AnyRoute, Prefix extends `/${string}`> =
+	R extends Route<
+		infer ContextFrom,
+		infer ContextTo,
+		infer Result,
+		infer Path,
+		infer Method,
+		infer Query,
+		infer BodyOutput
+	>
+		? Route<ContextFrom, ContextTo, Result, `${Prefix}${Path}`, Method, Query, BodyOutput>
+		: never;
+
+type PrefixRoutesPath<Prefix extends `/${string}`, R extends AnyRoute> = R extends R
+	? PrefixRoutesPathInner<R, Prefix>
+	: never;
+
+export type RouterState<Routes extends AnyRoute, ContextFrom, ContextTo> = {
+	routes: Set<Routes>;
+	through: (context: ContextFrom) => Promise<ContextTo>;
+};
+
+export type InferRoutes<R extends Router<any, any, any>> = R extends Router<any, any, infer R> ? R : never;
+
+export class Router<ContextFrom, ContextTo, R extends AnyRoute> {
+	private readonly state: RouterState<R, ContextFrom, ContextTo>;
+
+	public static create = <Context>(): Router<Context, Context, never> =>
+		new Router<Context, Context, never>({
+			through: async context => context,
+			routes: new Set(),
+		});
+
+	private static parseQuery<T extends AnyQueryDefinition>(schema: T | undefined, url: URL) {
+		if (!schema) {
+			return {};
+		}
+
+		const result: Record<PropertyKey, unknown> = {};
+		for (const key in schema) {
+			if (!schema.hasOwnProperty(key)) continue;
+			const value = url.searchParams.get(key);
+			result[key] = (schema[key] as Parsable).parse(value);
+		}
+
+		return result as {
+			[Key in keyof T]: ReturnType<T[Key]['parse']>;
+		};
+	}
+
+	public constructor(options: RouterState<R, ContextFrom, ContextTo>) {
+		this.state = options;
+	}
+
+	public get routes() {
+		return this.state.routes;
+	}
+
+	public add = <
+		Result,
+		Path extends string,
+		Method extends KaitoMethod,
+		Query extends AnyQueryDefinition = {},
+		Body extends Parsable = never,
+	>(
+		method: Method,
+		path: Path,
+		route:
+			| (Method extends 'GET'
+					? Omit<
+							Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>,
+							'body' | 'path' | 'method' | 'through'
+						>
+					: Omit<Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>, 'path' | 'method' | 'through'>)
+			| Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>['run'],
+	): Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>> => {
+		const merged: Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body> = {
+			// TODO: Ideally fix the typing here, but this will be replaced in Kaito v4 where all routes must return a Response (which we can type)
+			...((typeof route === 'object' ? route : {run: route}) as {run: never}),
+			method,
+			path,
+			through: this.state.through,
+		};
+
+		return new Router({
+			...this.state,
+			routes: new Set([...this.state.routes, merged]),
+		});
+	};
+
+	public readonly merge = <PathPrefix extends `/${string}`, OtherRoutes extends AnyRoute>(
+		pathPrefix: PathPrefix,
+		other: Router<ContextFrom, unknown, OtherRoutes>,
+	): Router<ContextFrom, ContextTo, Extract<R | PrefixRoutesPath<PathPrefix, OtherRoutes>, AnyRoute>> => {
+		const newRoutes = [...other.state.routes].map(route => ({
+			...route,
+			path: `${pathPrefix}${route.path as string}`,
+		}));
+
+		return new Router<ContextFrom, ContextTo, Extract<R | PrefixRoutesPath<PathPrefix, OtherRoutes>, AnyRoute>>({
+			...this.state,
+			routes: new Set([...this.state.routes, ...newRoutes] as never),
+		});
+	};
+
+	public freeze = (server: Omit<ServerConfig<ContextFrom>, 'router'>) => {
+		const routes = new Map<string, Map<KaitoMethod, AnyRoute>>();
+
+		for (const route of this.state.routes) {
+			if (!routes.has(route.path)) {
+				routes.set(route.path, new Map());
+			}
+
+			routes.get(route.path)!.set(route.method, route);
+		}
+
+		const findRoute = (method: KaitoMethod, path: string): {route?: AnyRoute; params: Record<string, string>} => {
+			const params: Record<string, string> = {};
+			const pathParts = path.split('/').filter(Boolean);
+
+			for (const [routePath, methodHandlers] of routes) {
+				const routeParts = routePath.split('/').filter(Boolean);
+
+				if (routeParts.length !== pathParts.length) continue;
+
+				let matches = true;
+				for (let i = 0; i < routeParts.length; i++) {
+					const routePart = routeParts[i];
+					const pathPart = pathParts[i];
+
+					if (routePart && pathPart && routePart.startsWith(':')) {
+						params[routePart.slice(1)] = pathPart;
+					} else if (routePart !== pathPart) {
+						matches = false;
+						break;
+					}
+				}
+
+				if (matches) {
+					const route = methodHandlers.get(method);
+					if (route) return {route, params};
+				}
+			}
+
+			return {params};
+		};
+
+		return async (req: Request): Promise<Response> => {
+			const url = new URL(req.url);
+			const method = req.method as KaitoMethod;
+
+			const {route, params} = findRoute(method, url.pathname);
+
+			if (!route) {
+				const body: ErroredAPIResponse = {
+					success: false,
+					data: null,
+					message: `Cannot ${method} ${url.pathname}`,
+				};
+
+				return Response.json(body, {status: 404});
+			}
+
+			const request = new KaitoRequest(url, req);
+			const response = new KaitoResponse();
+
+			try {
+				const body = route.body ? await route.body.parse(await req.json()) : undefined;
+				const query = Router.parseQuery(route.query, url);
+
+				const rootCtx = await server.getContext(request, response);
+				const ctx = await route.through(rootCtx);
+
+				const result = await route.run({
+					ctx,
+					body,
+					query,
+					params,
+				});
+
+				if (result instanceof Response) {
+					return result;
+				}
+
+				return response.toResponse({
+					success: true,
+					data: result,
+					message: 'OK',
+				});
+			} catch (e) {
+				const error = WrappedError.maybe(e);
+
+				if (error instanceof KaitoError) {
+					return response.status(error.status).toResponse({
+						success: false,
+						data: null,
+						message: error.message,
+					});
+				}
+
+				const {status, message} = await server
+					.onError({error, req: request})
+					.catch(() => ({status: 500, message: 'Internal Server Error'}));
+
+				return response.status(status).toResponse({
+					success: false,
+					data: null,
+					message,
+				});
+			}
+		};
+	};
+
+	private readonly method =
+		<M extends KaitoMethod>(method: M) =>
+		<Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(
+			path: Path,
+			route:
+				| (M extends 'GET'
+						? Omit<Route<ContextFrom, ContextTo, Result, Path, M, Query, Body>, 'body' | 'path' | 'method' | 'through'>
+						: Omit<Route<ContextFrom, ContextTo, Result, Path, M, Query, Body>, 'path' | 'method' | 'through'>)
+				| Route<ContextFrom, ContextTo, Result, Path, M, Query, Body>['run'],
+		) => {
+			return this.add<Result, Path, M, Query, Body>(method, path, route);
+		};
+
+	public get = this.method('GET');
+	public post = this.method('POST');
+	public put = this.method('PUT');
+	public patch = this.method('PATCH');
+	public delete = this.method('DELETE');
+	public head = this.method('HEAD');
+	public options = this.method('OPTIONS');
+
+	public through = <NextContext>(
+		transform: (context: ContextTo) => Promise<NextContext>,
+	): Router<ContextFrom, NextContext, R> =>
+		new Router<ContextFrom, NextContext, R>({
+			routes: this.state.routes,
+			through: async context => {
+				const fromCurrentRouter = await this.state.through(context);
+				return transform(fromCurrentRouter);
+			},
+		});
+}

package/src/router/types.ts

@@ -0,0 +1 @@
+export type KaitoMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';

package/src/server.ts

@@ -0,0 +1,87 @@
+import type {KaitoError} from './error.ts';
+import type {KaitoRequest} from './request.ts';
+import type {Router} from './router/router.ts';
+import type {GetContext} from './util.ts';
+
+export type Before = (req: Request) => Promise<Response | void | undefined>;
+
+export type ServerConfig<ContextFrom> = {
+	/**
+	 * The root router to mount on this server.
+	 */
+	router: Router<ContextFrom, unknown, any>;
+
+	/**
+	 * A function that is called to get the context for a request.
+	 *
+	 * This is useful for things like authentication, to pass in a database connection, etc.
+	 *
+	 * It's fine for this function to throw; if it does, the error is passed to the `onError` function.
+	 */
+	getContext: GetContext<ContextFrom>;
+
+	/**
+	 * A function that is called when an error occurs inside a route handler.
+	 *
+	 * The result of this function is used to determine the response status and message, and is
+	 * always sent to the client. You could include logic to check for production vs development
+	 * environments here, and this would also be a good place to include error tracking
+	 * like Sentry or Rollbar.
+	 *
+	 * @param arg - The error and the request
+	 * @returns A KaitoError or an object with a status and message
+	 */
+	onError: (arg: {error: Error; req: KaitoRequest}) => Promise<KaitoError | {status: number; message: string}>;
+
+	/**
+	 * A function that is called before every request. Most useful for bailing out early in the case of an OPTIONS request.
+	 *
+	 * @example
+	 * ```ts
+	 * before: async req => {
+	 * 	if (req.method === 'OPTIONS') {
+	 * 		return new Response(null, {status: 204});
+	 * 	}
+	 * }
+	 * ```
+	 */
+	before?: Before;
+
+	/**
+	 * Transforms the response before it is sent to the client. Very useful for settings headers like CORS.
+	 *
+	 * You can also return a new response in this function, or just mutate the current one.
+	 *
+	 * @example
+	 * ```ts
+	 * transform: async (req, res) => {
+	 * 	res.headers.set('Access-Control-Allow-Origin', 'http://localhost:3000');
+	 * 	res.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+	 * 	res.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+	 * 	res.headers.set('Access-Control-Max-Age', '86400');
+	 * 	res.headers.set('Access-Control-Allow-Credentials', 'true');
+	 * }
+	 * ```
+	 */
+	transform?: (req: Request, res: Response) => Promise<Response | void | undefined>;
+};
+
+export function createKaitoHandler<Context>(config: ServerConfig<Context>) {
+	const handle = config.router.freeze(config);
+
+	return async (request: Request): Promise<Response> => {
+		if (config.before) {
+			const result = await config.before(request);
+			if (result instanceof Response) return result;
+		}
+
+		const response = await handle(request);
+
+		if (config.transform) {
+			const result = await config.transform(request, response);
+			if (result instanceof Response) return result;
+		}
+
+		return response;
+	};
+}