@typokit/core 0.1.4

package/src/error-middleware.test.ts

@@ -0,0 +1,263 @@
+import { describe, it, expect } from "@rstest/core";
+import { createErrorMiddleware } from "./error-middleware.js";
+import { AppError, ValidationError, NotFoundError } from "@typokit/errors";
+import { createRequestContext } from "./middleware.js";
+
+import type {
+  TypoKitRequest,
+  TypoKitResponse,
+  ErrorResponse,
+} from "@typokit/types";
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function makeReq(): TypoKitRequest {
+  return {
+    method: "GET",
+    path: "/test",
+    headers: {},
+    body: undefined,
+    query: {},
+    params: {},
+  };
+}
+
+function makeCtx() {
+  return createRequestContext({ requestId: "trace-abc-123" });
+}
+
+function nextReturning(res: TypoKitResponse): () => Promise<TypoKitResponse> {
+  return async () => res;
+}
+
+function nextThrowing(error: unknown): () => Promise<TypoKitResponse> {
+  return async () => {
+    throw error;
+  };
+}
+
+// ─── AppError Serialization ──────────────────────────────────
+
+describe("createErrorMiddleware — AppError", () => {
+  it("serializes AppError with correct status, code, message, and traceId", async () => {
+    const mw = createErrorMiddleware();
+    const error = new AppError("SOME_ERROR", 422, "Something went wrong", {
+      field: "name",
+    });
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(error));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(422);
+    expect(res.headers["content-type"]).toBe("application/json");
+    expect(body.error.code).toBe("SOME_ERROR");
+    expect(body.error.message).toBe("Something went wrong");
+    expect(body.error.details).toEqual({ field: "name" });
+    expect(body.error.traceId).toBe("trace-abc-123");
+  });
+
+  it("serializes NotFoundError as 404", async () => {
+    const mw = createErrorMiddleware();
+    const error = new NotFoundError("NOT_FOUND", "Resource not found");
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(error));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(404);
+    expect(body.error.code).toBe("NOT_FOUND");
+    expect(body.error.traceId).toBe("trace-abc-123");
+  });
+
+  it("serializes ValidationError as 400", async () => {
+    const mw = createErrorMiddleware();
+    const error = new ValidationError("INVALID_INPUT", "Invalid input", {
+      fields: ["name"],
+    });
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(error));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("INVALID_INPUT");
+    expect(body.error.details).toEqual({ fields: ["name"] });
+  });
+
+  it("passes through successful responses without modification", async () => {
+    const mw = createErrorMiddleware();
+    const okResponse: TypoKitResponse = {
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { data: "ok" },
+    };
+    const res = await mw(makeReq(), makeCtx(), nextReturning(okResponse));
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ data: "ok" });
+  });
+});
+
+// ─── Unknown Error Redaction (Production) ────────────────────
+
+describe("createErrorMiddleware — unknown errors (production)", () => {
+  it("returns 500 with generic message for unknown errors", async () => {
+    const mw = createErrorMiddleware({ isDev: false });
+    const res = await mw(
+      makeReq(),
+      makeCtx(),
+      nextThrowing(new Error("DB connection failed")),
+    );
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(500);
+    expect(body.error.code).toBe("INTERNAL_SERVER_ERROR");
+    expect(body.error.message).toBe("Internal Server Error");
+    expect(body.error.traceId).toBe("trace-abc-123");
+  });
+
+  it("does not leak error details in production", async () => {
+    const mw = createErrorMiddleware({ isDev: false });
+    const res = await mw(
+      makeReq(),
+      makeCtx(),
+      nextThrowing(new Error("secret DB password: p@ss")),
+    );
+    const body = res.body as ErrorResponse;
+
+    expect(body.error.message).toBe("Internal Server Error");
+    expect(body.error.details).toBeUndefined();
+  });
+
+  it("logs full error details in production", async () => {
+    const logged: Array<{ message: string; data?: Record<string, unknown> }> =
+      [];
+    const ctx = createRequestContext({
+      requestId: "trace-log-test",
+      log: {
+        trace: () => {},
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: (message, data) => {
+          logged.push({ message, data });
+        },
+        fatal: () => {},
+      },
+    });
+    const mw = createErrorMiddleware({ isDev: false });
+    const thrown = new Error("secret failure");
+    await mw(makeReq(), ctx, nextThrowing(thrown));
+
+    expect(logged.length).toBe(1);
+    expect(logged[0].message).toBe("Unhandled error");
+    expect(logged[0].data?.message).toBe("secret failure");
+    expect(logged[0].data?.traceId).toBe("trace-log-test");
+    expect(typeof logged[0].data?.stack).toBe("string");
+  });
+
+  it("handles non-Error thrown values in production", async () => {
+    const mw = createErrorMiddleware({ isDev: false });
+    const res = await mw(makeReq(), makeCtx(), nextThrowing("string error"));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(500);
+    expect(body.error.message).toBe("Internal Server Error");
+  });
+});
+
+// ─── Development Mode ────────────────────────────────────────
+
+describe("createErrorMiddleware — development mode", () => {
+  it("includes stack trace for unknown errors in dev mode", async () => {
+    const mw = createErrorMiddleware({ isDev: true });
+    const thrown = new Error("dev error details");
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(thrown));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(500);
+    expect(body.error.code).toBe("INTERNAL_SERVER_ERROR");
+    expect(body.error.message).toBe("dev error details");
+    expect(body.error.details?.stack).toBeDefined();
+    expect(typeof body.error.details?.stack).toBe("string");
+    expect(body.error.details?.name).toBe("Error");
+    expect(body.error.traceId).toBe("trace-abc-123");
+  });
+
+  it("includes source location (stack) in dev mode", async () => {
+    const mw = createErrorMiddleware({ isDev: true });
+    const thrown = new TypeError("null is not a function");
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(thrown));
+    const body = res.body as ErrorResponse;
+
+    expect(body.error.details?.name).toBe("TypeError");
+    expect((body.error.details?.stack as string).includes("TypeError")).toBe(
+      true,
+    );
+  });
+
+  it("handles non-Error thrown values in dev mode", async () => {
+    const mw = createErrorMiddleware({ isDev: true });
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(42));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(500);
+    expect(body.error.message).toBe("42");
+  });
+});
+
+// ─── Typia Validation Errors ─────────────────────────────────
+
+describe("createErrorMiddleware — Typia validation errors", () => {
+  it("handles TypeGuardError with path, expected, value", async () => {
+    const mw = createErrorMiddleware();
+    const error = new Error("invalid type: expected string, got number");
+    error.name = "TypeGuardError";
+    Object.assign(error, {
+      path: "input.name",
+      expected: "string",
+      value: 123,
+    });
+
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(error));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("VALIDATION_ERROR");
+    expect(body.error.traceId).toBe("trace-abc-123");
+    expect(body.error.details?.fields).toEqual([
+      { path: "input.name", expected: "string", value: 123 },
+    ]);
+  });
+
+  it("handles Typia errors with errors array", async () => {
+    const mw = createErrorMiddleware();
+    const error = new Error("Validation failed");
+    error.name = "TypeGuardError";
+    Object.assign(error, {
+      errors: [
+        { path: "input.name", expected: "string", value: 42 },
+        { path: "input.age", expected: "number", value: "old" },
+      ],
+    });
+
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(error));
+    const body = res.body as ErrorResponse;
+
+    expect(res.status).toBe(400);
+    expect(body.error.code).toBe("VALIDATION_ERROR");
+    const fields = body.error.details?.fields as Array<Record<string, unknown>>;
+    expect(fields.length).toBe(2);
+    expect(fields[0].path).toBe("input.name");
+    expect(fields[1].path).toBe("input.age");
+  });
+
+  it("uses error.message for Typia validation errors", async () => {
+    const mw = createErrorMiddleware();
+    const error = new Error("Expected string but got number at input.name");
+    error.name = "TypeGuardError";
+    Object.assign(error, { path: "input.name", expected: "string", value: 99 });
+
+    const res = await mw(makeReq(), makeCtx(), nextThrowing(error));
+    const body = res.body as ErrorResponse;
+
+    expect(body.error.message).toBe(
+      "Expected string but got number at input.name",
+    );
+  });
+});

