adorn-api 1.0.22 → 1.0.24

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

@@ -0,0 +1,231 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  Params,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Returns,
+  parsePagination,
+  t,
+  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 {
+  CreateUserDto,
+  ReplaceUserDto,
+  UpdateUserDto,
+  UserDto,
+  UserErrors,
+  UserParamsDto,
+  UserWithPostsPagedResponseDto,
+  UserQueryDto,
+  UserQueryDtoClass
+} from "./user.dtos";
+import { CreateUserPostDto, CreateUserPostDtoClass, PostDto } from "./post.dtos";
+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 requireUserId(value: unknown): number {
+  const id = parseInteger(value, { min: 1 });
+  if (id === undefined) {
+    throw new HttpError(400, "Invalid user id.");
+  }
+  return id;
+}
+
+const userRef = entityRef(User);
+
+type UserFilter = SimpleWhereInput<typeof User, "name" | "email">;
+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 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 buildUserFilter(query?: UserQueryDto): UserFilter | undefined {
+  if (!query) {
+    return undefined;
+  }
+  const filter: UserFilter = {};
+  if (query.nameContains) {
+    filter.name = { contains: query.nameContains };
+  }
+  if (query.emailContains) {
+    filter.email = { contains: query.emailContains };
+  }
+  return Object.keys(filter).length ? filter : undefined;
+}
+
+@Controller("/users")
+export class UserController {
+  @Get("/")
+  @Query(UserQueryDtoClass)
+  @Returns(UserWithPostsPagedResponseDto)
+  async list(ctx: RequestContext<unknown, UserQueryDto>) {
+    const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      const filters = buildUserFilter(ctx.query);
+      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>) {
+    const id = requireUserId(ctx.params.id);
+    return withSession(async (session) => {
+      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(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>) {
+    const id = requireUserId(ctx.params.id);
+    return withSession(async (session) => {
+      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>) {
+    const id = requireUserId(ctx.params.id);
+    return withSession(async (session) => {
+      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>) {
+    const id = requireUserId(ctx.params.id);
+    return withSession(async (session) => {
+      const user = await getUserOrThrow(session, id);
+      return (await user.posts.load()) as PostDto[];
+    });
+  }
+
+  @Post("/:id/posts")
+  @Params(UserParamsDto)
+  @Body(CreateUserPostDtoClass)
+  @Returns({ status: 201, schema: PostDto })
+  @UserErrors
+  async createPost(
+    ctx: RequestContext<CreateUserPostDto, undefined, UserParamsDto>
+  ) {
+    const id = requireUserId(ctx.params.id);
+    return withSession(async (session) => {
+      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>) {
+    const id = requireUserId(ctx.params.id);
+    return withSession(async (session) => {
+      const user = await getUserOrThrow(session, id);
+      await session.remove(user);
+      await session.commit();
+    });
+  }
+}

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

@@ -0,0 +1,88 @@
+import {
+  Dto,
+  Field,
+  MergeDto,
+  Errors,
+  createMetalCrudDtoClasses,
+  createMetalDtoOverrides,
+  createPagedResponseDtoClass,
+  createPagedFilterQueryDtoClass,
+  SimpleErrorDto,
+  t
+} from "../../src";
+import { User } from "./user.entity";
+import { PostDto } from "./post.dtos";
+
+const userOverrides = createMetalDtoOverrides(User, {
+  overrides: {
+    email: t.nullable(t.string({ format: "email" }))
+  }
+});
+
+const userCrud = createMetalCrudDtoClasses(User, {
+  overrides: userOverrides,
+  response: { description: "User returned by API." },
+  mutationExclude: ["id", "createdAt"]
+});
+
+export const {
+  response: UserDto,
+  create: CreateUserDto,
+  replace: ReplaceUserDto,
+  update: UpdateUserDto,
+  params: UserParamsDto
+} = userCrud;
+
+export type UserDto = Omit<User, "posts">;
+type UserMutationDto = Omit<UserDto, "id" | "createdAt">;
+export type CreateUserDto = UserMutationDto;
+export type ReplaceUserDto = UserMutationDto;
+export type UpdateUserDto = Partial<UserMutationDto>;
+export type UserParamsDto = InstanceType<typeof UserParamsDto>;
+
+export interface UserWithPostsDto extends UserDto {
+  posts: PostDto[];
+}
+
+@Dto()
+class UserPostsDto {
+  @Field(t.array(t.ref(PostDto)))
+  posts!: PostDto[];
+}
+
+@MergeDto([UserDto, UserPostsDto], {
+  description: "User returned by API with posts."
+})
+export class UserWithPostsDto {}
+
+export const UserQueryDtoClass = createPagedFilterQueryDtoClass({
+  name: "UserQueryDto",
+  filters: {
+    nameContains: { schema: t.string({ minLength: 1 }), operator: "contains" },
+    emailContains: { schema: t.string({ minLength: 1 }), operator: "contains" }
+  }
+});
+
+export interface UserQueryDto {
+  page?: number;
+  pageSize?: number;
+  nameContains?: string;
+  emailContains?: string;
+}
+
+export const UserPagedResponseDto = createPagedResponseDtoClass({
+  name: "UserPagedResponseDto",
+  itemDto: UserDto,
+  description: "Paged user list response."
+});
+
+export const UserWithPostsPagedResponseDto = createPagedResponseDtoClass({
+  name: "UserWithPostsPagedResponseDto",
+  itemDto: UserWithPostsDto,
+  description: "Paged user list response with posts."
+});
+
+export const UserErrors = Errors(SimpleErrorDto, [
+  { status: 400, description: "Invalid user id." },
+  { status: 404, description: "User not found." }
+]);

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

@@ -0,0 +1,21 @@
+import { Column, Entity, HasMany, PrimaryKey, col } from "metal-orm";
+import type { HasManyCollection } from "metal-orm";
+import { Post } from "./post.entity";
+
+@Entity({ tableName: "users" })
+export class User {
+  @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;
+
+  @HasMany({ target: () => Post, foreignKey: "userId" })
+  posts!: HasManyCollection<Post>;
+}

package/examples/metal-orm-sqlite-music/album.controller.ts

@@ -0,0 +1,278 @@
+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 {
+  AlbumDto,
+  AlbumParamsDto,
+  AlbumQueryDto,
+  AlbumQueryDtoClass,
+  AlbumPagedResponseDto,
+  AlbumErrors,
+  CreateAlbumDto,
+  ReplaceAlbumDto,
+  UpdateAlbumDto,
+  CreateAlbumTrackDto,
+  CreateAlbumTrackDtoClass
+} from "./album.dtos";
+import {
+  TrackDto,
+  TrackQueryDto,
+  TrackQueryDtoClass,
+  TrackPagedResponseDto
+} from "./track.dtos";
+import { Album as AlbumEntity } from "./album.entity";
+import { Artist } from "./artist.entity";
+import { Track as TrackEntity } from "./track.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 requireAlbumId(value: unknown): number {
+  const id = parseInteger(value, { min: 1 });
+  if (id === undefined) {
+    const message = "Invalid album id.";
+    throw new HttpError(
+      400,
+      message,
+      buildErrorBody(message, "INVALID_ALBUM_ID", [{ field: "id", message }])
+    );
+  }
+  return id;
+}
+
+const albumRef = entityRef(AlbumEntity);
+const trackRef = entityRef(TrackEntity);
+
+type AlbumFilter = SimpleWhereInput<typeof AlbumEntity, "title" | "releaseYear" | "artistId">;
+type AlbumTrackFilter = SimpleWhereInput<typeof TrackEntity, "albumId">;
+type OrmSession = ReturnType<typeof createSession>;
+
+type ErrorDetail = { field: string; message: string };
+
+function buildErrorBody(message: string, code: string, errors?: ErrorDetail[]) {
+  return { message, code, errors };
+}
+
+async function withSession<T>(handler: (session: OrmSession) => Promise<T>) {
+  const session = createSession();
+  try {
+    return await handler(session);
+  } finally {
+    await session.dispose();
+  }
+}
+
+async function getAlbumOrThrow(session: OrmSession, id: number): Promise<AlbumEntity> {
+  const album = await session.find(AlbumEntity, id);
+  if (!album) {
+    const message = "Album not found.";
+    throw new HttpError(404, message, buildErrorBody(message, "ALBUM_NOT_FOUND"));
+  }
+  return album;
+}
+
+async function getArtistOrThrow(session: OrmSession, id: number): Promise<Artist> {
+  const artist = await session.find(Artist, id);
+  if (!artist) {
+    const message = "Artist not found.";
+    throw new HttpError(404, message, buildErrorBody(message, "ARTIST_NOT_FOUND"));
+  }
+  return artist;
+}
+
+function buildAlbumFilter(query?: AlbumQueryDto): AlbumFilter | undefined {
+  if (!query) {
+    return undefined;
+  }
+  const filter: AlbumFilter = {};
+  if (query.titleContains) {
+    filter.title = { contains: query.titleContains };
+  }
+  if (query.releaseYear !== undefined) {
+    (filter as any).releaseYear = { equals: query.releaseYear };
+  }
+  if (query.artistId !== undefined) {
+    filter.artistId = { equals: query.artistId };
+  }
+  return Object.keys(filter).length ? filter : undefined;
+}
+
+@Controller("/albums")
+export class AlbumController {
+  @Get("/")
+  @Query(AlbumQueryDtoClass)
+  @Returns(AlbumPagedResponseDto)
+  async list(ctx: RequestContext<unknown, AlbumQueryDto>) {
+    const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      const filters = buildAlbumFilter(ctx.query);
+      const query = applyFilter(
+        selectFromEntity(AlbumEntity).orderBy(albumRef.id, "ASC"),
+        AlbumEntity,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Get("/:id")
+  @Params(AlbumParamsDto)
+  @Returns(AlbumDto)
+  @AlbumErrors
+  async getOne(ctx: RequestContext<unknown, undefined, AlbumParamsDto>) {
+    const id = requireAlbumId(ctx.params.id);
+    return withSession(async (session) => {
+      const album = await getAlbumOrThrow(session, id);
+      return album as AlbumDto;
+    });
+  }
+
+  @Post("/")
+  @Body(CreateAlbumDto)
+  @Returns({ status: 201, schema: AlbumDto })
+  async create(ctx: RequestContext<CreateAlbumDto>) {
+    return withSession(async (session) => {
+      await getArtistOrThrow(session, ctx.body.artistId);
+      const album = new AlbumEntity();
+      album.title = ctx.body.title;
+      album.releaseYear = ctx.body.releaseYear ?? null;
+      album.artistId = ctx.body.artistId;
+      album.createdAt = new Date().toISOString();
+      await session.persist(album);
+      await session.commit();
+      return album as AlbumDto;
+    });
+  }
+
+  @Put("/:id")
+  @Params(AlbumParamsDto)
+  @Body(ReplaceAlbumDto)
+  @Returns(AlbumDto)
+  @AlbumErrors
+  async replace(ctx: RequestContext<ReplaceAlbumDto, undefined, AlbumParamsDto>) {
+    const id = requireAlbumId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getAlbumOrThrow(session, id);
+      entity.title = ctx.body.title;
+      entity.releaseYear = ctx.body.releaseYear ?? null;
+      await session.commit();
+      return entity as AlbumDto;
+    });
+  }
+
+  @Patch("/:id")
+  @Params(AlbumParamsDto)
+  @Body(UpdateAlbumDto)
+  @Returns(AlbumDto)
+  @AlbumErrors
+  async update(ctx: RequestContext<UpdateAlbumDto, undefined, AlbumParamsDto>) {
+    const id = requireAlbumId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getAlbumOrThrow(session, id);
+      if (ctx.body.title !== undefined) {
+        entity.title = ctx.body.title;
+      }
+      if (ctx.body.releaseYear !== undefined) {
+        entity.releaseYear = ctx.body.releaseYear ?? null;
+      }
+      await session.commit();
+      return entity as AlbumDto;
+    });
+  }
+
+  @Get("/:id/tracks")
+  @Params(AlbumParamsDto)
+  @Query(TrackQueryDtoClass)
+  @Returns(TrackPagedResponseDto)
+  @AlbumErrors
+  async listTracks(
+    ctx: RequestContext<unknown, TrackQueryDto, AlbumParamsDto>
+  ) {
+    const id = requireAlbumId(ctx.params.id);
+    const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      await getAlbumOrThrow(session, id);
+      const filters: AlbumTrackFilter = {
+        albumId: { equals: id }
+      };
+      const query = applyFilter(
+        selectFromEntity(TrackEntity).orderBy(trackRef.id, "ASC"),
+        TrackEntity,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Post("/:id/tracks")
+  @Params(AlbumParamsDto)
+  @Body(CreateAlbumTrackDtoClass)
+  @Returns({ status: 201, schema: TrackDto })
+  @AlbumErrors
+  async createTrack(
+    ctx: RequestContext<CreateAlbumTrackDto, undefined, AlbumParamsDto>
+  ) {
+    const id = requireAlbumId(ctx.params.id);
+    return withSession(async (session) => {
+      const album = await getAlbumOrThrow(session, id);
+      const track = album.tracks.add({
+        title: ctx.body.title,
+        durationSeconds: ctx.body.durationSeconds ?? null,
+        trackNumber: ctx.body.trackNumber ?? null,
+        createdAt: new Date().toISOString()
+      });
+      await session.commit();
+      return track as TrackDto;
+    });
+  }
+
+  @Delete("/:id")
+  @Params(AlbumParamsDto)
+  @Returns({ status: 204 })
+  @AlbumErrors
+  async remove(ctx: RequestContext<unknown, undefined, AlbumParamsDto>) {
+    const id = requireAlbumId(ctx.params.id);
+    return withSession(async (session) => {
+      const album = await getAlbumOrThrow(session, id);
+      await session.remove(album);
+      await session.commit();
+    });
+  }
+}

package/examples/metal-orm-sqlite-music/album.dtos.ts

@@ -0,0 +1,85 @@
+import {
+  Errors,
+  createMetalCrudDtoClasses,
+  createMetalDtoOverrides,
+  createPagedResponseDtoClass,
+  createNestedCreateDtoClass,
+  createPagedFilterQueryDtoClass,
+  StandardErrorDto,
+  t
+} from "../../src";
+import { Album } from "./album.entity";
+import { CreateAlbumTrackDto, CreateAlbumTrackDtoClass } from "./track.dtos";
+
+const albumOverrides = createMetalDtoOverrides(Album, {
+  overrides: {
+    releaseYear: t.nullable(t.integer({ minimum: 1900, maximum: 9999 }))
+  }
+});
+
+const albumCrud = createMetalCrudDtoClasses(Album, {
+  overrides: albumOverrides,
+  response: { description: "Album returned by API." },
+  mutationExclude: ["id", "createdAt"],
+  immutable: ["artistId"]
+});
+
+export const {
+  response: AlbumDto,
+  create: CreateAlbumDto,
+  replace: ReplaceAlbumDto,
+  update: UpdateAlbumDto,
+  params: AlbumParamsDto
+} = albumCrud;
+
+export type AlbumDto = Omit<Album, "artist" | "tracks">;
+type AlbumMutationDto = Omit<AlbumDto, "id" | "createdAt">;
+type AlbumUpdateDto = Omit<AlbumMutationDto, "artistId">;
+export type CreateAlbumDto = AlbumMutationDto;
+export type ReplaceAlbumDto = AlbumUpdateDto;
+export type UpdateAlbumDto = Partial<AlbumUpdateDto>;
+export type AlbumParamsDto = InstanceType<typeof AlbumParamsDto>;
+
+export const CreateArtistAlbumDtoClass = createNestedCreateDtoClass(
+  Album,
+  albumOverrides,
+  {
+    name: "CreateArtistAlbumDto",
+    additionalExclude: ["artistId"]
+  }
+);
+
+export interface CreateArtistAlbumDto {
+  title: string;
+  releaseYear?: number | null;
+}
+
+export const AlbumQueryDtoClass = createPagedFilterQueryDtoClass({
+  name: "AlbumQueryDto",
+  filters: {
+    titleContains: { schema: t.string({ minLength: 1 }), operator: "contains" },
+    releaseYear: { schema: t.integer({ minimum: 1900, maximum: 9999 }), operator: "equals" },
+    artistId: { schema: t.integer({ minimum: 1 }), operator: "equals" }
+  }
+});
+
+export interface AlbumQueryDto {
+  page?: number;
+  pageSize?: number;
+  titleContains?: string;
+  releaseYear?: number;
+  artistId?: number;
+}
+
+export const AlbumPagedResponseDto = createPagedResponseDtoClass({
+  name: "AlbumPagedResponseDto",
+  itemDto: AlbumDto,
+  description: "Paged album list response."
+});
+
+export const AlbumErrors = Errors(StandardErrorDto, [
+  { status: 400, description: "Invalid album id." },
+  { status: 404, description: "Album not found." }
+]);
+
+export { CreateAlbumTrackDto, CreateAlbumTrackDtoClass };