adorn-api 1.0.23 → 1.0.24

package/src/adapter/metal-orm.test.ts

@@ -0,0 +1,439 @@
+import { describe, expect, it } from "vitest";
+import {
+  parsePagination,
+  parseIdOrThrow,
+  parseFilter,
+  createFilterMappings,
+  withSession,
+  createPagedQueryDtoClass,
+  createPagedResponseDtoClass,
+  createMetalCrudDtos,
+  createMetalCrudDtoClasses,
+  createMetalDtoOverrides
+} from "./metal-orm/index";
+import { HttpError } from "../core/errors";
+import { Column, Entity, PrimaryKey, col } from "metal-orm";
+import { getDtoMeta } from "../core/metadata";
+
+describe("metal-orm helpers", () => {
+  describe("parsePagination", () => {
+    it("uses defaults when no query provided", () => {
+      const result = parsePagination({});
+      expect(result.page).toBe(1);
+      expect(result.pageSize).toBe(25);
+    });
+
+    it("applies custom defaults", () => {
+      const result = parsePagination({}, { defaultPageSize: 50, maxPageSize: 200 });
+      expect(result.page).toBe(1);
+      expect(result.pageSize).toBe(50);
+    });
+
+    it("parses page and pageSize from query", () => {
+      const result = parsePagination({ page: "2", pageSize: "10" });
+      expect(result.page).toBe(2);
+      expect(result.pageSize).toBe(10);
+    });
+
+    it("clamps pageSize to max", () => {
+      const result = parsePagination({ pageSize: "150" }, { maxPageSize: 100 });
+      expect(result.pageSize).toBe(100);
+    });
+
+    it("clamps page to min of 1", () => {
+      const result = parsePagination({ page: "0" });
+      expect(result.page).toBe(1);
+    });
+
+    it("handles invalid values as defaults", () => {
+      const result = parsePagination({ page: "invalid", pageSize: "not-a-number" });
+      expect(result.page).toBe(1);
+      expect(result.pageSize).toBe(25);
+    });
+  });
+
+  describe("parseIdOrThrow", () => {
+    it("parses valid ID", () => {
+      const result = parseIdOrThrow("123", "User");
+      expect(result).toBe(123);
+    });
+
+    it("parses number ID", () => {
+      const result = parseIdOrThrow(456, "Post");
+      expect(result).toBe(456);
+    });
+
+    it("throws error for invalid ID", () => {
+      expect(() => parseIdOrThrow("invalid", "User")).toThrow(HttpError);
+      expect(() => parseIdOrThrow("invalid", "User")).toThrow("Invalid User id.");
+    });
+
+    it("throws error for negative ID", () => {
+      expect(() => parseIdOrThrow("-1", "User")).toThrow(HttpError);
+    });
+
+    it("throws error for zero ID", () => {
+      expect(() => parseIdOrThrow("0", "User")).toThrow(HttpError);
+    });
+  });
+
+  describe("parseFilter", () => {
+    it("returns undefined when query is undefined", () => {
+      const mappings = { nameContains: { field: "name" as const, operator: "contains" as const } };
+      const result = parseFilter<{ name: string }, "name">(undefined, mappings);
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when no matching query keys", () => {
+      const mappings = { nameContains: { field: "name" as const, operator: "contains" as const } };
+      const result = parseFilter<{ name: string }, "name">({ unknown: "value" }, mappings);
+      expect(result).toBeUndefined();
+    });
+
+    it("builds filter with contains operator", () => {
+      const mappings = { nameContains: { field: "name" as const, operator: "contains" as const } };
+      const result = parseFilter<{ name: string }, "name">({ nameContains: "John" }, mappings);
+      expect(result).toEqual({ name: { contains: "John" } });
+    });
+
+    it("builds filter with equals operator", () => {
+      const mappings = { userId: { field: "userId" as const, operator: "equals" as const } };
+      const result = parseFilter<{ userId: number }, "userId">({ userId: 123 }, mappings);
+      expect(result).toEqual({ userId: { equals: 123 } });
+    });
+
+    it("builds filter with multiple fields", () => {
+      const mappings = {
+        nameContains: { field: "name" as const, operator: "contains" as const },
+        userId: { field: "userId" as const, operator: "equals" as const }
+      };
+      const result = parseFilter<{ name: string; userId: number }, "name" | "userId">(
+        { nameContains: "John", userId: 123 },
+        mappings
+      );
+      expect(result).toEqual({ name: { contains: "John" }, userId: { equals: 123 } });
+    });
+
+    it("ignores empty string values", () => {
+      const mappings = { nameContains: { field: "name" as const, operator: "contains" as const } };
+      const result = parseFilter<{ name: string }, "name">({ nameContains: "" }, mappings);
+      expect(result).toBeUndefined();
+    });
+
+    it("ignores null values", () => {
+      const mappings = { nameContains: { field: "name" as const, operator: "contains" as const } };
+      const result = parseFilter<{ name: string }, "name">({ nameContains: null }, mappings);
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("createFilterMappings", () => {
+    it("creates filter mappings from field definitions", () => {
+      const entity = { name: "", email: "", userId: 0 } as const;
+      const mappings = createFilterMappings(entity, [
+        { queryKey: "nameContains", field: "name", operator: "contains" },
+        { queryKey: "emailContains", field: "email", operator: "contains" },
+        { queryKey: "userId", field: "userId", operator: "equals" }
+      ]);
+
+      expect(mappings.nameContains).toEqual({ field: "name", operator: "contains" });
+      expect(mappings.emailContains).toEqual({ field: "email", operator: "contains" });
+      expect(mappings.userId).toEqual({ field: "userId", operator: "equals" });
+    });
+
+    it("uses equals as default operator", () => {
+      const entity = { name: "" } as const;
+      const mappings = createFilterMappings(entity, [
+        { queryKey: "name", field: "name" }
+      ]);
+
+      expect(mappings.name).toEqual({ field: "name", operator: "equals" });
+    });
+  });
+
+  describe("withSession", () => {
+    it("disposes session after handler completes", async () => {
+      let disposed = false;
+
+      const mockSession = {
+        dispose: async () => {
+          disposed = true;
+        }
+      } as any;
+
+      const createSession = () => mockSession;
+
+      const result = await withSession(createSession, async (_session) => {
+        return { id: 1 };
+      });
+
+      expect(result).toEqual({ id: 1 });
+      expect(disposed).toBe(true);
+    });
+
+    it("disposes session even when handler throws", async () => {
+      let disposed = false;
+
+      const mockSession = {
+        dispose: async () => {
+          disposed = true;
+        }
+      } as any;
+
+      const createSession = () => mockSession;
+
+      await expect(
+        withSession(createSession, async () => {
+          throw new Error("Test error");
+        })
+      ).rejects.toThrow("Test error");
+
+      expect(disposed).toBe(true);
+    });
+  });
+
+  describe("createPagedQueryDtoClass", () => {
+    it("creates DTO with pagination fields", () => {
+      const PagedQueryDto = createPagedQueryDtoClass();
+      expect(PagedQueryDto.name).toBe("PagedQueryDto");
+    });
+
+    it("applies custom defaults", () => {
+      const PagedQueryDto = createPagedQueryDtoClass({
+        defaultPageSize: 50,
+        maxPageSize: 200
+      });
+      expect(PagedQueryDto.name).toBe("PagedQueryDto");
+    });
+
+    it("uses custom name when provided", () => {
+      const PagedQueryDto = createPagedQueryDtoClass({
+        name: "UserPagedQueryDto"
+      });
+      const meta = getDtoMeta(PagedQueryDto);
+      expect(meta?.name).toBe("UserPagedQueryDto");
+    });
+  });
+
+  describe("createPagedResponseDtoClass", () => {
+    it("creates DTO with pagination fields", () => {
+      class ItemDto {}
+
+      const PagedResponseDto = createPagedResponseDtoClass({
+        itemDto: ItemDto as any,
+        description: "Test response"
+      });
+
+      expect(PagedResponseDto.name).toBe("PagedResponseDto");
+    });
+
+    it("uses custom name when provided", () => {
+      class ItemDto {}
+
+      const PagedResponseDto = createPagedResponseDtoClass({
+        itemDto: ItemDto as any,
+        name: "UserPagedResponseDto"
+      });
+
+      const meta = getDtoMeta(PagedResponseDto);
+      expect(meta?.name).toBe("UserPagedResponseDto");
+    });
+  });
+
+  describe("createMetalCrudDtos", () => {
+    @Entity({ tableName: "crud_dto_entities" })
+    class CrudDtoEntity {
+      @PrimaryKey(col.autoIncrement(col.int()))
+      id!: number;
+
+      @Column(col.notNull(col.text()))
+      name!: string;
+
+      @Column(col.text())
+      nickname?: string | null;
+    }
+
+    it("creates CRUD DTO decorators with defaults", () => {
+      const crud = createMetalCrudDtos(CrudDtoEntity, {
+        mutationExclude: ["id"]
+      });
+
+      @crud.response
+      class CrudDto {}
+
+      @crud.create
+      class CreateCrudDto {}
+
+      @crud.update
+      class UpdateCrudDto {}
+
+      @crud.params
+      class CrudParamsDto {}
+
+      const responseMeta = getDtoMeta(CrudDto);
+      const createMeta = getDtoMeta(CreateCrudDto);
+      const updateMeta = getDtoMeta(UpdateCrudDto);
+      const paramsMeta = getDtoMeta(CrudParamsDto);
+
+      expect(responseMeta?.fields.id).toBeDefined();
+      expect(createMeta?.fields.id).toBeUndefined();
+      expect(updateMeta?.fields.name?.optional).toBe(true);
+      expect(Object.keys(paramsMeta?.fields ?? {})).toEqual(["id"]);
+    });
+  });
+
+  describe("createMetalCrudDtoClasses", () => {
+    @Entity({ tableName: "crud_dto_class_entities" })
+    class CrudDtoClassEntity {
+      @PrimaryKey(col.autoIncrement(col.int()))
+      id!: number;
+
+      @Column(col.notNull(col.text()))
+      name!: string;
+
+      @Column(col.text())
+      nickname?: string | null;
+    }
+
+    it("builds ready-to-export DTO classes", () => {
+      const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
+        mutationExclude: ["id"]
+      });
+
+      const responseMeta = getDtoMeta(classes.response);
+      const createMeta = getDtoMeta(classes.create);
+      const paramsMeta = getDtoMeta(classes.params);
+
+      expect(classes.response.name).toBe("CrudDtoClassEntityDto");
+      expect(responseMeta?.fields.id).toBeDefined();
+      expect(createMeta?.fields.id).toBeUndefined();
+      expect(paramsMeta?.fields).toEqual({ id: expect.any(Object) });
+    });
+
+    it("applies custom name overrides", () => {
+      const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
+        baseName: "Person",
+        names: {
+          response: "PersonDto",
+          params: "PersonIdDto"
+        }
+      });
+
+      expect(classes.response.name).toBe("PersonDto");
+      expect(classes.params.name).toBe("PersonIdDto");
+      expect(classes.create.name).toBe("CreatePersonDto");
+    });
+  });
+
+  describe("createMetalDtoOverrides", () => {
+    @Entity({ tableName: "posts" })
+    class PostEntity {
+      @PrimaryKey(col.autoIncrement(col.int()))
+      id!: number;
+
+      @Column(col.notNull(col.text()))
+      title!: string;
+
+      @Column(col.text())
+      body?: string | null;
+
+      @Column(col.references(col.notNull(col.int()), { table: "users", column: "id" }))
+      userId!: number;
+
+      @Column(col.notNull(col.text()))
+      createdAt!: string;
+    }
+
+    @Entity({ tableName: "users" })
+    class UserEntity {
+      @PrimaryKey(col.autoIncrement(col.int()))
+      id!: number;
+
+      @Column(col.notNull(col.text()))
+      name!: string;
+
+      @Column(col.text())
+      email?: string | null;
+
+      @Column(col.notNull(col.text()))
+      createdAt!: string;
+    }
+
+    it("generates ID convention for primary key", () => {
+      const overrides = createMetalDtoOverrides(PostEntity);
+      expect(overrides.id.kind).toBe("integer");
+      expect((overrides.id as any).minimum).toBe(1);
+      expect((overrides.id as any).description).toBe("PostEntity id.");
+    });
+
+    it("generates FK convention from references metadata", () => {
+      const overrides = createMetalDtoOverrides(PostEntity);
+      expect(overrides.userId.kind).toBe("integer");
+      expect((overrides.userId as any).minimum).toBe(1);
+      expect((overrides.userId as any).description).toBe("User id.");
+    });
+
+    it("generates minLength for required text columns", () => {
+      const overrides = createMetalDtoOverrides(PostEntity);
+      expect(overrides.title.kind).toBe("string");
+      expect((overrides.title as any).minLength).toBe(1);
+    });
+
+    it("generates nullable for optional text columns", () => {
+      const overrides = createMetalDtoOverrides(PostEntity);
+      expect(overrides.body.kind).toBe("string");
+      expect((overrides.body as any).nullable).toBe(true);
+    });
+
+    it("allows custom entity name for descriptions", () => {
+      const overrides = createMetalDtoOverrides(PostEntity, {
+        entityName: "Post"
+      });
+      expect((overrides.id as any).description).toBe("Post id.");
+    });
+
+    it("allows selective overrides", () => {
+      const overrides = createMetalDtoOverrides(PostEntity, {
+        overrides: {
+          title: { kind: "string", minLength: 3, maxLength: 100 }
+        }
+      });
+      expect((overrides.title as any).minLength).toBe(3);
+      expect((overrides.title as any).maxLength).toBe(100);
+    });
+
+    it("excludes specified fields", () => {
+      const overrides = createMetalDtoOverrides(PostEntity, {
+        exclude: ["id", "createdAt"]
+      });
+      expect(overrides.id).toBeUndefined();
+      expect(overrides.createdAt).toBeUndefined();
+      expect(overrides.title).toBeDefined();
+    });
+
+    it("handles datetime type for timestamps", () => {
+      @Entity({ tableName: "events" })
+      class EventEntity {
+        @PrimaryKey(col.autoIncrement(col.int()))
+        id!: number;
+
+        @Column(col.notNull(col.text()))
+        name!: string;
+
+        @Column(col.notNull(col.datetime()))
+        eventDate!: string;
+      }
+
+      const overrides = createMetalDtoOverrides(EventEntity);
+      expect(overrides.eventDate.kind).toBe("string");
+      expect((overrides.eventDate as any).format).toBe("date-time");
+    });
+
+    it("extracts entity name from snake_case table name", () => {
+      const overrides = createMetalDtoOverrides(UserEntity, {
+        entityName: "User"
+      });
+      expect((overrides.id as any).description).toBe("User id.");
+    });
+  });
+});

