@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.25

package/src/adapters/node/static-content-server.ts

@@ -0,0 +1,239 @@
+import { createServer, type IncomingMessage, type Server as NodeHttpServer, type ServerResponse } from 'node:http';
+import { extname, join, normalize, sep } from 'node:path';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT, STATUS_MESSAGE } from '../../config/constants.ts';
+import { fileSystem } from '@ecopages/file-system';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { ServerUtils } from '../../utils/server-utils.module.ts';
+
+type NodeStaticContentServerOptions = {
+	hostname?: string;
+	port?: number;
+};
+
+/**
+ * Serves prebuilt static Ecopages output through Node's HTTP server.
+ *
+ * @remarks
+ * This server is used by the Node preview/build path once the app has already
+ * emitted its static output. It intentionally stays small: path sanitization,
+ * content-type selection, optional gzip serving, and 404 handling.
+ */
+export class NodeStaticContentServer {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly options: NodeStaticContentServerOptions;
+	private server: NodeHttpServer | null = null;
+
+	/**
+	 * Creates the Node static-content server for one built app output directory.
+	 */
+	constructor({ appConfig, options }: { appConfig: EcoPagesAppConfig; options?: NodeStaticContentServerOptions }) {
+		this.appConfig = appConfig;
+		this.options = {
+			hostname: options?.hostname ?? DEFAULT_ECOPAGES_HOSTNAME,
+			port: options?.port ?? DEFAULT_ECOPAGES_PORT,
+		};
+	}
+
+	/**
+	 * Returns whether the given content type should be served from a pre-gzipped
+	 * companion file when available.
+	 */
+	private shouldServeGzip(contentType: string): boolean {
+		return ['text/javascript', 'text/css'].includes(contentType);
+	}
+
+	/**
+	 * Normalizes a request pathname and rejects directory traversal attempts.
+	 */
+	private sanitizePath(pathname: string): string | null {
+		const withoutLeadingSlash = pathname.replace(/^\/+/, '');
+		const normalizedPath = normalize(withoutLeadingSlash);
+
+		if (normalizedPath.startsWith('..') || normalizedPath.includes(`..${sep}`)) {
+			return null;
+		}
+
+		return normalizedPath;
+	}
+
+	/**
+	 * Writes one HTTP response with the provided headers and optional body.
+	 */
+	private sendResponse(res: ServerResponse, status: number, headers: Record<string, string>, body?: Buffer): void {
+		res.statusCode = status;
+		for (const [key, value] of Object.entries(headers)) {
+			res.setHeader(key, value);
+		}
+
+		if (!body) {
+			res.end();
+			return;
+		}
+
+		res.end(body);
+	}
+
+	/**
+	 * Serves the generated 404 page when present, or a plain-text fallback.
+	 */
+	private sendNotFoundPage(req: IncomingMessage, res: ServerResponse): void {
+		const error404TemplatePath = join(this.appConfig.absolutePaths.distDir, '404.html');
+		const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
+
+		if (!fileSystem.exists(error404TemplatePath)) {
+			this.sendResponse(
+				res,
+				404,
+				{ 'Content-Type': 'text/plain' },
+				isHead ? undefined : Buffer.from(STATUS_MESSAGE[404]),
+			);
+			return;
+		}
+
+		const file = fileSystem.readFileAsBuffer(error404TemplatePath);
+		this.sendResponse(res, 404, { 'Content-Type': 'text/html' }, isHead ? undefined : file);
+	}
+
+	/**
+	 * Serves one concrete file path, honoring gzip and HEAD semantics.
+	 */
+	private serveFile(req: IncomingMessage, res: ServerResponse, filePath: string, status = 200): void {
+		const contentType = ServerUtils.getContentType(extname(filePath));
+		const acceptsGzip = req.headers['accept-encoding']?.includes('gzip');
+		const isHead = (req.method ?? 'GET').toUpperCase() === 'HEAD';
+
+		if (acceptsGzip && this.shouldServeGzip(contentType)) {
+			const gzipPath = `${filePath}.gz`;
+			if (fileSystem.exists(gzipPath)) {
+				const file = fileSystem.readFileAsBuffer(gzipPath);
+				this.sendResponse(
+					res,
+					status,
+					{
+						'Content-Type': contentType,
+						'Content-Encoding': 'gzip',
+						Vary: 'Accept-Encoding',
+					},
+					isHead ? undefined : file,
+				);
+				return;
+			}
+		}
+
+		if (!fileSystem.exists(filePath)) {
+			this.sendNotFoundPage(req, res);
+			return;
+		}
+
+		const file = fileSystem.readFileAsBuffer(filePath);
+		this.sendResponse(res, status, { 'Content-Type': contentType }, isHead ? undefined : file);
+	}
+
+	/**
+	 * Handles one incoming Node HTTP request against the built static output tree.
+	 */
+	private handleRequest(req: IncomingMessage, res: ServerResponse): void {
+		const method = (req.method ?? 'GET').toUpperCase();
+		const isHead = method === 'HEAD';
+		if (method !== 'GET' && method !== 'HEAD') {
+			this.sendResponse(
+				res,
+				405,
+				{ Allow: 'GET, HEAD', 'Content-Type': 'text/plain' },
+				isHead ? undefined : Buffer.from('Method Not Allowed'),
+			);
+			return;
+		}
+
+		const url = new URL(req.url ?? '/', 'http://localhost');
+		let decodedPathname = '/';
+		try {
+			decodedPathname = decodeURIComponent(url.pathname);
+		} catch {
+			this.sendResponse(
+				res,
+				400,
+				{ 'Content-Type': 'text/plain' },
+				isHead ? undefined : Buffer.from('Invalid path'),
+			);
+			return;
+		}
+
+		const pathname = decodedPathname === '/' ? '/index.html' : decodedPathname;
+		const relativePath = this.sanitizePath(pathname);
+
+		if (!relativePath) {
+			this.sendResponse(
+				res,
+				400,
+				{ 'Content-Type': 'text/plain' },
+				isHead ? undefined : Buffer.from('Invalid path'),
+			);
+			return;
+		}
+
+		const basePath = join(this.appConfig.absolutePaths.distDir, relativePath);
+
+		if (pathname.includes('.')) {
+			this.serveFile(req, res, basePath);
+			return;
+		}
+
+		const htmlCandidates = [`${basePath}.html`, join(basePath, 'index.html')];
+
+		for (const candidate of htmlCandidates) {
+			if (fileSystem.exists(candidate)) {
+				this.serveFile(req, res, candidate);
+				return;
+			}
+		}
+
+		this.sendNotFoundPage(req, res);
+	}
+
+	/**
+	 * Starts the static preview server.
+	 */
+	public async start(): Promise<NodeHttpServer> {
+		if (this.server) {
+			return this.server;
+		}
+
+		this.server = createServer(this.handleRequest.bind(this));
+		const hostname = this.options.hostname ?? DEFAULT_ECOPAGES_HOSTNAME;
+		const port = this.options.port ?? DEFAULT_ECOPAGES_PORT;
+
+		await new Promise<void>((resolve) => {
+			this.server!.listen(port, hostname, () => resolve());
+		});
+
+		return this.server;
+	}
+
+	/**
+	 * Stops the static preview server and optionally closes active connections.
+	 */
+	public async stop(force = true): Promise<void> {
+		if (!this.server) {
+			return;
+		}
+
+		const activeServer = this.server;
+		this.server = null;
+
+		await new Promise<void>((resolve, reject) => {
+			activeServer.close((error) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+
+				resolve();
+			});
+
+			if (force) {
+				activeServer.closeAllConnections();
+			}
+		});
+	}
+}

