adorn-api 1.1.4 → 1.1.5

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: {
@@ -530,6 +531,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-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

@@ -9,4 +9,4 @@ export { createMetalDtoOverrides, type CreateMetalDtoOverridesOptions } from "./
 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, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";

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

@@ -119,6 +119,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 +137,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 +389,8 @@ 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>;
 }
 /**
  * Metal Tree DTO class names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "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-dtos.ts

@@ -166,6 +166,17 @@ export function createMetalCrudDtoClasses<TEntity extends Record<string, unknown
 
   const errors = buildStandardCrudErrors(entityName, errorOptions);
 
+  const listConfig = {
+    filterMappings,
+    sortableColumns,
+    defaultSortBy: queryOptions.defaultSortBy,
+    defaultSortDirection: queryOptions.defaultSortDirection ?? "asc" as SortDirection,
+    defaultPageSize,
+    maxPageSize,
+    sortByKey,
+    sortDirectionKey
+  };
+
   return {
     response: crudClasses.response as DtoConstructor,
     create: crudClasses.create as DtoConstructor,
@@ -179,7 +190,8 @@ export function createMetalCrudDtoClasses<TEntity extends Record<string, unknown
     optionsDto,
     errors,
     filterMappings,
-    sortableColumns
+    sortableColumns,
+    listConfig
   };
 }
 

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

@@ -1,17 +1,17 @@
-// Ensure standard decorator metadata is available for metal-orm transformers.
-const symbolMetadata = (Symbol as { metadata?: symbol }).metadata;
-if (!symbolMetadata) {
-  (Symbol as { metadata?: symbol }).metadata = Symbol("Symbol.metadata");
-}
-
-export {
-  MetalDto
-} from "./dto";
-
-export {
-  parsePagination
-} from "./pagination";
-
+// Ensure standard decorator metadata is available for metal-orm transformers.
+const symbolMetadata = (Symbol as { metadata?: symbol }).metadata;
+if (!symbolMetadata) {
+  (Symbol as { metadata?: symbol }).metadata = Symbol("Symbol.metadata");
+}
+
+export {
+  MetalDto
+} from "./dto";
+
+export {
+  parsePagination
+} from "./pagination";
+
 export {
   parseFilter,
   createFilterMappings
@@ -20,13 +20,13 @@ export {
 export {
   parseSort
 } from "./sort";
-
-export {
-  createPagedQueryDtoClass,
-  createPagedResponseDtoClass,
-  createPagedFilterQueryDtoClass
-} from "./paged-dtos";
-
+
+export {
+  createPagedQueryDtoClass,
+  createPagedResponseDtoClass,
+  createPagedFilterQueryDtoClass
+} from "./paged-dtos";
+
 export {
   createMetalCrudDtos,
   createMetalCrudDtoClasses,
@@ -37,38 +37,38 @@ 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,
+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,
@@ -80,6 +80,7 @@ export type {
   ParseSortOptions,
   ParsedSort,
   SortDirection,
+  ListConfig,
   PagedQueryDtoOptions,
   PagedResponseDtoOptions,
   PagedFilterQueryDtoOptions,

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

@@ -31,6 +31,7 @@ export function parseSort<T>(
 
   const sortByKey = resolved.sortByKey ?? "sortBy";
   const sortDirectionKey = resolved.sortDirectionKey ?? "sortDirection";
+  const sortOrderKey = resolved.sortOrderKey ?? "sortOrder";
   const defaultSortBy = resolved.defaultSortBy;
   const defaultDirection = resolved.defaultSortDirection ?? "asc";
 
@@ -40,7 +41,8 @@ export function parseSort<T>(
     return undefined;
   }
 
-  const requestedDirection = toTrimmedString(query[sortDirectionKey]);
+  const requestedDirection = toTrimmedString(query[sortDirectionKey])
+    ?? toTrimmedString(query[sortOrderKey]);
   const sortDirection = normalizeDirection(requestedDirection, defaultDirection);
 
   return {
@@ -72,10 +74,11 @@ function normalizeDirection(
   raw: string | undefined,
   fallback: SortDirection
 ): SortDirection {
-  if (raw === "desc") {
+  const lower = raw?.toLowerCase();
+  if (lower === "desc") {
     return "desc";
   }
-  if (raw === "asc") {
+  if (lower === "asc") {
     return "asc";
   }
   return fallback;

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

@@ -1,14 +1,14 @@
-
+
 import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToManyCollection } from "metal-orm";
 import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
-
-/**
- * Metal ORM DTO modes.
- */
-export type MetalDtoMode = "response" | "create" | "update";
-
+
+/**
+ * Metal ORM DTO modes.
+ */
+export type MetalDtoMode = "response" | "create" | "update";
+
 /**
  * Options for Metal ORM DTOs.
  * @extends DtoOptions
@@ -25,47 +25,47 @@ export interface MetalDtoOptions extends DtoOptions {
   /** Whether to throw errors instead of warnings for invalid metadata (default: false) */
   strict?: boolean;
 }