package/src/core/__tests__/coerce.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeSingle,
+  parseBoolean,
+  parseId,
+  parseInteger,
+  parseNumber
+} from "../coerce";
+
+describe("coerce helpers", () => {
+  it("normalizes single values", () => {
+    expect(normalizeSingle([" 1 "])).toBe("1");
+    expect(normalizeSingle("")).toBeUndefined();
+    expect(normalizeSingle("", { empty: "allow" })).toBe("");
+  });
+
+  it("parses numbers with range controls", () => {
+    expect(parseNumber(" 1.5 ")).toBe(1.5);
+    expect(parseNumber("nope")).toBeUndefined();
+    expect(parseNumber("10", { max: 5 })).toBeUndefined();
+    expect(parseNumber("10", { max: 5, clamp: true })).toBe(5);
+  });
+
+  it("parses integers and ids", () => {
+    expect(parseInteger("2")).toBe(2);
+    expect(parseInteger("2.2")).toBeUndefined();
+    expect(parseInteger("-2", { min: 0, clamp: true })).toBe(0);
+    expect(parseId("1")).toBe(1);
+    expect(parseId("0")).toBeUndefined();
+    expect(parseId("0", { min: 0 })).toBe(0);
+  });
+
+  it("parses booleans", () => {
+    expect(parseBoolean("true")).toBe(true);
+    expect(parseBoolean("FALSE")).toBe(false);
+    expect(parseBoolean("0")).toBe(false);
+    expect(parseBoolean("yes")).toBeUndefined();
+  });
+});

