adorn-api 1.0.40 → 1.0.42

package/README.md

@@ -9,7 +9,7 @@ A modern, decorator-first web framework built on Express with built-in OpenAPI 3
 - 🔌 **Express Integration**: Built on top of Express for familiarity and extensibility
 - 🎯 **Type-Safe Data Transfer Objects**: Define schemas with TypeScript for compile-time checks
 - 🔄 **DTO Composition**: Reuse and compose DTOs with PickDto, OmitDto, PartialDto, and MergeDto
-- 📦 **Metal ORM Integration**: First-class support for Metal ORM with auto-generated CRUD DTOs, including transformer-aware schema generation
+- 📦 **Metal ORM Integration**: First-class support for Metal ORM with auto-generated CRUD DTOs, transformer-aware schema generation, and tree DTOs for nested set (MPTT) models
 - 🚀 **Streaming Support**: Server-Sent Events (SSE) and streaming responses
 - 📝 **Request Validation**: Automatic validation of request bodies, params, query, and headers
 - 🔧 **Transformers**: Custom field transformations with @Transform decorator and built-in transform functions
@@ -18,15 +18,15 @@ A modern, decorator-first web framework built on Express with built-in OpenAPI 3
 - 🌐 **CORS Support**: Built-in CORS configuration
 - 🏗️ **Lifecycle Hooks**: Application bootstrap and shutdown lifecycle events
 
-## Installation
-
-```bash
-npm install adorn-api
-```
-
-Note: Adorn uses Stage 3 decorator metadata (`Symbol.metadata`). If the runtime does not provide it, Adorn polyfills `Symbol.metadata` on import to keep decorator metadata consistent.
-
-## Quick Start
+## Installation
+
+```bash
+npm install adorn-api
+```
+
+Note: Adorn uses Stage 3 decorator metadata (`Symbol.metadata`). If the runtime does not provide it, Adorn polyfills `Symbol.metadata` on import to keep decorator metadata consistent.
+
+## Quick Start
 
 ### 1. Define DTOs
 
@@ -159,9 +159,9 @@ async getOne(ctx: RequestContext) {
 }
 ```
 
-### DTOs (Data Transfer Objects)
-
-DTOs define the shape of data sent to and from your API. They provide validation, documentation, and type safety.
+### DTOs (Data Transfer Objects)
+
+DTOs define the shape of data sent to and from your API. They provide validation, documentation, and type safety.
 
 ```typescript
 @Dto({ description: "User data" })
@@ -171,16 +171,16 @@ export class UserDto {
 
   @Field(t.string({ minLength: 2, maxLength: 100 }))
   name!: string;
-}
-```
-
-### Stage 3 Decorator Metadata
-
-Adorn relies on Stage 3 decorator metadata (`Symbol.metadata`) to connect information across decorators (DTO fields, routes, params, etc.). If the runtime does not provide it, Adorn polyfills `Symbol.metadata` on import so decorators share a consistent metadata object.
-
-### Request Context
-
-Each route handler receives a `RequestContext` object that provides access to:
+}
+```
+
+### Stage 3 Decorator Metadata
+
+Adorn relies on Stage 3 decorator metadata (`Symbol.metadata`) to connect information across decorators (DTO fields, routes, params, etc.). If the runtime does not provide it, Adorn polyfills `Symbol.metadata` on import so decorators share a consistent metadata object.
+
+### Request Context
+
+Each route handler receives a `RequestContext` object that provides access to:
 - `ctx.body` - The request body (validated and typed)
 - `ctx.params` - Route parameters
 - `ctx.query` - Query parameters
