adorn-api 1.1.6 → 1.1.8

package/README.md

@@ -398,13 +398,10 @@ import {
   Body,
   Query,
   Returns,
-  parseFilter,
-  parsePagination,
-  parseSort,
+  runPagedList,
   t,
   type RequestContext
 } from "adorn-api";
-import { applyFilter, toPagedResponse } from "metal-orm";
 import { createSession } from "./db";
 import { User } from "./user.entity";
 import {
@@ -428,24 +425,18 @@ export class UserController {
   @Query(UserQueryDto)
   @Returns(UserPagedResponseDto)
   async list(ctx: RequestContext<unknown, UserQueryDto>) {
-    const query = (ctx.query ?? {}) as Record<string, unknown>;
-    const { page, pageSize } = parsePagination(query);
-    const filters = parseFilter(query, USER_FILTER_MAPPINGS);
-    const sort = parseSort(query, USER_SORTABLE_COLUMNS, {
-      defaultSortBy: "id"
-    });
-    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);
+      return await runPagedList({
+        query: (ctx.query ?? {}) as Record<string, unknown>,
+        target: User,
+        qb: () => User.select(),
+        session,
+        filterMappings: USER_FILTER_MAPPINGS,
+        sortableColumns: USER_SORTABLE_COLUMNS,
+        defaultSortBy: "id"
+      });
     } finally {
       await session.dispose();
     }
@@ -613,10 +604,9 @@ Breaking changes summary:
 // user.controller.ts — using listConfig directly
 import {
   Controller, Get, Query, Returns,
-  parseFilter, parsePagination, parseSort,
+  runPagedList,
   type RequestContext
 } from "adorn-api";
-import { applyFilter, toPagedResponse } from "metal-orm";
 import { createSession } from "./db";
 import { User } from "./user.entity";
 import {
@@ -631,24 +621,15 @@ export class UserController {
   @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);
+      return await runPagedList({
+        query: (ctx.query ?? {}) as Record<string, unknown>,
+        target: User,
+        qb: () => User.select(),
+        session,
+        ...USER_LIST_CONFIG
+      });
     } finally {
       await session.dispose();
     }
@@ -658,6 +639,51 @@ export class UserController {
 
 The `listConfig` object contains: `filterMappings`, `sortableColumns`, `defaultSortBy`, `defaultSortDirection`, `defaultPageSize`, `maxPageSize`, `sortByKey`, and `sortDirectionKey`.
 
+### `BaseService.list` Before/After (Boilerplate Reduction)
+
+Before:
+
+```typescript
+async list(query: Record<string, unknown>) {
+  const { page, pageSize } = parsePagination(query, this.listConfig);
+  const filters = parseFilter(query, this.listConfig.filterMappings);
+  const sort = parseSort(query, this.listConfig.sortableColumns, {
+    defaultSortBy: this.listConfig.defaultSortBy,
+    defaultSortDirection: this.listConfig.defaultSortDirection,
+    sortByKey: this.listConfig.sortByKey,
+    sortDirectionKey: this.listConfig.sortDirectionKey
+  });
+  const direction = sort?.sortDirection === "desc" ? "DESC" : "ASC";
+
+  return withSession(this.createSession, async (session) => {
+    const qb = applyFilter(this.baseQuery().orderBy(this.ref.id, direction), this.entity, filters);
+    const paged = await qb.executePaged(session, { page, pageSize });
+    return toPagedResponse(paged);
+  });
+}
+```
+
+After:
+
+```typescript
+async list(query: Record<string, unknown>) {
+  return withSession(this.createSession, async (session) =>
+    runPagedList({
+      query,
+      target: this.entity,
+      qb: () => this.baseQuery(),
+      session,
+      ...this.listConfig
+    })
+  );
+}
+```
+
+Migration note:
+- Existing `parsePagination`, `parseFilter`, and `parseSort` remain unchanged and can still be used manually.
+- `runPagedList`/`executeCrudList` is additive and optional; no breaking API changes.
+- For sortable fields that are not direct columns of the base table, pass `allowedSortColumns` with explicit metal-orm sort terms.
+
 ### 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.

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

@@ -2,6 +2,7 @@ export { MetalDto } from "./dto";
 export { parsePagination } from "./pagination";
 export { parseFilter, createFilterMappings } from "./filters";
 export { parseSort } from "./sort";
+export { runPagedList, executeCrudList } from "./list";
 export { createPagedQueryDtoClass, createPagedResponseDtoClass, createPagedFilterQueryDtoClass } from "./paged-dtos";
 export { createMetalCrudDtos, createMetalCrudDtoClasses, createNestedCreateDtoClass } from "./crud-dtos";
 export { createCrudController } from "./crud-controller";
@@ -10,4 +11,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, 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";
+export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, CrudListSortTerm, RunPagedListOptions, ExecuteCrudListOptions, CrudPagedResponse, 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.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;
+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.executeCrudList = exports.runPagedList = 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) {
@@ -15,6 +15,9 @@ Object.defineProperty(exports, "parseFilter", { enumerable: true, get: function
 Object.defineProperty(exports, "createFilterMappings", { enumerable: true, get: function () { return filters_1.createFilterMappings; } });
 var sort_1 = require("./sort");
 Object.defineProperty(exports, "parseSort", { enumerable: true, get: function () { return sort_1.parseSort; } });
+var list_1 = require("./list");
+Object.defineProperty(exports, "runPagedList", { enumerable: true, get: function () { return list_1.runPagedList; } });
+Object.defineProperty(exports, "executeCrudList", { enumerable: true, get: function () { return list_1.executeCrudList; } });
 var paged_dtos_1 = require("./paged-dtos");
 Object.defineProperty(exports, "createPagedQueryDtoClass", { enumerable: true, get: function () { return paged_dtos_1.createPagedQueryDtoClass; } });
 Object.defineProperty(exports, "createPagedResponseDtoClass", { enumerable: true, get: function () { return paged_dtos_1.createPagedResponseDtoClass; } });

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

@@ -0,0 +1,11 @@
+import { type PagedResponse, type TableDef } from "metal-orm";
+import type { ExecuteCrudListOptions, RunPagedListOptions } from "./types";
+/**
+ * Runs a unified filtered/sorted/paginated list query for metal-orm.
+ */
+export declare function runPagedList<TResult, TTable extends TableDef = TableDef, TTarget = unknown, TFilterTarget = Record<string, unknown>>(options: RunPagedListOptions<TResult, TTable, TTarget, TFilterTarget>): Promise<PagedResponse<TResult>>;
+/**
+ * Alias for runPagedList.
+ */
+export declare const executeCrudList: typeof runPagedList;
+export type { ExecuteCrudListOptions, RunPagedListOptions };

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

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCrudList = void 0;
+exports.runPagedList = runPagedList;
+const metal_orm_1 = require("metal-orm");
+const filters_1 = require("./filters");
+const pagination_1 = require("./pagination");
+const sort_1 = require("./sort");
+/**
+ * Runs a unified filtered/sorted/paginated list query for metal-orm.
+ */
+async function runPagedList(options) {
+    const query = options.query ?? {};
+    const qb = resolveQueryBuilder(options.qb);
+    const { page, pageSize } = (0, pagination_1.parsePagination)(query, {
+        defaultPageSize: options.defaultPageSize,
+        maxPageSize: options.maxPageSize
+    });
+    const filters = (0, filters_1.parseFilter)(query, options.filterMappings);
+    const parsedSort = (0, sort_1.parseSort)(query, options.sortableColumns, {
+        defaultSortBy: options.defaultSortBy,
+        defaultSortDirection: options.defaultSortDirection,
+        sortByKey: options.sortByKey,
+        sortDirectionKey: options.sortDirectionKey,
+        sortOrderKey: options.sortOrderKey
+    });
+    const inferredSortColumns = inferAllowedSortColumns(qb.getTable(), options.sortableColumns);
+    const allowedSortColumns = {
+        ...inferredSortColumns,
+        ...(options.allowedSortColumns ?? {})
+    };
+    const sortBy = parsedSort?.sortBy && parsedSort.sortBy in allowedSortColumns
+        ? parsedSort.sortBy
+        : undefined;
+    const defaultSortBy = !sortBy && options.defaultSortBy && options.defaultSortBy in allowedSortColumns
+        ? options.defaultSortBy
+        : undefined;
+    return (0, metal_orm_1.executeFilteredPaged)({
+        qb,
+        tableOrEntity: options.target,
+        session: options.session,
+        page,
+        pageSize,
+        filters: filters,
+        sortBy,
+        sortDirection: toOrderDirection(parsedSort?.sortDirection),
+        allowedSortColumns: Object.keys(allowedSortColumns).length
+            ? allowedSortColumns
+            : undefined,
+        defaultSortBy,
+        defaultSortDirection: toOrderDirection(options.defaultSortDirection),
+        tieBreakerColumn: options.tieBreakerColumn
+    });
+}
+/**
+ * Alias for runPagedList.
+ */
+exports.executeCrudList = runPagedList;
+function resolveQueryBuilder(qbOrFactory) {
+    return typeof qbOrFactory === "function" ? qbOrFactory() : qbOrFactory;
+}
+function inferAllowedSortColumns(table, sortableColumns) {
+    const output = {};
+    for (const [queryKey, field] of Object.entries(sortableColumns)) {
+        const columnName = toSortableColumnName(field);
+        if (!columnName) {
+            continue;
+        }
+        const column = resolveTableColumn(table, columnName);
+        if (!column) {
+            continue;
+        }
+        output[queryKey] = column;
+    }
+    return output;
+}
+function toSortableColumnName(value) {
+    if (Array.isArray(value)) {
+        if (value.length !== 1) {
+            return undefined;
+        }
+        const segment = String(value[0]).trim();
+        return segment.length > 0 ? segment : undefined;
+    }
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const path = value
+        .split(".")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    if (path.length !== 1) {
+        return undefined;
+    }
+    return path[0];
+}
+function resolveTableColumn(table, name) {
+    const byKey = table.columns[name];
+    if (byKey) {
+        return byKey;
+    }
+    return Object.values(table.columns).find((column) => column.name === name);
+}
+function toOrderDirection(direction) {
+    if (direction === "desc") {
+        return "DESC";
+    }
+    if (direction === "asc") {
+        return "ASC";
+    }
+    return undefined;
+}

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

@@ -1,4 +1,4 @@
-import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToManyCollection } from "metal-orm";
+import type { BelongsToReference, ColumnDef, HasManyCollection, HasOneReference, ManyToManyCollection, OrmSession, PagedResponse, SelectQueryBuilder, TableDef } from "metal-orm";
 import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
@@ -138,6 +138,10 @@ export interface ParsedSort<T = Record<string, unknown>> {
     /** Resolved entity field */
     field?: FilterFieldInput<T>;
 }
+/**
+ * Sort terms accepted by metal-orm execution helpers.
+ */
+export type CrudListSortTerm = ColumnDef | Record<string, unknown>;
 /**
  * Ready-to-use list/query configuration extracted from CRUD DTO class generation.
  * Eliminates the need for consumers to reassemble filter/sort/pagination config
@@ -161,6 +165,45 @@ export interface ListConfig<T = Record<string, unknown>> {
     /** Sort direction query key */
     sortDirectionKey: string;
 }
+/**
+ * Unified paged list execution options for metal-orm adapter.
+ */
+export interface RunPagedListOptions<TResult, TTable extends TableDef = TableDef, TTarget = unknown, TFilterTarget = Record<string, unknown>> extends PaginationConfig {
+    /** Raw request query */
+    query?: Record<string, unknown>;
+    /** Entity class or table used by applyFilter */
+    target: TTarget;
+    /** Base query builder or factory to create one */
+    qb: SelectQueryBuilder<TResult, TTable> | (() => SelectQueryBuilder<TResult, TTable>);
+    /** Active ORM session */
+    session: OrmSession;
+    /** Query key -> filter mapping */
+    filterMappings: Record<string, FilterMapping<TFilterTarget>>;
+    /** Query key -> field path mapping used by parseSort */
+    sortableColumns: Record<string, FilterFieldInput<TFilterTarget>>;
+    /** Optional explicit metal-orm sortable terms, overrides inferred table columns */
+    allowedSortColumns?: Record<string, CrudListSortTerm>;
+    /** Default sort field key */
+    defaultSortBy?: string;
+    /** Default sort direction */
+    defaultSortDirection?: SortDirection;
+    /** Sort field query key */
+    sortByKey?: string;
+    /** Sort direction query key */
+    sortDirectionKey?: string;
+    /** Legacy sort order query key (e.g. sortOrder=DESC) */
+    sortOrderKey?: string;
+    /** Optional stable tie-breaker column name */
+    tieBreakerColumn?: string;
+}
+/**
+ * Alias for runPagedList options.
+ */
+export type ExecuteCrudListOptions<TResult, TTable extends TableDef = TableDef, TTarget = unknown, TFilterTarget = Record<string, unknown>> = RunPagedListOptions<TResult, TTable, TTarget, TFilterTarget>;
+/**
+ * Alias for runPagedList response.
+ */
+export type CrudPagedResponse<TResult> = PagedResponse<TResult>;
 /**
  * Filter operator.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "express": "^4.19.2",
-    "metal-orm": "^1.1.0"
+    "metal-orm": "^1.1.2"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.15",
@@ -24,12 +24,14 @@
     "@types/supertest": "^2.0.16",
     "@typescript-eslint/eslint-plugin": "^8.53.0",
     "@typescript-eslint/parser": "^8.53.0",
+    "@vitest/mocker": "^4.0.18",
     "eslint": "^8.57.1",
     "sqlite3": "^5.1.7",
     "supertest": "^6.3.4",
     "tedious": "^19.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.5",
-    "vitest": "^2.0.5"
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   }
 }

package/src/adapter/express/coercion.ts

@@ -192,8 +192,18 @@ function coerceArrayValue(
   if (value === undefined || value === null) {
     return { value, ok: true, changed: false };
   }
-  const input = Array.isArray(value) ? value : [value];
-  let changed = !Array.isArray(value);
+  let input: unknown[];
+  let changed: boolean;
+  if (Array.isArray(value)) {
+    input = value;
+    changed = false;
+  } else if (typeof value === "string" && value.includes(",")) {
+    input = value.split(",").map((s) => s.trim());
+    changed = true;
+  } else {
+    input = [value];
+    changed = true;
+  }
   let ok = true;
   const output = input.map((entry) => {
     const result = coerceValue(entry, schema.items, mode);

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

@@ -21,6 +21,11 @@ export {
   parseSort
 } from "./sort";
 
+export {
+  runPagedList,
+  executeCrudList
+} from "./list";
+
 export {
   createPagedQueryDtoClass,
   createPagedResponseDtoClass,
@@ -84,6 +89,10 @@ export type {
   ParseSortOptions,
   ParsedSort,
   SortDirection,
+  CrudListSortTerm,
+  RunPagedListOptions,
+  ExecuteCrudListOptions,
+  CrudPagedResponse,
   ListConfig,
   PagedQueryDtoOptions,
   PagedResponseDtoOptions,

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

@@ -0,0 +1,168 @@
+import {
+  executeFilteredPaged,
+  type PagedResponse,
+  type SelectQueryBuilder,
+  type TableDef
+} from "metal-orm";
+import { parseFilter } from "./filters";
+import { parsePagination } from "./pagination";
+import { parseSort } from "./sort";
+import type {
+  CrudListSortTerm,
+  ExecuteCrudListOptions,
+  FilterFieldInput,
+  RunPagedListOptions,
+  SortDirection
+} from "./types";
+
+/**
+ * Runs a unified filtered/sorted/paginated list query for metal-orm.
+ */
+export async function runPagedList<
+  TResult,
+  TTable extends TableDef = TableDef,
+  TTarget = unknown,
+  TFilterTarget = Record<string, unknown>
+>(
+  options: RunPagedListOptions<TResult, TTable, TTarget, TFilterTarget>
+): Promise<PagedResponse<TResult>> {
+  const query = options.query ?? {};
+  const qb = resolveQueryBuilder(options.qb);
+
+  const { page, pageSize } = parsePagination(query, {
+    defaultPageSize: options.defaultPageSize,
+    maxPageSize: options.maxPageSize
+  });
+
+  const filters = parseFilter(query, options.filterMappings);
+  const parsedSort = parseSort(query, options.sortableColumns, {
+    defaultSortBy: options.defaultSortBy,
+    defaultSortDirection: options.defaultSortDirection,
+    sortByKey: options.sortByKey,
+    sortDirectionKey: options.sortDirectionKey,
+    sortOrderKey: options.sortOrderKey
+  });
+
+  const inferredSortColumns = inferAllowedSortColumns(
+    qb.getTable(),
+    options.sortableColumns
+  );
+  const allowedSortColumns = {
+    ...inferredSortColumns,
+    ...(options.allowedSortColumns ?? {})
+  };
+
+  const sortBy =
+    parsedSort?.sortBy && parsedSort.sortBy in allowedSortColumns
+      ? parsedSort.sortBy
+      : undefined;
+
+  const defaultSortBy =
+    !sortBy && options.defaultSortBy && options.defaultSortBy in allowedSortColumns
+      ? options.defaultSortBy
+      : undefined;
+
+  return executeFilteredPaged({
+    qb,
+    tableOrEntity: options.target as any,
+    session: options.session,
+    page,
+    pageSize,
+    filters: filters as any,
+    sortBy,
+    sortDirection: toOrderDirection(parsedSort?.sortDirection),
+    allowedSortColumns: Object.keys(allowedSortColumns).length
+      ? allowedSortColumns
+      : undefined,
+    defaultSortBy,
+    defaultSortDirection: toOrderDirection(options.defaultSortDirection),
+    tieBreakerColumn: options.tieBreakerColumn
+  } as any) as Promise<PagedResponse<TResult>>;
+}
+
+/**
+ * Alias for runPagedList.
+ */
+export const executeCrudList = runPagedList;
+
+function resolveQueryBuilder<TResult, TTable extends TableDef>(
+  qbOrFactory:
+    | SelectQueryBuilder<TResult, TTable>
+    | (() => SelectQueryBuilder<TResult, TTable>)
+): SelectQueryBuilder<TResult, TTable> {
+  return typeof qbOrFactory === "function" ? qbOrFactory() : qbOrFactory;
+}
+
+function inferAllowedSortColumns<TFilterTarget>(
+  table: TableDef,
+  sortableColumns: Record<string, FilterFieldInput<TFilterTarget>>
+): Record<string, CrudListSortTerm> {
+  const output: Record<string, CrudListSortTerm> = {};
+
+  for (const [queryKey, field] of Object.entries(sortableColumns)) {
+    const columnName = toSortableColumnName(field);
+    if (!columnName) {
+      continue;
+    }
+
+    const column = resolveTableColumn(table, columnName);
+    if (!column) {
+      continue;
+    }
+
+    output[queryKey] = column;
+  }
+
+  return output;
+}
+
+function toSortableColumnName(value: unknown): string | undefined {
+  if (Array.isArray(value)) {
+    if (value.length !== 1) {
+      return undefined;
+    }
+    const segment = String(value[0]).trim();
+    return segment.length > 0 ? segment : undefined;
+  }
+
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const path = value
+    .split(".")
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+
+  if (path.length !== 1) {
+    return undefined;
+  }
+
+  return path[0];
+}
+
+function resolveTableColumn(table: TableDef, name: string): CrudListSortTerm | undefined {
+  const byKey = table.columns[name];
+  if (byKey) {
+    return byKey;
+  }
+
+  return Object.values(table.columns).find((column) => column.name === name);
+}
+
+function toOrderDirection(
+  direction: SortDirection | undefined
+): "ASC" | "DESC" | undefined {
+  if (direction === "desc") {
+    return "DESC";
+  }
+  if (direction === "asc") {
+    return "ASC";
+  }
+  return undefined;
+}
+
+export type {
+  ExecuteCrudListOptions,
+  RunPagedListOptions
+};

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

@@ -1,5 +1,15 @@
 
-import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToManyCollection } from "metal-orm";
+import type {
+  BelongsToReference,
+  ColumnDef,
+  HasManyCollection,
+  HasOneReference,
+  ManyToManyCollection,
+  OrmSession,
+  PagedResponse,
+  SelectQueryBuilder,
+  TableDef
+} from "metal-orm";
 import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
@@ -177,6 +187,11 @@ export interface ParsedSort<T = Record<string, unknown>> {
   field?: FilterFieldInput<T>;
 }
 
+/**
+ * Sort terms accepted by metal-orm execution helpers.
+ */
+export type CrudListSortTerm = ColumnDef | Record<string, unknown>;
+
 /**
  * Ready-to-use list/query configuration extracted from CRUD DTO class generation.
  * Eliminates the need for consumers to reassemble filter/sort/pagination config
@@ -201,6 +216,58 @@ export interface ListConfig<T = Record<string, unknown>> {
   sortDirectionKey: string;
 }
 
+/**
+ * Unified paged list execution options for metal-orm adapter.
+ */
+export interface RunPagedListOptions<
+  TResult,
+  TTable extends TableDef = TableDef,
+  TTarget = unknown,
+  TFilterTarget = Record<string, unknown>
+> extends PaginationConfig {
+  /** Raw request query */
+  query?: Record<string, unknown>;
+  /** Entity class or table used by applyFilter */
+  target: TTarget;
+  /** Base query builder or factory to create one */
+  qb: SelectQueryBuilder<TResult, TTable> | (() => SelectQueryBuilder<TResult, TTable>);
+  /** Active ORM session */
+  session: OrmSession;
+  /** Query key -> filter mapping */
+  filterMappings: Record<string, FilterMapping<TFilterTarget>>;
+  /** Query key -> field path mapping used by parseSort */
+  sortableColumns: Record<string, FilterFieldInput<TFilterTarget>>;
+  /** Optional explicit metal-orm sortable terms, overrides inferred table columns */
+  allowedSortColumns?: Record<string, CrudListSortTerm>;
+  /** Default sort field key */
+  defaultSortBy?: string;
+  /** Default sort direction */
+  defaultSortDirection?: SortDirection;
+  /** Sort field query key */
+  sortByKey?: string;
+  /** Sort direction query key */
+  sortDirectionKey?: string;
+  /** Legacy sort order query key (e.g. sortOrder=DESC) */
+  sortOrderKey?: string;
+  /** Optional stable tie-breaker column name */
+  tieBreakerColumn?: string;
+}
+
+/**
+ * Alias for runPagedList options.
+ */
+export type ExecuteCrudListOptions<
+  TResult,
+  TTable extends TableDef = TableDef,
+  TTarget = unknown,
+  TFilterTarget = Record<string, unknown>
+> = RunPagedListOptions<TResult, TTable, TTarget, TFilterTarget>;
+
+/**
+ * Alias for runPagedList response.
+ */
+export type CrudPagedResponse<TResult> = PagedResponse<TResult>;
+
 /**
  * Filter operator.
  */

package/src/core/openapi.ts

@@ -317,13 +317,31 @@ function buildParameters(
   if (!fieldEntries.length) {
     return [];
   }
-  return fieldEntries.map((entry) => ({
-    name: entry.name,
-    in: location,
-    required: location === "path" ? true : entry.required,
-    description: entry.description,
-    schema: buildSchemaFromSource(entry.schema, context)
-  }));
+  return fieldEntries.map((entry) => {
+    const param: Record<string, unknown> = {
+      name: entry.name,
+      in: location,
+      required: location === "path" ? true : entry.required,
+      description: entry.description,
+      schema: buildSchemaFromSource(entry.schema, context)
+    };
+
+    if (location === "query" && isSchemaNode(entry.schema)) {
+      if (entry.schema.kind === "array") {
+        param.style = "form";
+        param.explode = true;
+      } else if (entry.schema.kind === "object") {
+        param.style = "deepObject";
+        param.explode = true;
+      }
+
+      if (entry.schema.examples && entry.schema.examples.length > 0) {
+        param.example = entry.schema.examples[0];
+      }
+    }
+
+    return param;
+  });
 }
 
 function extractFields(

package/tests/metal-orm-integration/run-paged-list.test.ts

@@ -0,0 +1,169 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import sqlite3 from "sqlite3";
+import {
+  Orm,
+  SqliteDialect,
+  col,
+  createSqliteExecutor,
+  defineTable,
+  selectFrom,
+  type SqliteClientLike
+} from "metal-orm";
+import { runPagedList } from "../../src/adapter/metal-orm/list";
+
+const users = defineTable("users", {
+  id: col.primaryKey(col.autoIncrement(col.int())),
+  name: col.notNull(col.text()),
+  email: col.notNull(col.text())
+});
+
+let db: sqlite3.Database | null = null;
+let orm: Orm | null = null;
+
+function createSqliteClient(database: sqlite3.Database): SqliteClientLike {
+  return {
+    all(sql, params = []) {
+      return new Promise((resolve, reject) => {
+        database.all(sql, params, (err, rows) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve(rows as Record<string, unknown>[]);
+        });
+      });
+    }
+  };
+}
+
+function execSql(sql: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!db) {
+      reject(new Error("Database not initialized"));
+      return;
+    }
+    db.exec(sql, (err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function closeDb(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!db) {
+      resolve();
+      return;
+    }
+    db.close((err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+describe("runPagedList integration", () => {
+  beforeAll(async () => {
+    db = new sqlite3.Database(":memory:");
+    await execSql("create table users (id integer primary key autoincrement, name text not null, email text not null)");
+    await execSql("insert into users (name, email) values ('Ada', 'ada@example.com')");
+    await execSql("insert into users (name, email) values ('Alan', 'alan@example.com')");
+    await execSql("insert into users (name, email) values ('Bruna', 'bruna@example.com')");
+
+    const client = createSqliteClient(db);
+    const executor = createSqliteExecutor(client);
+    orm = new Orm({
+      dialect: new SqliteDialect(),
+      executorFactory: {
+        createExecutor: () => executor,
+        createTransactionalExecutor: () => executor,
+        dispose: async () => {}
+      }
+    });
+  });
+
+  afterAll(async () => {
+    await orm?.dispose();
+    await closeDb();
+  });
+
+  it("runs filtered + sorted + paginated list from raw query", async () => {
+    if (!orm) {
+      throw new Error("ORM not initialized");
+    }
+
+    const session = orm.createSession();
+    try {
+      const result = await runPagedList({
+        query: {
+          page: "1",
+          pageSize: "1",
+          nameContains: "a",
+          sortBy: "name",
+          sortOrder: "DESC"
+        },
+        target: users,
+        qb: () => selectFrom(users).select("id", "name", "email"),
+        session,
+        filterMappings: {
+          nameContains: { field: "name", operator: "contains" }
+        },
+        sortableColumns: {
+          id: "id",
+          name: "name"
+        },
+        defaultSortBy: "id",
+        defaultSortDirection: "asc"
+      });
+
+      expect(result.totalItems).toBe(3);
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0].name).toBe("Bruna");
+      expect(result.page).toBe(1);
+      expect(result.pageSize).toBe(1);
+      expect(result.totalPages).toBe(3);
+      expect(result.hasNextPage).toBe(true);
+      expect(result.hasPrevPage).toBe(false);
+    } finally {
+      await session.dispose();
+    }
+  });
+
+  it("supports defaults when sort/page params are omitted", async () => {
+    if (!orm) {
+      throw new Error("ORM not initialized");
+    }
+
+    const session = orm.createSession();
+    try {
+      const result = await runPagedList({
+        query: {},
+        target: users,
+        qb: () => selectFrom(users).select("id", "name", "email"),
+        session,
+        filterMappings: {},
+        sortableColumns: {
+          id: "id"
+        },
+        defaultSortBy: "id",
+        defaultSortDirection: "desc",
+        defaultPageSize: 2,
+        maxPageSize: 5
+      });
+
+      expect(result.items).toHaveLength(2);
+      expect(result.items[0].id).toBe(3);
+      expect(result.items[1].id).toBe(2);
+      expect(result.pageSize).toBe(2);
+      expect(result.totalItems).toBe(3);
+    } finally {
+      await session.dispose();
+    }
+  });
+});

package/tests/unit/openapi-parameters.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { t } from "../../src/core/schema";
+import { registerController, registerDto } from "../../src/core/metadata";
+import { buildOpenApi } from "../../src/core/openapi";
+import { createInputCoercer } from "../../src/adapter/express/coercion";
+
+describe("OpenAPI query parameter serialization", () => {
+  class QueryArrayController {}
+
+  beforeEach(() => {
+    registerController({
+      basePath: "/items",
+      controller: QueryArrayController,
+      routes: [
+        {
+          httpMethod: "get",
+          path: "/",
+          handlerName: "list",
+          query: {
+            schema: {
+              kind: "object",
+              properties: {
+                ids: t.array(t.string()),
+                nums: t.array(t.integer()),
+                tags: t.array(t.string(), { examples: [["a", "b"]] })
+              }
+            }
+          },
+          responses: [{ status: 200 }]
+        }
+      ]
+    });
+  });
+
+  it("query array<string> generates style=form + explode=true", () => {
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [QueryArrayController]
+    });
+
+    const params = (doc.paths["/items"] as any).get.parameters as any[];
+    const idsParam = params.find((p: any) => p.name === "ids");
+
+    expect(idsParam).toBeDefined();
+    expect(idsParam.style).toBe("form");
+    expect(idsParam.explode).toBe(true);
+  });
+
+  it("query array<integer> generates style=form + explode=true", () => {
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [QueryArrayController]
+    });
+
+    const params = (doc.paths["/items"] as any).get.parameters as any[];
+    const numsParam = params.find((p: any) => p.name === "nums");
+
+    expect(numsParam).toBeDefined();
+    expect(numsParam.style).toBe("form");
+    expect(numsParam.explode).toBe(true);
+  });
+
+  it("projects example from schema.examples to parameter.example", () => {
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [QueryArrayController]
+    });
+
+    const params = (doc.paths["/items"] as any).get.parameters as any[];
+    const tagsParam = params.find((p: any) => p.name === "tags");
+
+    expect(tagsParam).toBeDefined();
+    expect(tagsParam.example).toEqual(["a", "b"]);
+  });
+});
+
+describe("Query array coercion – CSV support", () => {
+  it("?ids=1&ids=2 -> [1,2] via repeated keys", () => {
+    const coerce = createInputCoercer(
+      { schema: { kind: "object", properties: { ids: t.array(t.integer()) } } },
+      { mode: "safe", location: "query" }
+    )!;
+
+    const result = coerce({ ids: ["1", "2"] });
+    expect(result.ids).toEqual([1, 2]);
+  });
+
+  it("?ids=1,2 -> [1,2] via CSV string", () => {
+    const coerce = createInputCoercer(
+      { schema: { kind: "object", properties: { ids: t.array(t.integer()) } } },
+      { mode: "safe", location: "query" }
+    )!;
+
+    const result = coerce({ ids: "1,2" });
+    expect(result.ids).toEqual([1, 2]);
+  });
+});

