adorn-api 1.1.11 → 1.1.13

package/src/adapter/fastify/types.ts

@@ -0,0 +1,119 @@
+import type {
+  Constructor,
+  RequestContext as CoreRequestContext,
+  UploadedFileInfo
+} from "../../core/types";
+import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+
+/**
+ * Request context provided to Fastify route handlers.
+ */
+export type RequestContext<
+  TBody = any,
+  TQuery extends object | undefined = Record<string, any>,
+  TParams extends object | undefined = Record<string, any>,
+  THeaders extends object | undefined = Record<string, any>,
+  TFiles extends Record<string, UploadedFileInfo | UploadedFileInfo[]> | undefined = any
+> = CoreRequestContext<TBody, TQuery, TParams, THeaders, TFiles>;
+
+/**
+ * Input coercion modes.
+ */
+export type InputCoercionMode = "safe" | "strict";
+
+/**
+ * Input coercion setting - can be a mode or disabled.
+ */
+export type InputCoercionSetting = InputCoercionMode | false;
+
+/**
+ * CORS configuration options.
+ */
+export interface CorsOptions {
+  /** Allowed origins. Use "*" for all, a string, array of strings, or a function for dynamic matching. */
+  origin?: string | string[] | ((origin: string | undefined) => boolean | string);
+  /** Allowed HTTP methods. Defaults to ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"]. */
+  methods?: string[];
+  /** Allowed headers. Defaults to ["Content-Type", "Authorization"]. */
+  allowedHeaders?: string[];
+  /** Headers exposed to the client. */
+  exposedHeaders?: string[];
+  /** Whether to include credentials (cookies, authorization headers). Defaults to false. */
+  credentials?: boolean;
+  /** Max age in seconds for preflight cache. Defaults to 86400 (24 hours). */
+  maxAge?: number;
+}
+
+/**
+ * Options for OpenAPI documentation UI.
+ */
+export interface OpenApiDocsOptions {
+  /** Path for documentation UI */
+  path?: string;
+  /** Title for documentation page */
+  title?: string;
+  /** URL for Swagger UI assets */
+  swaggerUiUrl?: string;
+}
+
+/**
+ * OpenAPI configuration for Fastify adapter.
+ */
+export interface OpenApiFastifyOptions {
+  /** OpenAPI document info */
+  info: OpenApiInfo;
+  /** Array of servers */
+  servers?: OpenApiServer[];
+  /** Path for OpenAPI JSON endpoint */
+  path?: string;
+  /** Whether to pretty-print the JSON output (defaults to false for minified output) */
+  prettyPrint?: boolean;
+  /** Documentation UI configuration */
+  docs?: boolean | OpenApiDocsOptions;
+}
+
+/**
+ * Multipart file upload configuration.
+ */
+export interface MultipartOptions {
+  /** Storage type: 'memory' or 'disk' (Fastify adapter mainly supports memory via @fastify/multipart) */
+  storage?: "memory" | "disk";
+  /** Directory for disk storage (defaults to OS temp directory) */
+  dest?: string;
+  /** Maximum file size in bytes (defaults to 10MB) */
+  maxFileSize?: number;
+  /** Maximum number of files per field (defaults to 10) */
+  maxFiles?: number;
+}
+
+/**
+ * Validation configuration options.
+ */
+export interface ValidationOptions {
+  /** Whether validation is enabled. Defaults to true. */
+  enabled?: boolean;
+  /** Validation mode. 'strict' mode fails on any validation error, 'lax' mode may allow some errors. Defaults to 'strict'. */
+  mode?: 'strict' | 'lax';
+}
+
+/**
+ * Options for creating a Fastify application adapter.
+ */
+export interface FastifyAdapterOptions {
+  /** Array of controller classes */
+  controllers: Constructor[];
+  /** Whether to enable JSON body parsing */
+  jsonBody?: boolean;
+  /** Max JSON body size (e.g. 1048576 for 1MB). */
+  bodyLimit?: number;
+  /** OpenAPI configuration */
+  openApi?: OpenApiFastifyOptions;
+  /** Input coercion setting */
+  inputCoercion?: InputCoercionSetting;
+  /** CORS configuration. Set to true for permissive defaults, or provide options. */
+  cors?: boolean | CorsOptions;
+  /** Multipart file upload configuration. Set to true for defaults, or provide options. */
+  multipart?: boolean | MultipartOptions;
+  /** Validation configuration. Set to false to disable validation, or provide options. */
+  validation?: boolean | ValidationOptions;
+}

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