@@ -267,10 +267,10 @@ class UploadController {
 }
 ```
 
-## Metal ORM Integration
+## Metal ORM Integration
 
-Adorn API has first-class support for Metal ORM, providing automatic CRUD DTO generation.
-Transformer decorators such as `@Email`, `@Length`, `@Pattern`, and `@Alphanumeric` are reflected in the generated DTO schemas (validation + OpenAPI).
+Adorn API has first-class support for Metal ORM, providing automatic CRUD DTO generation.
+Transformer decorators such as `@Email`, `@Length`, `@Pattern`, and `@Alphanumeric` are reflected in the generated DTO schemas (validation + OpenAPI).
 
 ### 1. Define Entities
 
@@ -308,7 +308,7 @@ export const {
 } = createMetalCrudDtoClasses(User);
 ```
 
-### 3. Create a CRUD Controller
+### 3. Create a CRUD Controller
 
 ```typescript
 // user.controller.ts
@@ -376,8 +376,46 @@ export class UserController {
   }
 
   // Other CRUD operations...
-}
-```
+}
+```
+
+### Tree DTOs (Nested Set / MPTT)
+
+Metal ORM's tree helpers map cleanly into Adorn. Use `createMetalTreeDtoClasses` to generate DTOs for tree nodes,
+node results, threaded trees, and tree lists. These schemas are included in OpenAPI automatically.
+
+```typescript
+// category.dtos.ts
+import { createMetalTreeDtoClasses } from "adorn-api";
+import { CategoryDto } from "./category.dtos";
+import { Category } from "./category.entity";
+
+export const {
+  node: CategoryNodeDto,
+  nodeResult: CategoryNodeResultDto,
+  threadedNode: CategoryThreadedNodeDto,
+  treeListEntry: CategoryTreeListEntryDto,
+  treeListSchema: CategoryTreeListSchema,
+  threadedTreeSchema: CategoryThreadedTreeSchema
+} = createMetalTreeDtoClasses(Category, {
+  entityDto: CategoryDto
+});
+```
+
+```typescript
+// category.controller.ts
+import { Controller, Get, Returns } from "adorn-api";
+import { CategoryThreadedTreeSchema } from "./category.dtos";
+
+@Controller("/categories")
+class CategoryController {
+  @Get("/tree")
+  @Returns(CategoryThreadedTreeSchema)
+  async tree() {
+    // return threaded tree data
+  }
+}
+```
 
 ## Configuration
 
@@ -723,14 +761,15 @@ export class UserDto {
 }
 ```
 
-## Examples
+## Examples
 
 Check out the `examples/` directory for more comprehensive examples:
 
 - `basic/` - Simple API with controllers and DTOs
 - `restful/` - RESTful API with complete CRUD operations
-- `metal-orm-sqlite/` - Metal ORM integration with SQLite
-- `metal-orm-sqlite-music/` - Complex relations with Metal ORM
+- `metal-orm-sqlite/` - Metal ORM integration with SQLite
+- `metal-orm-tree/` - Metal ORM tree (nested set) DTO + OpenAPI integration
+- `metal-orm-sqlite-music/` - Complex relations with Metal ORM
 - `streaming/` - SSE and streaming responses
 - `openapi/` - OpenAPI documentation customization
 - `validation/` - Comprehensive validation examples with various schema types

package/dist/adapter/express/openapi.js