package/src/adapters/shared/api-response.test.ts

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { ApiResponseBuilder } from './api-response';
+
+describe('ApiResponseBuilder', () => {
+	let builder: ApiResponseBuilder;
+
+	beforeEach(() => {
+		builder = new ApiResponseBuilder();
+	});
+
+	describe('json()', () => {
+		it('should create JSON response with correct content type and data', async () => {
+			const data = { foo: 'bar' };
+			const response = builder.json(data);
+
+			expect(response.headers.get('Content-Type')).toBe('application/json; charset=utf-8');
+			expect(await response.json()).toEqual(data);
+			expect(response.status).toBe(200);
+		});
+	});
+
+	describe('text()', () => {
+		it('should create text response with correct content type and data', async () => {
+			const text = 'Hello World';
+			const response = builder.text(text);
+
+			expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
+			expect(await response.text()).toBe(text);
+			expect(response.status).toBe(200);
+		});
+	});
+
+	describe('html()', () => {
+		it('should create HTML response with correct content type and data', async () => {
+			const html = '<h1>Hello</h1>';
+			const response = builder.html(html);
+
+			expect(response.headers.get('Content-Type')).toBe('text/html; charset=utf-8');
+			expect(await response.text()).toBe(html);
+			expect(response.status).toBe(200);
+		});
+	});
+
+	describe('status()', () => {
+		it('should set custom status code', () => {
+			const response = builder.status(404).json({ message: 'Not Found' });
+			expect(response.status).toBe(404);
+		});
+	});
+
+	describe('headers()', () => {
+		it('should set custom headers', () => {
+			const response = builder.headers({ 'X-Custom': 'Value' }).json({});
+			expect(response.headers.get('X-Custom')).toBe('Value');
+		});
+	});
+
+	describe('redirect()', () => {
+		it('should create redirect response with location header', () => {
+			const url = 'https://example.com';
+			const response = builder.redirect(url);
+
+			expect(response.headers.get('Location')).toBe(url);
+			expect(response.status).toBe(302);
+		});
+
+		it('should use explicit status for redirect', () => {
+			const response = builder.redirect('https://example.com', 301);
+			expect(response.status).toBe(301);
+		});
+	});
+
+	describe('error()', () => {
+		it('should create JSON error response for object data', async () => {
+			const error = { code: 'ERR_1', message: 'Error occurred' };
+			const response = builder.error(error);
+
+			expect(response.headers.get('Content-Type')).toBe('application/json; charset=utf-8');
+			expect(await response.json()).toEqual({ error });
+			expect(response.status).toBe(500);
+		});
+
+		it('should create text error response for string data', async () => {
+			const error = 'Error occurred';
+			const response = builder.error(error);
+
+			expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
+			expect(await response.text()).toBe(error);
+			expect(response.status).toBe(500);
+		});
+
+		it('should use explicit status for error', () => {
+			const response = builder.error('Not Found', 404);
+			expect(response.status).toBe(404);
+		});
+	});
+});

