adorn-api 1.1.11 → 1.1.13

package/src/core/types.ts

@@ -12,3 +12,118 @@ export type DtoConstructor<T = any> = new (...args: any[]) => T;
  * HTTP method types.
  */
 export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+
+/**
+ * Uploaded file information from multipart form data.
+ */
+export interface UploadedFileInfo {
+  /** Original filename as provided by the client */
+  originalName: string;
+  /** MIME type of the file */
+  mimeType: string;
+  /** Size of the file in bytes */
+  size: number;
+  /** File buffer (when using memory storage) */
+  buffer?: Buffer;
+  /** Path to the file on disk (when using disk storage) */
+  path?: string;
+  /** Field name from the form */
+  fieldName: string;
+}
+
+/**
+ * Generic request interface.
+ */
+export interface HttpRequest {
+  method: string;
+  url: string;
+  originalUrl?: string;
+  path?: string;
+  params: Record<string, any>;
+  query: Record<string, any>;
+  body: any;
+  headers: Record<string, any>;
+  ip?: string;
+  protocol?: string;
+  secure?: boolean;
+}
+
+/**
+ * Generic response interface.
+ */
+export interface HttpResponseHeaders {
+  [key: string]: string | string[] | undefined;
+}
+
+/**
+ * Generic response interface.
+ */
+export interface HttpResponseWriter {
+  statusCode: number;
+  headersSent: boolean;
+  setHeader(name: string, value: string | string[]): void;
+  getHeader(name: string): string | string[] | undefined;
+  removeHeader(name: string): void;
+  status(code: number): this;
+  send(body?: any): this;
+  end(): void;
+}
+
+/**
+ * Server-Sent Event emitter interface.
+ */
+export interface SseEmitterInterface {
+  send(data: any): void;
+  emit(event: string, data: any): void;
+  comment(text: string): void;
+  close(): void;
+  isClosed(): boolean;
+}
+
+/**
+ * Stream writer interface.
+ */
+export interface StreamWriterInterface {
+  write(data: string | Buffer): boolean;
+  writeLine(data: string): boolean;
+  writeJson(data: any): boolean;
+  writeJsonLine(data: any): boolean;
+  close(): void;
+  isClosed(): boolean;
+}
+
+/**
+ * Request context provided to route handlers.
+ */
+export interface RequestContext<
+  TBody = any,
+  TQuery extends object | undefined = Record<string, any>,
+  TParams extends object | undefined = Record<string, any>,
+  THeaders extends object | undefined = Record<string, any>,
+  TFiles extends Record<string, UploadedFileInfo | UploadedFileInfo[]> | undefined = any
+> {
+  /** Raw request object */
+  req: any;
+  /** Raw response object */
+  res: any;
+  /** Parsed request body */
+  body: TBody;
+  /** Parsed query parameters */
+  query: TQuery;
+  /** Parsed path parameters */
+  params: TParams;
+  /** Request headers */
+  headers: THeaders;
+  /** Uploaded files (when using multipart handling) */
+  files: TFiles;
+  /**
+   * Server-Sent Events emitter for streaming events to client.
+   * Only available on routes marked with @Sse decorator.
+   */
+  sse?: SseEmitterInterface;
+  /**
+   * Stream writer for streaming responses.
+   * Available on routes marked with @Streaming or @Sse decorator.
+   */
+  stream?: StreamWriterInterface;
+}

package/src/index.ts

@@ -1,17 +1,47 @@
-export * from "./core/decorators";
-export * from "./core/schema";
-export * from "./core/openapi";
-export * from "./core/errors";
-export * from "./core/response";
-export * from "./core/validation";
-export * from "./core/validation-errors";
-export * from "./core/coerce";
-export * from "./core/health";
-export * from "./core/logger";
-export * from "./core/serialization";
-export * from "./core/auth";
-export * from "./core/lifecycle";
-export * from "./core/streaming";
-export * from "./adapter/express/index";
-export * from "./adapter/metal-orm/index";
+export * from "./core/decorators";
+export * from "./core/schema";
+export * from "./core/openapi";
+export * from "./core/errors";
+export * from "./core/response";
+export * from "./core/validation";
+export * from "./core/validation-errors";
+export * from "./core/coerce";
+export * from "./core/health";
+export * from "./core/logger";
+export * from "./core/serialization";
+export * from "./core/auth";
+export * from "./core/lifecycle";
+export * from "./core/streaming";
+export {
+    createExpressApp,
+    attachControllers as attachExpressControllers,
+    attachOpenApi as attachExpressOpenApi,
+    shutdownApp as shutdownExpressApp
+} from "./adapter/express/index";
+export type {
+    ExpressAdapterOptions,
+    RequestContext as ExpressRequestContext
+} from "./adapter/express/index";
+export {
+    createFastifyApp,
+    attachControllers as attachFastifyControllers,
+    attachOpenApi as attachFastifyOpenApi,
+    shutdownApp as shutdownFastifyApp
+} from "./adapter/fastify/index";
+export type {
+    FastifyAdapterOptions,
+    RequestContext as FastifyRequestContext
+} from "./adapter/fastify/index";
+export {
+    createNativeApp,
+    attachControllers as attachNativeControllers,
+    attachOpenApi as attachNativeOpenApi,
+    shutdownApp as shutdownNativeApp
+} from "./adapter/native/index";
+export type {
+    NativeAdapterOptions,
+    RequestContext as NativeRequestContext,
+    NativeApp
+} from "./adapter/native/index";
+export * from "./adapter/metal-orm/index";
 export * from "./core/types";