@@ -16,7 +16,13 @@ function attachOpenApi(app, controllers, options) {
         controllers
     });
     app.get(openApiPath, (_req, res) => {
-        res.json(document);
+        if (options.prettyPrint) {
+            res.setHeader("Content-Type", "application/json");
+            res.send(JSON.stringify(document, null, 2));
+        }
+        else {
+            res.json(document);
+        }
     });
     if (!options.docs) {
         return;

package/dist/adapter/express/response-serializer.js

@@ -62,6 +62,9 @@ function serializeWithSchema(value, schema) {
     }
 }
 function serializeString(value, format) {
+    if (format === "byte" && Buffer.isBuffer(value)) {
+        return value.toString("base64");
+    }
     if (!(value instanceof Date)) {
         return value;
     }

package/dist/adapter/express/types.d.ts

@@ -94,6 +94,8 @@ export interface OpenApiExpressOptions {
     servers?: OpenApiServer[];
     /** Path for OpenAPI JSON endpoint */
     path?: string;
+    /** Whether to pretty-print the JSON output (defaults to false for minified output) */
+    prettyPrint?: boolean;
     /** Documentation UI configuration */
     docs?: boolean | OpenApiDocsOptions;
 }

package/dist/core/metadata.js

@@ -8,6 +8,11 @@ exports.getAllDtos = getAllDtos;
 exports.registerController = registerController;
 exports.getControllerMeta = getControllerMeta;
 exports.getAllControllers = getAllControllers;
+// Ensure standard decorator metadata is available for Stage 3 decorators.
+const symbolMetadata = Symbol.metadata;
+if (!symbolMetadata) {
+    Symbol.metadata = Symbol("Symbol.metadata");
+}
 const dtoStore = new Map();
 const controllerStore = new Map();
 exports.META_KEY = Symbol.for("adorn.metadata");

package/dist/core/schema.d.ts

@@ -210,6 +210,14 @@ export declare const t: {
      * @returns Date-time string schema
      */
     dateTime: (opts?: Omit<StringSchema, "kind" | "format">) => StringSchema;
+    /**
+     * Creates a bytes (base64-encoded binary) string schema.
+     * Maps to OpenAPI type: "string" with format: "byte".
+     * Buffer values are automatically base64-encoded during response serialization.
+     * @param opts - String schema options
+     * @returns Bytes string schema
+     */
+    bytes: (opts?: Omit<StringSchema, "kind" | "format">) => StringSchema;
     /**
      * Creates a number schema.
      * @param opts - Number schema options

package/dist/core/schema.js

@@ -34,6 +34,18 @@ exports.t = {
         format: "date-time",
         ...opts
     }),
+    /**
+     * Creates a bytes (base64-encoded binary) string schema.
+     * Maps to OpenAPI type: "string" with format: "byte".
+     * Buffer values are automatically base64-encoded during response serialization.
+     * @param opts - String schema options
+     * @returns Bytes string schema
+     */
+    bytes: (opts = {}) => ({
+        kind: "string",
+        format: "byte",
+        ...opts
+    }),
     /**
      * Creates a number schema.
      * @param opts - Number schema options

package/examples/basic/app.ts

@@ -1,12 +1,12 @@
 import { createExpressApp } from "../../src";
 import { UserController } from "./user.controller";
 
-export function createApp() {
-  return createExpressApp({
-    controllers: [UserController],
-    openApi: {
-      info: {
-        title: "Adorn API",
+export async function createApp() {
+  return createExpressApp({
+    controllers: [UserController],
+    openApi: {
+      info: {
+        title: "Adorn API",
         version: "1.0.0"
       },
       docs: true

package/examples/basic/index.ts

@@ -1,6 +1,12 @@
-import { createApp } from "./app";
-import { startExampleServer } from "../utils/start-server";
-
-const app = createApp();
-
-startExampleServer(app, { name: "Adorn API" });
+import { createApp } from "./app";
+import { startExampleServer } from "../utils/start-server";
+
+async function start() {
+  const app = await createApp();
+  startExampleServer(app, { name: "Adorn API" });
+}
+
+start().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/metal-orm-postgres/app.ts

@@ -7,7 +7,7 @@ import { startExampleServer } from "../utils/start-server";
 export async function start() {
   await initializeDatabase();
 
-  const app = createExpressApp({
+  const app = await createExpressApp({
     controllers: [UserController, PostController],
     openApi: {
       info: { title: "Postgres (PGlite) + MetalORM REST example", version: "1.0.0" },

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

@@ -7,12 +7,12 @@ import { startExampleServer } from "../utils/start-server";
 export async function start() {
   await initializeDatabase();
 
-  const app = createExpressApp({
-    controllers: [UserController, PostController],
-    openApi: {
-      info: { title: "SQLite + MetalORM REST example", version: "1.0.0" },
-      docs: true
-    }
+  const app = await createExpressApp({
+    controllers: [UserController, PostController],
+    openApi: {
+      info: { title: "SQLite + MetalORM REST example", version: "1.0.0" },
+      docs: true
+    }
   });
   startExampleServer(app, { name: "SQLite + MetalORM REST example" });
 }

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

@@ -8,12 +8,12 @@ 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
-    }
+  const app = await 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-tree/app.ts

@@ -0,0 +1,24 @@
+import { createExpressApp } from "../../src";
+import { initializeDatabase } from "./db";
+import { CategoryController } from "./entity.controller";
+import { startExampleServer } from "../utils/start-server";
+
+export async function start() {
+  await initializeDatabase();
+
+  const app = await createExpressApp({
+    controllers: [CategoryController],
+    openApi: {
+      info: { title: "MetalORM Tree example", version: "1.0.0" },
+      docs: true
+    }
+  });
+
+  startExampleServer(app, {
+    name: "MetalORM Tree example",
+    extraLogs: [
+      (port) => `Tree endpoint: http://localhost:${port}/categories/tree`,
+      (port) => `List endpoint: http://localhost:${port}/categories/list`
+    ]
+  });
+}

package/examples/metal-orm-tree/db.ts

@@ -0,0 +1,92 @@
+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 categories (
+      id integer primary key autoincrement,
+      name text not null,
+      parentId integer,
+      lft integer not null,
+      rght integer not null,
+      depth integer,
+      foreign key(parentId) references categories(id)
+    )`
+  );
+
+  await execSql(
+    db,
+    `insert into categories (id, name, parentId, lft, rght, depth) values
+      (1, 'Electronics', null, 1, 10, 0),
+      (2, 'Computers', 1, 2, 5, 1),
+      (3, 'Laptops', 2, 3, 4, 2),
+      (4, 'Phones', 1, 6, 9, 1),
+      (5, 'Smartphones', 4, 7, 8, 2)
+    `
+  );
+
+  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-tree/entity.controller.ts

@@ -0,0 +1,79 @@
+import {
+  Controller,
+  Get,
+  HttpError,
+  Params,
+  Returns,
+  parseIdOrThrow,
+  withSession,
+  type RequestContext
+} from "../../src";
+import {
+  createTreeManager,
+  formatTreeList,
+  getTableDefFromEntity,
+  threadResults,
+  treeQuery
+} from "metal-orm";
+import { createSession } from "./db";
+import { Category } from "./entity.entity";
+import {
+  CategoryNodeResultDto,
+  CategoryParamsDto,
+  CategoryThreadedTreeSchema,
+  CategoryTreeListSchema
+} from "./entity.dtos";
+
+const categoryTable = getTableDefFromEntity(Category);
+if (!categoryTable) {
+  throw new Error("Category entity metadata was not initialized.");
+}
+
+const tree = treeQuery(categoryTable, {
+  parentKey: "parentId",
+  leftKey: "lft",
+  rightKey: "rght",
+  depthKey: "depth"
+});
+
+@Controller("/categories")
+export class CategoryController {
+  @Get("/tree")
+  @Returns(CategoryThreadedTreeSchema)
+  async tree() {
+    return withSession(createSession, async (session) => {
+      const rows = await tree.findTreeList().execute(session);
+      return threadResults(rows, tree.config.leftKey, tree.config.rightKey);
+    });
+  }
+
+  @Get("/list")
+  @Returns(CategoryTreeListSchema)
+  async list() {
+    return withSession(createSession, async (session) => {
+      const rows = await tree.findTreeList().execute(session);
+      return formatTreeList(rows, {
+        keyPath: "id",
+        valuePath: "name",
+        depthKey: tree.config.depthKey,
+        leftKey: tree.config.leftKey,
+        rightKey: tree.config.rightKey
+      });
+    });
+  }
+
+  @Get("/:id")
+  @Params(CategoryParamsDto)
+  @Returns(CategoryNodeResultDto)
+  async getNode(ctx: RequestContext<unknown, undefined, { id: string | number }>) {
+    const id = parseIdOrThrow(ctx.params.id, "Category");
+    return withSession(createSession, async (session) => {
+      const manager = createTreeManager(session, categoryTable, tree.config);
+      const node = await manager.getNode(id);
+      if (!node) {
+        throw new HttpError(404, "Category not found.");
+      }
+      return node;
+    });
+  }
+}

package/examples/metal-orm-tree/entity.dtos.ts

@@ -0,0 +1,31 @@
+import {
+  createMetalCrudDtoClasses,
+  createMetalTreeDtoClasses
+} from "../../src";
+import { Category } from "./entity.entity";
+
+const categoryCrud = createMetalCrudDtoClasses(Category, {
+  response: {
+    description: "Category returned by API."
+  },
+  mutationExclude: ["id", "lft", "rght", "depth"]
+});
+
+export const {
+  response: CategoryDto,
+  create: CreateCategoryDto,
+  replace: ReplaceCategoryDto,
+  update: UpdateCategoryDto,
+  params: CategoryParamsDto
+} = categoryCrud;
+
+export const {
+  node: CategoryNodeDto,
+  nodeResult: CategoryNodeResultDto,
+  threadedNode: CategoryThreadedNodeDto,
+  treeListEntry: CategoryTreeListEntryDto,
+  treeListSchema: CategoryTreeListSchema,
+  threadedTreeSchema: CategoryThreadedTreeSchema
+} = createMetalTreeDtoClasses(Category, {
+  entityDto: CategoryDto
+});

package/examples/metal-orm-tree/entity.entity.ts

@@ -0,0 +1,29 @@
+import { Column, Entity, PrimaryKey, Tree, TreeChildren, TreeParent, col } from "metal-orm";
+
+@Entity({ tableName: "categories" })
+@Tree({ parentKey: "parentId", leftKey: "lft", rightKey: "rght", depthKey: "depth" })
+export class Category {
+  @PrimaryKey(col.autoIncrement(col.int()))
+  id!: number;
+
+  @Column(col.notNull(col.text()))
+  name!: string;
+
+  @Column(col.int())
+  parentId?: number | null;
+
+  @Column(col.notNull(col.int()))
+  lft!: number;
+
+  @Column(col.notNull(col.int()))
+  rght!: number;
+
+  @Column(col.int())
+  depth?: number | null;
+
+  @TreeParent()
+  parent?: Category;
+
+  @TreeChildren()
+  children?: Category[];
+}

package/examples/metal-orm-tree/index.ts

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

package/examples/restful/app.ts

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

package/examples/restful/index.ts

@@ -1,9 +1,15 @@
-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`]
-});
+import { createApp } from "./app";
+import { startExampleServer } from "../utils/start-server";
+
+async function start() {
+  const app = await createApp();
+  startExampleServer(app, {
+    name: "Tasks API",
+    extraLogs: [(port) => `Swagger UI available at http://localhost:${port}/docs`]
+  });
+}
+
+start().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.0.40",
+  "version": "1.0.42",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "express": "^4.19.2",
-    "metal-orm": "^1.0.109"
+    "metal-orm": "^1.0.115"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.15",

package/src/adapter/express/response-serializer.ts

@@ -65,6 +65,9 @@ function serializeWithSchema(value: unknown, schema: SchemaNode): unknown {
 }
 
 function serializeString(value: unknown, format: string | undefined): unknown {
+  if (format === "byte" && Buffer.isBuffer(value)) {
+    return value.toString("base64");
+  }
   if (!(value instanceof Date)) {
     return value;
   }