@prosopo/api-express-router 3.1.51 → 3.1.53

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

@@ -0,0 +1,215 @@
+// 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();
+	});
+});

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

@@ -0,0 +1,95 @@
+// 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 { ApiRoutes, ApiRoutesProvider } from "@prosopo/api-route";
+import { LogLevel } from "@prosopo/logger";
+import type { NextFunction, Request, Response } from "express";
+import { describe, expect, test, vi } from "vitest";
+import {
+	apiExpressRouterFactory,
+	authMiddleware,
+	createApiExpressDefaultEndpointAdapter,
+	handleErrors,
+	requestLoggerMiddleware,
+} from "../../index.js";
+
+/**
+ * The barrel is what every consuming package imports, so the shape of it is
+ * part of the contract — a missing re-export or a changed default breaks
+ * callers without touching any of the implementations.
+ */
+
+describe("createApiExpressDefaultEndpointAdapter", () => {
+	test("builds an adapter exposing handleRequest", () => {
+		const adapter = createApiExpressDefaultEndpointAdapter(LogLevel.enum.info);
+		expect(typeof adapter.handleRequest).toBe("function");
+	});
+
+	test("builds a fresh adapter per call", () => {
+		expect(createApiExpressDefaultEndpointAdapter(LogLevel.enum.info)).not.toBe(
+			createApiExpressDefaultEndpointAdapter(LogLevel.enum.info),
+		);
+	});
+
+	test("defaults the error status code so callers may omit it", () => {
+		expect(() =>
+			createApiExpressDefaultEndpointAdapter(LogLevel.enum.debug),
+		).not.toThrow();
+	});
+
+	test("accepts an explicit error status code", () => {
+		expect(() =>
+			createApiExpressDefaultEndpointAdapter(LogLevel.enum.debug, 503),
+		).not.toThrow();
+	});
+});
+
+describe("apiExpressRouterFactory", () => {
+	test("is exported as a single shared instance", () => {
+		// It holds no per-router state, so one instance is enough — but callers
+		// import the value rather than the class, so it must stay a singleton.
+		expect(typeof apiExpressRouterFactory.createRouter).toBe("function");
+	});
+
+	test("builds a router from a provider", () => {
+		const provider: ApiRoutesProvider = {
+			getRoutes: (): ApiRoutes => ({}),
+		};
+		const router = apiExpressRouterFactory.createRouter(provider, {
+			handleRequest: vi.fn<
+				(
+					endpoint: never,
+					request: Request,
+					response: Response,
+					next: NextFunction,
+				) => Promise<void>
+			>(async () => undefined),
+		});
+		expect(typeof router).toBe("function");
+	});
+});
+
+describe("the re-exported middleware", () => {
+	test("exposes the error handler", () => {
+		expect(typeof handleErrors).toBe("function");
+	});
+
+	test("exposes the auth middleware", () => {
+		expect(typeof authMiddleware).toBe("function");
+	});
+
+	test("exposes the request logger middleware", () => {
+		expect(typeof requestLoggerMiddleware).toBe("function");
+	});
+});