adorn-api 1.1.11 → 1.1.13

package/src/adapter/fastify/controllers.ts

@@ -0,0 +1,255 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import type { Constructor, RequestContext } from "../../core/types";
+import type { SchemaSource } from "../../core/schema";
+import { getControllerMeta } from "../../core/metadata";
+import { getRouteAuthMeta } from "../../core/auth";
+import { isHttpError, HttpError } from "../../core/errors";
+import { isHttpResponse } from "../../core/response";
+import type { InputCoercionSetting, MultipartOptions, ValidationOptions } from "./types";
+import { createInputCoercer } from "./coercion";
+import { serializeResponse } from "./response-serializer";
+import {
+  extractFiles,
+  hasFileUploads,
+  normalizeMultipartOptions
+} from "./multipart";
+import { lifecycleRegistry } from "../../core/lifecycle";
+import { createSseEmitter, createStreamWriter } from "../../core/streaming";
+import { validate } from "../../core/validation";
+import { ValidationErrors, isValidationErrors } from "../../core/validation-errors";
+
+/**
+ * Attaches controllers to a Fastify application.
+ */
+export async function attachControllers(
+  app: FastifyInstance,
+  controllers: Constructor[],
+  inputCoercion: InputCoercionSetting = "safe",
+  multipart?: boolean | MultipartOptions,
+  validation?: boolean | ValidationOptions
+): Promise<void> {
+  const multipartOptions = normalizeMultipartOptions(multipart);
+
+  for (const controller of controllers) {
+    const meta = getControllerMeta(controller);
+    if (!meta) {
+      throw new Error(`Controller "${controller.name}" is missing @Controller decorator.`);
+    }
+    const instance = new controller();
+    lifecycleRegistry.register(instance);
+    await lifecycleRegistry.callOnModuleInit(instance);
+
+    for (const route of meta.routes) {
+      const path = joinPaths(meta.basePath, route.path);
+      const handler = instance[route.handlerName as keyof typeof instance];
+
+      if (typeof handler !== "function") {
+        throw new Error(`Handler "${String(route.handlerName)}" is not a function on ${controller.name}.`);
+      }
+
+      const coerceParams = inputCoercion === false
+        ? undefined
+        : createInputCoercer<Record<string, any>>(
+          route.params,
+          { mode: inputCoercion, location: "params" }
+        );
+      const coerceQuery = inputCoercion === false
+        ? undefined
+        : createInputCoercer<Record<string, any>>(route.query, { mode: inputCoercion, location: "query" });
+      const coerceBody = inputCoercion === false
+        ? undefined
+        : createInputCoercer<Record<string, any>>(route.body, { mode: inputCoercion, location: "body" });
+
+      const isValidationEnabled = validation !== false && (validation as ValidationOptions)?.enabled !== false;
+
+      const authMeta = getRouteAuthMeta(controller, route.handlerName);
+
+      app.route({
+        method: route.httpMethod.toUpperCase() as any,
+        url: path,
+        handler: async (req: FastifyRequest, reply: FastifyReply) => {
+          try {
+            // Apply auth guard if metadata exists
+            if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
+              const user = (req as any).user || (req.raw as any).user;
+              if (!user) {
+                throw new HttpError(401, "Unauthorized");
+              }
+
+              if (authMeta.roles?.length) {
+                const hasRole = authMeta.roles.some((role: string) => user.roles?.includes(role));
+                if (!hasRole) {
+                  throw new HttpError(403, "Insufficient permissions");
+                }
+              }
+
+              if (authMeta.allRoles?.length) {
+                const hasAllRoles = authMeta.allRoles.every((role: string) => user.roles?.includes(role));
+                if (!hasAllRoles) {
+                  throw new HttpError(403, "Insufficient permissions");
+                }
+              }
+
+              if (authMeta.guard) {
+                const allowed = await authMeta.guard(user, req);
+                if (!allowed) {
+                  throw new HttpError(403, "Access denied by guard");
+                }
+              }
+            }
+
+            let files: any = undefined;
+            if (multipartOptions && hasFileUploads(route.files)) {
+              files = await extractFiles(req);
+            }
+
+            const body = req.body;
+            const query = (coerceQuery && req.query && Object.keys(req.query as any).length > 0) ? coerceQuery(req.query as any) : req.query;
+            const params = (coerceParams && req.params && Object.keys(req.params as any).length > 0) ? coerceParams(req.params as any) : req.params;
+
+            if (isValidationEnabled) {
+              const validationErrors = [];
+
+              if (route.body) {
+                const bodyErrors = validate(body, route.body.schema);
+                validationErrors.push(...bodyErrors);
+              }
+
+              if (route.query) {
+                const queryErrors = validate(query, route.query.schema);
+                validationErrors.push(...queryErrors);
+              }
+
+              if (route.params) {
+                const paramsErrors = validate(params, route.params.schema);
+                validationErrors.push(...paramsErrors);
+              }
+
+              if (route.headers) {
+                const headersErrors = validate(req.headers, route.headers.schema);
+                validationErrors.push(...headersErrors);
+              }
+
+              if (validationErrors.length > 0) {
+                throw new ValidationErrors(validationErrors);
+              }
+            }
+
+            const ctx = {
+              req,
+              res: reply.raw,
+              body,
+              query,
+              params,
+              headers: req.headers,
+              files,
+              sse: route.sse ? createSseEmitter(reply.raw) : undefined,
+              stream: route.streaming || route.sse ? createStreamWriter(reply.raw) : undefined
+            } as unknown as RequestContext;
+
+            const result = await (handler as (...args: any[]) => any).call(instance, ctx);
+
+            if (reply.sent || route.sse || route.streaming) {
+              return;
+            }
+
+            if (isHttpResponse(result)) {
+              if (result.headers) {
+                reply.headers(result.headers);
+              }
+
+              if (result.body === undefined) {
+                reply.status(result.status).send();
+              } else if (route.raw) {
+                if (!reply.getHeader("Content-Type")) {
+                  const ct = getResponseContentType(route) ?? "application/octet-stream";
+                  reply.type(ct);
+                }
+                reply.status(result.status).send(result.body);
+              } else {
+                const responseSchema = getResponseSchemaForStatus(route, result.status);
+                const output = responseSchema ? serializeResponse(result.body, responseSchema) : result.body;
+                reply.status(result.status).send(output);
+              }
+              return;
+            }
+
+            if (result === undefined) {
+              reply.status(defaultStatus(route)).send();
+              return;
+            }
+
+            if (route.raw) {
+              if (!reply.getHeader("Content-Type")) {
+                const ct = getResponseContentType(route) ?? "application/octet-stream";
+                reply.type(ct);
+              }
+              reply.status(defaultStatus(route)).send(result);
+            } else {
+              const responseSchema = getResponseSchema(route);
+              const output = responseSchema ? serializeResponse(result, responseSchema) : result;
+              reply.status(defaultStatus(route)).send(output);
+            }
+          } catch (error) {
+            if (isValidationErrors(error)) {
+              reply.status(error.status).send(error.body);
+              return;
+            }
+            if (isHttpError(error)) {
+              if (error.headers) {
+                reply.headers(error.headers);
+              }
+              const body = error.body ?? { message: error.message };
+              reply.status(error.status).send(body);
+              return;
+            }
+            throw error;
+          }
+        }
+      });
+    }
+  }
+}
+
+function defaultStatus(route: {
+  responses?: Array<{ status: number; error?: boolean }>;
+}): number {
+  const responses = route.responses ?? [];
+  const success = responses.find(
+    (response) => !response.error && response.status < 400
+  );
+  return success?.status ?? 200;
+}
+
+function getResponseSchema(route: {
+  responses?: Array<{ status: number; error?: boolean; schema?: SchemaSource }>;
+}): SchemaSource | undefined {
+  const responses = route.responses ?? [];
+  const success = responses.find((response) => !response.error && response.status < 400);
+  return success?.schema;
+}
+
+function getResponseContentType(route: {
+  responses?: Array<{ status: number; error?: boolean; contentType?: string }>;
+}): string | undefined {
+  const responses = route.responses ?? [];
+  const success = responses.find((r) => !r.error && r.status < 400);
+  return success?.contentType;
+}
+
+function getResponseSchemaForStatus(
+  route: {
+    responses?: Array<{ status: number; error?: boolean; schema?: SchemaSource }>;
+  },
+  status: number
+): SchemaSource | undefined {
+  const responses = route.responses ?? [];
+  const response = responses.find((r) => r.status === status);
+  return response?.schema;
+}
+
+function joinPaths(base: string, path: string): string {
+  const normalizedBase = base.replace(/\/+$/, "");
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}

