adorn-api 1.1.2 → 1.1.4

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

@@ -0,0 +1,82 @@
+import type { FilterFieldInput, ParseSortOptions, ParsedSort, SortDirection } from "./types";
+
+/**
+ * Parses sort parameters from query params using an allowed sortable column map.
+ * Returns undefined when no valid sort column is selected.
+ */
+export function parseSort<T>(
+  query: Record<string, unknown> | undefined,
+  sortableColumns: Record<string, FilterFieldInput<T>>,
+  options?: Omit<ParseSortOptions<T>, "query" | "sortableColumns">
+): ParsedSort<T> | undefined;
+export function parseSort<T>(options: ParseSortOptions<T>): ParsedSort<T> | undefined;
+export function parseSort<T>(
+  queryOrOptions: Record<string, unknown> | ParseSortOptions<T> | undefined,
+  sortableColumns?: Record<string, FilterFieldInput<T>>,
+  options?: Omit<ParseSortOptions<T>, "query" | "sortableColumns">
+): ParsedSort<T> | undefined {
+  const resolved = sortableColumns
+    ? {
+        query: queryOrOptions as Record<string, unknown> | undefined,
+        sortableColumns,
+        ...(options ?? {})
+      }
+    : (queryOrOptions as ParseSortOptions<T> | undefined);
+
+  const query = resolved?.query;
+  const allowed = resolved?.sortableColumns;
+  if (!query || !allowed || Object.keys(allowed).length === 0) {
+    return undefined;
+  }
+
+  const sortByKey = resolved.sortByKey ?? "sortBy";
+  const sortDirectionKey = resolved.sortDirectionKey ?? "sortDirection";
+  const defaultSortBy = resolved.defaultSortBy;
+  const defaultDirection = resolved.defaultSortDirection ?? "asc";
+
+  const requestedSortBy = toTrimmedString(query[sortByKey]);
+  const selectedSortBy = selectSortBy(requestedSortBy, defaultSortBy, allowed);
+  if (!selectedSortBy) {
+    return undefined;
+  }
+
+  const requestedDirection = toTrimmedString(query[sortDirectionKey]);
+  const sortDirection = normalizeDirection(requestedDirection, defaultDirection);
+
+  return {
+    sortBy: selectedSortBy,
+    sortDirection,
+    field: allowed[selectedSortBy]
+  };
+}
+
+function toTrimmedString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function selectSortBy<T>(
+  requestedSortBy: string | undefined,
+  defaultSortBy: string | undefined,
+  allowed: Record<string, FilterFieldInput<T>>
+): string | undefined {
+  if (requestedSortBy && requestedSortBy in allowed) {
+    return requestedSortBy;
+  }
+  if (defaultSortBy && defaultSortBy in allowed) {
+    return defaultSortBy;
+  }
+  return undefined;
+}
+
+function normalizeDirection(
+  raw: string | undefined,
+  fallback: SortDirection
+): SortDirection {
+  if (raw === "desc") {
+    return "desc";
+  }
+  if (raw === "asc") {
+    return "asc";
+  }
+  return fallback;
+}

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

@@ -1,6 +1,6 @@
 
 import type { BelongsToReference, HasManyCollection, HasOneReference, ManyToManyCollection } from "metal-orm";
