adorn-api 1.0.22 → 1.0.24

package/examples/metal-orm-sqlite/post.controller.ts

@@ -0,0 +1,209 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  Params,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Returns,
+  parsePagination,
+  type RequestContext
+} from "../../src";
+import { applyFilter, toPagedResponse } from "metal-orm";
+import type { SimpleWhereInput } from "metal-orm";
+import { entityRef, selectFromEntity } from "metal-orm";
+import { createSession } from "./db";
+import {
+  CreatePostDto,
+  PostDto,
+  PostErrors,
+  PostParamsDto,
+  PostPagedResponseDto,
+  PostQueryDto,
+  PostQueryDtoClass,
+  ReplacePostDto,
+  UpdatePostDto
+} from "./post.dtos";
+import { Post as PostEntity } from "./post.entity";
+import { User } from "./user.entity";
+
+type IntegerOptions = {
+  min?: number;
+  max?: number;
+  clamp?: boolean;
+};
+
+function parseInteger(value: unknown, options: IntegerOptions = {}): number | undefined {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    return undefined;
+  }
+  const result = value;
+  if (options.min !== undefined && result < options.min) {
+    return options.clamp ? options.min : undefined;
+  }
+  if (options.max !== undefined && result > options.max) {
+    return options.clamp ? options.max : undefined;
+  }
+  return result;
+}
+
+function requirePostId(value: unknown): number {
+  const id = parseInteger(value, { min: 1 });
+  if (id === undefined) {
+    throw new HttpError(400, "Invalid post id.");
+  }
+  return id;
+}
+
+const postRef = entityRef(PostEntity);
+
+type PostFilter = SimpleWhereInput<typeof PostEntity, "title" | "userId">;
+type OrmSession = ReturnType<typeof createSession>;
+
+async function withSession<T>(handler: (session: OrmSession) => Promise<T>) {
+  const session = createSession();
+  try {
+    return await handler(session);
+  } finally {
+    await session.dispose();
+  }
+}
+
+async function getPostOrThrow(session: OrmSession, id: number): Promise<PostEntity> {
+  const post = await session.find(PostEntity, id);
+  if (!post) {
+    throw new HttpError(404, "Post not found.");
+  }
+  return post;
+}
+
+async function getUserOrThrow(session: OrmSession, id: number): Promise<User> {
+  const user = await session.find(User, id);
+  if (!user) {
+    throw new HttpError(404, "User not found.");
+  }
+  return user;
+}
+
+function buildPostFilter(query?: PostQueryDto): PostFilter | undefined {
+  if (!query) {
+    return undefined;
+  }
+  const filter: PostFilter = {};
+  if (query.titleContains) {
+    filter.title = { contains: query.titleContains };
+  }
+  if (query.userId !== undefined) {
+    filter.userId = { equals: query.userId };
+  }
+  return Object.keys(filter).length ? filter : undefined;
+}
+
+@Controller("/posts")
+export class PostController {
+  @Get("/")
+  @Query(PostQueryDtoClass)
+  @Returns(PostPagedResponseDto)
+  async list(ctx: RequestContext<unknown, PostQueryDto>) {
+  const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+  const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      const filters = buildPostFilter(ctx.query);
+      const query = applyFilter(
+        selectFromEntity(PostEntity).orderBy(postRef.id, "ASC"),
+        PostEntity,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Get("/:id")
+  @Params(PostParamsDto)
+  @Returns(PostDto)
+  @PostErrors
+  async getOne(ctx: RequestContext<unknown, undefined, PostParamsDto>) {
+    const id = requirePostId(ctx.params.id);
+    return withSession(async (session) => {
+      const post = await getPostOrThrow(session, id);
+      return post as PostDto;
+    });
+  }
+
+  @Post("/")
+  @Body(CreatePostDto)
+  @Returns({ status: 201, schema: PostDto })
+  async create(ctx: RequestContext<CreatePostDto>) {
+    return withSession(async (session) => {
+      await getUserOrThrow(session, ctx.body.userId);
+      const post = new PostEntity();
+      post.title = ctx.body.title;
+      post.body = ctx.body.body ?? null;
+      post.userId = ctx.body.userId;
+      post.createdAt = new Date().toISOString();
+      await session.persist(post);
+      await session.commit();
+      return post as PostDto;
+    });
+  }
+
+  @Put("/:id")
+  @Params(PostParamsDto)
+  @Body(ReplacePostDto)
+  @Returns(PostDto)
+  @PostErrors
+  async replace(ctx: RequestContext<ReplacePostDto, undefined, PostParamsDto>) {
+    const id = requirePostId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getPostOrThrow(session, id);
+      await getUserOrThrow(session, ctx.body.userId);
+      entity.title = ctx.body.title;
+      entity.body = ctx.body.body ?? null;
+      entity.userId = ctx.body.userId;
+      await session.commit();
+      return entity as PostDto;
+    });
+  }
+
+  @Patch("/:id")
+  @Params(PostParamsDto)
+  @Body(UpdatePostDto)
+  @Returns(PostDto)
+  @PostErrors
+  async update(ctx: RequestContext<UpdatePostDto, undefined, PostParamsDto>) {
+    const id = requirePostId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getPostOrThrow(session, id);
+      if (ctx.body.title !== undefined) {
+        entity.title = ctx.body.title;
+      }
+      if (ctx.body.body !== undefined) {
+        entity.body = ctx.body.body ?? null;
+      }
+      if (ctx.body.userId !== undefined) {
+        await getUserOrThrow(session, ctx.body.userId);
+        entity.userId = ctx.body.userId;
+      }
+      await session.commit();
+      return entity as PostDto;
+    });
+  }
+
+  @Delete("/:id")
+  @Params(PostParamsDto)
+  @Returns({ status: 204 })
+  @PostErrors
+  async remove(ctx: RequestContext<unknown, undefined, PostParamsDto>) {
+    const id = requirePostId(ctx.params.id);
+    return withSession(async (session) => {
+      const post = await getPostOrThrow(session, id);
+      await session.remove(post);
+      await session.commit();
+    });
+  }
+}