package/src/adapter/fastify/index.ts

@@ -0,0 +1,53 @@
+import fastify from "fastify";
+import type { FastifyAdapterOptions } from "./types";
+import { attachControllers } from "./controllers";
+import { attachOpenApi } from "./openapi";
+import { lifecycleRegistry } from "../../core/lifecycle";
+import cors from "@fastify/cors";
+import multipart from "@fastify/multipart";
+
+export * from "./types";
+export { attachControllers } from "./controllers";
+export { attachOpenApi } from "./openapi";
+
+/**
+ * Creates a Fastify application with Adorn controllers.
+ * @param options - Fastify adapter options
+ * @returns Configured Fastify application
+ */
+export async function createFastifyApp(options: FastifyAdapterOptions): Promise<any> {
+  const app = fastify({
+    bodyLimit: options.bodyLimit
+  });
+
+  if (options.cors) {
+    app.register(cors, options.cors === true ? {} : options.cors);
+  }
+
+  if (options.multipart) {
+    app.register(multipart, {
+      limits: {
+        fileSize: typeof options.multipart === "object" ? options.multipart.maxFileSize : undefined
+      }
+    });
+  }
+
+  const inputCoercion = options.inputCoercion ?? "safe";
+  await attachControllers(app, options.controllers, inputCoercion, options.multipart, options.validation);
+
+  if (options.openApi) {
+    attachOpenApi(app, options.controllers, options.openApi);
+  }
+
+  await lifecycleRegistry.callOnApplicationBootstrap();
+
+  return app;
+}
+
+/**
+ * Trigger shutdown hooks for graceful application shutdown.
+ */
+export async function shutdownApp(signal?: string): Promise<void> {
+  await lifecycleRegistry.callShutdownHooks(signal);
+  lifecycleRegistry.clear();
+}

