adorn-api 1.0.23 → 1.0.24

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

@@ -0,0 +1,221 @@
+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 {
+  CreateTrackDto,
+  ReplaceTrackDto,
+  UpdateTrackDto,
+  TrackDto,
+  TrackErrors,
+  TrackParamsDto,
+  TrackPagedResponseDto,
+  TrackQueryDto,
+  TrackQueryDtoClass
+} from "./track.dtos";
+import { Track as TrackEntity } from "./track.entity";
+import { Album } from "./album.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 requireTrackId(value: unknown): number {
+  const id = parseInteger(value, { min: 1 });
+  if (id === undefined) {
+    const message = "Invalid track id.";
+    throw new HttpError(
+      400,
+      message,
+      buildErrorBody(message, "INVALID_TRACK_ID", [{ field: "id", message }])
+    );
+  }
+  return id;
+}
+
+const trackRef = entityRef(TrackEntity);
+
+type TrackFilter = SimpleWhereInput<typeof TrackEntity, "title" | "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 getTrackOrThrow(session: OrmSession, id: number): Promise<TrackEntity> {
+  const track = await session.find(TrackEntity, id);
+  if (!track) {
+    const message = "Track not found.";
+    throw new HttpError(404, message, buildErrorBody(message, "TRACK_NOT_FOUND"));
+  }
+  return track;
+}
+
+async function getAlbumOrThrow(session: OrmSession, id: number): Promise<Album> {
+  const album = await session.find(Album, id);
+  if (!album) {
+    const message = "Album not found.";
+    throw new HttpError(404, message, buildErrorBody(message, "ALBUM_NOT_FOUND"));
+  }
+  return album;
+}
+
+function buildTrackFilter(query?: TrackQueryDto): TrackFilter | undefined {
+  if (!query) {
+    return undefined;
+  }
+  const filter: TrackFilter = {};
+  if (query.titleContains) {
+    filter.title = { contains: query.titleContains };
+  }
+  if (query.albumId !== undefined) {
+    filter.albumId = { equals: query.albumId };
+  }
+  return Object.keys(filter).length ? filter : undefined;
+}
+
+@Controller("/tracks")
+export class TrackController {
+  @Get("/")
+  @Query(TrackQueryDtoClass)
+  @Returns(TrackPagedResponseDto)
+  async list(ctx: RequestContext<unknown, TrackQueryDto>) {
+    const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      const filters = buildTrackFilter(ctx.query);
+      const query = applyFilter(
+        selectFromEntity(TrackEntity).orderBy(trackRef.id, "ASC"),
+        TrackEntity,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Get("/:id")
+  @Params(TrackParamsDto)
+  @Returns(TrackDto)
+  @TrackErrors
+  async getOne(ctx: RequestContext<unknown, undefined, TrackParamsDto>) {
+    const id = requireTrackId(ctx.params.id);
+    return withSession(async (session) => {
+      const track = await getTrackOrThrow(session, id);
+      return track as TrackDto;
+    });
+  }
+
+  @Post("/")
+  @Body(CreateTrackDto)
+  @Returns({ status: 201, schema: TrackDto })
+  async create(ctx: RequestContext<CreateTrackDto>) {
+    return withSession(async (session) => {
+      await getAlbumOrThrow(session, ctx.body.albumId);
+      const track = new TrackEntity();
+      track.title = ctx.body.title;
+      track.durationSeconds = ctx.body.durationSeconds ?? null;
+      track.trackNumber = ctx.body.trackNumber ?? null;
+      track.albumId = ctx.body.albumId;
+      track.createdAt = new Date().toISOString();
+      await session.persist(track);
+      await session.commit();
+      return track as TrackDto;
+    });
+  }
+
+  @Put("/:id")
+  @Params(TrackParamsDto)
+  @Body(ReplaceTrackDto)
+  @Returns(TrackDto)
+  @TrackErrors
+  async replace(ctx: RequestContext<ReplaceTrackDto, undefined, TrackParamsDto>) {
+    const id = requireTrackId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getTrackOrThrow(session, id);
+      entity.title = ctx.body.title;
+      entity.durationSeconds = ctx.body.durationSeconds ?? null;
+      entity.trackNumber = ctx.body.trackNumber ?? null;
+      await session.commit();
+      return entity as TrackDto;
+    });
+  }
+
+  @Patch("/:id")
+  @Params(TrackParamsDto)
+  @Body(UpdateTrackDto)
+  @Returns(TrackDto)
+  @TrackErrors
+  async update(ctx: RequestContext<UpdateTrackDto, undefined, TrackParamsDto>) {
+    const id = requireTrackId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getTrackOrThrow(session, id);
+      if (ctx.body.title !== undefined) {
+        entity.title = ctx.body.title;
+      }
+      if (ctx.body.durationSeconds !== undefined) {
+        entity.durationSeconds = ctx.body.durationSeconds ?? null;
+      }
+      if (ctx.body.trackNumber !== undefined) {
+        entity.trackNumber = ctx.body.trackNumber ?? null;
+      }
+      await session.commit();
+      return entity as TrackDto;
+    });
+  }
+
+  @Delete("/:id")
+  @Params(TrackParamsDto)
+  @Returns({ status: 204 })
+  @TrackErrors
+  async remove(ctx: RequestContext<unknown, undefined, TrackParamsDto>) {
+    const id = requireTrackId(ctx.params.id);
+    return withSession(async (session) => {
+      const track = await getTrackOrThrow(session, id);
+      await session.remove(track);
+      await session.commit();
+    });
+  }
+}

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