package/examples/metal-orm-sqlite/post.dtos.ts

@@ -0,0 +1,78 @@
+import {
+  Errors,
+  createMetalCrudDtoClasses,
+  createMetalDtoOverrides,
+  createPagedResponseDtoClass,
+  createNestedCreateDtoClass,
+  createPagedFilterQueryDtoClass,
+  SimpleErrorDto,
+  t
+} from "../../src";
+import { Post } from "./post.entity";
+
+const postOverrides = createMetalDtoOverrides(Post, {
+  overrides: {
+    email: t.nullable(t.string({ format: "email" }))
+  }
+});
+
+const postCrud = createMetalCrudDtoClasses(Post, {
+  overrides: postOverrides,
+  response: { description: "Post returned by API." },
+  mutationExclude: ["id", "createdAt"]
+});
+
+export const {
+  response: PostDto,
+  create: CreatePostDto,
+  replace: ReplacePostDto,
+  update: UpdatePostDto,
+  params: PostParamsDto
+} = postCrud;
+
+export type PostDto = Omit<Post, "user">;
+type PostMutationDto = Omit<PostDto, "id" | "createdAt">;
+export type CreatePostDto = PostMutationDto;
+export type ReplacePostDto = PostMutationDto;
+export type UpdatePostDto = Partial<PostMutationDto>;
+export type PostParamsDto = InstanceType<typeof PostParamsDto>;
+
+export const CreateUserPostDtoClass = createNestedCreateDtoClass(
+  Post,
+  postOverrides,
+  {
+    name: "CreateUserPostDto",
+    additionalExclude: ["userId"]
+  }
+);
+
+export interface CreateUserPostDto {
+  title: string;
+  body?: string | null;
+}
+
+export const PostQueryDtoClass = createPagedFilterQueryDtoClass({
+  name: "PostQueryDto",
+  filters: {
+    titleContains: { schema: t.string({ minLength: 1 }), operator: "contains" },
+    userId: { schema: t.integer({ minimum: 1 }), operator: "equals" }
+  }
+});
+
+export interface PostQueryDto {
+  page?: number;
+  pageSize?: number;
+  titleContains?: string;
+  userId?: number;
+}
+
+export const PostPagedResponseDto = createPagedResponseDtoClass({
+  name: "PostPagedResponseDto",
+  itemDto: PostDto,
+  description: "Paged post list response."
+});
+
+export const PostErrors = Errors(SimpleErrorDto, [
+  { status: 400, description: "Invalid post id." },
+  { status: 404, description: "Post not found." }
+]);

package/examples/metal-orm-sqlite/post.entity.ts

@@ -0,0 +1,24 @@
+import { BelongsTo, Column, Entity, PrimaryKey, col } from "metal-orm";
+import type { BelongsToReference } from "metal-orm";
+import { User } from "./user.entity";
+
+@Entity({ tableName: "posts" })
+export class Post {
+  @PrimaryKey(col.autoIncrement(col.int()))
+  id!: number;
+
+  @Column(col.notNull(col.text()))
+  title!: string;
+
+  @Column(col.text())
+  body?: string | null;
+
+  @Column(col.notNull(col.int()))
+  userId!: number;
+
+  @Column(col.notNull(col.text()))
+  createdAt!: string;
+
+  @BelongsTo({ target: () => User, foreignKey: "userId" })
+  user!: BelongsToReference<User>;
+}

