@prosopo/api-express-router 3.2.0 → 3.2.2

package/src/tests/unit/apiExpressDefaultEndpointAdapter.unit.test.ts

@@ -1,414 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import {
-	type ApiEndpoint,
-	type ApiEndpointResponse,
-	ApiEndpointResponseStatus,
-} from "@prosopo/api-route";
-import { ProsopoApiError } from "@prosopo/common";
-import { LogLevel, type Logger } from "@prosopo/logger";
-import type { Request, Response } from "express";
-import { beforeEach, describe, expect, test, vi } from "vitest";
-import { type ZodType, z } from "zod";
-import { ApiExpressDefaultEndpointAdapter } from "../../endpointAdapter/apiExpressDefaultEndpointAdapter.js";
-import { type NextCapture, captureNext } from "./testDoubles.js";
-
-/**
- * The adapter is the only place request bodies are validated and the only place
- * an endpoint's throw is turned into a response, so the split matters: a bad
- * body must reach the error handler through next(), while a failure inside the
- * endpoint must be answered directly with a 500.
- */
-
-interface Harness {
-	adapter: ApiExpressDefaultEndpointAdapter;
-	request: Request;
-	response: Response;
-	next: NextCapture;
-	logger: Logger;
-	json: ReturnType<typeof vi.fn<(body: unknown) => Response>>;
-	status: ReturnType<typeof vi.fn<(code: number) => Response>>;
-	send: ReturnType<typeof vi.fn<(body: unknown) => Response>>;
-	logged: ReturnType<typeof vi.fn<(entry: () => unknown) => void>>;
-}
-
-const build = (body: unknown = {}, errorStatusCode = 500): Harness => {
-	const logged = vi.fn<(entry: () => unknown) => void>();
-	const logger = {
-		error: logged,
-		info: vi.fn<(entry: () => unknown) => void>(),
-		debug: vi.fn<(entry: () => unknown) => void>(),
-		warn: vi.fn<(entry: () => unknown) => void>(),
-	} as unknown as Logger;
-
-	const json = vi.fn<(payload: unknown) => Response>();
-	const send = vi.fn<(payload: unknown) => Response>();
-	const status = vi.fn<(code: number) => Response>();
-	const response = { json, send, status } as unknown as Response;
-	status.mockReturnValue(response);
-
-	return {
-		adapter: new ApiExpressDefaultEndpointAdapter(
-			LogLevel.enum.info,
-			errorStatusCode,
-		),
-		request: { body, logger } as unknown as Request,
-		response,
-		next: captureNext(),
-		logger,
-		json,
-		status,
-		send,
-		logged,
-	};
-};
-
-const endpoint = (
-	schema: ZodType | undefined,
-	process: ApiEndpoint<ZodType | undefined>["processRequest"] = async () => ({
-		status: ApiEndpointResponseStatus.SUCCESS,
-	}),
-): ApiEndpoint<ZodType | undefined> => ({
-	getRequestArgsSchema: () => schema,
-	processRequest:
-		vi.fn<ApiEndpoint<ZodType | undefined>["processRequest"]>(process),
-});
-
-let harness: Harness;
-
-beforeEach(() => {
-	harness = build();
-});
-
-describe("a request the endpoint accepts", () => {
-	test("parses the body and passes the parsed value on", async () => {
-		harness = build({ count: "5" });
-		const schema = z.object({ count: z.coerce.number() });
-		const target = endpoint(schema);
-
-		await harness.adapter.handleRequest(
-			target,
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		// The parsed value, not the raw body: coercion has to survive the trip.
-		expect(target.processRequest).toHaveBeenCalledWith(
-			{ count: 5 },
-			harness.logger,
-		);
-	});
-
-	test("passes undefined args when the endpoint declares no schema", async () => {
-		const target = endpoint(undefined);
-		await harness.adapter.handleRequest(
-			target,
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(target.processRequest).toHaveBeenCalledWith(
-			undefined,
-			harness.logger,
-		);
-	});
-
-	test("hands the endpoint the request's own logger", async () => {
-		const target = endpoint(undefined);
-		await harness.adapter.handleRequest(
-			target,
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(vi.mocked(target.processRequest).mock.calls[0]?.[1]).toBe(
-			harness.logger,
-		);
-	});
-
-	test("answers with the endpoint's response as JSON", async () => {
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => ({
-				status: ApiEndpointResponseStatus.SUCCESS,
-				data: { value: 1 },
-			})),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.json).toHaveBeenCalledWith({
-			status: ApiEndpointResponseStatus.SUCCESS,
-			data: { value: 1 },
-		});
-		expect(harness.next.calls).toHaveLength(0);
-	});
-
-	test("stringifies bigints, which res.json() cannot serialise", async () => {
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => ({
-				status: ApiEndpointResponseStatus.SUCCESS,
-				data: { big: 10n },
-			})),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.json).toHaveBeenCalledWith({
-			status: ApiEndpointResponseStatus.SUCCESS,
-			data: { big: "10" },
-		});
-	});
-
-	test("passes an empty data payload straight through", async () => {
-		// Nothing coerces an empty result into a body, so the client sees
-		// exactly what the endpoint returned.
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => ({
-				status: ApiEndpointResponseStatus.SUCCESS,
-				data: {},
-			})),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.json).toHaveBeenCalledWith({
-			status: ApiEndpointResponseStatus.SUCCESS,
-			data: {},
-		});
-	});
-
-	test("an absent request body is still handed to the schema", async () => {
-		// Express only populates req.body when a body parser is mounted, so an
-		// endpoint whose schema tolerates undefined has to keep working.
-		harness.request.body = undefined;
-		const schema = z.object({ a: z.string() }).optional();
-		const target = endpoint(schema);
-		await harness.adapter.handleRequest(
-			target,
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(target.processRequest).toHaveBeenCalledWith(
-			undefined,
-			harness.logger,
-		);
-		expect(harness.json).toHaveBeenCalledWith({
-			status: ApiEndpointResponseStatus.SUCCESS,
-		});
-	});
-});
-
-describe("a body the schema rejects", () => {
-	test("goes to the error handler rather than being answered here", async () => {
-		harness = build({ count: "not a number" });
-		const target = endpoint(z.object({ count: z.number() }));
-
-		await harness.adapter.handleRequest(
-			target,
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		expect(harness.next.calls).toHaveLength(1);
-		expect(harness.json).not.toHaveBeenCalled();
-		expect(target.processRequest).not.toHaveBeenCalled();
-	});
-
-	test("is reported as a 400 parse error carrying the cause", async () => {
-		harness = build({ count: "not a number" });
-		await harness.adapter.handleRequest(
-			endpoint(z.object({ count: z.number() })),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		const [forwarded] = harness.next.calls[0] ?? [];
-		expect(forwarded).toBeInstanceOf(ProsopoApiError);
-		const error = forwarded as ProsopoApiError;
-		expect(error.context?.code).toBe(400);
-		expect(error.context?.error).toBeDefined();
-	});
-
-	test("a schema that throws something other than a ZodError is treated the same", async () => {
-		// getRequestArgsSchema().parse is only known to throw; nothing depends
-		// on it being a ZodError, so a custom schema cannot escape the 400.
-		const schema = {
-			parse: () => {
-				throw new Error("custom validator exploded");
-			},
-		} as unknown as ZodType;
-
-		await harness.adapter.handleRequest(
-			endpoint(schema),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		expect(harness.next.calls).toHaveLength(1);
-		expect(harness.next.calls[0]?.[0]).toBeInstanceOf(ProsopoApiError);
-	});
-
-	test("an endpoint that fails while building its schema is caught too", async () => {
-		// getRequestArgsSchema() is called inside the same try as parse(), so a
-		// broken schema factory is reported as a bad request rather than
-		// escaping handleRequest as an unhandled rejection.
-		const target: ApiEndpoint<ZodType | undefined> = {
-			getRequestArgsSchema: () => {
-				throw new Error("schema construction failed");
-			},
-			processRequest:
-				vi.fn<ApiEndpoint<ZodType | undefined>["processRequest"]>(),
-		};
-
-		await harness.adapter.handleRequest(
-			target,
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		expect(harness.next.calls[0]?.[0]).toBeInstanceOf(ProsopoApiError);
-		expect(target.processRequest).not.toHaveBeenCalled();
-	});
-});
-
-describe("an endpoint that fails", () => {
-	test("is answered with the adapter's error status and the json envelope", async () => {
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw new Error("database down");
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		expect(harness.status).toHaveBeenCalledWith(500);
-		// Every other route answers `{ error: ... }`; a plain-text body here meant
-		// a client parsing the envelope got a parse failure instead of the error.
-		expect(harness.json).toHaveBeenCalledWith({
-			error: expect.anything(),
-		});
-	});
-
-	test("does not leak the failure's message to the client", async () => {
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw new Error("connection string: postgres://user:secret@host");
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(JSON.stringify(harness.json.mock.calls[0]?.[0])).not.toContain(
-			"secret",
-		);
-	});
-
-	test("logs the failure against the request's logger", async () => {
-		const failure = new Error("database down");
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw failure;
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-
-		expect(harness.logged).toHaveBeenCalledTimes(1);
-		const entry = harness.logged.mock.calls[0]?.[0];
-		expect(entry?.()).toEqual({ err: failure });
-	});
-
-	test("does not also call next(), so the error handler is not double-run", async () => {
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw new Error("database down");
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.next.calls).toHaveLength(0);
-	});
-
-	test("answers with the configured errorStatusCode", async () => {
-		// The admin router builds its adapter with 400, so a client error there
-		// used to surface as a 500 in plain text.
-		harness = build({}, 503);
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw new Error("unavailable");
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.status).toHaveBeenCalledWith(503);
-		expect(harness.status).not.toHaveBeenCalledWith(500);
-	});
-
-	test("an error carrying its own status code keeps that code", async () => {
-		// A ProsopoApiError already knows what it is; overwriting its code with
-		// the adapter's default turned a 400 into a 500.
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw new ProsopoApiError("API.BAD_REQUEST", {
-					context: { code: 400 },
-				});
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.status).toHaveBeenCalledWith(400);
-	});
-
-	test("a rejection with a non-Error value is handled just the same", async () => {
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => {
-				throw "a bare string";
-			}),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.status).toHaveBeenCalledWith(500);
-		expect(harness.logged).toHaveBeenCalledTimes(1);
-	});
-
-	test("a failure while serialising the response is caught too", async () => {
-		// stringifyBigInts walks the response, so a getter that throws lands in
-		// the same catch as an endpoint failure rather than escaping.
-		const hostile: ApiEndpointResponse = {
-			get status(): ApiEndpointResponseStatus {
-				throw new Error("getter exploded");
-			},
-		};
-		await harness.adapter.handleRequest(
-			endpoint(undefined, async () => hostile),
-			harness.request,
-			harness.response,
-			harness.next.fn,
-		);
-		expect(harness.status).toHaveBeenCalledWith(500);
-	});
-});