package/src/adapters/shared/api-response.ts

@@ -0,0 +1,104 @@
+/**
+ * A builder class for creating Response objects fluently.
+ */
+export class ApiResponseBuilder {
+	private _status: Response['status'] = 200;
+	private _headers: Headers = new Headers();
+
+	/**
+	 * Sets the HTTP status code for the response.
+	 * @param code - The HTTP status code.
+	 * @returns The builder instance for chaining.
+	 */
+	status(code: Response['status']): this {
+		this._status = code;
+		return this;
+	}
+
+	/**
+	 * Adds or merges headers for the response.
+	 * @param headersInit - Headers to add or merge.
+	 * @returns The builder instance for chaining.
+	 */
+	headers(headersInit: HeadersInit): this {
+		const inputHeaders = new Headers(headersInit);
+		inputHeaders.forEach((value, key) => {
+			this._headers.set(key, value);
+		});
+		return this;
+	}
+
+	/**
+	 * Creates a JSON response using the configured status and headers.
+	 * @param data - The data to serialize.
+	 * @returns A Response object.
+	 */
+	json(data: any): Response {
+		if (!this._headers.has('Content-Type')) {
+			this._headers.set('Content-Type', 'application/json; charset=utf-8');
+		}
+		return new Response(JSON.stringify(data), { status: this._status, headers: this._headers });
+	}
+
+	/**
+	 * Creates a plain text response using the configured status and headers.
+	 * @param data - The text content.
+	 * @returns A Response object.
+	 */
+	text(data: string): Response {
+		if (!this._headers.has('Content-Type')) {
+			this._headers.set('Content-Type', 'text/plain; charset=utf-8');
+		}
+		return new Response(data, { status: this._status, headers: this._headers });
+	}
+
+	/**
+	 * Creates an HTML response using the configured status and headers.
+	 * @param data - The HTML content.
+	 * @returns A Response object.
+	 */
+	html(data: string): Response {
+		if (!this._headers.has('Content-Type')) {
+			this._headers.set('Content-Type', 'text/html; charset=utf-8');
+		}
+		return new Response(data, { status: this._status, headers: this._headers });
+	}
+
+	/**
+	 * Creates a redirect response.
+	 * @param url - The URL to redirect to.
+	 * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
+	 * @returns A Response object.
+	 */
+	redirect(url: string, explicitStatus?: Response['status']): Response {
+		const redirectStatus = explicitStatus ?? (this._status === 200 ? 302 : this._status); // Default to 302 if status wasn't explicitly set
+		this._headers.set('Location', url);
+		return new Response(null, { status: redirectStatus, headers: this._headers });
+	}
+
+	/**
+	 * Creates an error response using the configured status and headers.
+	 * If data is an object, it's treated as JSON, otherwise as text.
+	 * @param data - The error data (string or object).
+	 * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
+	 * @returns A Response object.
+	 */
+	error(data: string | object, explicitStatus?: Response['status']): Response {
+		const errorStatus = explicitStatus ?? (this._status === 200 ? 500 : this._status); // Default to 500 if status wasn't explicitly set
+		this.status(errorStatus);
+
+		if (typeof data === 'object' && data !== null) {
+			if (!this._headers.has('Content-Type')) {
+				this._headers.set('Content-Type', 'application/json; charset=utf-8');
+			}
+			return new Response(JSON.stringify({ error: data }), {
+				status: this._status,
+				headers: this._headers,
+			});
+		}
+		if (!this._headers.has('Content-Type')) {
+			this._headers.set('Content-Type', 'text/plain; charset=utf-8');
+		}
+		return new Response(String(data), { status: this._status, headers: this._headers });
+	}
+}

