adorn-api 1.0.23 → 1.0.24

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

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

package/examples/metal-orm-sqlite-music/app.ts

@@ -0,0 +1,19 @@
+import { createExpressApp } from "../../src";
+import { initializeDatabase } from "./db";
+import { AlbumController } from "./album.controller";
+import { ArtistController } from "./artist.controller";
+import { TrackController } from "./track.controller";
+import { startExampleServer } from "../utils/start-server";
+
+export async function start() {
+  await initializeDatabase();
+
+  const app = createExpressApp({
+    controllers: [ArtistController, AlbumController, TrackController],
+    openApi: {
+      info: { title: "Music Library API", version: "1.0.0" },
+      docs: true
+    }
+  });
+  startExampleServer(app, { name: "Music Library API" });
+}

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

@@ -0,0 +1,272 @@
+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 {
+  CreateArtistDto,
+  ReplaceArtistDto,
+  UpdateArtistDto,
+  AlbumDto,
+  ArtistDto,
+  ArtistErrors,
+  ArtistParamsDto,
+  ArtistPagedResponseDto,
+  ArtistQueryDto,
+  ArtistQueryDtoClass
+} from "./artist.dtos";
+import {
+  CreateArtistAlbumDto,
+  CreateArtistAlbumDtoClass,
+  AlbumQueryDto,
+  AlbumQueryDtoClass,
+  AlbumPagedResponseDto
+} from "./album.dtos";
+import { Album as AlbumEntity } from "./album.entity";
+import { Artist } from "./artist.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 requireArtistId(value: unknown): number {
+  const id = parseInteger(value, { min: 1 });
+  if (id === undefined) {
+    const message = "Invalid artist id.";
+    throw new HttpError(
+      400,
+      message,
+      buildErrorBody(message, "INVALID_ARTIST_ID", [{ field: "id", message }])
+    );
+  }
+  return id;
+}
+
+const artistRef = entityRef(Artist);
+const albumRef = entityRef(AlbumEntity);
+
+type ArtistFilter = SimpleWhereInput<typeof Artist, "name" | "genre">;
+type ArtistAlbumFilter = SimpleWhereInput<typeof AlbumEntity, "artistId">;
+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 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 buildArtistFilter(query?: ArtistQueryDto): ArtistFilter | undefined {
+  if (!query) {
+    return undefined;
+  }
+  const filter: ArtistFilter = {};
+  if (query.nameContains) {
+    filter.name = { contains: query.nameContains };
+  }
+  if (query.genreContains) {
+    filter.genre = { contains: query.genreContains };
+  }
+  return Object.keys(filter).length ? filter : undefined;
+}
+
+@Controller("/artists")
+export class ArtistController {
+  @Get("/")
+  @Query(ArtistQueryDtoClass)
+  @Returns(ArtistPagedResponseDto)
+  async list(ctx: RequestContext<unknown, ArtistQueryDto>) {
+    const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      const filters = buildArtistFilter(ctx.query);
+      const query = applyFilter(
+        selectFromEntity(Artist).orderBy(artistRef.id, "ASC"),
+        Artist,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Get("/:id")
+  @Params(ArtistParamsDto)
+  @Returns(ArtistDto)
+  @ArtistErrors
+  async getOne(ctx: RequestContext<unknown, undefined, ArtistParamsDto>) {
+    const id = requireArtistId(ctx.params.id);
+    return withSession(async (session) => {
+      const artist = await getArtistOrThrow(session, id);
+      return artist as ArtistDto;
+    });
+  }
+
+  @Post("/")
+  @Body(CreateArtistDto)
+  @Returns({ status: 201, schema: ArtistDto })
+  async create(ctx: RequestContext<CreateArtistDto>) {
+    return withSession(async (session) => {
+      const artist = new Artist();
+      artist.name = ctx.body.name;
+      artist.genre = ctx.body.genre ?? null;
+      artist.country = ctx.body.country ?? null;
+      artist.formedYear = ctx.body.formedYear ?? null;
+      artist.createdAt = new Date().toISOString();
+      await session.persist(artist);
+      await session.commit();
+      return artist as ArtistDto;
+    });
+  }
+
+  @Put("/:id")
+  @Params(ArtistParamsDto)
+  @Body(ReplaceArtistDto)
+  @Returns(ArtistDto)
+  @ArtistErrors
+  async replace(ctx: RequestContext<ReplaceArtistDto, undefined, ArtistParamsDto>) {
+    const id = requireArtistId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getArtistOrThrow(session, id);
+      entity.name = ctx.body.name;
+      entity.genre = ctx.body.genre ?? null;
+      entity.country = ctx.body.country ?? null;
+      entity.formedYear = ctx.body.formedYear ?? null;
+      await session.commit();
+      return entity as ArtistDto;
+    });
+  }
+
+  @Patch("/:id")
+  @Params(ArtistParamsDto)
+  @Body(UpdateArtistDto)
+  @Returns(ArtistDto)
+  @ArtistErrors
+  async update(ctx: RequestContext<UpdateArtistDto, undefined, ArtistParamsDto>) {
+    const id = requireArtistId(ctx.params.id);
+    return withSession(async (session) => {
+      const entity = await getArtistOrThrow(session, id);
+      if (ctx.body.name !== undefined) {
+        entity.name = ctx.body.name;
+      }
+      if (ctx.body.genre !== undefined) {
+        entity.genre = ctx.body.genre ?? null;
+      }
+      if (ctx.body.country !== undefined) {
+        entity.country = ctx.body.country ?? null;
+      }
+      if (ctx.body.formedYear !== undefined) {
+        entity.formedYear = ctx.body.formedYear ?? null;
+      }
+      await session.commit();
+      return entity as ArtistDto;
+    });
+  }
+
+  @Get("/:id/albums")
+  @Params(ArtistParamsDto)
+  @Query(AlbumQueryDtoClass)
+  @Returns(AlbumPagedResponseDto)
+  @ArtistErrors
+  async listAlbums(
+    ctx: RequestContext<unknown, AlbumQueryDto, ArtistParamsDto>
+  ) {
+    const id = requireArtistId(ctx.params.id);
+    const paginationQuery = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(paginationQuery);
+    return withSession(async (session) => {
+      await getArtistOrThrow(session, id);
+      const filters: ArtistAlbumFilter = {
+        artistId: { equals: id }
+      };
+      const query = applyFilter(
+        selectFromEntity(AlbumEntity).orderBy(albumRef.id, "ASC"),
+        AlbumEntity,
+        filters
+      );
+      const paged = await query.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    });
+  }
+
+  @Post("/:id/albums")
+  @Params(ArtistParamsDto)
+  @Body(CreateArtistAlbumDtoClass)
+  @Returns({ status: 201, schema: AlbumDto })
+  @ArtistErrors
+  async createAlbum(
+    ctx: RequestContext<CreateArtistAlbumDto, undefined, ArtistParamsDto>
+  ) {
+    const id = requireArtistId(ctx.params.id);
+    return withSession(async (session) => {
+      const artist = await getArtistOrThrow(session, id);
+      const album = artist.albums.add({
+        title: ctx.body.title,
+        releaseYear: ctx.body.releaseYear ?? null,
+        createdAt: new Date().toISOString()
+      });
+      await session.commit();
+      return album as AlbumDto;
+    });
+  }
+
+  @Delete("/:id")
+  @Params(ArtistParamsDto)
+  @Returns({ status: 204 })
+  @ArtistErrors
+  async remove(ctx: RequestContext<unknown, undefined, ArtistParamsDto>) {
+    const id = requireArtistId(ctx.params.id);
+    return withSession(async (session) => {
+      const artist = await getArtistOrThrow(session, id);
+      await session.remove(artist);
+      await session.commit();
+    });
+  }
+}

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