package/src/tests/unit/apiExpressRouterFactory.unit.test.ts

@@ -1,215 +0,0 @@
-// Copyright 2021-2026 Prosopo (UK) Ltd.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-import {
-	type ApiEndpoint,
-	ApiEndpointResponseStatus,
-	type ApiRoutes,
-	type ApiRoutesProvider,
-} from "@prosopo/api-route";
-import type { NextFunction, Request, Response, Router } from "express";
-import { beforeEach, describe, expect, test, vi } from "vitest";
-import type { ZodType } from "zod";
-import { ApiExpressRouterFactory } from "../../apiExpressRouterFactory.js";
-import type { ApiExpressEndpointAdapter } from "../../endpointAdapter/apiExpressEndpointAdapter.js";
-import { handleErrors } from "../../errorHandler.js";
-import { captureNext } from "./testDoubles.js";
-
-/**
- * The factory is the wiring between a routes provider and express. What matters
- * is that every declared route reaches the adapter untouched, that the error
- * handler is mounted last, and that a provider handing back nothing still
- * produces a usable router rather than throwing.
- */
-
-type Handler = (
-	request: Request,
-	response: Response,
-	next: NextFunction,
-) => Promise<void>;
-
-const endpoint = (): ApiEndpoint<ZodType | undefined> => ({
-	getRequestArgsSchema: vi.fn<() => ZodType | undefined>(() => undefined),
-	processRequest: vi.fn<ApiEndpoint<ZodType | undefined>["processRequest"]>(
-		async () => ({ status: ApiEndpointResponseStatus.SUCCESS }),
-	),
-});
-
-const provider = (routes: ApiRoutes): ApiRoutesProvider => ({
-	getRoutes: (): ApiRoutes => routes,
-});
-
-const adapter = (): ApiExpressEndpointAdapter => ({
-	handleRequest: vi.fn<ApiExpressEndpointAdapter["handleRequest"]>(
-		async () => undefined,
-	),
-});
-
-/** The (path, handler) pairs the factory registered as POST routes. */
-const postRoutes = (router: Router): [string, Handler][] => {
-	const registered: [string, Handler][] = [];
-	for (const layer of router.stack) {
-		const route = layer.route;
-		if (!route) continue;
-		const handler = route.stack[route.stack.length - 1]?.handle as
-			| Handler
-			| undefined;
-		if (handler) registered.push([route.path, handler]);
-	}
-	return registered;
-};
-
-let factory: ApiExpressRouterFactory;
-
-beforeEach(() => {
-	factory = new ApiExpressRouterFactory();
-});
-
-describe("createRouter", () => {
-	test("registers one POST route per entry the provider declares", () => {
-		const router = factory.createRouter(
-			provider({ "/a": endpoint(), "/b": endpoint() }),
-			adapter(),
-		);
-		expect(postRoutes(router).map(([path]) => path)).toEqual(["/a", "/b"]);
-	});
-
-	test("registers the routes as POST only", () => {
-		// express records the verbs it accepted on the route itself; anything
-		// beyond post here would widen the API surface silently.
-		const router = factory.createRouter(
-			provider({ "/a": endpoint() }),
-			adapter(),
-		);
-		const route = router.stack.find((layer) => layer.route)?.route as
-			| { methods: Record<string, boolean> }
-			| undefined;
-		expect(route?.methods).toEqual({ post: true });
-	});
-
-	test("a provider with no routes still yields a router", () => {
-		// An empty route table is a legitimate state during start-up, so it must
-		// not throw: the router simply has nothing but the error handler on it.
-		const router = factory.createRouter(provider({}), adapter());
-		expect(postRoutes(router)).toEqual([]);
-		expect(router.stack).toHaveLength(1);
-	});
-
-	test("mounts the error handler last, after every route", () => {
-		// Express only reaches an error handler declared after the handlers that
-		// might fail, so its position is load-bearing rather than cosmetic.
-		const router = factory.createRouter(
-			provider({ "/a": endpoint(), "/b": endpoint() }),
-			adapter(),
-		);
-		const last = router.stack[router.stack.length - 1];
-		expect(last?.handle).toBe(handleErrors);
-		expect(last?.route).toBeUndefined();
-	});
-
-	test("asks the provider for its routes exactly once", () => {
-		const getRoutes = vi.fn<() => ApiRoutes>(() => ({ "/a": endpoint() }));
-		factory.createRouter({ getRoutes }, adapter());
-		expect(getRoutes).toHaveBeenCalledTimes(1);
-	});
-
-	test("each call builds a fresh router", () => {
-		const routes = provider({ "/a": endpoint() });
-		expect(factory.createRouter(routes, adapter())).not.toBe(
-			factory.createRouter(routes, adapter()),
-		);
-	});
-
-	test("routes named oddly are passed to express verbatim", () => {
-		// The factory does no normalising of its own, so a provider is free to
-		// use path parameters or a bare root route.
-		const router = factory.createRouter(
-			provider({ "/": endpoint(), "/nested/:id": endpoint() }),
-			adapter(),
-		);
-		expect(postRoutes(router).map(([path]) => path)).toEqual([
-			"/",
-			"/nested/:id",
-		]);
-	});
-});
-
-describe("the handler each route is given", () => {
-	test("hands the endpoint and the express trio to the adapter", async () => {
-		const target = endpoint();
-		const endpointAdapter = adapter();
-		const router = factory.createRouter(
-			provider({ "/a": target }),
-			endpointAdapter,
-		);
-		const request = {} as Request;
-		const response = {} as Response;
-		const next = captureNext();
-
-		const handler = postRoutes(router)[0]?.[1];
-		await handler?.(request, response, next.fn);
-
-		expect(endpointAdapter.handleRequest).toHaveBeenCalledWith(
-			target,
-			request,
-			response,
-			next.fn,
-		);
-	});
-
-	test("routes each path to its own endpoint, not the last one registered", () => {
-		// A loop that closes over the wrong variable would send every request to
-		// whichever endpoint happened to be last.
-		const first = endpoint();
-		const second = endpoint();
-		const endpointAdapter = adapter();
-		const router = factory.createRouter(
-			provider({ "/first": first, "/second": second }),
-			endpointAdapter,
-		);
-
-		for (const [, handler] of postRoutes(router)) {
-			void handler({} as Request, {} as Response, captureNext().fn);
-		}
-
-		const handled = vi.mocked(endpointAdapter.handleRequest).mock.calls;
-		expect(handled.map(([called]) => called)).toEqual([first, second]);
-	});
-
-	test("propagates a rejection from the adapter to the caller", async () => {
-		// The handler returns the adapter's promise, so express receives the
-		// rejection rather than it becoming an unhandled one.
-		const endpointAdapter = adapter();
-		vi.mocked(endpointAdapter.handleRequest).mockRejectedValue(
-			new Error("adapter blew up"),
-		);
-		const router = factory.createRouter(
-			provider({ "/a": endpoint() }),
-			endpointAdapter,
-		);
-
-		const handler = postRoutes(router)[0]?.[1];
-		await expect(
-			handler?.({} as Request, {} as Response, captureNext().fn),
-		).rejects.toThrow("adapter blew up");
-	});
-
-	test("does not call the endpoint itself — that is the adapter's job", async () => {
-		const target = endpoint();
-		const router = factory.createRouter(provider({ "/a": target }), adapter());
-		const handler = postRoutes(router)[0]?.[1];
-		await handler?.({} as Request, {} as Response, captureNext().fn);
-		expect(target.processRequest).not.toHaveBeenCalled();
-	});
-});