package/src/adapter/fastify/multipart.ts

@@ -0,0 +1,94 @@
+import type { FastifyRequest } from "fastify";
+import type { UploadedFileMeta } from "../../core/metadata";
+import type { UploadedFileInfo } from "../../core/types";
+import type { MultipartOptions } from "./types";
+
+/**
+ * Normalized multipart options with defaults applied.
+ */
+export interface NormalizedMultipartOptions {
+  storage: "memory" | "disk";
+  dest: string;
+  maxFileSize: number;
+  maxFiles: number;
+}
+
+const DEFAULT_OPTIONS: NormalizedMultipartOptions = {
+  storage: "memory",
+  dest: "",
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  maxFiles: 10
+};
+
+/**
+ * Normalizes multipart options with defaults.
+ */
+export function normalizeMultipartOptions(
+  options: boolean | MultipartOptions | undefined
+): NormalizedMultipartOptions | undefined {
+  if (!options) {
+    return undefined;
+  }
+  if (options === true) {
+    return DEFAULT_OPTIONS;
+  }
+  return {
+    storage: options.storage ?? DEFAULT_OPTIONS.storage,
+    dest: options.dest ?? DEFAULT_OPTIONS.dest,
+    maxFileSize: options.maxFileSize ?? DEFAULT_OPTIONS.maxFileSize,
+    maxFiles: options.maxFiles ?? DEFAULT_OPTIONS.maxFiles
+  };
+}
+
+/**
+ * Extracts uploaded files from the Fastify request.
+ * For Fastify, files are expected to be attached to the request by @fastify/multipart
+ */
+export async function extractFiles(
+  req: FastifyRequest
+): Promise<Record<string, UploadedFileInfo | UploadedFileInfo[]> | undefined> {
+  const parts = (req as any).parts();
+  const filesMap: Record<string, UploadedFileInfo | UploadedFileInfo[]> = {};
+
+  const fields: Record<string, any> = {};
+
+  for await (const part of parts) {
+    if ((part as any).file) {
+      const buffer = await (part as any).toBuffer();
+      const info: UploadedFileInfo = {
+        originalName: (part as any).filename,
+        mimeType: (part as any).mimetype,
+        size: buffer.length,
+        buffer: buffer,
+        fieldName: (part as any).fieldname
+      };
+
+      if (filesMap[(part as any).fieldname]) {
+        if (Array.isArray(filesMap[(part as any).fieldname])) {
+          (filesMap[(part as any).fieldname] as UploadedFileInfo[]).push(info);
+        } else {
+          filesMap[(part as any).fieldname] = [filesMap[(part as any).fieldname] as UploadedFileInfo, info];
+        }
+      } else {
+        filesMap[(part as any).fieldname] = info;
+      }
+    } else {
+      // It's a field
+      fields[(part as any).fieldname] = (part as any).value;
+    }
+  }
+
+  // Merge fields into body if it's a multipart request
+  if (Object.keys(fields).length > 0) {
+    Object.assign(req.body ?? (req.body = {}), fields);
+  }
+
+  return Object.keys(filesMap).length > 0 ? filesMap : undefined;
+}
+
+/**
+ * Checks if a route has file uploads configured.
+ */
+export function hasFileUploads(files: UploadedFileMeta[] | undefined): boolean {
+  return !!files && files.length > 0;
+}