package/src/adapters/shared/application-adapter.ts

@@ -0,0 +1,199 @@
+import type {
+	ApiHandler,
+	ApiHandlerContext,
+	Middleware,
+	RouteGroupBuilder,
+	RouteOptions,
+	RouteSchema,
+} from '../../types/public-types.ts';
+import {
+	AbstractApplicationAdapter,
+	type ApplicationAdapterOptions,
+	type RouteGroupDefinition,
+	type RouteHandler,
+} from '../abstract/application-adapter.ts';
+
+export abstract class SharedApplicationAdapter<
+	TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions,
+	TServer = any,
+	TRequest extends Request = Request,
+> extends AbstractApplicationAdapter<TOptions, TServer, TRequest> {
+	protected register<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		method: ApiHandler['method'],
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.addRouteHandler(path, method, handler, options?.middleware, options?.schema);
+	}
+
+	get<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'GET', handler, options);
+	}
+
+	post<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'POST', handler, options);
+	}
+
+	put<P extends string, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'PUT', handler, options);
+	}
+
+	delete<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'DELETE', handler, options);
+	}
+
+	patch<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'PATCH', handler, options);
+	}
+
+	options<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'OPTIONS', handler, options);
+	}
+
+	head<
+		P extends string,
+		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
+	>(
+		path: P,
+		handler: RouteHandler<TRequest, TServer, TContext>,
+		options?: RouteOptions<TRequest, TServer, TContext>,
+	): this {
+		return this.register(path, 'HEAD', handler, options);
+	}
+
+	route<P extends string>(
+		path: P,
+		method: ApiHandler['method'],
+		handler: RouteHandler<TRequest, TServer>,
+		options?: RouteOptions<TRequest, TServer>,
+	): this {
+		return this.register(path, method, handler, options);
+	}
+
+	add(handler: ApiHandler<string, TRequest, TServer>): this {
+		return this.addRouteHandler(handler.path, handler.method, handler.handler, handler.middleware, handler.schema);
+	}
+
+	group<TMiddleware extends readonly Middleware<TRequest, TServer, any>[] = []>(
+		prefixOrGroup: string | RouteGroupDefinition<TRequest, TServer>,
+		callback?: (
+			builder: TMiddleware extends readonly Middleware<TRequest, TServer, infer TContext>[]
+				? RouteGroupBuilder<TRequest, TServer, TContext>
+				: RouteGroupBuilder<TRequest, TServer>,
+		) => void,
+		options?: {
+			middleware?: TMiddleware;
+		},
+	): this {
+		if (typeof prefixOrGroup === 'object') {
+			return this.registerGroup(prefixOrGroup);
+		}
+
+		type TContext = TMiddleware extends readonly Middleware<TRequest, TServer, infer TCtx>[]
+			? TCtx
+			: ApiHandlerContext<TRequest, TServer>;
+
+		const normalizedPrefix = prefixOrGroup.endsWith('/') ? prefixOrGroup.slice(0, -1) : prefixOrGroup;
+		const groupMiddleware = (options?.middleware ?? []) as Middleware<TRequest, TServer, TContext>[];
+
+		const createHandler = (
+			method: ApiHandler['method'],
+		): RouteGroupBuilder<TRequest, TServer, TContext>[Lowercase<typeof method>] => {
+			return ((
+				path: string,
+				handler: (context: TContext) => Promise<Response> | Response,
+				routeOptions?: RouteOptions<TRequest, TServer, TContext> & { schema?: RouteSchema },
+			) => {
+				const combinedMiddleware: Middleware<TRequest, TServer, TContext>[] = [
+					...groupMiddleware,
+					...(routeOptions?.middleware ?? []),
+				];
+				const fullPath = path === '/' ? normalizedPrefix : `${normalizedPrefix}${path}`;
+				this.addRouteHandler(
+					fullPath,
+					method,
+					handler as RouteHandler<TRequest, TServer, ApiHandlerContext<TRequest, TServer>>,
+					combinedMiddleware.length > 0
+						? (combinedMiddleware as Middleware<TRequest, TServer, ApiHandlerContext<TRequest, TServer>>[])
+						: undefined,
+					routeOptions?.schema,
+				);
+				return builder;
+			}) as RouteGroupBuilder<TRequest, TServer, TContext>[Lowercase<typeof method>];
+		};
+
+		const builder: RouteGroupBuilder<TRequest, TServer, TContext> = {
+			get: createHandler('GET'),
+			post: createHandler('POST'),
+			put: createHandler('PUT'),
+			delete: createHandler('DELETE'),
+			patch: createHandler('PATCH'),
+			options: createHandler('OPTIONS'),
+			head: createHandler('HEAD'),
+		};
+
+		callback?.(builder as never);
+		return this;
+	}
+
+	private registerGroup(group: RouteGroupDefinition<TRequest, TServer>): this {
+		const normalizedPrefix = group.prefix.endsWith('/') ? group.prefix.slice(0, -1) : group.prefix;
+		const groupMiddleware = group.middleware ?? [];
+
+		for (const route of group.routes) {
+			const normalizedPath = route.path.startsWith('/') ? route.path : `/${route.path}`;
+			const fullPath = route.path === '/' ? normalizedPrefix : `${normalizedPrefix}${normalizedPath}`;
+			const combinedMiddleware = [...groupMiddleware, ...(route.middleware ?? [])];
+
+			this.addRouteHandler(
+				fullPath,
+				route.method,
+				route.handler,
+				combinedMiddleware.length > 0 ? combinedMiddleware : undefined,
+				route.schema,
+			);
+		}
+
+		return this;
+	}
+}