package/src/core/__tests__/dto-compose.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { Dto, Field, MergeDto, OmitDto, PartialDto, PickDto } from "../decorators";
+import { getDtoMeta } from "../metadata";
+import { t } from "../schema";
+
+@Dto()
+class BaseDto {
+  @Field(t.integer())
+  id!: number;
+
+  @Field(t.string({ minLength: 1 }))
+  name!: string;
+
+  @Field(t.optional(t.boolean()))
+  active?: boolean;
+}
+
+@PickDto(BaseDto, ["id", "name"])
+class PickedDto {}
+
+@OmitDto(BaseDto, ["id"], {
+  overrides: {
+    active: { optional: false }
+  }
+})
+class OmittedDto {}
+
+@PartialDto(OmittedDto)
+class PartialOmittedDto {}
+
+@Dto()
+class AuditDto {
+  @Field(t.string({ minLength: 3 }))
+  name!: string;
+
+  @Field(t.string())
+  updatedBy!: string;
+}
+
+@MergeDto([PickedDto, AuditDto])
+class MergedDto {}
+
+describe("dto composition decorators", () => {
+  it("picks and omits fields", () => {
+    const pickMeta = getDtoMeta(PickedDto);
+    expect(pickMeta).toBeTruthy();
+    expect(Object.keys(pickMeta!.fields)).toEqual(["id", "name"]);
+
+    const omitMeta = getDtoMeta(OmittedDto);
+    expect(omitMeta).toBeTruthy();
+    expect(Object.keys(omitMeta!.fields)).toEqual(["name", "active"]);
+    expect(omitMeta!.fields.active.optional).toBe(false);
+  });
+
+  it("marks partial DTOs as optional", () => {
+    const meta = getDtoMeta(PartialOmittedDto);
+    expect(meta).toBeTruthy();
+    expect(meta!.fields.name.optional).toBe(true);
+    expect(meta!.fields.active.optional).toBe(true);
+  });
+
+  it("merges DTO fields with later overrides", () => {
+    const meta = getDtoMeta(MergedDto);
+    expect(meta).toBeTruthy();
+    expect(Object.keys(meta!.fields)).toEqual(["id", "name", "updatedBy"]);
+    expect((meta!.fields.name.schema as { minLength?: number }).minLength).toBe(3);
+  });
+});