@@ -0,0 +1,82 @@
+import {
+  Errors,
+  createMetalCrudDtoClasses,
+  createMetalDtoOverrides,
+  createPagedResponseDtoClass,
+  createNestedCreateDtoClass,
+  createPagedFilterQueryDtoClass,
+  StandardErrorDto,
+  t
+} from "../../src";
+import { Track } from "./track.entity";
+
+const trackOverrides = createMetalDtoOverrides(Track, {
+  overrides: {
+    durationSeconds: t.nullable(t.integer({ minimum: 0 })),
+    trackNumber: t.nullable(t.integer({ minimum: 1 }))
+  }
+});
+
+const trackCrud = createMetalCrudDtoClasses(Track, {
+  overrides: trackOverrides,
+  response: { description: "Track returned by API." },
+  mutationExclude: ["id", "createdAt"],
+  immutable: ["albumId"]
+});
+
+export const {
+  response: TrackDto,
+  create: CreateTrackDto,
+  replace: ReplaceTrackDto,
+  update: UpdateTrackDto,
+  params: TrackParamsDto
+} = trackCrud;
+
+export type TrackDto = Omit<Track, "album">;
+type TrackMutationDto = Omit<TrackDto, "id" | "createdAt">;
+type TrackUpdateDto = Omit<TrackMutationDto, "albumId">;
+export type CreateTrackDto = TrackMutationDto;
+export type ReplaceTrackDto = TrackUpdateDto;
+export type UpdateTrackDto = Partial<TrackUpdateDto>;
+export type TrackParamsDto = InstanceType<typeof TrackParamsDto>;
+
+export const CreateAlbumTrackDtoClass = createNestedCreateDtoClass(
+  Track,
+  trackOverrides,
+  {
+    name: "CreateAlbumTrackDto",
+    additionalExclude: ["albumId"]
+  }
+);
+
+export interface CreateAlbumTrackDto {
+  title: string;
+  durationSeconds?: number | null;
+  trackNumber?: number | null;
+}
+
+export const TrackQueryDtoClass = createPagedFilterQueryDtoClass({
+  name: "TrackQueryDto",
+  filters: {
+    titleContains: { schema: t.string({ minLength: 1 }), operator: "contains" },
+    albumId: { schema: t.integer({ minimum: 1 }), operator: "equals" }
+  }
+});
+
+export interface TrackQueryDto {
+  page?: number;
+  pageSize?: number;
+  titleContains?: string;
+  albumId?: number;
+}
+
+export const TrackPagedResponseDto = createPagedResponseDtoClass({
+  name: "TrackPagedResponseDto",
+  itemDto: TrackDto,
+  description: "Paged track list response."
+});
+
+export const TrackErrors = Errors(StandardErrorDto, [
+  { status: 400, description: "Invalid track id." },
+  { status: 404, description: "Track not found." }
+]);

package/examples/metal-orm-sqlite-music/track.entity.ts

@@ -0,0 +1,27 @@
+import { BelongsTo, Column, Entity, PrimaryKey, col } from "metal-orm";
+import type { BelongsToReference } from "metal-orm";
+import { Album } from "./album.entity";
+
+@Entity({ tableName: "tracks" })
+export class Track {
+  @PrimaryKey(col.autoIncrement(col.int()))
+  id!: number;
+
+  @Column(col.notNull(col.text()))
+  title!: string;
+
+  @Column(col.int())
+  durationSeconds?: number | null;
+
+  @Column(col.int())
+  trackNumber?: number | null;
+
+  @Column(col.notNull(col.int()))
+  albumId!: number;
+
+  @Column(col.notNull(col.text()))
+  createdAt!: string;
+
+  @BelongsTo({ target: () => Album, foreignKey: "albumId" })
+  album!: BelongsToReference<Album>;
+}

package/examples/openapi/health.controller.ts

@@ -0,0 +1,11 @@
+import { Controller, Get, Returns } from "../../src";
+import { HealthDto } from "./health.dto";
+
+@Controller("/health")
+export class HealthController {
+  @Get("/")
+  @Returns(HealthDto)
+  ping() {
+    return { message: "ok" };
+  }
+}