package/examples/metal-orm-sqlite/user.controller.helpers.ts

@@ -0,0 +1,305 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  Params,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Returns,
+  MetalDto,
+  OmitDto,
+  PartialDto,
+  PickDto,
+  MergeDto,
+  Dto,
+  Field,
+  Errors,
+  t,
+  createMetalDtoOverrides,
+  type RequestContext
+} from "../../src";
+import { applyFilter, toPagedResponse, selectFromEntity, entityRef } from "metal-orm";
+import { createSession } from "./db";
+import {
+  withSession,
+  parsePagination,
+  parseFilter,
+  createPagedQueryDtoClass,
+  createPagedResponseDtoClass
+} from "../../src";
+import { User } from "./user.entity";
+import { PostDto } from "./post.dtos";
+
+const userRef = entityRef(User);
+
+const userOverrides = createMetalDtoOverrides(User, {
+  overrides: {
+    email: t.nullable(t.string({ format: "email" }))
+  }
+});
+
+@MetalDto(User, {
+  description: "User returned by the API.",
+  overrides: userOverrides
+})
+export class UserDto {
+  declare id: number;
+  declare name: string;
+  declare email?: string | null;
+  declare createdAt: string;
+}
+
+@Dto()
+class UserPostsDto {
+  @Field(t.array(t.ref(PostDto)))
+  posts!: PostDto[];
+}
+
+@MergeDto([UserDto, UserPostsDto], {
+  description: "User returned by the API with posts."
+})
+class UserWithPostsDto {}
+
+const USER_MUTATION_KEYS: Array<keyof UserDto> = ["id", "createdAt"];
+
+@OmitDto(UserDto, USER_MUTATION_KEYS)
+export class CreateUserDto {
+  declare name: string;
+  declare email?: string | null;
+}
+
+@OmitDto(UserDto, USER_MUTATION_KEYS)
+export class ReplaceUserDto {
+  declare name: string;
+  declare email?: string | null;
+}
+
+@PartialDto(ReplaceUserDto)
+export class UpdateUserDto {
+  declare name?: string;
+  declare email?: string | null;
+}
+
+@PickDto(UserDto, ["id"])
+export class UserParamsDto {
+  declare id: number;
+}
+
+const PagedQueryDto = createPagedQueryDtoClass({
+  name: "UserPagedQueryDto"
+});
+
+@Dto()
+class UserFilterQueryDto {
+  @Field(t.optional(t.string({ minLength: 1 })))
+  nameContains?: string;
+
+  @Field(t.optional(t.string({ minLength: 1 })))
+  emailContains?: string;
+}
+
+@MergeDto([PagedQueryDto, UserFilterQueryDto])
+export class UserQueryDto {
+  declare page?: number;
+  declare pageSize?: number;
+  declare nameContains?: string;
+  declare emailContains?: string;
+}
+
+const UserWithPostsPagedResponseDto = createPagedResponseDtoClass({
+  itemDto: UserWithPostsDto,
+  description: "Paged user list response with posts.",
+  name: "UserWithPostsPagedResponseDto"
+});
+
+@Dto()
+class ErrorDto {
+  @Field(t.string())
+  message!: string;
+}
+
+export const UserErrors = Errors(ErrorDto, [
+  { status: 400, description: "Invalid user id." },
+  { status: 404, description: "User not found." }
+]);
+
+const USER_FILTER_MAPPINGS = {
+  nameContains: { field: "name" as const, operator: "contains" as const },
+  emailContains: { field: "email" as const, operator: "contains" as const }
+};
+
+type IntegerOptions = {
+  min?: number;
+  max?: number;
+  clamp?: boolean;
+};
+
+function parseInteger(value: unknown, options: IntegerOptions = {}): number | undefined {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    return undefined;
+  }
+  const result = value;
+  if (options.min !== undefined && result < options.min) {
+    return options.clamp ? options.min : undefined;
+  }
+  if (options.max !== undefined && result > options.max) {
+    return options.clamp ? options.max : undefined;
+  }
+  return result;
+}
+
+function requireUserId(value: unknown): number {
+  const id = parseInteger(value, { min: 1 });
+  if (id === undefined) {
+    throw new HttpError(400, "Invalid user id.");
+  }
+  return id;
+}
+
+async function getUserOrThrow(session: any, id: number): Promise<User> {
+  const user = await session.find(User, id);
+  if (!user) {
+    throw new HttpError(404, "User not found.");
+  }
+  return user;
+}
+
+@Controller("/users")
+export class UserController {
+  @Get("/")
+  @Query(UserQueryDto)
+  @Returns(UserWithPostsPagedResponseDto)
+  async list(ctx: RequestContext<unknown, UserQueryDto>) {
+    return withSession(createSession, async (session) => {
+      const { page, pageSize } = parsePagination((ctx.query ?? {}) as Record<string, unknown>);
+      const filters = parseFilter<User, "name" | "email">((ctx.query ?? {}) as Record<string, unknown>, USER_FILTER_MAPPINGS);
+      const query = applyFilter(
+        selectFromEntity(User)
+          .orderBy(userRef.id, "ASC")
+          .include("posts", {
+            columns: ["id", "title", "body", "userId", "createdAt"]
+          }),
+        User,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Get("/:id")
+  @Params(UserParamsDto)
+  @Returns(UserDto)
+  @UserErrors
+  async getOne(ctx: RequestContext<unknown, undefined, UserParamsDto>) {
+    return withSession(createSession, async (session) => {
+      const id = requireUserId(ctx.params.id);
+      const user = await getUserOrThrow(session, id);
+      return user as UserDto;
+    });
+  }
+
+  @Post("/")
+  @Body(CreateUserDto)
+  @Returns({ status: 201, schema: UserDto })
+  async create(ctx: RequestContext<CreateUserDto>) {
+    return withSession(createSession, async (session) => {
+      const user = new User();
+      user.name = ctx.body.name;
+      user.email = ctx.body.email ?? null;
+      user.createdAt = new Date().toISOString();
+      await session.persist(user);
+      await session.commit();
+      return user as UserDto;
+    });
+  }
+
+  @Put("/:id")
+  @Params(UserParamsDto)
+  @Body(ReplaceUserDto)
+  @Returns(UserDto)
+  @UserErrors
+  async replace(ctx: RequestContext<ReplaceUserDto, undefined, UserParamsDto>) {
+    return withSession(createSession, async (session) => {
+      const id = requireUserId(ctx.params.id);
+      const entity = await getUserOrThrow(session, id);
+      entity.name = ctx.body.name;
+      entity.email = ctx.body.email ?? null;
+      await session.commit();
+      return entity as UserDto;
+    });
+  }
+
+  @Patch("/:id")
+  @Params(UserParamsDto)
+  @Body(UpdateUserDto)
+  @Returns(UserDto)
+  @UserErrors
+  async update(ctx: RequestContext<UpdateUserDto, undefined, UserParamsDto>) {
+    return withSession(createSession, async (session) => {
+      const id = requireUserId(ctx.params.id);
+      const entity = await getUserOrThrow(session, id);
+      if (ctx.body.name !== undefined) {
+        entity.name = ctx.body.name;
+      }
+      if (ctx.body.email !== undefined) {
+        entity.email = ctx.body.email ?? null;
+      }
+      await session.commit();
+      return entity as UserDto;
+    });
+  }
+
+  @Get("/:id/posts")
+  @Params(UserParamsDto)
+  @Returns(t.array(t.ref(PostDto)))
+  @UserErrors
+  async listPosts(ctx: RequestContext<unknown, undefined, UserParamsDto>) {
+    return withSession(createSession, async (session) => {
+      const id = requireUserId(ctx.params.id);
+      const user = await getUserOrThrow(session, id);
+      return (await user.posts.load()) as PostDto[];
+    });
+  }
+
+  @Post("/:id/posts")
+  @Params(UserParamsDto)
+  @Body(t.object({
+    title: t.string({ minLength: 1 }),
+    body: t.nullable(t.string())
+  }))
+  @Returns({ status: 201, schema: PostDto })
+  @UserErrors
+  async createPost(
+    ctx: RequestContext<any, undefined, UserParamsDto>
+  ) {
+    return withSession(createSession, async (session) => {
+      const id = requireUserId(ctx.params.id);
+      const user = await getUserOrThrow(session, id);
+      const post = user.posts.add({
+        title: ctx.body.title,
+        body: ctx.body.body ?? null,
+        createdAt: new Date().toISOString()
+      });
+      await session.commit();
+      return post as PostDto;
+    });
+  }
+
+  @Delete("/:id")
+  @Params(UserParamsDto)
+  @Returns({ status: 204 })
+  @UserErrors
+  async remove(ctx: RequestContext<unknown, undefined, UserParamsDto>) {
+    return withSession(createSession, async (session) => {
+      const id = requireUserId(ctx.params.id);
+      const user = await getUserOrThrow(session, id);
+      await session.remove(user);
+      await session.commit();
+    });
+  }
+}