adorn-api 1.0.23 → 1.0.24

package/src/adapter/metal-orm/crud-dtos.ts

@@ -0,0 +1,141 @@
+import { Dto } from "../../core/decorators";
+import type { DtoConstructor } from "../../core/types";
+import { MetalDto } from "./dto";
+import type {
+  MetalCrudDtoOptions,
+  MetalCrudDtoClassOptions,
+  MetalCrudDtoClasses,
+  MetalCrudDtoDecorators,
+  NestedCreateDtoOptions
+} from "./types";
+
+export function createMetalCrudDtos(
+  target: any,
+  options: MetalCrudDtoOptions = {}
+): MetalCrudDtoDecorators {
+  const mutationExclude = options.mutationExclude;
+  const immutable = options.immutable;
+
+  const response = buildCrudOptions(options.response, options.overrides);
+  const create = buildCrudOptions(options.create, options.overrides, {
+    mode: "create",
+    exclude: mergeStringArrays(mutationExclude, options.create?.exclude)
+  });
+  const replace = buildCrudOptions(options.replace, options.overrides, {
+    mode: "create",
+    exclude: mergeStringArrays(mutationExclude, immutable, options.replace?.exclude)
+  });
+  const update = buildCrudOptions(options.update, options.overrides, {
+    mode: "update",
+    exclude: mergeStringArrays(mutationExclude, immutable, options.update?.exclude)
+  });
+
+  const params = buildCrudOptions(options.params, options.overrides);
+  params.include = params.include ?? options.paramsInclude ?? ["id"];
+
+  return {
+    response: MetalDto(target, response),
+    create: MetalDto(target, create),
+    replace: MetalDto(target, replace),
+    update: MetalDto(target, update),
+    params: MetalDto(target, params)
+  };
+}
+
+export function createMetalCrudDtoClasses(
+  target: any,
+  options: MetalCrudDtoClassOptions = {}
+): MetalCrudDtoClasses {
+  const { baseName, names, ...crudOptions } = options;
+  const decorators = createMetalCrudDtos(target, crudOptions);
+  const entityName = baseName ?? getTargetName(target);
+  const defaultNames: Record<keyof MetalCrudDtoDecorators, string> = {
+    response: `${entityName}Dto`,
+    create: `Create${entityName}Dto`,
+    replace: `Replace${entityName}Dto`,
+    update: `Update${entityName}Dto`,
+    params: `${entityName}ParamsDto`
+  };
+
+  const classes: Partial<MetalCrudDtoClasses> = {};
+  for (const key of Object.keys(decorators) as Array<keyof MetalCrudDtoDecorators>) {
+    const name = names?.[key] ?? defaultNames[key];
+    classes[key] = buildDtoClass(name, decorators[key]);
+  }
+  return classes as MetalCrudDtoClasses;
+}
+
+export function createNestedCreateDtoClass(
+  target: any,
+  overrides: Record<string, any>,
+  options: NestedCreateDtoOptions
+): DtoConstructor {
+  const { additionalExclude, name, parentEntity, ...metalDtoOptions } = options;
+
+  const allExcludes = mergeStringArrays(
+    ["id", "createdAt"],
+    additionalExclude,
+    metalDtoOptions.exclude
+  );
+
+  @MetalDto(target, {
+    ...metalDtoOptions,
+    mode: "create",
+    exclude: allExcludes,
+    overrides
+  })
+  class NestedCreateDto {}
+
+  Object.defineProperty(NestedCreateDto, "name", { value: name, configurable: true });
+
+  return NestedCreateDto;
+}
+
+function buildDtoClass(name: string, decorator: (target: DtoConstructor) => void): DtoConstructor {
+  const DtoClass = class {};
+  Object.defineProperty(DtoClass, "name", { value: name, configurable: true });
+  decorator(DtoClass);
+  return DtoClass;
+}
+
+function getTargetName(target: any): string {
+  if (typeof target === "function" && target.name) {
+    return target.name;
+  }
+  return "Entity";
+}
+
+function mergeOverrides(
+  base?: Record<string, any>,
+  override?: Record<string, any>
+): Record<string, any> | undefined {
+  if (!base && !override) {
+    return undefined;
+  }
+  return { ...(base ?? {}), ...(override ?? {}) };
+}
+
+function mergeStringArrays(
+  ...entries: Array<string[] | undefined>
+): string[] | undefined {
+  const merged = new Set<string>();
+  for (const entry of entries) {
+    for (const value of entry ?? []) {
+      merged.add(value);
+    }
+  }
+  return merged.size ? Array.from(merged) : undefined;
+}
+
+function buildCrudOptions(
+  base: any | undefined,
+  overrides: Record<string, any> | undefined,
+  extra: any = {}
+): any {
+  const mergedOverrides = mergeOverrides(overrides, base?.overrides);
+  const output: any = { ...base, ...extra };
+  if (mergedOverrides) {
+    output.overrides = mergedOverrides;
+  }
+  return output;
+}

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