package/examples/openapi/health.dto.ts

@@ -0,0 +1,7 @@
+import { Dto, Field, t } from "../../src";
+
+@Dto()
+export class HealthDto {
+  @Field(t.string())
+  message!: string;
+}

package/examples/openapi/index.ts

@@ -0,0 +1,12 @@
+import { buildOpenApi } from "../../src";
+import { HealthController } from "./health.controller";
+
+const doc = buildOpenApi({
+  info: {
+    title: "Health API",
+    version: "1.0.0"
+  },
+  controllers: [HealthController]
+});
+
+console.log(JSON.stringify(doc, null, 2));

package/examples/restful/app.ts

@@ -0,0 +1,15 @@
+import { createExpressApp } from "../../src";
+import { TaskController } from "./task.controller";
+
+export function createApp() {
+  return createExpressApp({
+    controllers: [TaskController],
+    openApi: {
+      info: {
+        title: "Tasks API",
+        version: "1.0.0"
+      },
+      docs: true
+    }
+  });
+}

package/examples/restful/index.ts

@@ -0,0 +1,9 @@
+import { createApp } from "./app";
+import { startExampleServer } from "../utils/start-server";
+
+const app = createApp();
+
+startExampleServer(app, {
+  name: "Tasks API",
+  extraLogs: [(port) => `Swagger UI available at http://localhost:${port}/docs`]
+});

package/examples/restful/task.controller.ts

@@ -0,0 +1,118 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  Params,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Returns,
+  coerce,
+  t,
+  type RequestContext
+} from "../../src";
+import {
+  CreateTaskDto,
+  ReplaceTaskDto,
+  TaskDto,
+  TaskErrors,
+  TaskParamsDto,
+  TaskQueryDto,
+  UpdateTaskDto
+} from "./task.dtos";
+import {
+  createTask,
+  getTask,
+  listTasks,
+  removeTask,
+  replaceTask,
+  updateTask
+} from "./task.store";
+
+function parseTaskId(value: string) {
+  const id = coerce.id(value);
+  if (id === undefined) {
+    throw new HttpError(400, "Invalid task id.");
+  }
+  return id;
+}
+
+@Controller("/tasks")
+export class TaskController {
+  @Get("/")
+  @Query(TaskQueryDto)
+  @Returns(t.array(t.ref(TaskDto)))
+  list(ctx: RequestContext<unknown, TaskQueryDto>) {
+    const offset =
+      coerce.integer(ctx.query?.offset, { min: 0, clamp: true }) ?? 0;
+    const limit =
+      coerce.integer(ctx.query?.limit, { min: 1, max: 100, clamp: true }) ??
+      25;
+    const completed = coerce.boolean(ctx.query?.completed);
+
+    return listTasks({ offset, limit, completed });
+  }
+
+  @Get("/:id")
+  @Params(TaskParamsDto)
+  @Returns(TaskDto)
+  @TaskErrors
+  getOne(ctx: RequestContext<unknown, undefined, { id: string }>) {
+    const id = parseTaskId(ctx.params.id);
+    const task = getTask(id);
+    if (!task) {
+      throw new HttpError(404, "Task not found.");
+    }
+    return task;
+  }
+
+  @Post("/")
+  @Body(CreateTaskDto)
+  @Returns({ status: 201, schema: TaskDto, description: "Created." })
+  create(ctx: RequestContext<CreateTaskDto>) {
+    return createTask(ctx.body);
+  }
+
+  @Put("/:id")
+  @Params(TaskParamsDto)
+  @Body(ReplaceTaskDto)
+  @Returns(TaskDto)
+  @TaskErrors
+  replace(ctx: RequestContext<ReplaceTaskDto, undefined, { id: string }>) {
+    const id = parseTaskId(ctx.params.id);
+    const updated = replaceTask(id, ctx.body);
+    if (!updated) {
+      throw new HttpError(404, "Task not found.");
+    }
+    return updated;
+  }
+
+  @Patch("/:id")
+  @Params(TaskParamsDto)
+  @Body(UpdateTaskDto)
+  @Returns(TaskDto)
+  @TaskErrors
+  update(ctx: RequestContext<UpdateTaskDto, undefined, { id: string }>) {
+    const id = parseTaskId(ctx.params.id);
+    const task = updateTask(id, ctx.body);
+    if (!task) {
+      throw new HttpError(404, "Task not found.");
+    }
+    return task;
+  }
+
+  @Delete("/:id")
+  @Params(TaskParamsDto)
+  @Returns({ status: 204, description: "Deleted." })
+  @TaskErrors
+  remove(ctx: RequestContext<unknown, undefined, { id: string }>) {
+    const id = parseTaskId(ctx.params.id);
+    const removed = removeTask(id);
+    if (!removed) {
+      throw new HttpError(404, "Task not found.");
+    }
+  }
+}