package/src/error-middleware.ts

@@ -0,0 +1,186 @@
+// @typokit/core — Error Middleware
+
+import type {
+  TypoKitRequest,
+  RequestContext,
+  TypoKitResponse,
+  ErrorResponse,
+  Logger,
+} from "@typokit/types";
+import { AppError } from "@typokit/errors";
+
+// ─── Options ─────────────────────────────────────────────────
+
+/** Options for configuring the error middleware */
+export interface ErrorMiddlewareOptions {
+  /** Override dev mode detection (defaults to NODE_ENV === "development") */
+  isDev?: boolean;
+}
+
+// ─── Typia Validation Error Detection ────────────────────────
+
+/** Shape of a single Typia validation failure */
+interface TypiaValidationFailure {
+  path: string;
+  expected: string;
+  value: unknown;
+}
+
+/** Duck-type check for Typia TypeGuardError (thrown by typia.assert) */
+function isTypiaTypeGuardError(
+  error: unknown,
+): error is Error & { path?: string; expected?: string; value?: unknown } {
+  if (!(error instanceof Error)) return false;
+  return error.name === "TypeGuardError";
+}
+
+/** Duck-type check for objects with Typia-style errors array */
+function hasTypiaErrors(
+  error: unknown,
+): error is Error & { errors: TypiaValidationFailure[] } {
+  if (!(error instanceof Error)) return false;
+  const candidate = error as unknown as Record<string, unknown>;
+  return (
+    Array.isArray(candidate.errors) &&
+    candidate.errors.length > 0 &&
+    typeof (candidate.errors[0] as Record<string, unknown>).path === "string"
+  );
+}
+
+/** Extract field-level details from a Typia validation error */
+function extractTypiaDetails(error: Error): Record<string, unknown> {
+  if (hasTypiaErrors(error)) {
+    return {
+      fields: error.errors.map((e) => ({
+        path: e.path,
+        expected: e.expected,
+        value: e.value,
+      })),
+    };
+  }
+
+  const guard = error as { path?: string; expected?: string; value?: unknown };
+  if (guard.path !== undefined) {
+    return {
+      fields: [
+        {
+          path: guard.path,
+          expected: guard.expected,
+          value: guard.value,
+        },
+      ],
+    };
+  }
+
+  return {};
+}
+
+// ─── Error Middleware Factory ─────────────────────────────────
+
+/**
+ * Built-in error middleware — catches all thrown errors and serializes
+ * them into the ErrorResponse schema.
+ *
+ * - AppError: serialized with correct status, code, message, details, traceId
+ * - Typia validation errors: 400 with field-level failure details
+ * - Unknown errors (prod): 500 generic message, full details logged
+ * - Unknown errors (dev): 500 with stack trace and message exposed
+ */
+export function createErrorMiddleware(
+  options?: ErrorMiddlewareOptions,
+): (
+  req: TypoKitRequest,
+  ctx: RequestContext,
+  next: () => Promise<TypoKitResponse>,
+) => Promise<TypoKitResponse> {
+  const isDev =
+    options?.isDev ??
+    (typeof globalThis !== "undefined" &&
+      (globalThis as unknown as { process?: { env?: Record<string, string> } })
+        .process?.env?.NODE_ENV === "development");
+
+  return async (_req, ctx, next) => {
+    try {
+      return await next();
+    } catch (error: unknown) {
+      const traceId = ctx.requestId;
+
+      // ── AppError instances ──
+      if (error instanceof AppError) {
+        const json: ErrorResponse = error.toJSON();
+        json.error.traceId = traceId;
+        return {
+          status: error.status,
+          headers: { "content-type": "application/json" },
+          body: json,
+        };
+      }
+
+      // ── Typia validation errors ──
+      if (isTypiaTypeGuardError(error) || hasTypiaErrors(error)) {
+        const details = extractTypiaDetails(error);
+        const body: ErrorResponse = {
+          error: {
+            code: "VALIDATION_ERROR",
+            message: error.message || "Validation failed",
+            details,
+            traceId,
+          },
+        };
+        return {
+          status: 400,
+          headers: { "content-type": "application/json" },
+          body,
+        };
+      }
+
+      // ── Unknown errors ──
+      const err = error instanceof Error ? error : new Error(String(error));
+
+      if (isDev) {
+        // Development: expose stack trace and message
+        const body: ErrorResponse = {
+          error: {
+            code: "INTERNAL_SERVER_ERROR",
+            message: err.message,
+            details: {
+              stack: err.stack,
+              name: err.name,
+            },
+            traceId,
+          },
+        };
+        return {
+          status: 500,
+          headers: { "content-type": "application/json" },
+          body,
+        };
+      }
+
+      // Production: log full details, return redacted response
+      logUnknownError(ctx.log, err, traceId);
+      const body: ErrorResponse = {
+        error: {
+          code: "INTERNAL_SERVER_ERROR",
+          message: "Internal Server Error",
+          traceId,
+        },
+      };
+      return {
+        status: 500,
+        headers: { "content-type": "application/json" },
+        body,
+      };
+    }
+  };
+}
+
+/** Log full error details in production mode */
+function logUnknownError(log: Logger, err: Error, traceId: string): void {
+  log.error("Unhandled error", {
+    traceId,
+    name: err.name,
+    message: err.message,
+    stack: err.stack,
+  });
+}