package/tests/e2e/fastify.e2e.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { createFastifyApp } from "../../src";
+import { Controller, Get, Post, Body, Params, Query, t, type RequestContext, Auth, Roles, Sse } from "../../src";
+
+@Controller("/test")
+class TestController {
+  @Get("/hello")
+  hello() {
+    return { message: "Hello from Fastify" };
+  }
+
+  @Post("/echo")
+  @Body(t.object({ name: t.string() }))
+  echo(ctx: RequestContext<{ name: string }>) {
+    return { name: ctx.body.name };
+  }
+
+  @Get("/params/:id")
+  @Params(t.object({ id: t.string() }))
+  getParam(ctx: RequestContext<any, any, { id: string }>) {
+    return { id: ctx.params.id };
+  }
+
+  @Get("/query")
+  @Query(t.object({ q: t.string() }))
+  getQuery(ctx: RequestContext<any, { q: string }>) {
+    return { q: ctx.query.q };
+  }
+
+  @Get("/protected")
+  @Auth()
+  protected() {
+    return { message: "Authenticated" };
+  }
+
+  @Get("/roles")
+  @Roles("admin")
+  roles() {
+    return { message: "Admin only" };
+  }
+
+  @Get("/sse")
+  @Sse()
+  sse(ctx: RequestContext) {
+    ctx.sse?.send({ message: "Hello SSE" });
+    ctx.sse?.close();
+  }
+}
+
+describe("Fastify Adapter E2E", () => {
+  let app: any;
+
+  beforeAll(async () => {
+    app = await createFastifyApp({
+      controllers: [TestController]
+    });
+    await app.ready();
+  });
+
+  it("should handle GET /hello", async () => {
+    const response = await app.inject({
+      method: "GET",
+      url: "/test/hello"
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ message: "Hello from Fastify" });
+  });
+
+  it("should handle POST /echo with body", async () => {
+    const response = await app.inject({
+      method: "POST",
+      url: "/test/echo",
+      payload: { name: "Adorn" }
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ name: "Adorn" });
+  });
+
+  it("should handle GET /params/:id", async () => {
+    const response = await app.inject({
+      method: "GET",
+      url: "/test/params/123"
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ id: "123" });
+  });
+
+  it("should handle GET /query", async () => {
+    const response = await app.inject({
+      method: "GET",
+      url: "/test/query?q=search"
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ q: "search" });
+  });
+
+  it("should handle validation errors", async () => {
+    const response = await app.inject({
+      method: "POST",
+      url: "/test/echo",
+      payload: { name: 123 } // Invalid type
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+
+  it("should block unauthorized access to protected route", async () => {
+    const app401 = await createFastifyApp({
+      controllers: [TestController]
+    });
+    const response = await app401.inject({
+      method: "GET",
+      url: "/test/protected"
+    });
+
+    console.log("401 response body:", response.body);
+    expect(response.statusCode).toBe(401);
+  });
+
+  it("should allow authorized access to protected route", async () => {
+    const appAuth = await createFastifyApp({
+      controllers: [TestController]
+    });
+    appAuth.addHook("preHandler", async (req: any, _reply: any) => {
+      req.user = { id: "1" };
+    });
+
+    const response = await appAuth.inject({
+      method: "GET",
+      url: "/test/protected"
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ message: "Authenticated" });
+  });
+
+  it("should block access without required role", async () => {
+    const appNoRole = await createFastifyApp({
+      controllers: [TestController]
+    });
+    appNoRole.addHook("preHandler", async (req: any, _reply: any) => {
+      req.user = { id: "1", roles: ["user"] };
+    });
+    const response = await appNoRole.inject({
+      method: "GET",
+      url: "/test/roles"
+    });
+
+    expect(response.statusCode).toBe(403);
+  });
+
+  it("should allow access with required role", async () => {
+    // Overriding user with admin role
+    const appWithAdmin = await createFastifyApp({
+      controllers: [TestController]
+    });
+    appWithAdmin.addHook("preHandler", async (req: any) => {
+      req.user = { id: "1", roles: ["admin"] };
+    });
+
+    const response = await appWithAdmin.inject({
+      method: "GET",
+      url: "/test/roles"
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ message: "Admin only" });
+  });
+
+});

package/tests/native.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  Controller,
+  Get,
+  Post,
+  Body,
+  Params,
+  Query,
+  Returns,
+  t,
+  createNativeApp,
+  shutdownNativeApp,
+  type NativeRequestContext
+} from "../src";
+
+@Controller("/test")
+class TestController {
+  @Get("/hello")
+  async hello() {
+    return { message: "hello" };
+  }
+
+  @Post("/echo")
+  @Body(t.object({ name: t.string() }))
+  async echo(ctx: NativeRequestContext<{ name: string }>) {
+    return { hello: ctx.body.name };
+  }
+
+  @Get("/greet/:name")
+  @Params(t.object({ name: t.string() }))
+  async greet(ctx: NativeRequestContext<any, any, { name: string }>) {
+    return { message: `Hello, ${ctx.params.name}!` };
+  }
+
+  @Get("/query")
+  @Query(t.object({ q: t.string() }))
+  async query(ctx: NativeRequestContext<any, { q: string }>) {
+    return { result: ctx.query.q };
+  }
+}
+
+describe("Native Adapter", () => {
+  let app: any;
+
+  beforeEach(async () => {
+    app = await createNativeApp({
+      controllers: [TestController]
+    });
+  });
+
+  afterEach(async () => {
+    await shutdownNativeApp();
+  });
+
+  it("should handle GET request", async () => {
+    const req: any = {
+      method: "GET",
+      url: "/test/hello",
+      headers: {}
+    };
+    const res: any = {
+      statusCode: 0,
+      headers: {},
+      setHeader(name: string, value: string) {
+        this.headers[name] = value;
+      },
+      getHeader(name: string) {
+        return this.headers[name];
+      },
+      end: (data: string) => {
+        res.body = data;
+      }
+    };
+
+    await app.handle(req, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ message: "hello" });
+  });
+
+  it("should handle POST request with body", async () => {
+    const req: any = {
+      method: "POST",
+      url: "/test/echo",
+      headers: { "content-type": "application/json" },
+      on: (event: string, cb: any) => {
+        if (event === "data") {
+          cb(JSON.stringify({ name: "World" }));
+        }
+        if (event === "end") {
+          cb();
+        }
+      }
+    };
+    const res: any = {
+      statusCode: 0,
+      headers: {},
+      setHeader(name: string, value: string) {
+        this.headers[name] = value;
+      },
+      getHeader(name: string) {
+        return this.headers[name];
+      },
+      end: (data: string) => {
+        res.body = data;
+      }
+    };
+
+    await app.handle(req, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ hello: "World" });
+  });
+
+  it("should handle path parameters", async () => {
+    const req: any = {
+      method: "GET",
+      url: "/test/greet/John",
+      headers: {}
+    };
+    const res: any = {
+      statusCode: 0,
+      headers: {},
+      setHeader(name: string, value: string) {
+        this.headers[name] = value;
+      },
+      getHeader(name: string) {
+        return this.headers[name];
+      },
+      end: (data: string) => {
+        res.body = data;
+      }
+    };
+
+    await app.handle(req, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ message: "Hello, John!" });
+  });
+
+  it("should handle query parameters", async () => {
+    const req: any = {
+      method: "GET",
+      url: "/test/query?q=search",
+      headers: {}
+    };
+    const res: any = {
+      statusCode: 0,
+      headers: {},
+      setHeader(name: string, value: string) {
+        this.headers[name] = value;
+      },
+      getHeader(name: string) {
+        return this.headers[name];
+      },
+      end: (data: string) => {
+        res.body = data;
+      }
+    };
+
+    await app.handle(req, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ result: "search" });
+  });
+
+  it("should return 404 for unknown route", async () => {
+    const req: any = {
+      method: "GET",
+      url: "/unknown",
+      headers: {}
+    };
+    const res: any = {
+      statusCode: 0,
+      headers: {},
+      setHeader(name: string, value: string) {
+        this.headers[name] = value;
+      },
+      getHeader(name: string) {
+        return this.headers[name];
+      },
+      end: (data: string) => {
+        res.body = data;
+      }
+    };
+
+    await app.handle(req, res);
+
+    expect(res.statusCode).toBe(404);
+  });
+});

