adorn-api 1.1.5 → 1.1.7

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "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/metal-orm/crud-controller.ts

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

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

@@ -21,6 +21,11 @@ export {
   parseSort
 } from "./sort";
 
+export {
+  runPagedList,
+  executeCrudList
+} from "./list";
+
 export {
   createPagedQueryDtoClass,
   createPagedResponseDtoClass,
@@ -33,6 +38,10 @@ export {
   createNestedCreateDtoClass
 } from "./crud-dtos";
 
+export {
+  createCrudController
+} from "./crud-controller";
+
 export {
   createMetalTreeDtoClasses
 } from "./tree-dtos";
@@ -80,6 +89,10 @@ export type {
   ParseSortOptions,
   ParsedSort,
   SortDirection,
+  CrudListSortTerm,
+  RunPagedListOptions,
+  ExecuteCrudListOptions,
+  CrudPagedResponse,
   ListConfig,
   PagedQueryDtoOptions,
   PagedResponseDtoOptions,
@@ -96,6 +109,9 @@ export type {
   MetalCrudDtoClasses,
   MetalCrudDtoClassNameKey,
   MetalCrudDtoClassNames,
+  CrudControllerService,
+  CrudControllerServiceInput,
+  CreateCrudControllerOptions,
   RouteErrorsDecorator,
   NestedCreateDtoOptions,
   MetalTreeDtoClassOptions,

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
+};