package/src/adapters/shared/define-api-handler.ts

@@ -0,0 +1,66 @@
+import type {
+	ApiHandler,
+	ApiHandlerContext,
+	Middleware,
+	RouteSchema,
+	TypedGroupHandlerContext,
+} from '../../types/public-types.ts';
+
+type UniversalContext = ApiHandlerContext<Request, unknown>;
+
+type SchemaHandlerContext<
+	TSchema extends RouteSchema | undefined,
+	TContext extends UniversalContext,
+> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
+
+export function defineApiHandler<
+	TPath extends string,
+	TSchema extends RouteSchema | undefined = undefined,
+	TContext extends UniversalContext = UniversalContext,
+>(
+	handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
+		handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+		middleware?: Middleware<Request, unknown, TContext>[];
+		schema?: TSchema;
+	},
+): ApiHandler<TPath, Request, unknown> {
+	return handler as ApiHandler<TPath, Request, unknown>;
+}
+
+export interface GroupHandler<TPrefix extends string = string> {
+	prefix: TPrefix;
+	middleware?: readonly Middleware<Request, unknown, any>[];
+	routes: readonly ApiHandler<string, Request, unknown>[];
+}
+
+type GroupDefineHandler<TContext extends UniversalContext> = <
+	const TPath extends string,
+	TSchema extends RouteSchema | undefined = undefined,
+>(
+	handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
+		path: TPath;
+		handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+		middleware?: Middleware<Request, unknown, TContext>[];
+		schema?: TSchema;
+	},
+) => ApiHandler<TPath, Request, unknown>;
+
+export function defineGroupHandler<
+	TPrefix extends string,
+	TMiddleware extends readonly Middleware<Request, unknown, any>[] = [],
+	TContext extends UniversalContext = TMiddleware extends readonly Middleware<Request, unknown, infer TGroupContext>[]
+		? TGroupContext
+		: UniversalContext,
+>(config: {
+	prefix: TPrefix;
+	middleware?: TMiddleware;
+	routes: (define: GroupDefineHandler<TContext>) => readonly ApiHandler<string, Request, unknown>[];
+}): GroupHandler<TPrefix> {
+	const define = ((handler) => handler) as GroupDefineHandler<TContext>;
+
+	return {
+		prefix: config.prefix,
+		middleware: config.middleware,
+		routes: config.routes(define),
+	};
+}