adorn-api 1.1.5 → 1.1.7

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();
     }
@@ -491,6 +482,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
@@ -539,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 {
@@ -557,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();
     }
@@ -584,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/crud-controller.d.ts

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

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

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

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

@@ -2,11 +2,13 @@ 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";
 export { createMetalTreeDtoClasses } from "./tree-dtos";
 export { createMetalDtoOverrides, type CreateMetalDtoOverridesOptions } from "./convention-overrides";
 export { createErrorDtoClass, StandardErrorDto, SimpleErrorDto, BasicErrorDto } from "./error-dtos";
 export { withSession, parseIdOrThrow, compactUpdates, applyInput, getEntityOrThrow } from "./utils";
 export { validateEntityMetadata, hasValidEntityMetadata } from "./field-builder";
-export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, ListConfig, PagedQueryDtoOptions, PagedResponseDtoOptions, PagedFilterQueryDtoOptions, FilterFieldDef, MetalCrudQueryFilterDef, MetalCrudSortableColumns, MetalCrudOptionsQueryOptions, MetalCrudQueryOptions, MetalCrudStandardErrorsOptions, MetalCrudDtoOptions, MetalCrudDtoClassOptions, MetalCrudDtoDecorators, MetalCrudDtoClasses, MetalCrudDtoClassNameKey, MetalCrudDtoClassNames, RouteErrorsDecorator, NestedCreateDtoOptions, MetalTreeDtoClassOptions, MetalTreeDtoClasses, MetalTreeDtoClassNames, MetalTreeListEntryOptions, ErrorDtoOptions, CreateSessionFn } from "./types";
+export type { MetalDtoMode, MetalDtoOptions, MetalDtoTarget, PaginationConfig, PaginationOptions, ParsedPagination, Filter, FilterMapping, FilterFieldMapping, FilterFieldPath, FilterFieldPathArray, FilterFieldInput, RelationQuantifier, ParseFilterOptions, ParseSortOptions, ParsedSort, SortDirection, 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.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; } });
@@ -23,6 +26,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/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;
+}