-
-/**
- * Metal ORM DTO target type.
- */
-export type MetalDtoTarget = Parameters<typeof import("metal-orm").getColumnMap>[0];
-
-/**
- * Pagination configuration.
- */
-export interface PaginationConfig {
-  /** Default page size */
-  defaultPageSize?: number;
-  /** Maximum page size */
-  maxPageSize?: number;
-}
-
-/**
- * Pagination parsing options.
- */
-export interface PaginationOptions {
-  /** Minimum value */
-  min?: number;
-  /** Maximum value */
-  max?: number;
-  /** Whether to clamp values */
-  clamp?: boolean;
-}
-
-/**
- * Parsed pagination result.
- */
-export interface ParsedPagination {
-  /** Page number */
-  page: number;
-  /** Page size */
-  pageSize: number;
-}
-
-/**
- * Filter field mapping.
- */
+
+/**
+ * Metal ORM DTO target type.
+ */
+export type MetalDtoTarget = Parameters<typeof import("metal-orm").getColumnMap>[0];
+
+/**
+ * Pagination configuration.
+ */
+export interface PaginationConfig {
+  /** Default page size */
+  defaultPageSize?: number;
+  /** Maximum page size */
+  maxPageSize?: number;
+}
+
+/**
+ * Pagination parsing options.
+ */
+export interface PaginationOptions {
+  /** Minimum value */
+  min?: number;
+  /** Maximum value */
+  max?: number;
+  /** Whether to clamp values */
+  clamp?: boolean;
+}
+
+/**
+ * Parsed pagination result.
+ */
+export interface ParsedPagination {
+  /** Page number */
+  page: number;
+  /** Page size */
+  pageSize: number;
+}
+
+/**
+ * Filter field mapping.
+ */
 export interface FilterFieldMapping {
   /** Maps query keys to field names */
   [queryKey: string]: string;
@@ -118,20 +118,20 @@ export type FilterFieldPathArray<T> = FilterFieldPathSegments<T>;
  * Supported filter field input types.
  */
 export type FilterFieldInput<T> = FilterFieldPath<T> | FilterFieldPathArray<T>;
-
-/**
- * Filter mapping configuration.
- */
+
+/**
+ * Filter mapping configuration.
+ */
 export interface FilterMapping<T = Record<string, unknown>> {
   /** Field name */
   field: FilterFieldInput<T>;
   /** Filter operator */
   operator: FilterOperator;
 }
-
-/**
- * Options for parsing filters.
- */
+
+/**
+ * Options for parsing filters.
+ */
 export interface ParseFilterOptions<T = Record<string, unknown>> {
   /** Query parameters */
   query?: Record<string, unknown>;
@@ -156,6 +156,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 */
@@ -174,6 +176,30 @@ export interface ParsedSort<T = Record<string, unknown>> {
   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.
  */
@@ -211,34 +237,34 @@ export type Filter<T, K extends keyof T> = {
     mode?: "default" | "insensitive";
   };
 };
-
-/**
- * Options for paged query DTOs.
- */
-export interface PagedQueryDtoOptions {
-  /** Default page size */
-  defaultPageSize?: number;
-  /** Maximum page size */
-  maxPageSize?: number;
-  /** DTO name */
-  name?: string;
-}
-
-/**
- * Options for paged response DTOs.
- */
-export interface PagedResponseDtoOptions {
-  /** Item DTO constructor */
-  itemDto: DtoConstructor;
-  /** DTO description */
-  description?: string;
-  /** DTO name */
-  name?: string;
-}
-
-/**
- * Filter field definition.
- */
+
+/**
+ * Options for paged query DTOs.
+ */
+export interface PagedQueryDtoOptions {
+  /** Default page size */
+  defaultPageSize?: number;
+  /** Maximum page size */
+  maxPageSize?: number;
+  /** DTO name */
+  name?: string;
+}
+
+/**
+ * Options for paged response DTOs.
+ */
+export interface PagedResponseDtoOptions {
+  /** Item DTO constructor */
+  itemDto: DtoConstructor;
+  /** DTO description */
+  description?: string;
+  /** DTO name */
+  name?: string;
+}
+
+/**
+ * Filter field definition.
+ */
 export interface FilterFieldDef {
   /** Field schema */
   schema?: SchemaNode;
@@ -320,18 +346,18 @@ export interface MetalCrudStandardErrorsOptions {
   /** 404 not found error config (set false to disable) */
   notFound?: false | ErrorResponseOptions;
 }
-
-/**
- * Options for paged filter query DTOs.
- * @extends PagedQueryDtoOptions
- */
-export interface PagedFilterQueryDtoOptions extends PagedQueryDtoOptions {
-  /** Filter definitions */
-  filters: Record<string, FilterFieldDef>;
-  /** DTO name */
-  name?: string;
-}
-
+
+/**
+ * Options for paged filter query DTOs.
+ * @extends PagedQueryDtoOptions
+ */
+export interface PagedFilterQueryDtoOptions extends PagedQueryDtoOptions {
+  /** Filter definitions */
+  filters: Record<string, FilterFieldDef>;
+  /** DTO name */
+  name?: string;
+}
+
 /**
  * Options for Metal CRUD DTOs.
  */
@@ -361,26 +387,26 @@ export interface MetalCrudDtoOptions<T = Record<string, unknown>> {
   /** Whether to throw errors instead of warnings for invalid metadata (default: false) */
   strict?: boolean;
 }
-
-/**
- * Metal CRUD DTO decorators.
- */
-export interface MetalCrudDtoDecorators {
-  /** Response DTO decorator */
-  response: (target: DtoConstructor) => void;
-  /** Create DTO decorator */
-  create: (target: DtoConstructor) => void;
-  /** Replace DTO decorator */
-  replace: (target: DtoConstructor) => void;
-  /** Update DTO decorator */
-  update: (target: DtoConstructor) => void;
-  /** Params DTO decorator */
-  params: (target: DtoConstructor) => void;
-}
-
-/**
- * Metal CRUD DTO class names.
- */
+
+/**
+ * Metal CRUD DTO decorators.
+ */
+export interface MetalCrudDtoDecorators {
+  /** Response DTO decorator */
+  response: (target: DtoConstructor) => void;
+  /** Create DTO decorator */
+  create: (target: DtoConstructor) => void;
+  /** Replace DTO decorator */
+  replace: (target: DtoConstructor) => void;
+  /** Update DTO decorator */
+  update: (target: DtoConstructor) => void;
+  /** Params DTO decorator */
+  params: (target: DtoConstructor) => void;
+}
+
+/**
+ * Metal CRUD DTO class names.
+ */
 export type RouteErrorsDecorator = (
   value: unknown,
   context: ClassMethodDecoratorContext
@@ -401,7 +427,7 @@ export type MetalCrudDtoClassNameKey =
  * Metal CRUD DTO class names.
  */
 export type MetalCrudDtoClassNames = Partial<Record<MetalCrudDtoClassNameKey, string>>;
-
+
 /**
  * Options for Metal CRUD DTO classes.
  * @extends MetalCrudDtoOptions
@@ -414,19 +440,19 @@ export interface MetalCrudDtoClassOptions<T = Record<string, unknown>> extends M
   /** Whether to throw errors instead of warnings for invalid metadata (default: false) */
   strict?: boolean;
 }
-
-/**
- * Metal CRUD DTO classes.
- */
+
+/**
+ * Metal CRUD DTO classes.
+ */
 export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
   /** Response DTO class */
   response: DtoConstructor;
   /** Create DTO class */
   create: DtoConstructor;
-  /** Replace DTO class */
-  replace: DtoConstructor;
-  /** Update DTO class */
-  update: DtoConstructor;
+  /** Replace DTO class */
+  replace: DtoConstructor;
+  /** Update DTO class */
+  update: DtoConstructor;
   /** Params DTO class */
   params: DtoConstructor;
   /** Query DTO class (paged + filters + sort) */
@@ -445,6 +471,8 @@ 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>;
 }
 
 /**
@@ -518,25 +546,25 @@ export interface MetalTreeDtoClasses {
  * @extends MetalDtoOptions
  */
 export interface NestedCreateDtoOptions extends MetalDtoOptions {
-  /** Additional fields to exclude */
-  additionalExclude?: string[];
-  /** DTO name */
-  name: string;
-  /** Parent entity name */
-  parentEntity?: string;
-}
-
-/**
- * Options for error DTOs.
- */
-export interface ErrorDtoOptions {
-  /** Whether to include error details */
-  withDetails?: boolean;
-  /** Whether to include trace ID */
-  includeTraceId?: boolean;
-}
-
-/**
- * Function type for creating ORM sessions.
- */
-export type CreateSessionFn = () => import("metal-orm").OrmSession;
+  /** Additional fields to exclude */
+  additionalExclude?: string[];
+  /** DTO name */
+  name: string;
+  /** Parent entity name */
+  parentEntity?: string;
+}
+
+/**
+ * Options for error DTOs.
+ */
+export interface ErrorDtoOptions {
+  /** Whether to include error details */
+  withDetails?: boolean;
+  /** Whether to include trace ID */
+  includeTraceId?: boolean;
+}
+
+/**
+ * Function type for creating ORM sessions.
+ */
+export type CreateSessionFn = () => import("metal-orm").OrmSession;

package/tests/unit/crud-dtos.test.ts

@@ -7,98 +7,98 @@ import type { FilterMapping } from "../../src/adapter/metal-orm/index";
 import { getDtoMeta } from "../../src/core/metadata";
 import { t } from "../../src/core/schema";
 import { Alphanumeric, Column, Email, Entity, Length, Pattern, PrimaryKey, col } from "metal-orm";
-
-describe("createMetalCrudDtos", () => {
-  @Entity({ tableName: "crud_dto_entities" })
-  class CrudDtoEntity {
-    @PrimaryKey(col.autoIncrement(col.int()))
-    id!: number;
-
-    @Column(col.notNull(col.text()))
-    name!: string;
-
-    @Column(col.text())
-    nickname?: string | null;
-  }
-
-  it("creates CRUD DTO decorators with defaults", () => {
-    const crud = createMetalCrudDtos(CrudDtoEntity, {
-      mutationExclude: ["id"]
-    });
-
-    @crud.response
-    class CrudDto {}
-
-    @crud.create
-    class CreateCrudDto {}
-
-    @crud.update
-    class UpdateCrudDto {}
-
-    @crud.params
-    class CrudParamsDto {}
-
-    const responseMeta = getDtoMeta(CrudDto);
-    const createMeta = getDtoMeta(CreateCrudDto);
-    const updateMeta = getDtoMeta(UpdateCrudDto);
-    const paramsMeta = getDtoMeta(CrudParamsDto);
-
-    expect(responseMeta?.fields.id).toBeDefined();
-    expect(createMeta?.fields.id).toBeUndefined();
-    expect(updateMeta?.fields.name?.optional).toBe(true);
-    expect(Object.keys(paramsMeta?.fields ?? {})).toEqual(["id"]);
-  });
-
-  @Entity({ tableName: "transformer_entities" })
-  class TransformerEntity {
-    @PrimaryKey(col.autoIncrement(col.int()))
-    id!: number;
-
-    @Column(col.varchar(50))
-    @Length({ min: 2, max: 10 })
-    name!: string;
-
-    @Column(col.text())
-    @Pattern({ pattern: /^[A-Z]+$/ })
-    code!: string;
-
-    @Column(col.text())
-    @Email()
-    email!: string;
-
-    @Column(col.text())
-    @Alphanumeric({ allowHyphens: true })
-    slug!: string;
-  }
-
-  it("maps transformer validators into string schemas", () => {
-    const crud = createMetalCrudDtos(TransformerEntity);
-
-    @crud.create
-    class CreateTransformerDto {}
-
-    const meta = getDtoMeta(CreateTransformerDto);
-    expect((meta?.fields.email?.schema as any).format).toBe("email");
-    expect((meta?.fields.name?.schema as any).minLength).toBe(2);
-    expect((meta?.fields.name?.schema as any).maxLength).toBe(10);
-    expect((meta?.fields.code?.schema as any).pattern).toBe("^[A-Z]+$");
-    expect((meta?.fields.slug?.schema as any).pattern).toBe("^[a-zA-Z0-9-]*$");
-  });
-});
-
-describe("createMetalCrudDtoClasses", () => {
-  @Entity({ tableName: "crud_dto_class_entities" })
-  class CrudDtoClassEntity {
-    @PrimaryKey(col.autoIncrement(col.int()))
-    id!: number;
-
-    @Column(col.notNull(col.text()))
-    name!: string;
-
-    @Column(col.text())
-    nickname?: string | null;
-  }
-
+
+describe("createMetalCrudDtos", () => {
+  @Entity({ tableName: "crud_dto_entities" })
+  class CrudDtoEntity {
+    @PrimaryKey(col.autoIncrement(col.int()))
+    id!: number;
+
+    @Column(col.notNull(col.text()))
+    name!: string;
+
+    @Column(col.text())
+    nickname?: string | null;
+  }
+
+  it("creates CRUD DTO decorators with defaults", () => {
+    const crud = createMetalCrudDtos(CrudDtoEntity, {
+      mutationExclude: ["id"]
+    });
+
+    @crud.response
+    class CrudDto {}
+
+    @crud.create
+    class CreateCrudDto {}
+
+    @crud.update
+    class UpdateCrudDto {}
+
+    @crud.params
+    class CrudParamsDto {}
+
+    const responseMeta = getDtoMeta(CrudDto);
+    const createMeta = getDtoMeta(CreateCrudDto);
+    const updateMeta = getDtoMeta(UpdateCrudDto);
+    const paramsMeta = getDtoMeta(CrudParamsDto);
+
+    expect(responseMeta?.fields.id).toBeDefined();
+    expect(createMeta?.fields.id).toBeUndefined();
+    expect(updateMeta?.fields.name?.optional).toBe(true);
+    expect(Object.keys(paramsMeta?.fields ?? {})).toEqual(["id"]);
+  });
+
+  @Entity({ tableName: "transformer_entities" })
+  class TransformerEntity {
+    @PrimaryKey(col.autoIncrement(col.int()))
+    id!: number;
+
+    @Column(col.varchar(50))
+    @Length({ min: 2, max: 10 })
+    name!: string;
+
+    @Column(col.text())
+    @Pattern({ pattern: /^[A-Z]+$/ })
+    code!: string;
+
+    @Column(col.text())
+    @Email()
+    email!: string;
+
+    @Column(col.text())
+    @Alphanumeric({ allowHyphens: true })
+    slug!: string;
+  }
+
+  it("maps transformer validators into string schemas", () => {
+    const crud = createMetalCrudDtos(TransformerEntity);
+
+    @crud.create
+    class CreateTransformerDto {}
+
+    const meta = getDtoMeta(CreateTransformerDto);
+    expect((meta?.fields.email?.schema as any).format).toBe("email");
+    expect((meta?.fields.name?.schema as any).minLength).toBe(2);
+    expect((meta?.fields.name?.schema as any).maxLength).toBe(10);
+    expect((meta?.fields.code?.schema as any).pattern).toBe("^[A-Z]+$");
+    expect((meta?.fields.slug?.schema as any).pattern).toBe("^[a-zA-Z0-9-]*$");
+  });
+});
+
+describe("createMetalCrudDtoClasses", () => {
+  @Entity({ tableName: "crud_dto_class_entities" })
+  class CrudDtoClassEntity {
+    @PrimaryKey(col.autoIncrement(col.int()))
+    id!: number;
+
+    @Column(col.notNull(col.text()))
+    name!: string;
+
+    @Column(col.text())
+    nickname?: string | null;
+  }
+
   it("builds ready-to-export DTO classes", () => {
     const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
       mutationExclude: ["id"]
@@ -127,16 +127,16 @@ describe("createMetalCrudDtoClasses", () => {
     });
     expect(classes.sortableColumns).toEqual({});
   });
-
-  it("applies custom name overrides", () => {
-    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
-      baseName: "Person",
-      names: {
-        response: "PersonDto",
-        params: "PersonIdDto"
-      }
-    });
-
+
+  it("applies custom name overrides", () => {
+    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
+      baseName: "Person",
+      names: {
+        response: "PersonDto",
+        params: "PersonIdDto"
+      }
+    });
+
     expect(classes.response.name).toBe("PersonDto");
     expect(classes.params.name).toBe("PersonIdDto");
     expect(classes.create.name).toBe("CreatePersonDto");
@@ -197,4 +197,52 @@ describe("createMetalCrudDtoClasses", () => {
     });
     expect(typeof classes.errors).toBe("function");
   });
+
+  it("exposes listConfig with all query defaults ready for service layer", () => {
+    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
+      query: {
+        filters: {
+          nameContains: {
+            schema: t.string({ minLength: 1 }),
+            field: "name",
+            operator: "contains"
+          }
+        },
+        sortableColumns: {
+          name: "name",
+          nickname: "nickname"
+        },
+        defaultSortBy: "name",
+        defaultSortDirection: "desc",
+        defaultPageSize: 10,
+        maxPageSize: 50
+      }
+    });
+
+    expect(classes.listConfig).toEqual({
+      filterMappings: classes.filterMappings,
+      sortableColumns: { name: "name", nickname: "nickname" },
+      defaultSortBy: "name",
+      defaultSortDirection: "desc",
+      defaultPageSize: 10,
+      maxPageSize: 50,
+      sortByKey: "sortBy",
+      sortDirectionKey: "sortDirection"
+    });
+  });
+
+  it("listConfig uses sensible defaults when query options are minimal", () => {
+    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity);
+
+    expect(classes.listConfig).toEqual({
+      filterMappings: classes.filterMappings,
+      sortableColumns: {},
+      defaultSortBy: undefined,
+      defaultSortDirection: "asc",
+      defaultPageSize: 25,
+      maxPageSize: 100,
+      sortByKey: "sortBy",
+      sortDirectionKey: "sortDirection"
+    });
+  });
 });