package/examples/restful/task.dtos.ts

@@ -0,0 +1,66 @@
+import { Dto, Errors, Field, OmitDto, PartialDto, PickDto, t } from "../../src";
+
+@Dto({ description: "Task returned by the API." })
+export class TaskDto {
+  @Field(t.integer({ description: "Task identifier." }))
+  id!: number;
+
+  @Field(t.string({ minLength: 1 }))
+  title!: string;
+
+  @Field(t.boolean())
+  completed!: boolean;
+
+  @Field(t.dateTime({ description: "Creation timestamp." }))
+  createdAt!: string;
+}
+
+export interface CreateTaskDto
+  extends Omit<TaskDto, "id" | "createdAt" | "completed"> {
+  completed?: boolean;
+}
+
+@OmitDto(TaskDto, ["id", "createdAt"], {
+  overrides: {
+    completed: { optional: true }
+  }
+})
+export class CreateTaskDto {}
+
+export interface ReplaceTaskDto extends Omit<TaskDto, "id" | "createdAt"> {}
+
+@OmitDto(TaskDto, ["id", "createdAt"])
+export class ReplaceTaskDto {}
+
+export interface UpdateTaskDto extends Partial<ReplaceTaskDto> {}
+
+@PartialDto(ReplaceTaskDto)
+export class UpdateTaskDto {}
+
+export interface TaskParamsDto extends Pick<TaskDto, "id"> {}
+
+@PickDto(TaskDto, ["id"])
+export class TaskParamsDto {}
+
+@Dto()
+export class TaskQueryDto {
+  @Field(t.optional(t.integer({ minimum: 0 })))
+  offset?: number;
+
+  @Field(t.optional(t.integer({ minimum: 1, maximum: 100 })))
+  limit?: number;
+
+  @Field(t.optional(t.boolean()))
+  completed?: boolean;
+}
+
+@Dto()
+class ErrorDto {
+  @Field(t.string())
+  message!: string;
+}
+
+export const TaskErrors = Errors(ErrorDto, [
+  { status: 400, description: "Invalid id." },
+  { status: 404, description: "Not found." }
+]);

package/examples/restful/task.store.ts

@@ -0,0 +1,95 @@
+export type TaskRecord = {
+  id: number;
+  title: string;
+  completed: boolean;
+  createdAt: string;
+};
+
+let nextId = 1;
+const tasks: TaskRecord[] = [
+  {
+    id: nextId++,
+    title: "Sketch the REST surface",
+    completed: false,
+    createdAt: new Date().toISOString()
+  },
+  {
+    id: nextId++,
+    title: "Ship the first version",
+    completed: true,
+    createdAt: new Date().toISOString()
+  }
+];
+
+type TaskFilters = {
+  offset: number;
+  limit: number;
+  completed?: boolean;
+};
+
+export function listTasks({ offset, limit, completed }: TaskFilters) {
+  let result = tasks;
+  if (completed !== undefined) {
+    result = result.filter((task) => task.completed === completed);
+  }
+  return result.slice(offset, offset + limit);
+}
+
+export function getTask(id: number) {
+  return tasks.find((entry) => entry.id === id);
+}
+
+export function createTask(data: { title: string; completed?: boolean }) {
+  const task: TaskRecord = {
+    id: nextId++,
+    title: data.title,
+    completed: data.completed ?? false,
+    createdAt: new Date().toISOString()
+  };
+  tasks.push(task);
+  return task;
+}
+
+export function replaceTask(
+  id: number,
+  data: { title: string; completed: boolean }
+) {
+  const index = tasks.findIndex((entry) => entry.id === id);
+  if (index === -1) {
+    return undefined;
+  }
+  const updated: TaskRecord = {
+    id,
+    title: data.title,
+    completed: data.completed,
+    createdAt: tasks[index].createdAt
+  };
+  tasks[index] = updated;
+  return updated;
+}
+
+export function updateTask(
+  id: number,
+  data: { title?: string; completed?: boolean }
+) {
+  const task = tasks.find((entry) => entry.id === id);
+  if (!task) {
+    return undefined;
+  }
+  if (data.title !== undefined) {
+    task.title = data.title;
+  }
+  if (data.completed !== undefined) {
+    task.completed = data.completed;
+  }
+  return task;
+}
+
+export function removeTask(id: number) {
+  const index = tasks.findIndex((entry) => entry.id === id);
+  if (index === -1) {
+    return false;
+  }
+  tasks.splice(index, 1);
+  return true;
+}

package/examples/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true
+  },
+  "include": ["**/*.ts"]
+}