adorn-api 1.1.5 → 1.1.6

package/README.md

@@ -491,6 +491,80 @@ export class UserController {
 
 ### Migration Guide (Breaking)
 
+### CRUD Controller Factory (`createCrudController`)
+
+When your controller only wires DTOs + service calls, you can generate the full CRUD controller and remove decorator boilerplate.
+
+```typescript
+// user.controller.ts
+import { createCrudController } from "adorn-api";
+import { userCrudDtos } from "./user.dtos";
+import { UserCrudService } from "./user.service";
+
+export const UserController = createCrudController({
+  path: "/users",
+  service: UserCrudService, // class or instance
+  dtos: userCrudDtos,       // result of createMetalCrudDtoClasses(...)
+  entityName: "User",       // used by parseIdOrThrow messages
+  withOptionsRoute: true,
+  withReplace: true,
+  withPatch: true,
+  withDelete: true
+});
+```
+
+Generated routes:
+- `GET /`
+- `GET /options` (optional)
+- `GET /:id`
+- `POST /`
+- `PUT /:id` (optional)
+- `PATCH /:id` (optional)
+- `DELETE /:id` (optional)
+
+The factory applies the correct `@Query/@Body/@Params/@Returns` schemas and also propagates `dtos.errors` to all `/:id` routes.
+
+Before (manual, repeated decorators/status/schema wiring):
+
+```typescript
+@Controller("/users")
+class UserController {
+  @Get("/")
+  @Query(UserQueryDto)
+  @Returns(UserPagedResponseDto)
+  async list(ctx: RequestContext<unknown, UserQueryDto>) { ... }
+
+  @Get("/:id")
+  @Params(UserParamsDto)
+  @Returns(UserDto)
+  @UserErrors
+  async getById(ctx: RequestContext<unknown, undefined, UserParamsDto>) { ... }
+
+  @Post("/")
+  @Body(CreateUserDto)
+  @Returns({ status: 201, schema: UserDto })
+  async create(ctx: RequestContext<CreateUserDto>) { ... }
+
+  // put/patch/delete/options...
+}
+```
+
+After (factory + service):
+
+```typescript
+export const UserController = createCrudController({
+  path: "/users",
+  service: new UserCrudService(),
+  dtos: userCrudDtos,
+  entityName: "User"
+});
+```
+
+When to use factory vs manual controller:
+- Use `createCrudController` when routes follow standard CRUD and behavior lives in a service.
+- Use a manual controller when route contracts diverge (custom status/body shape, non-standard params, upload/stream/raw endpoints, or route-level auth/doc decorators not shared by all CRUD routes).
+- For extra endpoints, keep the generated CRUD controller and add a second manual controller for custom routes on the same base path.
+
 Before (duplicated config):
 
 ```typescript

package/dist/adapter/metal-orm/crud-controller.d.ts

@@ -0,0 +1,16 @@
+import type { DtoConstructor } from "../../core/types";
+import type { RequestContext } from "../express/types";
+import type { CreateCrudControllerOptions, MetalCrudDtoClasses } from "./types";
+type DtoInstance<TDto extends DtoConstructor> = InstanceType<TDto>;
+export declare function createCrudController<TDtos extends MetalCrudDtoClasses<any>>(options: CreateCrudControllerOptions<TDtos>): {
+    new (): {
+        list(ctx: RequestContext<unknown, DtoInstance<TDtos["queryDto"]>>): Promise<DtoInstance<TDtos["pagedResponseDto"]>>;
+        options(ctx: RequestContext<unknown, DtoInstance<TDtos["optionsQueryDto"]>>): Promise<DtoInstance<TDtos["optionsDto"]>>;
+        getById(ctx: RequestContext<unknown, undefined, DtoInstance<TDtos["params"]>>): Promise<DtoInstance<TDtos["response"]>>;
+        create(ctx: RequestContext<DtoInstance<TDtos["create"]>>): Promise<DtoInstance<TDtos["response"]>>;
+        replace(ctx: RequestContext<DtoInstance<TDtos["replace"]>, undefined, DtoInstance<TDtos["params"]>>): Promise<DtoInstance<TDtos["response"]>>;
+        update(ctx: RequestContext<DtoInstance<TDtos["update"]>, undefined, DtoInstance<TDtos["params"]>>): Promise<DtoInstance<TDtos["response"]>>;
+        delete(ctx: RequestContext<unknown, undefined, DtoInstance<TDtos["params"]>>): Promise<void>;
+    };
+};
+export {};

package/dist/adapter/metal-orm/crud-controller.js

@@ -0,0 +1,156 @@
+"use strict";
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCrudController = createCrudController;
+const decorators_1 = require("../../core/decorators");
+const utils_1 = require("./utils");
+function createCrudController(options) {
+    const withOptionsRoute = options.withOptionsRoute ?? true;
+    const withReplace = options.withReplace ?? true;
+    const withPatch = options.withPatch ?? true;
+    const withDelete = options.withDelete ?? true;
+    const service = resolveService(options.service);
+    const routeErrorsDecorator = options.dtos.errors;
+    let GeneratedCrudController = (() => {
+        let _classDecorators = [(0, decorators_1.Controller)({ path: options.path, tags: options.tags })];
+        let _classDescriptor;
+        let _classExtraInitializers = [];
+        let _classThis;
+        let _instanceExtraInitializers = [];
+        let _list_decorators;
+        let _options_decorators;
+        let _getById_decorators;
+        let _create_decorators;
+        let _replace_decorators;
+        let _update_decorators;
+        let _delete_decorators;
+        var GeneratedCrudController = class {
+            static { _classThis = this; }
+            static {
+                const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+                _list_decorators = [(0, decorators_1.Get)("/"), (0, decorators_1.Query)(options.dtos.queryDto), (0, decorators_1.Returns)(options.dtos.pagedResponseDto)];
+                _options_decorators = [when(withOptionsRoute, (0, decorators_1.Get)("/options")), when(withOptionsRoute, (0, decorators_1.Query)(options.dtos.optionsQueryDto)), when(withOptionsRoute, (0, decorators_1.Returns)(options.dtos.optionsDto))];
+                _getById_decorators = [(0, decorators_1.Get)("/:id"), (0, decorators_1.Params)(options.dtos.params), (0, decorators_1.Returns)(options.dtos.response), applyRouteErrors(routeErrorsDecorator)];
+                _create_decorators = [(0, decorators_1.Post)("/"), (0, decorators_1.Body)(options.dtos.create), (0, decorators_1.Returns)({ status: 201, schema: options.dtos.response })];
+                _replace_decorators = [when(withReplace, (0, decorators_1.Put)("/:id")), when(withReplace, (0, decorators_1.Params)(options.dtos.params)), when(withReplace, (0, decorators_1.Body)(options.dtos.replace)), when(withReplace, (0, decorators_1.Returns)(options.dtos.response)), when(withReplace, applyRouteErrors(routeErrorsDecorator))];
+                _update_decorators = [when(withPatch, (0, decorators_1.Patch)("/:id")), when(withPatch, (0, decorators_1.Params)(options.dtos.params)), when(withPatch, (0, decorators_1.Body)(options.dtos.update)), when(withPatch, (0, decorators_1.Returns)(options.dtos.response)), when(withPatch, applyRouteErrors(routeErrorsDecorator))];
+                _delete_decorators = [when(withDelete, (0, decorators_1.Delete)("/:id")), when(withDelete, (0, decorators_1.Params)(options.dtos.params)), when(withDelete, (0, decorators_1.Returns)({ status: 204, description: "No Content" })), when(withDelete, applyRouteErrors(routeErrorsDecorator))];
+                __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _options_decorators, { kind: "method", name: "options", static: false, private: false, access: { has: obj => "options" in obj, get: obj => obj.options }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _getById_decorators, { kind: "method", name: "getById", static: false, private: false, access: { has: obj => "getById" in obj, get: obj => obj.getById }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _create_decorators, { kind: "method", name: "create", static: false, private: false, access: { has: obj => "create" in obj, get: obj => obj.create }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _replace_decorators, { kind: "method", name: "replace", static: false, private: false, access: { has: obj => "replace" in obj, get: obj => obj.replace }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _update_decorators, { kind: "method", name: "update", static: false, private: false, access: { has: obj => "update" in obj, get: obj => obj.update }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _delete_decorators, { kind: "method", name: "delete", static: false, private: false, access: { has: obj => "delete" in obj, get: obj => obj.delete }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+                GeneratedCrudController = _classThis = _classDescriptor.value;
+                if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+                __runInitializers(_classThis, _classExtraInitializers);
+            }
+            async list(ctx) {
+                return await service.list(ctx);
+            }
+            async options(ctx) {
+                assertServiceMethod(service, "options");
+                return await service.options(ctx);
+            }
+            async getById(ctx) {
+                const id = parseContextId(ctx, options.entityName);
+                return await service.getById(id, ctx);
+            }
+            async create(ctx) {
+                return await service.create(ctx.body, ctx);
+            }
+            async replace(ctx) {
+                assertServiceMethod(service, "replace");
+                const id = parseContextId(ctx, options.entityName);
+                return await service.replace(id, ctx.body, ctx);
+            }
+            async update(ctx) {
+                assertServiceMethod(service, "update");
+                const id = parseContextId(ctx, options.entityName);
+                return await service.update(id, ctx.body, ctx);
+            }
+            async delete(ctx) {
+                assertServiceMethod(service, "delete");
+                const id = parseContextId(ctx, options.entityName);
+                await service.delete(id, ctx);
+            }
+            constructor() {
+                __runInitializers(this, _instanceExtraInitializers);
+            }
+        };
+        return GeneratedCrudController = _classThis;
+    })();
+    Object.defineProperty(GeneratedCrudController, "name", {
+        value: `${options.entityName}CrudController`,
+        configurable: true
+    });
+    return GeneratedCrudController;
+}
+function resolveService(input) {
+    if (typeof input === "function") {
+        return new input();
+    }
+    return input;
+}
+function when(enabled, decorator) {
+    return (value, context) => {
+        if (enabled) {
+            decorator(value, context);
+        }
+    };
+}
+function applyRouteErrors(decorator) {
+    return (value, context) => {
+        decorator?.(value, context);
+    };
+}
+function parseContextId(ctx, entityName) {
+    const params = (ctx.params ?? {});
+    return (0, utils_1.parseIdOrThrow)(toIdValue(params.id), entityName);
+}
+function toIdValue(value) {
+    if (typeof value === "string" || typeof value === "number") {
+        return value;
+    }
+    return "";
+}
+function assertServiceMethod(service, method) {
+    if (typeof service[method] !== "function") {
+        throw new Error(`CRUD service is missing "${method}" method required by enabled route.`);
+    }
+}

package/dist/adapter/metal-orm/index.d.ts

@@ -4,9 +4,10 @@ export { parseFilter, createFilterMappings } from "./filters";
 export { parseSort } from "./sort";
 export { createPagedQueryDtoClass, createPagedResponseDtoClass, createPagedFilterQueryDtoClass } from "./paged-dtos";
 export { createMetalCrudDtos, createMetalCrudDtoClasses, createNestedCreateDtoClass } from "./crud-dtos";
+export { createCrudController } from "./crud-controller";
 export { createMetalTreeDtoClasses } from "./tree-dtos";
 export { createMetalDtoOverrides, type CreateMetalDtoOverridesOptions } from "./convention-overrides";
 export { createErrorDtoClass, StandardErrorDto, SimpleErrorDto, BasicErrorDto } from "./error-dtos";
 export { withSession, parseIdOrThrow, compactUpdates, applyInput, getEntityOrThrow } from "./utils";
 export { validateEntityMetadata, hasValidEntityMetadata } from "./field-builder";
-export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, ListConfig, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudQueryFilterDef, MetalCrudSortableColumns, MetalCrudOptionsQueryOptions, MetalCrudQueryOptions, MetalCrudStandardErrorsOptions, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNameKey, MetalCrudDtoClassNames, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";
+export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, ListConfig, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudQueryFilterDef, MetalCrudSortableColumns, MetalCrudOptionsQueryOptions, MetalCrudQueryOptions, MetalCrudStandardErrorsOptions, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNameKey, MetalCrudDtoClassNames, CrudControllerService, CrudControllerServiceInput, CreateCrudControllerOptions, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";

package/dist/adapter/metal-orm/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasValidEntityMetadata = exports.validateEntityMetadata = exports.getEntityOrThrow = exports.applyInput = exports.compactUpdates = exports.parseIdOrThrow = exports.withSession = exports.BasicErrorDto = exports.SimpleErrorDto = exports.StandardErrorDto = exports.createErrorDtoClass = exports.createMetalDtoOverrides = exports.createMetalTreeDtoClasses = exports.createNestedCreateDtoClass = exports.createMetalCrudDtoClasses = exports.createMetalCrudDtos = exports.createPagedFilterQueryDtoClass = exports.createPagedResponseDtoClass = exports.createPagedQueryDtoClass = exports.parseSort = exports.createFilterMappings = exports.parseFilter = exports.parsePagination = exports.MetalDto = void 0;
+exports.hasValidEntityMetadata = exports.validateEntityMetadata = exports.getEntityOrThrow = exports.applyInput = exports.compactUpdates = exports.parseIdOrThrow = exports.withSession = exports.BasicErrorDto = exports.SimpleErrorDto = exports.StandardErrorDto = exports.createErrorDtoClass = exports.createMetalDtoOverrides = exports.createMetalTreeDtoClasses = exports.createCrudController = exports.createNestedCreateDtoClass = exports.createMetalCrudDtoClasses = exports.createMetalCrudDtos = exports.createPagedFilterQueryDtoClass = exports.createPagedResponseDtoClass = exports.createPagedQueryDtoClass = exports.parseSort = exports.createFilterMappings = exports.parseFilter = exports.parsePagination = exports.MetalDto = void 0;
 // Ensure standard decorator metadata is available for metal-orm transformers.
 const symbolMetadata = Symbol.metadata;
 if (!symbolMetadata) {
@@ -23,6 +23,8 @@ var crud_dtos_1 = require("./crud-dtos");
 Object.defineProperty(exports, "createMetalCrudDtos", { enumerable: true, get: function () { return crud_dtos_1.createMetalCrudDtos; } });
 Object.defineProperty(exports, "createMetalCrudDtoClasses", { enumerable: true, get: function () { return crud_dtos_1.createMetalCrudDtoClasses; } });
 Object.defineProperty(exports, "createNestedCreateDtoClass", { enumerable: true, get: function () { return crud_dtos_1.createNestedCreateDtoClass; } });
+var crud_controller_1 = require("./crud-controller");
+Object.defineProperty(exports, "createCrudController", { enumerable: true, get: function () { return crud_controller_1.createCrudController; } });
 var tree_dtos_1 = require("./tree-dtos");
 Object.defineProperty(exports, "createMetalTreeDtoClasses", { enumerable: true, get: function () { return tree_dtos_1.createMetalTreeDtoClasses; } });
 var convention_overrides_1 = require("./convention-overrides");

package/dist/adapter/metal-orm/types.d.ts

@@ -2,6 +2,7 @@ import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToMany
 import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
+import type { RequestContext } from "../express/types";
 /**
  * Metal ORM DTO modes.
  */
@@ -392,6 +393,49 @@ export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
     /** Ready-to-use config for list/query endpoints (combines filters, sort, pagination defaults) */
     listConfig: ListConfig<T>;
 }
+/**
+ * Awaitable helper for CRUD service methods.
+ */
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * Input for CRUD controller service: class or ready instance.
+ */
+export type CrudControllerServiceInput<TDtos extends MetalCrudDtoClasses<any>> = CrudControllerService<TDtos> | (new () => CrudControllerService<TDtos>);
+/**
+ * CRUD controller service contract used by createCrudController.
+ */
+export interface CrudControllerService<TDtos extends MetalCrudDtoClasses<any>> {
+    list(ctx: RequestContext<unknown, InstanceType<TDtos["queryDto"]>>): Awaitable<InstanceType<TDtos["pagedResponseDto"]>>;
+    options?(ctx: RequestContext<unknown, InstanceType<TDtos["optionsQueryDto"]>>): Awaitable<InstanceType<TDtos["optionsDto"]>>;
+    getById(id: number, ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>): Awaitable<InstanceType<TDtos["response"]>>;
+    create(body: InstanceType<TDtos["create"]>, ctx: RequestContext<InstanceType<TDtos["create"]>>): Awaitable<InstanceType<TDtos["response"]>>;
+    replace?(id: number, body: InstanceType<TDtos["replace"]>, ctx: RequestContext<InstanceType<TDtos["replace"]>, undefined, InstanceType<TDtos["params"]>>): Awaitable<InstanceType<TDtos["response"]>>;
+    update?(id: number, body: InstanceType<TDtos["update"]>, ctx: RequestContext<InstanceType<TDtos["update"]>, undefined, InstanceType<TDtos["params"]>>): Awaitable<InstanceType<TDtos["response"]>>;
+    delete?(id: number, ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>): Awaitable<void>;
+}
+/**
+ * createCrudController options.
+ */
+export interface CreateCrudControllerOptions<TDtos extends MetalCrudDtoClasses<any>> {
+    /** Controller path. */
+    path: string;
+    /** Service instance or class (new () => service). */
+    service: CrudControllerServiceInput<TDtos>;
+    /** DTO bundle produced by createMetalCrudDtoClasses. */
+    dtos: TDtos;
+    /** Entity label used by parseIdOrThrow messages. */
+    entityName: string;
+    /** Generate GET /options route (default: true). */
+    withOptionsRoute?: boolean;
+    /** Generate PUT /:id route (default: true). */
+    withReplace?: boolean;
+    /** Generate PATCH /:id route (default: true). */
+    withPatch?: boolean;
+    /** Generate DELETE /:id route (default: true). */
+    withDelete?: boolean;
+    /** Optional OpenAPI tags for generated controller. */
+    tags?: string[];
+}
 /**
  * Metal Tree DTO class names.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/adapter/metal-orm/crud-controller.ts

@@ -0,0 +1,188 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Params,
+  Patch,
+  Post,
+  Put,
+  Query,
+  Returns
+} from "../../core/decorators";
+import type { DtoConstructor } from "../../core/types";
+import type { RequestContext } from "../express/types";
+import type {
+  CreateCrudControllerOptions,
+  CrudControllerService,
+  CrudControllerServiceInput,
+  MetalCrudDtoClasses,
+  RouteErrorsDecorator
+} from "./types";
+import { parseIdOrThrow } from "./utils";
+
+type DtoInstance<TDto extends DtoConstructor> = InstanceType<TDto>;
+type MethodDecorator = (
+  value: unknown,
+  context: ClassMethodDecoratorContext
+) => void;
+
+export function createCrudController<TDtos extends MetalCrudDtoClasses<any>>(
+  options: CreateCrudControllerOptions<TDtos>
+) {
+  const withOptionsRoute = options.withOptionsRoute ?? true;
+  const withReplace = options.withReplace ?? true;
+  const withPatch = options.withPatch ?? true;
+  const withDelete = options.withDelete ?? true;
+  const service = resolveService(options.service);
+  const routeErrorsDecorator = options.dtos.errors;
+
+  @Controller({ path: options.path, tags: options.tags })
+  class GeneratedCrudController {
+    @Get("/")
+    @Query(options.dtos.queryDto)
+    @Returns(options.dtos.pagedResponseDto)
+    async list(
+      ctx: RequestContext<unknown, DtoInstance<TDtos["queryDto"]>>
+    ): Promise<DtoInstance<TDtos["pagedResponseDto"]>> {
+      return await service.list(ctx);
+    }
+
+    @when(withOptionsRoute, Get("/options"))
+    @when(withOptionsRoute, Query(options.dtos.optionsQueryDto))
+    @when(withOptionsRoute, Returns(options.dtos.optionsDto))
+    async options(
+      ctx: RequestContext<unknown, DtoInstance<TDtos["optionsQueryDto"]>>
+    ): Promise<DtoInstance<TDtos["optionsDto"]>> {
+      assertServiceMethod(service, "options");
+      return await service.options(ctx);
+    }
+
+    @Get("/:id")
+    @Params(options.dtos.params)
+    @Returns(options.dtos.response)
+    @applyRouteErrors(routeErrorsDecorator)
+    async getById(
+      ctx: RequestContext<unknown, undefined, DtoInstance<TDtos["params"]>>
+    ): Promise<DtoInstance<TDtos["response"]>> {
+      const id = parseContextId(ctx, options.entityName);
+      return await service.getById(id, ctx);
+    }
+
+    @Post("/")
+    @Body(options.dtos.create)
+    @Returns({ status: 201, schema: options.dtos.response })
+    async create(
+      ctx: RequestContext<DtoInstance<TDtos["create"]>>
+    ): Promise<DtoInstance<TDtos["response"]>> {
+      return await service.create(ctx.body, ctx);
+    }
+
+    @when(withReplace, Put("/:id"))
+    @when(withReplace, Params(options.dtos.params))
+    @when(withReplace, Body(options.dtos.replace))
+    @when(withReplace, Returns(options.dtos.response))
+    @when(withReplace, applyRouteErrors(routeErrorsDecorator))
+    async replace(
+      ctx: RequestContext<
+        DtoInstance<TDtos["replace"]>,
+        undefined,
+        DtoInstance<TDtos["params"]>
+      >
+    ): Promise<DtoInstance<TDtos["response"]>> {
+      assertServiceMethod(service, "replace");
+      const id = parseContextId(ctx, options.entityName);
+      return await service.replace(id, ctx.body, ctx);
+    }
+
+    @when(withPatch, Patch("/:id"))
+    @when(withPatch, Params(options.dtos.params))
+    @when(withPatch, Body(options.dtos.update))
+    @when(withPatch, Returns(options.dtos.response))
+    @when(withPatch, applyRouteErrors(routeErrorsDecorator))
+    async update(
+      ctx: RequestContext<
+        DtoInstance<TDtos["update"]>,
+        undefined,
+        DtoInstance<TDtos["params"]>
+      >
+    ): Promise<DtoInstance<TDtos["response"]>> {
+      assertServiceMethod(service, "update");
+      const id = parseContextId(ctx, options.entityName);
+      return await service.update(id, ctx.body, ctx);
+    }
+
+    @when(withDelete, Delete("/:id"))
+    @when(withDelete, Params(options.dtos.params))
+    @when(withDelete, Returns({ status: 204, description: "No Content" }))
+    @when(withDelete, applyRouteErrors(routeErrorsDecorator))
+    async delete(
+      ctx: RequestContext<unknown, undefined, DtoInstance<TDtos["params"]>>
+    ): Promise<void> {
+      assertServiceMethod(service, "delete");
+      const id = parseContextId(ctx, options.entityName);
+      await service.delete(id, ctx);
+    }
+  }
+
+  Object.defineProperty(GeneratedCrudController, "name", {
+    value: `${options.entityName}CrudController`,
+    configurable: true
+  });
+
+  return GeneratedCrudController;
+}
+
+function resolveService<TDtos extends MetalCrudDtoClasses<any>>(
+  input: CrudControllerServiceInput<TDtos>
+): CrudControllerService<TDtos> {
+  if (typeof input === "function") {
+    return new input();
+  }
+  return input;
+}
+
+function when(enabled: boolean, decorator: MethodDecorator): MethodDecorator {
+  return (value, context) => {
+    if (enabled) {
+      decorator(value, context);
+    }
+  };
+}
+
+function applyRouteErrors(
+  decorator: RouteErrorsDecorator | undefined
+): MethodDecorator {
+  return (value, context) => {
+    decorator?.(value, context);
+  };
+}
+
+function parseContextId(
+  ctx: RequestContext<unknown, undefined, object | undefined>,
+  entityName: string
+): number {
+  const params = (ctx.params ?? {}) as Record<string, unknown>;
+  return parseIdOrThrow(toIdValue(params.id), entityName);
+}
+
+function toIdValue(value: unknown): string | number {
+  if (typeof value === "string" || typeof value === "number") {
+    return value;
+  }
+  return "";
+}
+
+function assertServiceMethod<
+  TDtos extends MetalCrudDtoClasses<any>,
+  TMethod extends "options" | "replace" | "update" | "delete"
+>(
+  service: CrudControllerService<TDtos>,
+  method: TMethod
+): asserts service is CrudControllerService<TDtos> & Record<TMethod, NonNullable<CrudControllerService<TDtos>[TMethod]>> {
+  if (typeof service[method] !== "function") {
+    throw new Error(
+      `CRUD service is missing "${method}" method required by enabled route.`
+    );
+  }
+}

package/src/adapter/metal-orm/index.ts

@@ -33,6 +33,10 @@ export {
   createNestedCreateDtoClass
 } from "./crud-dtos";
 
+export {
+  createCrudController
+} from "./crud-controller";
+
 export {
   createMetalTreeDtoClasses
 } from "./tree-dtos";
@@ -96,6 +100,9 @@ export type {
   MetalCrudDtoClasses,
   MetalCrudDtoClassNameKey,
   MetalCrudDtoClassNames,
+  CrudControllerService,
+  CrudControllerServiceInput,
+  CreateCrudControllerOptions,
   RouteErrorsDecorator,
   NestedCreateDtoOptions,
   MetalTreeDtoClassOptions,

package/src/adapter/metal-orm/types.ts

@@ -3,6 +3,7 @@ import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToMany
 import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
+import type { RequestContext } from "../express/types";
 
 /**
  * Metal ORM DTO modes.
@@ -475,6 +476,86 @@ export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
   listConfig: ListConfig<T>;
 }
 
+/**
+ * Awaitable helper for CRUD service methods.
+ */
+export type Awaitable<T> = T | Promise<T>;
+
+/**
+ * Input for CRUD controller service: class or ready instance.
+ */
+export type CrudControllerServiceInput<TDtos extends MetalCrudDtoClasses<any>> =
+  CrudControllerService<TDtos>
+  | (new () => CrudControllerService<TDtos>);
+
+/**
+ * CRUD controller service contract used by createCrudController.
+ */
+export interface CrudControllerService<TDtos extends MetalCrudDtoClasses<any>> {
+  list(
+    ctx: RequestContext<unknown, InstanceType<TDtos["queryDto"]>>
+  ): Awaitable<InstanceType<TDtos["pagedResponseDto"]>>;
+  options?(
+    ctx: RequestContext<unknown, InstanceType<TDtos["optionsQueryDto"]>>
+  ): Awaitable<InstanceType<TDtos["optionsDto"]>>;
+  getById(
+    id: number,
+    ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  create(
+    body: InstanceType<TDtos["create"]>,
+    ctx: RequestContext<InstanceType<TDtos["create"]>>
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  replace?(
+    id: number,
+    body: InstanceType<TDtos["replace"]>,
+    ctx: RequestContext<
+      InstanceType<TDtos["replace"]>,
+      undefined,
+      InstanceType<TDtos["params"]>
+    >
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  update?(
+    id: number,
+    body: InstanceType<TDtos["update"]>,
+    ctx: RequestContext<
+      InstanceType<TDtos["update"]>,
+      undefined,
+      InstanceType<TDtos["params"]>
+    >
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  delete?(
+    id: number,
+    ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>
+  ): Awaitable<void>;
+}
+
+/**
+ * createCrudController options.
+ */
+export interface CreateCrudControllerOptions<
+  TDtos extends MetalCrudDtoClasses<any>
+> {
+  /** Controller path. */
+  path: string;
+  /** Service instance or class (new () => service). */
+  service: CrudControllerServiceInput<TDtos>;
+  /** DTO bundle produced by createMetalCrudDtoClasses. */
+  dtos: TDtos;
+  /** Entity label used by parseIdOrThrow messages. */
+  entityName: string;
+  /** Generate GET /options route (default: true). */
+  withOptionsRoute?: boolean;
+  /** Generate PUT /:id route (default: true). */
+  withReplace?: boolean;
+  /** Generate PATCH /:id route (default: true). */
+  withPatch?: boolean;
+  /** Generate DELETE /:id route (default: true). */
+  withDelete?: boolean;
+  /** Optional OpenAPI tags for generated controller. */
+  tags?: string[];
+}
+
 /**
  * Metal Tree DTO class names.
  */

package/tests/unit/crud-controller-factory.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildOpenApi,
+  createCrudController,
+  createMetalCrudDtoClasses,
+  t,
+  type RequestContext
+} from "../../src/index";
+import { getControllerMeta } from "../../src/core/metadata";
+import { Column, Entity, PrimaryKey, col } from "metal-orm";
+
+@Entity({ tableName: "crud_factory_entities" })
+class CrudFactoryEntity {
+  @PrimaryKey(col.autoIncrement(col.int()))
+  id!: number;
+
+  @Column(col.notNull(col.text()))
+  nome!: string;
+
+  @Column(col.notNull(col.boolean()))
+  ativo!: boolean;
+}
+
+const crudDtos = createMetalCrudDtoClasses(CrudFactoryEntity, {
+  mutationExclude: ["id"],
+  query: {
+    filters: {
+      nomeContains: {
+        schema: t.string({ minLength: 1 }),
+        field: "nome",
+        operator: "contains"
+      },
+      ativo: {
+        schema: t.boolean(),
+        field: "ativo",
+        operator: "equals"
+      }
+    },
+    sortableColumns: {
+      id: "id",
+      nome: "nome"
+    },
+    options: {
+      labelField: "nome"
+    }
+  },
+  errors: true
+});
+
+class CrudFactoryService {
+  async list(_ctx: RequestContext<unknown, InstanceType<typeof crudDtos.queryDto>>) {
+    return { items: [], total: 0, page: 1, pageSize: 25 } as InstanceType<typeof crudDtos.pagedResponseDto>;
+  }
+
+  async options(_ctx: RequestContext<unknown, InstanceType<typeof crudDtos.optionsQueryDto>>) {
+    return { items: [], total: 0, page: 1, pageSize: 25 } as InstanceType<typeof crudDtos.optionsDto>;
+  }
+
+  async getById(
+    id: number,
+    _ctx: RequestContext<unknown, undefined, InstanceType<typeof crudDtos.params>>
+  ) {
+    return { id, nome: "Teste", ativo: true } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async create(
+    body: InstanceType<typeof crudDtos.create>,
+    _ctx: RequestContext<InstanceType<typeof crudDtos.create>>
+  ) {
+    return { id: 1, ...body } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async replace(
+    id: number,
+    body: InstanceType<typeof crudDtos.replace>,
+    _ctx: RequestContext<InstanceType<typeof crudDtos.replace>, undefined, InstanceType<typeof crudDtos.params>>
+  ) {
+    return { id, ...body } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async update(
+    id: number,
+    body: InstanceType<typeof crudDtos.update>,
+    _ctx: RequestContext<InstanceType<typeof crudDtos.update>, undefined, InstanceType<typeof crudDtos.params>>
+  ) {
+    return { id, ...body } as InstanceType<typeof crudDtos.response>;
+  }
+
+  async delete(
+    _id: number,
+    _ctx: RequestContext<unknown, undefined, InstanceType<typeof crudDtos.params>>
+  ) {}
+}
+
+const CrudFactoryController = createCrudController({
+  path: "/crud-factory",
+  service: CrudFactoryService,
+  dtos: crudDtos,
+  entityName: "CrudFactoryEntity"
+});
+
+describe("createCrudController", () => {
+  it("registers CRUD routes with expected schemas and statuses", () => {
+    const meta = getControllerMeta(CrudFactoryController);
+    expect(meta).toBeDefined();
+    expect(meta?.basePath).toBe("/crud-factory");
+
+    const routeKeys = (meta?.routes ?? [])
+      .map((route) => `${route.httpMethod} ${route.path}`)
+      .sort();
+
+    expect(routeKeys).toEqual([
+      "delete /:id",
+      "get /",
+      "get /:id",
+      "get /options",
+      "patch /:id",
+      "post /",
+      "put /:id"
+    ]);
+
+    const byKey = new Map(
+      (meta?.routes ?? []).map((route) => [`${route.httpMethod} ${route.path}`, route] as const)
+    );
+
+    const listRoute = byKey.get("get /");
+    expect(listRoute?.query?.schema).toBe(crudDtos.queryDto);
+    expect(listRoute?.responses).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: 200, schema: crudDtos.pagedResponseDto })
+      ])
+    );
+
+    const optionsRoute = byKey.get("get /options");
+    expect(optionsRoute?.query?.schema).toBe(crudDtos.optionsQueryDto);
+    expect(optionsRoute?.responses).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: 200, schema: crudDtos.optionsDto })
+      ])
+    );
+
+    const createRoute = byKey.get("post /");
+    expect(createRoute?.body?.schema).toBe(crudDtos.create);
+    expect(createRoute?.responses).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ status: 201, schema: crudDtos.response })
+      ])
+    );
+
+    for (const key of ["get /:id", "put /:id", "patch /:id", "delete /:id"]) {
+      const route = byKey.get(key);
+      expect(route?.params?.schema).toBe(crudDtos.params);
+      expect(route?.responses).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ status: 400, error: true }),
+          expect.objectContaining({ status: 404, error: true })
+        ])
+      );
+    }
+
+    expect(byKey.get("put /:id")?.body?.schema).toBe(crudDtos.replace);
+    expect(byKey.get("patch /:id")?.body?.schema).toBe(crudDtos.update);
+    expect(byKey.get("delete /:id")?.responses).toEqual(
+      expect.arrayContaining([expect.objectContaining({ status: 204 })])
+    );
+  });
+
+  it("exposes matching schemas/status in OpenAPI", () => {
+    const doc = buildOpenApi({
+      info: { title: "Test API", version: "1.0.0" },
+      controllers: [CrudFactoryController]
+    });
+
+    const listResponses = (doc.paths["/crud-factory"]?.get as Record<string, any>)?.responses;
+    const createResponses = (doc.paths["/crud-factory"]?.post as Record<string, any>)?.responses;
+    const getByIdResponses = (doc.paths["/crud-factory/{id}"]?.get as Record<string, any>)?.responses;
+    const deleteResponses = (doc.paths["/crud-factory/{id}"]?.delete as Record<string, any>)?.responses;
+
+    expect(listResponses?.["200"]).toBeDefined();
+    expect(createResponses?.["201"]).toBeDefined();
+    expect(getByIdResponses?.["200"]).toBeDefined();
+    expect(getByIdResponses?.["400"]).toBeDefined();
+    expect(getByIdResponses?.["404"]).toBeDefined();
+    expect(deleteResponses?.["204"]).toBeDefined();
+  });
+
+  it("supports disabling optional routes with flags", () => {
+    const MinimalController = createCrudController({
+      path: "/crud-factory-minimal",
+      service: new CrudFactoryService(),
+      dtos: crudDtos,
+      entityName: "CrudFactoryEntity",
+      withOptionsRoute: false,
+      withReplace: false,
+      withPatch: false,
+      withDelete: false
+    });
+
+    const meta = getControllerMeta(MinimalController);
+    const routeKeys = (meta?.routes ?? [])
+      .map((route) => `${route.httpMethod} ${route.path}`)
+      .sort();
+
+    expect(routeKeys).toEqual([
+      "get /",
+      "get /:id",
+      "post /"
+    ]);
+  });
+
+  it("uses entityName in parseIdOrThrow messages", async () => {
+    const controller = new CrudFactoryController();
+    await expect(
+      controller.getById({
+        params: { id: "invalid" }
+      } as any)
+    ).rejects.toMatchObject({
+      status: 400,
+      message: "Invalid CrudFactoryEntity id."
+    });
+  });
+});