package/tests/unit/parse-sort.test.ts

@@ -45,4 +45,115 @@ describe("parseSort", () => {
       field: "createdAt"
     });
   });
+
+  it("parses sortOrder with uppercase DESC", () => {
+    const result = parseSort({
+      query: { sortBy: "name", sortOrder: "DESC" },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
+
+  it("parses sortOrder with uppercase ASC", () => {
+    const result = parseSort({
+      query: { sortBy: "name", sortOrder: "ASC" },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "asc",
+      field: "name"
+    });
+  });
+
+  it("gives sortDirection precedence over sortOrder when both present", () => {
+    const result = parseSort({
+      query: { sortBy: "name", sortDirection: "asc", sortOrder: "DESC" },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "asc",
+      field: "name"
+    });
+  });
+
+  it("falls back to sortOrder when sortDirection is absent", () => {
+    const result = parseSort({
+      query: { sortBy: "name", sortOrder: "desc" },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
+
+  it("falls back to default when neither sortDirection nor sortOrder present", () => {
+    const result = parseSort({
+      query: { sortBy: "name" },
+      sortableColumns: { name: "name" },
+      defaultSortDirection: "desc"
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
+
+  it("supports custom sortOrderKey", () => {
+    const result = parseSort({
+      query: { sortBy: "name", order: "DESC" },
+      sortableColumns: { name: "name" },
+      sortOrderKey: "order"
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
+
+  it("ignores invalid sortOrder values and uses default", () => {
+    const result = parseSort({
+      query: { sortBy: "name", sortOrder: "INVALID" },
+      sortableColumns: { name: "name" },
+      defaultSortDirection: "asc"
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "asc",
+      field: "name"
+    });
+  });
+
+  it("normalizes mixed-case sortDirection (e.g. Desc)", () => {
+    const result = parseSort({
+      query: { sortBy: "name", sortDirection: "Desc" },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
+
+  it("works with positional args and sortOrder fallback", () => {
+    const result = parseSort(
+      { sortBy: "name", sortOrder: "DESC" },
+      { name: "name" }
+    );
+    expect(result).toEqual({
+      sortBy: "name",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
 });