package/tests/typecheck/query-params.typecheck.ts

@@ -0,0 +1,42 @@
+import type {
+  PagedQueryParams,
+  PaginationQueryParams,
+  SortDirection,
+  SortingQueryParams
+} from "../../src/index";
+
+type Assert<T extends true> = T;
+type IsEqual<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends
+    (<T>() => T extends B ? 1 : 2)
+    ? true
+    : false;
+
+type _SortDirectionMatchesPublicType = Assert<
+  IsEqual<SortingQueryParams["sortDirection"], SortDirection | undefined>
+>;
+
+const paginationOnly: PaginationQueryParams = {
+  page: 1,
+  pageSize: 25
+};
+
+const sortingOnly: SortingQueryParams = {
+  sortBy: "createdAt",
+  sortDirection: "desc"
+};
+
+const pagedWithSorting: PagedQueryParams = {
+  page: paginationOnly.page,
+  pageSize: paginationOnly.pageSize,
+  sortBy: sortingOnly.sortBy,
+  sortDirection: "asc"
+};
+
+// @ts-expect-error sortDirection accepts only "asc" | "desc"
+const invalidSorting: SortingQueryParams = { sortDirection: "ASC" };
+
+void paginationOnly;
+void sortingOnly;
+void pagedWithSorting;
+void invalidSorting;