@@ -0,0 +1,20 @@
+import { getColumnMap } from "metal-orm";
+import type { DtoConstructor } from "../../core/types";
+import { registerDto } from "../../core/metadata";
+import { buildFields, type MetalDtoOptions } from "./field-builder";
+
+export type MetalDtoTarget = Parameters<typeof getColumnMap>[0];
+
+export function MetalDto(target: MetalDtoTarget, options: MetalDtoOptions = {}) {
+  return (value: DtoConstructor): void => {
+    const fields = buildFields(target, options);
+    registerDto(value, {
+      name: options.name ?? value.name,
+      description: options.description,
+      fields,
+      additionalProperties: options.additionalProperties
+    });
+  };
+}
+
+export type { MetalDtoOptions } from "./field-builder";

package/src/adapter/metal-orm/error-dtos.ts

@@ -0,0 +1,51 @@
+import { Dto, Field } from "../../core/decorators";
+import type { DtoConstructor } from "../../core/types";
+import type { ErrorDtoOptions } from "./types";
+import { t } from "../../core/schema";
+
+export function createErrorDtoClass(options: ErrorDtoOptions = {}): DtoConstructor {
+  const { withDetails = true, includeTraceId = true } = options;
+
+  if (withDetails) {
+    @Dto()
+    class ErrorDetailDto {
+      @Field(t.string())
+      field!: string;
+
+      @Field(t.string())
+      message!: string;
+    }
+
+    @Dto()
+    class ErrorDto {
+      @Field(t.string())
+      message!: string;
+
+      @Field(t.optional(t.string()))
+      code?: string;
+
+      @Field(t.optional(t.array(t.ref(ErrorDetailDto))))
+      errors?: ErrorDetailDto[];
+
+      @Field(t.optional(t.string()))
+      traceId?: string;
+    }
+
+    return ErrorDto;
+  }
+
+  @Dto()
+  class SimpleErrorDto {
+    @Field(t.string())
+    message!: string;
+
+    @Field(t.optional(t.string()))
+    traceId?: string;
+  }
+
+  return SimpleErrorDto;
+}
+
+export const StandardErrorDto = createErrorDtoClass({ withDetails: true, includeTraceId: true });
+export const SimpleErrorDto = createErrorDtoClass({ withDetails: false, includeTraceId: true });
+export const BasicErrorDto = createErrorDtoClass({ withDetails: false, includeTraceId: false });

package/src/adapter/metal-orm/field-builder.ts

