adorn-api 1.1.4 → 1.1.6

package/README.md

@@ -353,7 +353,8 @@ export const {
   optionsDto: UserOptionsDto,
   errors: UserErrors,
   filterMappings: USER_FILTER_MAPPINGS,
-  sortableColumns: USER_SORTABLE_COLUMNS
+  sortableColumns: USER_SORTABLE_COLUMNS,
+  listConfig: USER_LIST_CONFIG
 } = createMetalCrudDtoClasses(User, {
   mutationExclude: ["id", "createdAt"],
   query: {
@@ -490,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
@@ -530,6 +605,82 @@ Breaking changes summary:
 - Generated outputs now include `queryDto`, `optionsQueryDto`, `pagedResponseDto`, `optionDto`, `optionsDto`, `errors`, `filterMappings`, and `sortableColumns`.
 - Consumers no longer need internal `dist/...` imports for query/filter metadata types; all relevant types/utilities are publicly exported from `adorn-api`.
 
+### Using `listConfig` (Zero-Duplication Service Layer)
+
+`createMetalCrudDtoClasses` now exposes a `listConfig` object that bundles all filter/sort/pagination config needed by your service layer. No more re-declaring mappings in your repository:
+
+```typescript
+// user.controller.ts — using listConfig directly
+import {
+  Controller, Get, Query, Returns,
+  parseFilter, parsePagination, parseSort,
+  type RequestContext
+} from "adorn-api";
+import { applyFilter, toPagedResponse } from "metal-orm";
+import { createSession } from "./db";
+import { User } from "./user.entity";
+import {
+  UserQueryDto,
+  UserPagedResponseDto,
+  USER_LIST_CONFIG
+} from "./user.dtos";
+
+@Controller("/users")
+export class UserController {
+  @Get("/")
+  @Query(UserQueryDto)
+  @Returns(UserPagedResponseDto)
+  async list(ctx: RequestContext<unknown, UserQueryDto>) {
+    const query = (ctx.query ?? {}) as Record<string, unknown>;
+    const { page, pageSize } = parsePagination(query, USER_LIST_CONFIG);
+    const filters = parseFilter(query, USER_LIST_CONFIG.filterMappings);
+    const sort = parseSort(query, USER_LIST_CONFIG.sortableColumns, {
+      defaultSortBy: USER_LIST_CONFIG.defaultSortBy,
+      defaultSortDirection: USER_LIST_CONFIG.defaultSortDirection
+    });
+    const direction = sort?.sortDirection === "desc" ? "DESC" : "ASC";
+
+    const session = createSession();
+    try {
+      const ormQuery = applyFilter(
+        User.select().orderBy(User.id, direction),
+        User,
+        filters
+      );
+      const paged = await ormQuery.executePaged(session, { page, pageSize });
+      return toPagedResponse(paged);
+    } finally {
+      await session.dispose();
+    }
+  }
+}
+```
+
+The `listConfig` object contains: `filterMappings`, `sortableColumns`, `defaultSortBy`, `defaultSortDirection`, `defaultPageSize`, `maxPageSize`, `sortByKey`, and `sortDirectionKey`.
+
+### Sort Order Compatibility (`sortOrder` / `sortDirection`)
+
+`parseSort` now accepts both `sortDirection` (lowercase `asc`/`desc`) and `sortOrder` (uppercase `ASC`/`DESC`). This avoids the need for a custom helper when integrating with clients that send uppercase sort orders.
+
+**Precedence**: `sortDirection` > `sortOrder` > default. Direction values are case-insensitive.
+
+```typescript
+// Client sends: ?sortBy=name&sortOrder=DESC
+const sort = parseSort(query, sortableColumns);
+// → { sortBy: "name", sortDirection: "desc", field: "name" }
+
+// Client sends both: ?sortBy=name&sortDirection=asc&sortOrder=DESC
+const sort2 = parseSort(query, sortableColumns);
+// → { sortBy: "name", sortDirection: "asc", field: "name" }  (sortDirection wins)
+
+// Custom sortOrder key:
+const sort3 = parseSort({
+  query,
+  sortableColumns,
+  sortOrderKey: "order"  // reads from query.order instead of query.sortOrder
+});
+```
+
 ### Deep Relation Filters
 
 `parseFilter` now accepts nested relation paths, so you can filter deep chains like Alpha → Bravo → Charlie → Delta. If

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/crud-dtos.js

@@ -161,6 +161,16 @@ function createMetalCrudDtoClasses(target, options = {}) {
         description: `${entityName} options response.`
     });
     const errors = buildStandardCrudErrors(entityName, errorOptions);
+    const listConfig = {
+        filterMappings,
+        sortableColumns,
+        defaultSortBy: queryOptions.defaultSortBy,
+        defaultSortDirection: queryOptions.defaultSortDirection ?? "asc",
+        defaultPageSize,
+        maxPageSize,
+        sortByKey,
+        sortDirectionKey
+    };
     return {
         response: crudClasses.response,
         create: crudClasses.create,
@@ -174,7 +184,8 @@ function createMetalCrudDtoClasses(target, options = {}) {
         optionsDto,
         errors,
         filterMappings,
-        sortableColumns
+        sortableColumns,
+        listConfig
     };
 }
 function createNestedCreateDtoClass(target, overrides, options) {

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, 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/sort.js

@@ -16,6 +16,7 @@ function parseSort(queryOrOptions, sortableColumns, options) {
     }
     const sortByKey = resolved.sortByKey ?? "sortBy";
     const sortDirectionKey = resolved.sortDirectionKey ?? "sortDirection";
+    const sortOrderKey = resolved.sortOrderKey ?? "sortOrder";
     const defaultSortBy = resolved.defaultSortBy;
     const defaultDirection = resolved.defaultSortDirection ?? "asc";
     const requestedSortBy = toTrimmedString(query[sortByKey]);
@@ -23,7 +24,8 @@ function parseSort(queryOrOptions, sortableColumns, options) {
     if (!selectedSortBy) {
         return undefined;
     }
-    const requestedDirection = toTrimmedString(query[sortDirectionKey]);
+    const requestedDirection = toTrimmedString(query[sortDirectionKey])
+        ?? toTrimmedString(query[sortOrderKey]);
     const sortDirection = normalizeDirection(requestedDirection, defaultDirection);
     return {
         sortBy: selectedSortBy,
@@ -44,10 +46,11 @@ function selectSortBy(requestedSortBy, defaultSortBy, allowed) {
     return undefined;
 }
 function normalizeDirection(raw, fallback) {
-    if (raw === "desc") {
+    const lower = raw?.toLowerCase();
+    if (lower === "desc") {
         return "desc";
     }
-    if (raw === "asc") {
+    if (lower === "asc") {
         return "asc";
     }
     return fallback;

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.
  */
@@ -119,6 +120,8 @@ export interface ParseSortOptions<T = Record<string, unknown>> {
     sortByKey?: string;
     /** Sort direction query key */
     sortDirectionKey?: string;
+    /** Query key for legacy sort order param (default: "sortOrder") */
+    sortOrderKey?: string;
     /** Default sort field */
     defaultSortBy?: string;
     /** Default sort direction */
@@ -135,6 +138,29 @@ export interface ParsedSort<T = Record<string, unknown>> {
     /** Resolved entity field */
     field?: FilterFieldInput<T>;
 }
+/**
+ * Ready-to-use list/query configuration extracted from CRUD DTO class generation.
+ * Eliminates the need for consumers to reassemble filter/sort/pagination config
+ * in their service or repository layer.
+ */
+export interface ListConfig<T = Record<string, unknown>> {
+    /** Execution-ready filter mappings for parseFilter */
+    filterMappings: Record<string, FilterMapping<T>>;
+    /** Execution-ready sortable column mappings for parseSort */
+    sortableColumns: MetalCrudSortableColumns<T>;
+    /** Default sort field key */
+    defaultSortBy?: string;
+    /** Default sort direction */
+    defaultSortDirection: SortDirection;
+    /** Default page size */
+    defaultPageSize: number;
+    /** Maximum page size */
+    maxPageSize: number;
+    /** Sort field query key */
+    sortByKey: string;
+    /** Sort direction query key */
+    sortDirectionKey: string;
+}
 /**
  * Filter operator.
  */
@@ -364,6 +390,51 @@ export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
     filterMappings: Record<string, FilterMapping<T>>;
     /** Execution-ready sortable column mappings */
     sortableColumns: MetalCrudSortableColumns<T>;
+    /** 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.4",
+  "version": "1.1.6",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",