-import type { DtoOptions, FieldOverride } from "../../core/decorators";
+import type { DtoOptions, ErrorResponseOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";
 
@@ -139,6 +139,41 @@ export interface ParseFilterOptions<T = Record<string, unknown>> {
   fieldMappings?: Record<string, FilterMapping<T>>;
 }
 
+/**
+ * Sort direction.
+ */
+export type SortDirection = "asc" | "desc";
+
+/**
+ * Sort parsing options.
+ */
+export interface ParseSortOptions<T = Record<string, unknown>> {
+  /** Query parameters */
+  query?: Record<string, unknown>;
+  /** Allowed sortable columns */
+  sortableColumns?: Record<string, FilterFieldInput<T>>;
+  /** Sort field query key */
+  sortByKey?: string;
+  /** Sort direction query key */
+  sortDirectionKey?: string;
+  /** Default sort field */
+  defaultSortBy?: string;
+  /** Default sort direction */
+  defaultSortDirection?: SortDirection;
+}
+
+/**
+ * Parsed sort result.
+ */
+export interface ParsedSort<T = Record<string, unknown>> {
+  /** Requested sort key */
+  sortBy?: string;
+  /** Direction */
+  sortDirection: SortDirection;
+  /** Resolved entity field */
+  field?: FilterFieldInput<T>;
+}
+
 /**
  * Filter operator.
  */
@@ -204,12 +239,87 @@ export interface PagedResponseDtoOptions {
 /**
  * Filter field definition.
  */
-export interface FilterFieldDef {
-  /** Field schema */
-  schema?: SchemaNode;
-  /** Filter operator */
-  operator?: "equals" | "contains" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte";
-}
+export interface FilterFieldDef {
+  /** Field schema */
+  schema?: SchemaNode;
+  /** Filter operator */
+  operator?: "equals" | "contains" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte";
+}
+
+/**
+ * Single filter definition for CRUD query generation.
+ */
+export interface MetalCrudQueryFilterDef<T = Record<string, unknown>> {
+  /** Field schema for query validation/OpenAPI */
+  schema: SchemaNode;
+  /** Entity field path mapping */
+  field: FilterFieldInput<T>;
+  /** Filter operator (default: equals) */
+  operator?: FilterOperator;
+}
+
+/**
+ * Sortable columns mapping for CRUD query generation.
+ * Key is accepted `sortBy` value and value is mapped entity field path.
+ */
+export type MetalCrudSortableColumns<T = Record<string, unknown>> =
+  Record<string, FilterFieldInput<T>>;
+
+/**
+ * Options-query generation options.
+ */
+export interface MetalCrudOptionsQueryOptions<T = Record<string, unknown>>
+  extends PaginationConfig {
+  /** Whether options query artifacts are generated (default: true) */
+  enabled?: boolean;
+  /** Query key used for label search (default: "search") */
+  searchKey?: string;
+  /** Entity field used as option label (default: "nome") */
+  labelField?: keyof T & string;
+  /** Entity field used as option value (default: "id") */
+  valueField?: keyof T & string;
+  /** Operator used for label search (default: "contains") */
+  searchOperator?: FilterOperator;
+}
+
+/**
+ * Query generation options for CRUD DTO factory.
+ */
+export interface MetalCrudQueryOptions<T = Record<string, unknown>>
+  extends PaginationConfig {
+  /** Filters in one place: schema + mapping + operator */
+  filters?: Record<string, MetalCrudQueryFilterDef<T>>;
+  /** Allowed sortBy values mapped to entity fields */
+  sortableColumns?: MetalCrudSortableColumns<T>;
+  /** Query key for sort field (default: "sortBy") */
+  sortByKey?: string;
+  /** Query key for sort direction (default: "sortDirection") */
+  sortDirectionKey?: string;
+  /** Default sort field key */
+  defaultSortBy?: string;
+  /** Default sort direction */
+  defaultSortDirection?: SortDirection;
+  /** Options endpoint query generation options */
+  options?: MetalCrudOptionsQueryOptions<T>;
+}
+
+/**
+ * Standard CRUD errors generation options.
+ */
+export interface MetalCrudStandardErrorsOptions {
+  /** Enable generation (default: false) */
+  enabled?: boolean;
+  /** Reuse a specific error DTO schema */
+  schema?: DtoConstructor;
+  /** Generate default schema with details */
+  withDetails?: boolean;
+  /** Include traceId in generated schema */
+  includeTraceId?: boolean;
+  /** 400 invalid id error config (set false to disable) */
+  invalidId?: false | ErrorResponseOptions;
+  /** 404 not found error config (set false to disable) */
+  notFound?: false | ErrorResponseOptions;
+}
 
 /**
  * Options for paged filter query DTOs.
@@ -225,7 +335,7 @@ export interface PagedFilterQueryDtoOptions extends PagedQueryDtoOptions {
 /**
  * Options for Metal CRUD DTOs.
  */
-export interface MetalCrudDtoOptions {
+export interface MetalCrudDtoOptions<T = Record<string, unknown>> {
   /** Field overrides */
   overrides?: Record<string, FieldOverride>;
   /** Response DTO options */
@@ -244,6 +354,10 @@ export interface MetalCrudDtoOptions {
   paramsInclude?: string[];
   /** Immutable fields */
   immutable?: string[];
+  /** Query/options/paged artifact generation */
+  query?: MetalCrudQueryOptions<T>;
+  /** Standard CRUD errors generation */
+  errors?: boolean | MetalCrudStandardErrorsOptions;
   /** Whether to throw errors instead of warnings for invalid metadata (default: false) */
   strict?: boolean;
 }
@@ -267,13 +381,32 @@ export interface MetalCrudDtoDecorators {
 /**
  * Metal CRUD DTO class names.
  */
-export type MetalCrudDtoClassNames = Partial<Record<keyof MetalCrudDtoDecorators, string>>;
+export type RouteErrorsDecorator = (
+  value: unknown,
+  context: ClassMethodDecoratorContext
+) => void;
+
+/**
+ * Metal CRUD generated class names.
+ */
+export type MetalCrudDtoClassNameKey =
+  keyof MetalCrudDtoDecorators
+  | "queryDto"
+  | "optionsQueryDto"
+  | "pagedResponseDto"
+  | "optionDto"
+  | "optionsDto";
+
+/**
+ * Metal CRUD DTO class names.
+ */
+export type MetalCrudDtoClassNames = Partial<Record<MetalCrudDtoClassNameKey, string>>;
 
 /**
  * Options for Metal CRUD DTO classes.
  * @extends MetalCrudDtoOptions
  */
-export interface MetalCrudDtoClassOptions extends MetalCrudDtoOptions {
+export interface MetalCrudDtoClassOptions<T = Record<string, unknown>> extends MetalCrudDtoOptions<T> {
   /** Base name for DTO classes */
   baseName?: string;
   /** Custom class names */
@@ -285,7 +418,7 @@ export interface MetalCrudDtoClassOptions extends MetalCrudDtoOptions {
 /**
  * Metal CRUD DTO classes.
  */
-export interface MetalCrudDtoClasses {
+export interface MetalCrudDtoClasses<T = Record<string, unknown>> {
   /** Response DTO class */
   response: DtoConstructor;
   /** Create DTO class */
@@ -296,6 +429,22 @@ export interface MetalCrudDtoClasses {
   update: DtoConstructor;
   /** Params DTO class */
   params: DtoConstructor;
+  /** Query DTO class (paged + filters + sort) */
+  queryDto: DtoConstructor;
+  /** Options query DTO class */
+  optionsQueryDto: DtoConstructor;
+  /** Paged response DTO class for main list endpoints */
+  pagedResponseDto: DtoConstructor;
+  /** Option DTO class (value + label fields) */
+  optionDto: DtoConstructor;
+  /** Paged response DTO class for options endpoints */
+  optionsDto: DtoConstructor;
+  /** Prebuilt CRUD error decorator (400 invalid id, 404 not found) */
+  errors?: RouteErrorsDecorator;
+  /** Execution-ready filter mappings for parseFilter */
+  filterMappings: Record<string, FilterMapping<T>>;
+  /** Execution-ready sortable column mappings */
+  sortableColumns: MetalCrudSortableColumns<T>;
 }
 
 /**

package/tests/e2e/metal-crud-openapi.e2e.test.ts

@@ -8,8 +8,6 @@ import {
   Query,
   buildOpenApi,
   createMetalCrudDtoClasses,
-  createPagedResponseDtoClass,
-  createPagedFilterQueryDtoClass,
   t,
   type RequestContext
 } from "../../src/index";
@@ -40,29 +38,34 @@ class NotaVersao {
 }
 
 const notaVersaoCrud = createMetalCrudDtoClasses(NotaVersao, {
-  mutationExclude: ["id", "data_exclusao", "data_inativacao"]
+  mutationExclude: ["id", "data_exclusao", "data_inativacao"],
+  query: {
+    filters: {
+      sprint: { schema: t.integer({ minimum: 1 }), field: "sprint", operator: "equals" },
+      ativo: { schema: t.boolean(), field: "ativo", operator: "equals" },
+      mensagemContains: { schema: t.string({ minLength: 1 }), field: "mensagem", operator: "contains" }
+    },
+    sortableColumns: {
+      id: "id",
+      sprint: "sprint",
+      data: "data"
+    },
+    options: {
+      labelField: "mensagem"
+    }
+  },
+  errors: true
 });
 
 const {
   response: NotaVersaoDto,
-  create: CreateNotaVersaoDto
+  create: CreateNotaVersaoDto,
+  queryDto: NotaVersaoQueryDtoClass,
+  pagedResponseDto: NotaVersaoPagedResponseDto,
+  filterMappings: NotaVersaoFilterMappings,
+  sortableColumns: NotaVersaoSortableColumns
 } = notaVersaoCrud;
 
-const NotaVersaoQueryDtoClass = createPagedFilterQueryDtoClass({
-  name: "NotaVersaoQueryDto",
-  filters: {
-    sprint: { schema: t.integer({ minimum: 1 }), operator: "equals" },
-    ativo: { schema: t.boolean(), operator: "equals" },
-    mensagemContains: { schema: t.string({ minLength: 1 }), operator: "contains" }
-  }
-});
-
-const NotaVersaoPagedResponseDto = createPagedResponseDtoClass({
-  name: "NotaVersaoPagedResponseDto",
-  itemDto: NotaVersaoDto,
-  description: "Lista paginada de notas de versão."
-});
-
 @Controller({ path: "/nota-versao", tags: ["Nota Versão"] })
 class NotaVersaoController {
   @Get("/")
@@ -81,6 +84,20 @@ class NotaVersaoController {
 }
 
 describe("e2e metal-orm CRUD DTOs to OpenAPI", () => {
+  it("provides execution-ready query metadata", () => {
+    expect(NotaVersaoFilterMappings).toEqual({
+      sprint: { field: "sprint", operator: "equals" },
+      ativo: { field: "ativo", operator: "equals" },
+      mensagemContains: { field: "mensagem", operator: "contains" },
+      search: { field: "mensagem", operator: "contains" }
+    });
+    expect(NotaVersaoSortableColumns).toEqual({
+      id: "id",
+      sprint: "sprint",
+      data: "data"
+    });
+  });
+
   it("generates OpenAPI schemas with properties from createMetalCrudDtoClasses", () => {
     const doc = buildOpenApi({
       info: { title: "Test API", version: "1.0.0" },

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

@@ -1,10 +1,12 @@
-import { describe, expect, it } from "vitest";
-import {
-  createMetalCrudDtos,
-  createMetalCrudDtoClasses
-} from "../../src/adapter/metal-orm/index";
-import { getDtoMeta } from "../../src/core/metadata";
-import { Alphanumeric, Column, Email, Entity, Length, Pattern, PrimaryKey, col } from "metal-orm";
+import { describe, expect, it } from "vitest";
+import {
+  createMetalCrudDtos,
+  createMetalCrudDtoClasses
+} from "../../src/adapter/metal-orm/index";
+import type { FilterMapping } from "../../src/adapter/metal-orm/index";
+import { getDtoMeta } from "../../src/core/metadata";
+import { t } from "../../src/core/schema";
+import { Alphanumeric, Column, Email, Entity, Length, Pattern, PrimaryKey, col } from "metal-orm";
 
 describe("createMetalCrudDtos", () => {
   @Entity({ tableName: "crud_dto_entities" })
@@ -97,20 +99,34 @@ describe("createMetalCrudDtoClasses", () => {
     nickname?: string | null;
   }
 
-  it("builds ready-to-export DTO classes", () => {
-    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
-      mutationExclude: ["id"]
-    });
-
-    const responseMeta = getDtoMeta(classes.response);
-    const createMeta = getDtoMeta(classes.create);
-    const paramsMeta = getDtoMeta(classes.params);
-
-    expect(classes.response.name).toBe("CrudDtoClassEntityDto");
-    expect(responseMeta?.fields.id).toBeDefined();
-    expect(createMeta?.fields.id).toBeUndefined();
-    expect(paramsMeta?.fields).toEqual({ id: expect.any(Object) });
-  });
+  it("builds ready-to-export DTO classes", () => {
+    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
+      mutationExclude: ["id"]
+    });
+
+    const responseMeta = getDtoMeta(classes.response);
+    const createMeta = getDtoMeta(classes.create);
+    const paramsMeta = getDtoMeta(classes.params);
+    const pagedResponseMeta = getDtoMeta(classes.pagedResponseDto);
+    const optionsMeta = getDtoMeta(classes.optionsDto);
+
+    expect(classes.response.name).toBe("CrudDtoClassEntityDto");
+    expect(classes.queryDto.name).toBe("CrudDtoClassEntityQueryDto");
+    expect(classes.optionsQueryDto.name).toBe("CrudDtoClassEntityOptionsQueryDto");
+    expect(classes.optionDto.name).toBe("CrudDtoClassEntityOptionDto");
+    expect(pagedResponseMeta?.name).toBe("CrudDtoClassEntityPagedResponseDto");
+    expect(optionsMeta?.name).toBe("CrudDtoClassEntityOptionsDto");
+    expect(responseMeta?.fields.id).toBeDefined();
+    expect(createMeta?.fields.id).toBeUndefined();
+    expect(paramsMeta?.fields).toEqual({ id: expect.any(Object) });
+    expect(classes.filterMappings).toEqual({
+      search: {
+        field: "nome",
+        operator: "contains"
+      }
+    });
+    expect(classes.sortableColumns).toEqual({});
+  });
 
   it("applies custom name overrides", () => {
     const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
@@ -121,8 +137,64 @@ describe("createMetalCrudDtoClasses", () => {
       }
     });
 
-    expect(classes.response.name).toBe("PersonDto");
-    expect(classes.params.name).toBe("PersonIdDto");
-    expect(classes.create.name).toBe("CreatePersonDto");
-  });
-});
+    expect(classes.response.name).toBe("PersonDto");
+    expect(classes.params.name).toBe("PersonIdDto");
+    expect(classes.create.name).toBe("CreatePersonDto");
+  });
+
+  it("generates query/options artifacts and execution-ready metadata from one config", () => {
+    const classes = createMetalCrudDtoClasses(CrudDtoClassEntity, {
+      query: {
+        filters: {
+          nameContains: {
+            schema: t.string({ minLength: 1 }),
+            field: "name",
+            operator: "contains"
+          },
+          nickname: {
+            schema: t.string({ minLength: 1 }),
+            field: "nickname"
+          }
+        },
+        sortableColumns: {
+          name: "name",
+          nickname: "nickname"
+        },
+        options: {
+          labelField: "name",
+          searchKey: "labelContains"
+        }
+      },
+      errors: true
+    });
+
+    const queryMeta = getDtoMeta(classes.queryDto);
+    const optionsQueryMeta = getDtoMeta(classes.optionsQueryDto);
+    const optionMeta = getDtoMeta(classes.optionDto);
+
+    expect(queryMeta?.fields.page).toBeDefined();
+    expect(queryMeta?.fields.pageSize).toBeDefined();
+    expect(queryMeta?.fields.nameContains).toBeDefined();
+    expect(queryMeta?.fields.nickname).toBeDefined();
+    expect(queryMeta?.fields.sortBy).toBeDefined();
+    expect(queryMeta?.fields.sortDirection).toBeDefined();
+
+    expect(optionsQueryMeta?.fields.labelContains).toBeDefined();
+    expect(optionMeta?.fields.id).toBeDefined();
+    expect(optionMeta?.fields.name).toBeDefined();
+
+    expect(classes.filterMappings).toEqual({
+      nameContains: { field: "name", operator: "contains" },
+      nickname: { field: "nickname", operator: "equals" },
+      labelContains: { field: "name", operator: "contains" }
+    });
+
+    const typedMappings: Record<string, FilterMapping<CrudDtoClassEntity>> = classes.filterMappings;
+    expect(typedMappings.nameContains.field).toBe("name");
+    expect(classes.sortableColumns).toEqual({
+      name: "name",
+      nickname: "nickname"
+    });
+    expect(typeof classes.errors).toBe("function");
+  });
+});

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { parseFilter } from "../../src/adapter/metal-orm/index";
-import type { FilterMapping } from "../../src/adapter/metal-orm/types";
+import type { FilterMapping } from "../../src/adapter/metal-orm/index";
 
 describe("parseFilter", () => {
   it("returns undefined when query is undefined", () => {

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { parseSort } from "../../src/adapter/metal-orm/index";
+
+describe("parseSort", () => {
+  it("returns undefined when sortBy is missing", () => {
+    const result = parseSort({
+      query: { page: 1 },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when sortBy is not allowed", () => {
+    const result = parseSort({
+      query: { sortBy: "email" },
+      sortableColumns: { name: "name" }
+    });
+    expect(result).toBeUndefined();
+  });
+
+  it("parses valid sort and resolves mapped field", () => {
+    const result = parseSort({
+      query: { sortBy: "userName", sortDirection: "desc" },
+      sortableColumns: { userName: "name" }
+    });
+    expect(result).toEqual({
+      sortBy: "userName",
+      sortDirection: "desc",
+      field: "name"
+    });
+  });
+
+  it("supports custom sort keys and defaults", () => {
+    const result = parseSort({
+      query: { direction: "desc" },
+      sortableColumns: { createdAt: "createdAt" },
+      sortByKey: "orderBy",
+      sortDirectionKey: "direction",
+      defaultSortBy: "createdAt",
+      defaultSortDirection: "asc"
+    });
+    expect(result).toEqual({
+      sortBy: "createdAt",
+      sortDirection: "desc",
+      field: "createdAt"
+    });
+  });
+});