@@ -0,0 +1,185 @@
+import type { ColumnDef } from "metal-orm";
+import {
+  columnTypeToOpenApiFormat,
+  columnTypeToOpenApiType,
+  getColumnMap
+} from "metal-orm";
+import type { SchemaNode } from "../../core/schema";
+import { t } from "../../core/schema";
+import type { FieldMeta } from "../../core/metadata";
+import type { FieldOverride } from "../../core/decorators";
+
+export type MetalDtoMode = "response" | "create" | "update";
+
+export interface MetalDtoOptions {
+  mode?: MetalDtoMode;
+  include?: string[];
+  exclude?: string[];
+  overrides?: Record<string, FieldOverride>;
+  description?: string;
+  name?: string;
+  additionalProperties?: boolean;
+}
+
+export function buildFields(
+  target: any,
+  options: MetalDtoOptions
+): Record<string, FieldMeta> {
+  const columns = getColumnMap(target);
+  const include = options.include ? new Set(options.include) : undefined;
+  const exclude = options.exclude ? new Set(options.exclude) : undefined;
+  const mode = options.mode ?? "response";
+  const fields: Record<string, FieldMeta> = {};
+
+  for (const [name, col] of Object.entries(columns)) {
+    if (include && !include.has(name)) {
+      continue;
+    }
+    if (exclude && exclude.has(name)) {
+      continue;
+    }
+    if ((mode === "create" || mode === "update") && isAutoGenerated(col)) {
+      continue;
+    }
+    fields[name] = buildFieldMeta(col, mode);
+  }
+
+  return applyOverrides(fields, options.overrides, columns);
+}
+
+export function buildFieldMeta(col: any, mode: MetalDtoMode): FieldMeta {
+  let schema = columnToSchemaNode(col);
+  if (!col.notNull) {
+    schema = t.nullable(schema);
+  }
+
+  const optional = isOptional(col, mode);
+  const field: FieldMeta = { schema };
+  if (optional) {
+    field.optional = true;
+  }
+  if (col.comment) {
+    field.description = col.comment;
+  }
+  return field;
+}
+
+function isOptional(col: ColumnDef, mode: MetalDtoMode): boolean {
+  if (mode === "update") {
+    return true;
+  }
+  if (mode === "create") {
+    if (isAutoGenerated(col)) {
+      return true;
+    }
+    if (!col.notNull) {
+      return true;
+    }
+    if (col.default !== undefined) {
+      return true;
+    }
+    return false;
+  }
+  return !(col.notNull || col.primary);
+}
+
+function isAutoGenerated(col: ColumnDef): boolean {
+  return col.autoIncrement === true ||
+    col.generated === "always" ||
+    col.generated === "byDefault";
+}
+
+function columnToSchemaNode(col: ColumnDef): SchemaNode {
+  const enumValues = getEnumValues(col);
+  if (enumValues) {
+    return t.enum(enumValues);
+  }
+
+  const openApiType = columnTypeToOpenApiType(col);
+  switch (openApiType) {
+    case "integer":
+      return t.integer();
+    case "number":
+      return t.number();
+    case "boolean":
+      return t.boolean();
+    case "string":
+      return buildStringSchema(col);
+    case "array":
+      return t.array(t.any());
+    case "object":
+      return t.object({}, { additionalProperties: true });
+    case "null":
+      return t.null();
+    default:
+      return t.any();
+  }
+}
+
+function buildStringSchema(col: ColumnDef): SchemaNode {
+  const format = columnTypeToOpenApiFormat(col);
+  const type = col.type.toUpperCase();
+  const length = col.args?.[0];
+  if ((type === "VARCHAR" || type === "CHAR") && typeof length === "number") {
+    return t.string({
+      format,
+      maxLength: length,
+      minLength: type === "CHAR" ? length : undefined
+    });
+  }
+  return t.string({ format });
+}
+
+function getEnumValues(col: ColumnDef): string[] | undefined {
+  if (col.type.toUpperCase() !== "ENUM") {
+    return undefined;
+  }
+  if (!Array.isArray(col.args) || !col.args.every((value) => typeof value === "string")) {
+    return undefined;
+  }
+  return col.args as string[];
+}
+
+function applyOverrides(
+  fields: Record<string, FieldMeta>,
+  overrides: Record<string, FieldOverride> | undefined,
+  columns: Record<string, ColumnDef>
+): Record<string, FieldMeta> {
+  if (!overrides) {
+    return fields;
+  }
+  const output: Record<string, FieldMeta> = { ...fields };
+  const availableColumns = new Set(Object.keys(columns));
+  for (const [name, override] of Object.entries(overrides)) {
+    const field = output[name];
+    if (!field) {
+      if (availableColumns.has(name)) {
+        continue;
+      }
+      throw new Error(`DTO field "${name}" does not exist.`);
+    }
+    output[name] = normalizeOverride(field, override);
+  }
+  return output;
+}
+
+function normalizeOverride(field: FieldMeta, override: FieldOverride): FieldMeta {
+  if (isSchemaNode(override)) {
+    return {
+      schema: override,
+      optional: (override as any).optional ?? field.optional ?? (field.schema as any).optional,
+      description: field.description
+    };
+  }
+  const schema = override.schema ?? field.schema;
+  const optional = override.optional ?? (schema as any).optional ?? field.optional ?? (field.schema as any).optional;
+  return {
+    schema,
+    optional,
+    description: override.description ?? field.description
+  };
+}
+
+function isSchemaNode(value: unknown): value is SchemaNode {
+  return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
+}

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

