adorn-api 1.1.4 → 1.1.6

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

@@ -1,14 +1,15 @@
-
+
 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";
-
+import type { RequestContext } from "../express/types";
+
+/**
+ * Metal ORM DTO modes.
+ */
+export type MetalDtoMode = "response" | "create" | "update";
+
 /**
  * Options for Metal ORM DTOs.
  * @extends DtoOptions
@@ -25,47 +26,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 +119,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 +157,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 +177,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 +238,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 +347,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 +388,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 +428,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 +441,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 +472,88 @@ export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
   filterMappings: Record<string, FilterMapping<T>>;
   /** Execution-ready sortable column mappings */
   sortableColumns: MetalCrudSortableColumns<T>;
+  /** Ready-to-use config for list/query endpoints (combines filters, sort, pagination defaults) */
+  listConfig: ListConfig<T>;
+}
+
+/**
+ * Awaitable helper for CRUD service methods.
+ */
+export type Awaitable<T> = T | Promise<T>;
+
+/**
+ * Input for CRUD controller service: class or ready instance.
+ */
+export type CrudControllerServiceInput<TDtos extends MetalCrudDtoClasses<any>> =
+  CrudControllerService<TDtos>
+  | (new () => CrudControllerService<TDtos>);
+
+/**
+ * CRUD controller service contract used by createCrudController.
+ */
+export interface CrudControllerService<TDtos extends MetalCrudDtoClasses<any>> {
+  list(
+    ctx: RequestContext<unknown, InstanceType<TDtos["queryDto"]>>
+  ): Awaitable<InstanceType<TDtos["pagedResponseDto"]>>;
+  options?(
+    ctx: RequestContext<unknown, InstanceType<TDtos["optionsQueryDto"]>>
+  ): Awaitable<InstanceType<TDtos["optionsDto"]>>;
+  getById(
+    id: number,
+    ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  create(
+    body: InstanceType<TDtos["create"]>,
+    ctx: RequestContext<InstanceType<TDtos["create"]>>
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  replace?(
+    id: number,
+    body: InstanceType<TDtos["replace"]>,
+    ctx: RequestContext<
+      InstanceType<TDtos["replace"]>,
+      undefined,
+      InstanceType<TDtos["params"]>
+    >
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  update?(
+    id: number,
+    body: InstanceType<TDtos["update"]>,
+    ctx: RequestContext<
+      InstanceType<TDtos["update"]>,
+      undefined,
+      InstanceType<TDtos["params"]>
+    >
+  ): Awaitable<InstanceType<TDtos["response"]>>;
+  delete?(
+    id: number,
+    ctx: RequestContext<unknown, undefined, InstanceType<TDtos["params"]>>
+  ): Awaitable<void>;
+}
+
+/**
+ * createCrudController options.
+ */
+export interface CreateCrudControllerOptions<
+  TDtos extends MetalCrudDtoClasses<any>
+> {
+  /** Controller path. */
+  path: string;
+  /** Service instance or class (new () => service). */
+  service: CrudControllerServiceInput<TDtos>;
+  /** DTO bundle produced by createMetalCrudDtoClasses. */
+  dtos: TDtos;
+  /** Entity label used by parseIdOrThrow messages. */
+  entityName: string;
+  /** Generate GET /options route (default: true). */
+  withOptionsRoute?: boolean;
+  /** Generate PUT /:id route (default: true). */
+  withReplace?: boolean;
+  /** Generate PATCH /:id route (default: true). */
+  withPatch?: boolean;
+  /** Generate DELETE /:id route (default: true). */
+  withDelete?: boolean;
+  /** Optional OpenAPI tags for generated controller. */
+  tags?: string[];
 }
 
 /**
@@ -518,25 +627,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;