package/tests/unit/run-paged-list.test.ts

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { col, defineTable } from "metal-orm";
+
+const { executeFilteredPagedMock } = vi.hoisted(() => ({
+  executeFilteredPagedMock: vi.fn()
+}));
+
+vi.mock("metal-orm", async () => {
+  const actual = await vi.importActual<typeof import("metal-orm")>("metal-orm");
+  return {
+    ...actual,
+    executeFilteredPaged: executeFilteredPagedMock
+  };
+});
+
+import { runPagedList } from "../../src/adapter/metal-orm/list";
+
+describe("runPagedList", () => {
+  const users = defineTable("users", {
+    id: col.primaryKey(col.autoIncrement(col.int())),
+    name: col.notNull(col.text()),
+    email: col.notNull(col.text())
+  });
+
+  const qb = {
+    getTable: () => users
+  } as unknown as import("metal-orm").SelectQueryBuilder<
+    { id: number; name: string; email: string },
+    typeof users
+  >;
+
+  beforeEach(() => {
+    executeFilteredPagedMock.mockReset();
+    executeFilteredPagedMock.mockResolvedValue({
+      items: [],
+      totalItems: 0,
+      page: 1,
+      pageSize: 25,
+      totalPages: 0,
+      hasNextPage: false,
+      hasPrevPage: false
+    });
+  });
+
+  it("combines parsing and forwards normalized sort from sortOrder", async () => {
+    await runPagedList({
+      query: {
+        page: "2",
+        pageSize: "10",
+        nameContains: "Ada",
+        sortBy: "name",
+        sortOrder: "DESC"
+      },
+      target: users,
+      qb,
+      session: {} as import("metal-orm").OrmSession,
+      filterMappings: {
+        nameContains: { field: "name", operator: "contains" }
+      },
+      sortableColumns: {
+        name: "name",
+        email: "email"
+      },
+      defaultSortBy: "email",
+      defaultSortDirection: "asc"
+    });
+
+    expect(executeFilteredPagedMock).toHaveBeenCalledTimes(1);
+    expect(executeFilteredPagedMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        page: 2,
+        pageSize: 10,
+        filters: {
+          name: { contains: "Ada" }
+        },
+        sortBy: "name",
+        sortDirection: "DESC",
+        defaultSortBy: undefined,
+        defaultSortDirection: "ASC"
+      })
+    );
+  });
+
+  it("ignores unresolved sortable path and keeps helper execution safe", async () => {
+    await runPagedList({
+      query: {
+        sortBy: "deepField"
+      },
+      target: users,
+      qb,
+      session: {} as import("metal-orm").OrmSession,
+      filterMappings: {},
+      sortableColumns: {
+        deepField: "profile.some.name"
+      },
+      defaultSortBy: "deepField",
+      defaultSortDirection: "desc"
+    });
+
+    expect(executeFilteredPagedMock).toHaveBeenCalledTimes(1);
+    expect(executeFilteredPagedMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sortBy: undefined,
+        defaultSortBy: undefined,
+        defaultSortDirection: "DESC"
+      })
+    );
+  });
+});