@@ -78,6 +78,7 @@ export type {
   PaginationConfig,
   PaginationOptions,
   ParsedPagination,
+  PaginationQueryParams,
   Filter,
   FilterMapping,
   FilterFieldMapping,
@@ -89,6 +90,8 @@ export type {
   ParseSortOptions,
   ParsedSort,
   SortDirection,
+  SortingQueryParams,
+  PagedQueryParams,
   CrudListSortTerm,
   RunPagedListOptions,
   ExecuteCrudListOptions,

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

@@ -74,6 +74,16 @@ export interface ParsedPagination {
   pageSize: number;
 }
 
+/**
+ * Pagination query params for consumer-side TypeScript interfaces.
+ */
+export interface PaginationQueryParams {
+  /** Page number */
+  page?: number;
+  /** Page size */
+  pageSize?: number;
+}
+
 /**
  * Filter field mapping.
  */
@@ -155,6 +165,21 @@ export interface ParseFilterOptions<T = Record<string, unknown>> {
  */
 export type SortDirection = "asc" | "desc";
 
+/**
+ * Sorting query params for consumer-side TypeScript interfaces.
+ */
+export interface SortingQueryParams {
+  /** Requested sort key */
+  sortBy?: string;
+  /** Sort direction */
+  sortDirection?: SortDirection;
+}
+
+/**
+ * Combined pagination + sorting query params.
+ */
+export interface PagedQueryParams extends PaginationQueryParams, SortingQueryParams {}
+
 /**
  * Sort parsing options.
  */

package/src/adapter/native/coercion.ts

@@ -0,0 +1,369 @@
+import { getDtoMeta, type InputMeta } from "../../core/metadata";
+import type {
+  SchemaNode,
+  SchemaSource,
+  StringSchema,
+  ArraySchema,
+  NumberSchema,
+  ObjectSchema,
+  RecordSchema,
+  RefSchema,
+  UnionSchema
+} from "../../core/schema";
+import { coerce } from "../../core/coerce";
+import { HttpError } from "../../core/errors";
+import type { InputCoercionMode } from "./types";
+import type { DtoConstructor } from "../../core/types";
+
+export type InputLocation = "params" | "query" | "body";
+
+interface CoerceInputOptions {
+  mode: InputCoercionMode;
+  location: InputLocation;
+}
+
+interface CoerceField {
+  name: string;
+  schema: SchemaNode;
+}
+
+interface CoerceResult {
+  value: unknown;
+  invalidFields: string[];
+}
+
+interface CoerceOutcome {
+  value: unknown;
+  ok: boolean;
+  changed: boolean;
+}
+
+/**
+ * Creates an input coercer function for the given input metadata.
+ */
+export function createInputCoercer<T extends Record<string, unknown> = Record<string, unknown>>(
+  input: InputMeta | undefined,
+  options: CoerceInputOptions
+): ((value: T) => T) | undefined {
+  if (!input) {
+    return undefined;
+  }
+  const fields = extractFields(input.schema);
+  if (!fields.length) {
+    return undefined;
+  }
+  return (value: T): T => {
+    const result = coerceRecord(value, fields, options.mode);
+    if (options.mode === "strict" && result.invalidFields.length) {
+      throw new HttpError(400, buildInvalidMessage(options.location, result.invalidFields));
+    }
+    return result.value as T;
+  };
+}
+
+function coerceRecord(
+  value: unknown,
+  fields: CoerceField[],
+  mode: InputCoercionMode
+): CoerceResult {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { value, invalidFields: [] };
+  }
+  const input = value as Record<string, unknown>;
+  let changed = false;
+  const output: Record<string, unknown> = { ...input };
+  const invalidFields: string[] = [];
+  for (const field of fields) {
+    if (!(field.name in input)) {
+      continue;
+    }
+    const original = input[field.name];
+    const result = coerceValue(original, field.schema, mode);
+    if (!result.ok && mode === "strict") {
+      invalidFields.push(field.name);
+    }
+    if (result.changed) {
+      output[field.name] = result.value;
+      changed = true;
+    }
+  }
+  return { value: changed ? output : value, invalidFields };
+}
+
+function coerceValue(
+  value: unknown,
+  schema: SchemaNode,
+  mode: InputCoercionMode
+): CoerceOutcome {
+  switch (schema.kind) {
+    case "integer":
+      return coerceNumber(value, schema, true);
+    case "number":
+      return coerceNumber(value, schema, false);
+    case "boolean": {
+      return coerceBoolean(value);
+    }
+    case "string": {
+      return coerceString(value, schema);
+    }
+    case "array":
+      return coerceArrayValue(value, schema, mode);
+    case "object":
+      return coerceObjectValue(value, schema, mode);
+    case "record":
+      return coerceRecordValue(value, schema, mode);
+    case "ref":
+      return coerceRefValue(value, schema, mode);
+    case "union":
+      return coerceUnionValue(value, schema, mode);
+    default:
+      return { value, ok: true, changed: false };
+  }
+}
+
+function coerceNumber(value: unknown, schema: NumberSchema, integer: boolean): CoerceOutcome {
+  if (!isPresent(value)) {
+    return { value, ok: true, changed: false };
+  }
+  const parsed = integer
+    ? coerce.integer(value, { min: schema.minimum, max: schema.maximum })
+    : coerce.number(value, { min: schema.minimum, max: schema.maximum });
+  if (parsed === undefined) {
+    return { value, ok: false, changed: false };
+  }
+  if (schema.exclusiveMinimum !== undefined && parsed <= schema.exclusiveMinimum) {
+    return { value, ok: false, changed: false };
+  }
+  if (schema.exclusiveMaximum !== undefined && parsed >= schema.exclusiveMaximum) {
+    return { value, ok: false, changed: false };
+  }
+  return { value: parsed, ok: true, changed: parsed !== value };
+}
+
+function coerceBoolean(value: unknown): CoerceOutcome {
+  if (!isPresent(value)) {
+    return { value, ok: true, changed: false };
+  }
+  const parsed = coerce.boolean(value);
+  if (parsed === undefined) {
+    return { value, ok: false, changed: false };
+  }
+  return { value: parsed, ok: true, changed: parsed !== value };
+}
+
+function coerceString(value: unknown, schema: StringSchema): CoerceOutcome {
+  if (!isPresent(value)) {
+    return { value, ok: true, changed: false };
+  }
+  if (schema.format === "date" || schema.format === "date-time") {
+    const parsed = parseDateValue(value);
+    if (!parsed) {
+      return { value, ok: false, changed: false };
+    }
+    return { value: parsed, ok: true, changed: parsed !== value };
+  }
+  const parsed = coerce.string(value);
+  if (parsed === undefined) {
+    return { value, ok: true, changed: false };
+  }
+  return { value: parsed, ok: true, changed: parsed !== value };
+}
+
+function parseDateValue(value: unknown): Date | undefined {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? undefined : value;
+  }
+  const text = coerce.string(value);
+  if (text === undefined) {
+    return undefined;
+  }
+  const parsed = new Date(text);
+  if (Number.isNaN(parsed.getTime())) {
+    return undefined;
+  }
+  return parsed;
+}
+
+function coerceArrayValue(
+  value: unknown,
+  schema: ArraySchema,
+  mode: InputCoercionMode
+): CoerceOutcome {
+  if (value === undefined || value === null) {
+    return { value, ok: true, changed: false };
+  }
+  let input: unknown[];
+  let changed: boolean;
+  if (Array.isArray(value)) {
+    input = value;
+    changed = false;
+  } else if (typeof value === "string" && value.includes(",")) {
+    input = value.split(",").map((s) => s.trim());
+    changed = true;
+  } else {
+    input = [value];
+    changed = true;
+  }
+  let ok = true;
+  const output = input.map((entry) => {
+    const result = coerceValue(entry, schema.items, mode);
+    if (!result.ok) {
+      ok = false;
+    }
+    if (result.changed) {
+      changed = true;
+    }
+    return result.value;
+  });
+  return { value: changed ? output : value, ok, changed };
+}
+
+function coerceObjectValue(
+  value: unknown,
+  schema: ObjectSchema,
+  mode: InputCoercionMode
+): CoerceOutcome {
+  if (value === undefined || value === null) {
+    return { value, ok: true, changed: false };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return { value, ok: mode === "safe", changed: false };
+  }
+  const properties = schema.properties ?? {};
+  const fields = Object.entries(properties).map(([name, fieldSchema]) => ({
+    name,
+    schema: fieldSchema
+  }));
+  if (!fields.length) {
+    return { value, ok: true, changed: false };
+  }
+  const result = coerceRecord(value, fields, mode);
+  return {
+    value: result.value,
+    ok: result.invalidFields.length === 0,
+    changed: result.value !== value
+  };
+}
+
+function coerceRecordValue(
+  value: unknown,
+  schema: RecordSchema,
+  mode: InputCoercionMode
+): CoerceOutcome {
+  if (value === undefined || value === null) {
+    return { value, ok: true, changed: false };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return { value, ok: mode === "safe", changed: false };
+  }
+  const input = value as Record<string, unknown>;
+  let changed = false;
+  let ok = true;
+  const output: Record<string, unknown> = { ...input };
+  for (const [key, entry] of Object.entries(input)) {
+    const result = coerceValue(entry, schema.values, mode);
+    if (!result.ok) {
+      ok = false;
+    }
+    if (result.changed) {
+      output[key] = result.value;
+      changed = true;
+    }
+  }
+  return { value: changed ? output : value, ok, changed };
+}
+
+function coerceRefValue(
+  value: unknown,
+  schema: RefSchema,
+  mode: InputCoercionMode
+): CoerceOutcome {
+  if (value === undefined || value === null) {
+    return { value, ok: true, changed: false };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return { value, ok: mode === "safe", changed: false };
+  }
+  const meta = getDtoMetaSafe(schema.dto);
+  const fields = Object.entries(meta.fields).map(([name, field]) => ({
+    name,
+    schema: field.schema
+  }));
+  if (!fields.length) {
+    return { value, ok: true, changed: false };
+  }
+  const result = coerceRecord(value, fields, mode);
+  return {
+    value: result.value,
+    ok: result.invalidFields.length === 0,
+    changed: result.value !== value
+  };
+}
+
+function coerceUnionValue(
+  value: unknown,
+  schema: UnionSchema,
+  mode: InputCoercionMode
+): CoerceOutcome {
+  let fallback: CoerceOutcome | undefined;
+  for (const option of schema.anyOf) {
+    const result = coerceValue(value, option, mode);
+    if (!result.ok) {
+      continue;
+    }
+    if (result.changed) {
+      return result;
+    }
+    fallback ??= result;
+  }
+  if (fallback) {
+    return fallback;
+  }
+  return { value, ok: mode === "safe", changed: false };
+}
+
+function extractFields(schema: SchemaSource): CoerceField[] {
+  if (isSchemaNode(schema)) {
+    if (schema.kind === "object" && schema.properties) {
+      return Object.entries(schema.properties).map(([name, fieldSchema]) => ({
+        name,
+        schema: fieldSchema
+      }));
+    }
+    return [];
+  }
+  const meta = getDtoMetaSafe(schema);
+  return Object.entries(meta.fields).map(([name, field]) => ({
+    name,
+    schema: field.schema
+  }));
+}
+
+function getDtoMetaSafe(dto: DtoConstructor): {
+  fields: Record<string, { schema: SchemaNode }>;
+} {
+  const meta = getDtoMeta(dto);
+  if (!meta) {
+    throw new Error(`DTO "${dto.name}" is missing @Dto decorator.`);
+  }
+  return meta;
+}
+
+function isSchemaNode(value: unknown): value is SchemaNode {
+  return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
+}
+
+function isPresent(value: unknown): boolean {
+  return coerce.string(value) !== undefined;
+}
+
+function buildInvalidMessage(location: InputLocation, fields: string[]): string {
+  let label = "query parameter";
+  if (location === "params") {
+    label = "path parameter";
+  } else if (location === "body") {
+    label = "request body field";
+  }
+  const suffix = fields.length > 1 ? "s" : "";
+  return `Invalid ${label}${suffix}: ${fields.join(", ")}.`;
+}