@@ -0,0 +1,68 @@
+import {
+  Errors,
+  createMetalCrudDtoClasses,
+  createMetalDtoOverrides,
+  createPagedResponseDtoClass,
+  createPagedFilterQueryDtoClass,
+  StandardErrorDto,
+  t
+} from "../../src";
+import { Artist } from "./artist.entity";
+import { AlbumDto, CreateArtistAlbumDto } from "./album.dtos";
+
+const artistOverrides = createMetalDtoOverrides(Artist, {
+  overrides: {
+    genre: t.nullable(t.string()),
+    country: t.nullable(t.string()),
+    formedYear: t.nullable(t.integer({ minimum: 1000, maximum: 9999 }))
+  }
+});
+
+const artistCrud = createMetalCrudDtoClasses(Artist, {
+  overrides: artistOverrides,
+  response: { description: "Artist returned by API." },
+  mutationExclude: ["id", "createdAt"]
+});
+
+export const {
+  response: ArtistDto,
+  create: CreateArtistDto,
+  replace: ReplaceArtistDto,
+  update: UpdateArtistDto,
+  params: ArtistParamsDto
+} = artistCrud;
+
+export type ArtistDto = Omit<Artist, "albums">;
+type ArtistMutationDto = Omit<ArtistDto, "id" | "createdAt">;
+export type CreateArtistDto = ArtistMutationDto;
+export type ReplaceArtistDto = ArtistMutationDto;
+export type UpdateArtistDto = Partial<ArtistMutationDto>;
+export type ArtistParamsDto = InstanceType<typeof ArtistParamsDto>;
+
+export const ArtistQueryDtoClass = createPagedFilterQueryDtoClass({
+  name: "ArtistQueryDto",
+  filters: {
+    nameContains: { schema: t.string({ minLength: 1 }), operator: "contains" },
+    genreContains: { schema: t.string({ minLength: 1 }), operator: "contains" }
+  }
+});
+
+export interface ArtistQueryDto {
+  page?: number;
+  pageSize?: number;
+  nameContains?: string;
+  genreContains?: string;
+}
+
+export const ArtistPagedResponseDto = createPagedResponseDtoClass({
+  name: "ArtistPagedResponseDto",
+  itemDto: ArtistDto,
+  description: "Paged artist list response."
+});
+
+export const ArtistErrors = Errors(StandardErrorDto, [
+  { status: 400, description: "Invalid artist id." },
+  { status: 404, description: "Artist not found." }
+]);
+
+export { AlbumDto, CreateArtistAlbumDto };

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