package/src/core/__tests__/schema-builder.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { t, type SchemaNode } from "../schema";
+import {
+  buildSchemaFromNode,
+  buildSchemaFromDto,
+  createSchemaContext
+} from "../schema-builder";
+import { registerDto } from "../metadata";
+
+describe("schema builder", () => {
+  it("maps primitive string options", () => {
+    const schema = buildSchemaFromNode(
+      t.string({ minLength: 2, maxLength: 4, pattern: "^[a-z]+$" }),
+      createSchemaContext()
+    );
+
+    expect(schema).toEqual({
+      type: "string",
+      minLength: 2,
+      maxLength: 4,
+      pattern: "^[a-z]+$"
+    });
+  });
+
+  it("adds nullability to schemas", () => {
+    const schema = buildSchemaFromNode(
+      t.nullable(t.integer({ minimum: 1 })),
+      createSchemaContext()
+    );
+
+    expect(schema).toEqual({
+      type: ["integer", "null"],
+      minimum: 1
+    });
+  });
+
+  it("builds dto schemas into components", () => {
+    class UserDto {
+      name!: string;
+      nickname?: string;
+    }
+
+    registerDto(UserDto, {
+      name: "UserDto",
+      fields: {
+        name: { schema: t.string({ minLength: 1 }) },
+        nickname: { schema: t.optional(t.string()) }
+      },
+      additionalProperties: false
+    });
+
+    const context = createSchemaContext();
+    const ref = buildSchemaFromDto(UserDto, context);
+
+    expect(ref).toEqual({ $ref: "#/components/schemas/UserDto" });
+    expect(context.components.UserDto).toEqual({
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        nickname: { type: "string" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    });
+  });
+
+  it("supports arrays and enums", () => {
+    const schemaNode: SchemaNode = t.array(
+      t.enum(["draft", "published", "archived"])
+    );
+
+    const schema = buildSchemaFromNode(schemaNode, createSchemaContext());
+
+    expect(schema).toEqual({
+      type: "array",
+      items: {
+        enum: ["draft", "published", "archived"],
+        type: "string"
+      }
+    });
+  });
+});