package/src/adapter/fastify/openapi.ts

@@ -0,0 +1,93 @@
+import type { FastifyInstance } from "fastify";
+import type { Constructor } from "../../core/types";
+import { buildOpenApi } from "../../core/openapi";
+import type { OpenApiFastifyOptions } from "./types";
+
+/**
+ * Attaches OpenAPI endpoints to a Fastify application.
+ * @param app - Fastify application instance
+ * @param controllers - Array of controller classes
+ * @param options - OpenAPI options
+ */
+export function attachOpenApi(
+  app: FastifyInstance,
+  controllers: Constructor[],
+  options: OpenApiFastifyOptions
+): void {
+  const openApiPath = normalizePath(options.path, "/openapi.json");
+  const document = buildOpenApi({
+    info: options.info,
+    servers: options.servers,
+    controllers
+  });
+
+  app.get(openApiPath, (_req, reply) => {
+    if (options.prettyPrint) {
+      reply.header("Content-Type", "application/json");
+      reply.send(JSON.stringify(document, null, 2));
+    } else {
+      reply.send(document);
+    }
+  });
+
+  if (!options.docs) {
+    return;
+  }
+
+  const docsOptions = typeof options.docs === "object" ? options.docs : {};
+  const docsPath = normalizePath(docsOptions.path, "/docs");
+  const title = docsOptions.title ?? `${options.info.title} Docs`;
+  const swaggerUiUrl = (docsOptions.swaggerUiUrl ?? "https://unpkg.com/swagger-ui-dist@5").replace(
+    /\/+$/,
+    ""
+  );
+
+  const html = buildSwaggerUiHtml({ title, swaggerUiUrl, openApiPath });
+  app.get(docsPath, (_req, reply) => {
+    reply.type("text/html").send(html);
+  });
+}
+
+function normalizePath(path: string | undefined, fallback: string): string {
+  if (!path) {
+    return fallback;
+  }
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+function buildSwaggerUiHtml(options: {
+  title: string;
+  swaggerUiUrl: string;
+  openApiPath: string;
+}): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>${options.title}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="${options.swaggerUiUrl}/swagger-ui.css" />
+    <style>
+      body {
+        margin: 0;
+        background: #f6f6f6;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="${options.swaggerUiUrl}/swagger-ui-bundle.js"></script>
+    <script>
+      window.onload = () => {
+        window.ui = SwaggerUIBundle({
+          url: "${options.openApiPath}",
+          dom_id: "#swagger-ui",
+          deepLinking: true,
+          presets: [SwaggerUIBundle.presets.apis],
+          layout: "BaseLayout"
+        });
+      };
+    </script>
+  </body>
+</html>`;
+}

package/src/adapter/fastify/response-serializer.ts

@@ -0,0 +1,179 @@
+import type { SchemaNode, SchemaSource } from "../../core/schema";
+import type { DtoConstructor } from "../../core/types";
+import { getDtoMeta } from "../../core/metadata";
+
+export function serializeResponse(value: unknown, schema: SchemaSource): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (isSchemaNode(schema)) {
+    return serializeWithSchema(value, schema);
+  }
+  return serializeWithDto(value, schema);
+}
+
+function serializeWithDto(value: unknown, dto: DtoConstructor): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeWithDto(entry, dto));
+  }
+  const plainValue = toPlainObject(value);
+  if (!plainValue) {
+    return value;
+  }
+  const meta = getDtoMeta(dto);
+  if (!meta) {
+    return plainValue;
+  }
+  const output: Record<string, unknown> = { ...plainValue };
+  for (const [name, field] of Object.entries(meta.fields)) {
+    if (name in plainValue) {
+      output[name] = serializeWithSchema(plainValue[name], field.schema);
+    }
+  }
+  return output;
+}
+
+function serializeWithSchema(value: unknown, schema: SchemaNode): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  switch (schema.kind) {
+    case "string":
+      return serializeString(value, schema.format);
+    case "array":
+      if (!Array.isArray(value)) {
+        return value;
+      }
+      return value.map((entry) => serializeWithSchema(entry, schema.items));
+    case "object":
+      return serializeObject(value, schema.properties);
+    case "record":
+      if (!isPlainObject(value)) {
+        return value;
+      }
+      return serializeRecord(value as Record<string, unknown>, schema.values);
+    case "ref":
+      return serializeWithDto(value, schema.dto);
+    case "union":
+      return serializeUnion(value, schema.anyOf);
+    default:
+      return value;
+  }
+}
+
+function serializeString(value: unknown, format: string | undefined): unknown {
+  if (format === "byte" && Buffer.isBuffer(value)) {
+    return value.toString("base64");
+  }
+  if (!(value instanceof Date)) {
+    return value;
+  }
+  if (Number.isNaN(value.getTime())) {
+    return value;
+  }
+  if (format === "date") {
+    return value.toISOString().slice(0, 10);
+  }
+  if (format === "date-time") {
+    return value.toISOString();
+  }
+  return value;
+}
+
+function serializeObject(
+  value: unknown,
+  properties: Record<string, SchemaNode> | undefined
+): unknown {
+  const plainValue = toPlainObject(value);
+  if (!plainValue) {
+    return value;
+  }
+  const output: Record<string, unknown> = { ...plainValue };
+  if (!properties) {
+    return output;
+  }
+  for (const [key, schema] of Object.entries(properties)) {
+    if (key in plainValue) {
+      output[key] = serializeWithSchema(plainValue[key], schema);
+    }
+  }
+  return output;
+}
+
+function serializeRecord(
+  value: Record<string, unknown>,
+  schema: SchemaNode
+): Record<string, unknown> {
+  const output: Record<string, unknown> = { ...value };
+  for (const [key, entry] of Object.entries(value)) {
+    output[key] = serializeWithSchema(entry, schema);
+  }
+  return output;
+}
+
+function serializeUnion(value: unknown, options: SchemaNode[]): unknown {
+  for (const option of options) {
+    const serialized = serializeWithSchema(value, option);
+    if (serialized !== value) {
+      return serialized;
+    }
+  }
+  return value;
+}
+
+function isSchemaNode(value: unknown): value is SchemaNode {
+  return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    !(value instanceof Date)
+  );
+}
+
+function toPlainObject(value: unknown): Record<string, unknown> | null {
+  // 1. Check if value has custom toJSON method (e.g., metal-orm entities)
+  if (value !== null &&
+      typeof value === "object" &&
+      typeof (value as { toJSON?: () => unknown }).toJSON === "function") {
+    // Use the custom toJSON which handles circular refs and includes properly
+    const jsonResult = (value as { toJSON: () => unknown }).toJSON();
+    return jsonResult as Record<string, unknown>;
+  }
+
+  // 2. Handle lazy-load wrappers (BelongsToReference)
+  if (typeof value === "object" && typeof (value as Record<string, unknown>).load === "function") {
+    const wrapper = value as { current: unknown; loaded: boolean; load: () => unknown };
+    if (wrapper.current !== undefined && wrapper.current !== null) {
+      return toPlainObject(wrapper.current);
+    }
+    if (wrapper.loaded) {
+      return null;
+    }
+    return null;
+  }
+  // 3. Handle plain objects
+  if (isPlainObject(value)) {
+    return value;
+  }
+  // 4. Convert class instances to plain objects
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.getOwnPropertyNames(value)) {
+      if (key.startsWith('_') || key === 'constructor' || key === 'prototype') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor && descriptor.enumerable) {
+        const propertyValue = (value as Record<string, unknown>)[key];
+        result[key] = propertyValue;
+      }
+    }
+    return result;
+  }
+  return null;
+}