@@ -0,0 +1,27 @@
+import { Column, Entity, HasMany, PrimaryKey, col } from "metal-orm";
+import type { HasManyCollection } from "metal-orm";
+import { Album } from "./album.entity";
+
+@Entity({ tableName: "artists" })
+export class Artist {
+  @PrimaryKey(col.autoIncrement(col.int()))
+  id!: number;
+
+  @Column(col.notNull(col.text()))
+  name!: string;
+
+  @Column(col.text())
+  genre?: string | null;
+
+  @Column(col.text())
+  country?: string | null;
+
+  @Column(col.int())
+  formedYear?: number | null;
+
+  @Column(col.notNull(col.text()))
+  createdAt!: string;
+
+  @HasMany({ target: () => Album, foreignKey: "artistId" })
+  albums!: HasManyCollection<Album>;
+}

package/examples/metal-orm-sqlite-music/db.ts

@@ -0,0 +1,148 @@
+import sqlite3 from "sqlite3";
+import {
+  Orm,
+  SqliteDialect,
+  createSqliteExecutor,
+  type SqliteClientLike
+} from "metal-orm";
+
+let db: sqlite3.Database | null = null;
+let orm: Orm | null = null;
+
+function execSql(database: sqlite3.Database, sql: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    database.exec(sql, (err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function createSqliteClient(database: sqlite3.Database): SqliteClientLike {
+  return {
+    all(sql, params = []) {
+      return new Promise((resolve, reject) => {
+        database.all(sql, params, (err, rows) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve(rows as Record<string, unknown>[]);
+        });
+      });
+    },
+    beginTransaction() {
+      return execSql(database, "BEGIN");
+    },
+    commitTransaction() {
+      return execSql(database, "COMMIT");
+    },
+    rollbackTransaction() {
+      return execSql(database, "ROLLBACK");
+    }
+  };
+}
+
+export async function initializeDatabase() {
+  db = new sqlite3.Database(":memory:");
+  await execSql(db, "pragma foreign_keys = ON");
+  await execSql(
+    db,
+    "create table artists (id integer primary key autoincrement, name text not null, genre text, country text, formedYear integer, createdAt text not null)"
+  );
+  await execSql(
+    db,
+    "create table albums (id integer primary key autoincrement, title text not null, releaseYear integer, artistId integer not null, createdAt text not null, foreign key(artistId) references artists(id))"
+  );
+  await execSql(
+    db,
+    "create table tracks (id integer primary key autoincrement, title text not null, durationSeconds integer, trackNumber integer, albumId integer not null, createdAt text not null, foreign key(albumId) references albums(id))"
+  );
+
+  await execSql(db, `
+    INSERT INTO artists (name, genre, country, formedYear, createdAt) VALUES 
+      ('The Beatles', 'Rock', 'United Kingdom', 1960, '2026-01-17T00:00:00.000Z'),
+      ('Led Zeppelin', 'Rock', 'United Kingdom', 1968, '2026-01-17T00:00:00.000Z'),
+      ('Pink Floyd', 'Progressive Rock', 'United Kingdom', 1965, '2026-01-17T00:00:00.000Z')
+  `);
+
+  await execSql(db, `
+    INSERT INTO albums (title, releaseYear, artistId, createdAt) VALUES 
+      ('Abbey Road', 1969, 1, '2026-01-17T00:00:00.000Z'),
+      ('Led Zeppelin IV', 1971, 2, '2026-01-17T00:00:00.000Z'),
+      ('The Dark Side of the Moon', 1973, 3, '2026-01-17T00:00:00.000Z'),
+      ('Sgt. Pepper''s Lonely Hearts Club Band', 1967, 1, '2026-01-17T00:00:00.000Z')
+  `);
+
+  await execSql(db, `
+    INSERT INTO tracks (title, durationSeconds, trackNumber, albumId, createdAt) VALUES 
+      ('Come Together', 259, 1, 1, '2026-01-17T00:00:00.000Z'),
+      ('Something', 182, 2, 1, '2026-01-17T00:00:00.000Z'),
+      ('Maxwell''s Silver Hammer', 207, 3, 1, '2026-01-17T00:00:00.000Z'),
+      ('Oh! Darling', 207, 4, 1, '2026-01-17T00:00:00.000Z'),
+      ('Octopus''s Garden', 169, 5, 1, '2026-01-17T00:00:00.000Z'),
+      ('I Want You (She''s So Heavy)', 467, 6, 1, '2026-01-17T00:00:00.000Z'),
+      ('Here Comes the Sun', 185, 7, 1, '2026-01-17T00:00:00.000Z'),
+      ('Because', 165, 8, 1, '2026-01-17T00:00:00.000Z'),
+      ('You Never Give Me Your Money', 239, 9, 1, '2026-01-17T00:00:00.000Z'),
+      ('Sun King', 146, 10, 1, '2026-01-17T00:00:00.000Z'),
+      ('Mean Mr. Mustard', 68, 11, 1, '2026-01-17T00:00:00.000Z'),
+      ('Polythene Pam', 75, 12, 1, '2026-01-17T00:00:00.000Z'),
+      ('She Came In Through the Bathroom Window', 119, 13, 1, '2026-01-17T00:00:00.000Z'),
+      ('Golden Slumbers', 90, 14, 1, '2026-01-17T00:00:00.000Z'),
+      ('Carry That Weight', 97, 15, 1, '2026-01-17T00:00:00.000Z'),
+      ('The End', 130, 16, 1, '2026-01-17T00:00:00.000Z'),
+      ('Her Majesty', 23, 17, 1, '2026-01-17T00:00:00.000Z'),
+      ('Black Dog', 296, 1, 2, '2026-01-17T00:00:00.000Z'),
+      ('Rock and Roll', 219, 2, 2, '2026-01-17T00:00:00.000Z'),
+      ('The Battle of Evermore', 354, 3, 2, '2026-01-17T00:00:00.000Z'),
+      ('Stairway to Heaven', 482, 4, 2, '2026-01-17T00:00:00.000Z'),
+      ('Misty Mountain Hop', 285, 5, 2, '2026-01-17T00:00:00.000Z'),
+      ('Four Sticks', 284, 6, 2, '2026-01-17T00:00:00.000Z'),
+      ('Going to California', 209, 7, 2, '2026-01-17T00:00:00.000Z'),
+      ('When the Levee Breaks', 427, 8, 2, '2026-01-17T00:00:00.000Z'),
+      ('Speak to Me', 90, 1, 3, '2026-01-17T00:00:00.000Z'),
+      ('Breathe', 156, 2, 3, '2026-01-17T00:00:00.000Z'),
+      ('On the Run', 216, 3, 3, '2026-01-17T00:00:00.000Z'),
+      ('Time', 404, 4, 3, '2026-01-17T00:00:00.000Z'),
+      ('The Great Gig in the Sky', 274, 5, 3, '2026-01-17T00:00:00.000Z'),
+      ('Money', 382, 6, 3, '2026-01-17T00:00:00.000Z'),
+      ('Us and Them', 462, 7, 3, '2026-01-17T00:00:00.000Z'),
+      ('Any Colour You Like', 206, 8, 3, '2026-01-17T00:00:00.000Z'),
+      ('Brain Damage', 228, 9, 3, '2026-01-17T00:00:00.000Z'),
+      ('Eclipse', 123, 10, 3, '2026-01-17T00:00:00.000Z'),
+      ('Sgt. Pepper''s Lonely Hearts Club Band', 120, 1, 4, '2026-01-17T00:00:00.000Z'),
+      ('With a Little Help from My Friends', 159, 2, 4, '2026-01-17T00:00:00.000Z'),
+      ('Lucy in the Sky with Diamonds', 209, 3, 4, '2026-01-17T00:00:00.000Z'),
+      ('Getting Better', 149, 4, 4, '2026-01-17T00:00:00.000Z'),
+      ('Fixing a Hole', 136, 5, 4, '2026-01-17T00:00:00.000Z'),
+      ('She''s Leaving Home', 271, 6, 4, '2026-01-17T00:00:00.000Z'),
+      ('Being for the Benefit of Mr. Kite!', 184, 7, 4, '2026-01-17T00:00:00.000Z'),
+      ('Within You Without You', 311, 8, 4, '2026-01-17T00:00:00.000Z'),
+      ('When I''m Sixty-Four', 161, 9, 4, '2026-01-17T00:00:00.000Z'),
+      ('Lovely Rita', 172, 10, 4, '2026-01-17T00:00:00.000Z'),
+      ('Good Morning Good Morning', 158, 11, 4, '2026-01-17T00:00:00.000Z'),
+      ('Sgt. Pepper''s Lonely Hearts Club Band (Reprise)', 61, 12, 4, '2026-01-17T00:00:00.000Z'),
+      ('A Day in the Life', 334, 13, 4, '2026-01-17T00:00:00.000Z')
+  `);
+
+  const executor = createSqliteExecutor(createSqliteClient(db));
+  orm = new Orm({
+    dialect: new SqliteDialect(),
+    executorFactory: {
+      createExecutor: () => executor,
+      createTransactionalExecutor: () => executor,
+      dispose: async () => {}
+    }
+  });
+}
+
+export function createSession() {
+  if (!orm) {
+    throw new Error("ORM not initialized");
+  }
+  return orm.createSession();
+}

package/examples/metal-orm-sqlite-music/index.ts

@@ -0,0 +1,6 @@
+import { start } from "./app";
+
+start().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});