@@ -0,0 +1,52 @@
+import type { Filter, FilterMapping, ParseFilterOptions } from "./types";
+
+/**
+ * Parses filter parameters from query parameters.
+ * @param query - Query parameters
+ * @param mappings - Filter field mappings
+ * @returns Parsed filter or undefined
+ */
+export function parseFilter<T, K extends keyof T>(
+  query: Record<string, unknown> | undefined,
+  mappings: Record<string, { field: K; operator: "equals" | "contains" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" }>
+): Filter<T, K> | undefined {
+  if (!query) {
+    return undefined;
+  }
+
+  const filter: Filter<T, K> = {};
+
+  for (const [queryKey, value] of Object.entries(query)) {
+    const mapping = mappings[queryKey];
+    if (!mapping || value === undefined || value === null || value === "") {
+      continue;
+    }
+
+    const { field, operator } = mapping;
+    if (!filter[field]) {
+      filter[field] = {};
+    }
+    filter[field]![operator] = value as T[K];
+  }
+
+  return Object.keys(filter).length ? filter : undefined;
+}
+
+/**
+ * Creates filter mappings for an entity.
+ * @param entity - Entity type
+ * @param fields - Array of field definitions
+ * @returns Filter mappings
+ */
+export function createFilterMappings<T extends Record<string, unknown>>(
+  entity: T,
+  fields: Array<{ queryKey: string; field: keyof T; operator?: "equals" | "contains" | "startsWith" | "endsWith" }>
+): Record<string, { field: keyof T; operator: "equals" | "contains" | "startsWith" | "endsWith" }> {
+  const mappings: Record<string, { field: keyof T; operator: "equals" | "contains" | "startsWith" | "endsWith" }> = {};
+
+  for (const { queryKey, field, operator = "equals" } of fields) {
+    mappings[queryKey] = { field, operator };
+  }
+
+  return mappings;
+}

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

@@ -0,0 +1,66 @@
+export {
+  MetalDto
+} from "./dto";
+
+export {
+  parsePagination
+} from "./pagination";
+
+export {
+  parseFilter,
+  createFilterMappings
+} from "./filters";
+
+export {
+  createPagedQueryDtoClass,
+  createPagedResponseDtoClass,
+  createPagedFilterQueryDtoClass
+} from "./paged-dtos";
+
+export {
+  createMetalCrudDtos,
+  createMetalCrudDtoClasses,
+  createNestedCreateDtoClass
+} from "./crud-dtos";
+
+export {
+  createMetalDtoOverrides,
+  type CreateMetalDtoOverridesOptions
+} from "./convention-overrides";
+
+export {
+  createErrorDtoClass,
+  StandardErrorDto,
+  SimpleErrorDto,
+  BasicErrorDto
+} from "./error-dtos";
+
+export {
+  withSession,
+  parseIdOrThrow
+} from "./utils";
+
+export type {
+  MetalDtoMode,
+  MetalDtoOptions,
+  MetalDtoTarget,
+  PaginationConfig,
+  PaginationOptions,
+  ParsedPagination,
+  Filter,
+  FilterMapping,
+  FilterFieldMapping,
+  ParseFilterOptions,
+  PagedQueryDtoOptions,
+  PagedResponseDtoOptions,
+  PagedFilterQueryDtoOptions,
+  FilterFieldDef,
+  MetalCrudDtoOptions,
+  MetalCrudDtoClassOptions,
+  MetalCrudDtoDecorators,
+  MetalCrudDtoClasses,
+  MetalCrudDtoClassNames,
+  NestedCreateDtoOptions,
+  ErrorDtoOptions,
+  CreateSessionFn
+} from "./types";

package/src/adapter/metal-orm/paged-dtos.ts

@@ -0,0 +1,94 @@
+import { Dto, Field } from "../../core/decorators";
+import type { DtoConstructor } from "../../core/types";
+import type { SchemaNode } from "../../core/schema";
+import { t } from "../../core/schema";
+import type { FieldMeta } from "../../core/metadata";
+import { registerDto } from "../../core/metadata";
+import type {
+  PagedQueryDtoOptions,
+  PagedResponseDtoOptions,
+  PagedFilterQueryDtoOptions
+} from "./types";
+
+export function createPagedQueryDtoClass(
+  options: PagedQueryDtoOptions = {}
+): DtoConstructor {
+  const { defaultPageSize = 25, maxPageSize = 100 } = options;
+
+  @Dto({ name: options.name })
+  class PagedQueryDto {
+    @Field(t.optional(t.integer({ minimum: 1, default: 1 })))
+    page?: number;
+
+    @Field(
+      t.optional(
+        t.integer({ minimum: 1, maximum: maxPageSize, default: defaultPageSize })
+      )
+    )
+    pageSize?: number;
+  }
+
+  return PagedQueryDto;
+}
+
+export function createPagedFilterQueryDtoClass(
+  options: PagedFilterQueryDtoOptions
+): DtoConstructor {
+  const { filters, defaultPageSize = 25, maxPageSize = 100, name } = options;
+
+  const PagedFilterQueryDto = class {
+    page?: number;
+    pageSize?: number;
+    [key: string]: any;
+  };
+
+  const fields: Record<string, FieldMeta> = {
+    page: { schema: t.optional(t.integer({ minimum: 1, default: 1 })), optional: true },
+    pageSize: { schema: t.optional(t.integer({ minimum: 1, maximum: maxPageSize, default: defaultPageSize })), optional: true }
+  };
+
+  for (const [fieldName, def] of Object.entries(filters)) {
+    const schema = def.schema ?? t.string({ minLength: 1 });
+    fields[fieldName] = { schema: t.optional(schema), optional: true };
+  }
+
+  registerDto(PagedFilterQueryDto, {
+    name: name ?? "PagedFilterQueryDto",
+    fields
+  });
+
+  return PagedFilterQueryDto as DtoConstructor;
+}
+
+export function createPagedResponseDtoClass(
+  options: PagedResponseDtoOptions
+): DtoConstructor {
+  const { itemDto, description, name } = options;
+  const responseDescription = description ?? "Paged response.";
+
+  @Dto({ name, description: responseDescription })
+  class PagedResponseDto {
+    @Field(t.array(t.ref(itemDto)))
+    items!: unknown[];
+
+    @Field(t.integer({ minimum: 0 }))
+    totalItems!: number;
+
+    @Field(t.integer({ minimum: 1 }))
+    page!: number;
+
+    @Field(t.integer({ minimum: 1 }))
+    pageSize!: number;
+
+    @Field(t.integer({ minimum: 1 }))
+    totalPages!: number;
+
+    @Field(t.boolean())
+    hasNextPage!: boolean;
+
+    @Field(t.boolean())
+    hasPrevPage!: boolean;
+  }
+
+  return PagedResponseDto;
+}

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

@@ -0,0 +1,28 @@
+import type { PaginationConfig, PaginationOptions, ParsedPagination } from "./types";
+import { coerce } from "../../core/coerce";
+
+/**
+ * Parses pagination parameters from query parameters.
+ * @param query - Query parameters
+ * @param config - Pagination configuration
+ * @returns Parsed pagination result
+ */
+export function parsePagination(
+  query: Record<string, unknown>,
+  config: PaginationConfig = {}
+): ParsedPagination {
+  const { defaultPageSize = 25, maxPageSize = 100 } = config;
+
+  const page = coerce.integer(query.page as string | number, {
+    min: 1,
+    clamp: true
+  }) ?? 1;
+
+  const pageSize = coerce.integer(query.pageSize as string | number, {
+    min: 1,
+    max: maxPageSize,
+    clamp: true
+  }) ?? defaultPageSize;
+
+  return { page, pageSize };
+}