adorn-api 1.0.31 → 1.0.32

package/README.md

@@ -9,10 +9,11 @@ A modern, decorator-first web framework built on Express with built-in OpenAPI 3
 - 🔌 **Express Integration**: Built on top of Express for familiarity and extensibility
 - 🎯 **Type-Safe Data Transfer Objects**: Define schemas with TypeScript for compile-time checks
 - 🔄 **DTO Composition**: Reuse and compose DTOs with PickDto, OmitDto, PartialDto, and MergeDto
-- 📦 **Metal ORM Integration**: First-class support for Metal ORM with auto-generated CRUD DTOs
+- 📦 **Metal ORM Integration**: First-class support for Metal ORM with auto-generated CRUD DTOs, including transformer-aware schema generation
 - 🚀 **Streaming Support**: Server-Sent Events (SSE) and streaming responses
 - 📝 **Request Validation**: Automatic validation of request bodies, params, query, and headers
-- 🔒 **Error Handling**: Structured error responses with error DTO support
+- 🔧 **Transformers**: Custom field transformations with @Transform decorator and built-in transform functions
+-  **Error Handling**: Structured error responses with error DTO support
 - 💾 **File Uploads**: Easy handling of file uploads with multipart form data
 - 🌐 **CORS Support**: Built-in CORS configuration
 - 🏗️ **Lifecycle Hooks**: Application bootstrap and shutdown lifecycle events
@@ -262,7 +263,8 @@ class UploadController {
 
 ## Metal ORM Integration
 
-Adorn API has first-class support for Metal ORM, providing automatic CRUD DTO generation.
+Adorn API has first-class support for Metal ORM, providing automatic CRUD DTO generation.
+Transformer decorators such as `@Email`, `@Length`, `@Pattern`, and `@Alphanumeric` are reflected in the generated DTO schemas (validation + OpenAPI).
 
 ### 1. Define Entities
 
@@ -384,6 +386,10 @@ createExpressApp({
   cors: true, // Enable CORS with default options or configure
   jsonBody: true, // Parse JSON bodies (default: true)
   inputCoercion: "safe", // Input coercion mode ("safe" or "strict")
+  validation: { // Validation configuration
+    enabled: true, // Enable validation (default: true)
+    mode: "strict" // Validation mode: "strict" or "safe"
+  },
   multipart: { // File upload configuration
     dest: "./uploads",
     limits: { fileSize: 50 * 1024 * 1024 }
@@ -483,6 +489,234 @@ import { lifecycleRegistry } from "adorn-api";
 lifecycleRegistry.register(new DatabaseService());
 ```
 
+## Validation
+
+Adorn API provides automatic request validation and a comprehensive validation system for your DTOs and schemas.
+
+### Validation Configuration
+
+```typescript
+createExpressApp({
+  controllers: [UserController],
+  validation: {
+    enabled: true, // Enable validation (default: true)
+    mode: "strict" // Validation mode: "strict" or "safe"
+  }
+});
+```
+
+### Validation Errors
+
+Invalid requests automatically return structured validation errors:
+
+```typescript
+// Example error response
+{
+  "statusCode": 400,
+  "message": "Validation failed",
+  "errors": [
+    {
+      "field": "name",
+      "message": "must be at least 1 character long",
+      "value": "",
+      "code": "STRING_MIN_LENGTH"
+    },
+    {
+      "field": "email",
+      "message": "must be a valid email",
+      "value": "invalid-email",
+      "code": "FORMAT_EMAIL"
+    }
+  ]
+}
+```
+
+### Validation Error Codes
+
+Adorn API provides machine-readable error codes for programmatic error handling:
+
+```typescript
+import { ValidationErrorCode } from "adorn-api";
+
+console.log(ValidationErrorCode.FORMAT_EMAIL); // "FORMAT_EMAIL"
+console.log(ValidationErrorCode.STRING_MIN_LENGTH); // "STRING_MIN_LENGTH"
+```
+
+### Manual Validation
+
+You can also manually validate data using the `validate` function:
+
+```typescript
+import { validate, ValidationErrors, t } from "adorn-api";
+
+const data = { name: "", email: "invalid" };
+const errors = validate(data, t.object({
+  name: t.string({ minLength: 1 }),
+  email: t.string({ format: "email" })
+}));
+
+if (errors.length > 0) {
+  throw new ValidationErrors(errors);
+}
+```
+
+## Transformers
+
+Transform fields during serialization with custom transform functions or built-in transform utilities.
+
+### Basic Transform
+
+```typescript
+import { Dto, Field, Transform, t } from "adorn-api";
+
+@Dto()
+export class UserDto {
+  @Field(t.string())
+  @Transform((value) => value.toUpperCase())
+  name!: string;
+
+  @Field(t.dateTime())
+  @Transform((value) => value.toISOString())
+  createdAt!: Date;
+}
+```
+
+### Built-in Transforms
+
+Adorn API includes common transform functions:
+
+```typescript
+import { Dto, Field, Transform, Transforms, t } from "adorn-api";
+
+@Dto()
+export class UserDto {
+  @Field(t.string())
+  @Transform(Transforms.toLowerCase)
+  email!: string;
+
+  @Field(t.number())
+  @Transform(Transforms.round(2))
+  price!: number;
+
+  @Field(t.string())
+  @Transform(Transforms.mask(4)) // Mask all but last 4 characters
+  creditCard!: string;
+
+  @Field(t.dateTime())
+  @Transform(Transforms.toISOString)
+  birthDate!: Date;
+}
+```
+
+### Conditional Transforms with Groups
+
+Apply transforms only to specific serialization groups:
+
+```typescript
+import { Dto, Field, Transform, Expose, t } from "adorn-api";
+
+@Dto()
+export class UserDto {
+  @Field(t.string())
+  name!: string;
+
+  @Field(t.string())
+  @Expose({ groups: ["admin"] })
+  @Transform((value) => Transforms.mask(2), { groups: ["admin"] })
+  phoneNumber!: string;
+
+  @Field(t.string())
+  @Expose({ groups: ["internal"] })
+  @Transform((value) => "[REDACTED]", { groups: ["external"] })
+  internalNote!: string;
+}
+```
+
+### Custom Transform Functions
+
+Create custom transform functions:
+
+```typescript
+import { Dto, Field, Transform, t } from "adorn-api";
+
+const toCurrency = (value: number, currency: string = "USD") => {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency
+  }).format(value);
+};
+
+@Dto()
+export class ProductDto {
+  @Field(t.string())
+  name!: string;
+
+  @Field(t.number())
+  @Transform(toCurrency)
+  price!: number;
+
+  @Field(t.number())
+  @Transform((value) => toCurrency(value, "EUR"))
+  priceEUR!: number;
+}
+```
+
+### Serialization with Options
+
+Control serialization with custom options:
+
+```typescript
+import { serialize, createSerializer } from "adorn-api";
+import { UserDto } from "./user.dtos";
+
+const user = new UserDto();
+user.name = "John Doe";
+user.phoneNumber = "123-456-7890";
+user.internalNote = "This is an internal note";
+
+// Basic serialization
+const basic = serialize(user);
+// Output: { name: "John Doe" }
+
+// Admin group serialization
+const admin = serialize(user, { groups: ["admin"] });
+// Output: { name: "John Doe", phoneNumber: "********90" }
+
+// External group serialization
+const external = serialize(user, { groups: ["external"] });
+// Output: { name: "John Doe", internalNote: "[REDACTED]" }
+
+// Create a preset serializer
+const adminSerializer = createSerializer({ groups: ["admin"] });
+const adminData = adminSerializer(user);
+```
+
+### Exclude Fields
+
+Control which fields are excluded or exposed:
+
+```typescript
+import { Dto, Field, Exclude, Expose, t } from "adorn-api";
+
+@Dto()
+export class UserDto {
+  @Field(t.string())
+  name!: string;
+
+  @Field(t.string())
+  @Exclude() // Always exclude from serialization
+  password!: string;
+
+  @Field(t.string())
+  @Expose({ name: "email_address" }) // Rename field in output
+  email!: string;
+
+  @Field(t.string())
+  @Exclude({ groups: ["public"] }) // Exclude from public group
+  internalComment!: string;
+}
+```
+
 ## Examples
 
 Check out the `examples/` directory for more comprehensive examples:
@@ -493,6 +727,7 @@ Check out the `examples/` directory for more comprehensive examples:
 - `metal-orm-sqlite-music/` - Complex relations with Metal ORM
 - `streaming/` - SSE and streaming responses
 - `openapi/` - OpenAPI documentation customization
+- `validation/` - Comprehensive validation examples with various schema types
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "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.0.91"
+    "metal-orm": "^1.0.94"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",

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

@@ -1,10 +1,12 @@
-import type { ColumnDef } from "metal-orm";
 import {
   columnTypeToOpenApiFormat,
   columnTypeToOpenApiType,
-  getColumnMap
+  getColumnMap,
+  getDecoratorMetadata,
+  type ColumnDef,
+  type TransformerMetadata
 } from "metal-orm";
-import type { SchemaNode } from "../../core/schema";
+import type { SchemaNode, StringSchema } from "../../core/schema";
 import { t } from "../../core/schema";
 import type { FieldMeta } from "../../core/metadata";
 import type { FieldOverride } from "../../core/decorators";
@@ -46,6 +48,7 @@ export function buildFields(
   const include = options.include ? new Set(options.include) : undefined;
   const exclude = options.exclude ? new Set(options.exclude) : undefined;
   const mode = options.mode ?? "response";
+  const transformerMetadata = getTransformerMetadata(target);
   const fields: Record<string, FieldMeta> = {};
 
   for (const [name, col] of Object.entries(columns)) {
@@ -59,7 +62,7 @@ export function buildFields(
       continue;
     }
 
-    fields[name] = buildFieldMeta(col, mode);
+    fields[name] = buildFieldMeta(col, mode, transformerMetadata?.[name]);
   }
 
   if (options.overrides) {
@@ -69,11 +72,16 @@ export function buildFields(
   return fields;
 }
 
-export function buildFieldMeta(col: any, mode: MetalDtoMode): FieldMeta {
+export function buildFieldMeta(
+  col: any,
+  mode: MetalDtoMode,
+  transformer?: TransformerMetadata
+): FieldMeta {
   let schema = columnToSchemaNode(col);
   if (!col.notNull) {
     schema = t.nullable(schema);
   }
+  schema = applyTransformerMetadata(schema, transformer, mode);
 
   const optional = isOptional(col, mode);
   const field: FieldMeta = { schema };
@@ -206,6 +214,141 @@ function isSchemaNode(value: unknown): value is SchemaNode {
   return !!value && typeof value === "object" && "kind" in (value as SchemaNode);
 }
 
+function getTransformerMetadata(
+  target: any
+): Record<string, TransformerMetadata> | undefined {
+  if (typeof target !== "function") {
+    return undefined;
+  }
+  const meta = getDecoratorMetadata(target);
+  if (!meta?.transformers?.length) {
+    return undefined;
+  }
+  const output: Record<string, TransformerMetadata> = {};
+  for (const entry of meta.transformers) {
+    output[entry.propertyName] = entry.metadata;
+  }
+  return output;
+}
+
+function applyTransformerMetadata(
+  schema: SchemaNode,
+  transformer: TransformerMetadata | undefined,
+  mode: MetalDtoMode
+): SchemaNode {
+  if (!transformer || !shouldApplyTransformers(transformer, mode)) {
+    return schema;
+  }
+  if (schema.kind !== "string") {
+    return schema;
+  }
+  const stringSchema = schema as StringSchema;
+  for (const validator of transformer.validators ?? []) {
+    applyStringValidator(stringSchema, validator);
+  }
+  return stringSchema;
+}
+
+function shouldApplyTransformers(
+  transformer: TransformerMetadata,
+  mode: MetalDtoMode
+): boolean {
+  if (transformer.executionOrder === "both") {
+    return true;
+  }
+  if (mode === "response") {
+    return transformer.executionOrder === "after-load";
+  }
+  return transformer.executionOrder === "before-save";
+}
+
+function applyStringValidator(
+  schema: StringSchema,
+  validator: { name?: string }
+): void {
+  const name = validator.name?.toLowerCase();
+  switch (name) {
+    case "email":
+      if (!schema.format || schema.format === "email") {
+        schema.format = "email";
+      }
+      break;
+    case "length":
+      applyLengthValidator(schema, validator);
+      break;
+    case "pattern":
+      applyPatternValidator(schema, validator);
+      break;
+    case "alphanumeric":
+      applyAlphanumericValidator(schema, validator);
+      break;
+    default:
+      break;
+  }
+}
+
+function applyLengthValidator(
+  schema: StringSchema,
+  validator: { [key: string]: unknown }
+): void {
+  const options = (validator as { options?: { min?: number; max?: number; exact?: number } }).options;
+  if (!options) {
+    return;
+  }
+  if (typeof options.exact === "number") {
+    schema.minLength = options.exact;
+    schema.maxLength = options.exact;
+    return;
+  }
+  if (typeof options.min === "number") {
+    schema.minLength = schema.minLength !== undefined
+      ? Math.max(schema.minLength, options.min)
+      : options.min;
+  }
+  if (typeof options.max === "number") {
+    schema.maxLength = schema.maxLength !== undefined
+      ? Math.min(schema.maxLength, options.max)
+      : options.max;
+  }
+}
+
+function applyPatternValidator(
+  schema: StringSchema,
+  validator: { [key: string]: unknown }
+): void {
+  if (schema.pattern) {
+    return;
+  }
+  const options = (validator as { options?: { pattern?: RegExp } }).options;
+  if (!options?.pattern) {
+    return;
+  }
+  schema.pattern = options.pattern.source;
+}
+
+function applyAlphanumericValidator(
+  schema: StringSchema,
+  validator: { [key: string]: unknown }
+): void {
+  if (schema.pattern) {
+    return;
+  }
+  const options = (validator as {
+    options?: { allowSpaces?: boolean; allowUnderscores?: boolean; allowHyphens?: boolean }
+  }).options;
+  const extras: string[] = [];
+  if (options?.allowSpaces) {
+    extras.push(" ");
+  }
+  if (options?.allowUnderscores) {
+    extras.push("_");
+  }
+  if (options?.allowHyphens) {
+    extras.push("-");
+  }
+  schema.pattern = `^[a-zA-Z0-9${extras.join("")}]*$`;
+}
+
 /**
  * Validates that an entity has properly loaded metadata (columns).
  * Throws an error with helpful message if validation fails.

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

@@ -1,3 +1,9 @@
+// Ensure standard decorator metadata is available for metal-orm transformers.
+const symbolMetadata = (Symbol as { metadata?: symbol }).metadata;
+if (!symbolMetadata) {
+  (Symbol as { metadata?: symbol }).metadata = Symbol("Symbol.metadata");
+}
+
 export {
   MetalDto
 } from "./dto";

package/tests/unit/metal-orm.test.ts

@@ -12,7 +12,7 @@ import {
   createMetalDtoOverrides
 } from "../../src/adapter/metal-orm/index";
 import { HttpError } from "../../src/core/errors";
-import { Column, Entity, PrimaryKey, col } from "metal-orm";
+import { Alphanumeric, Column, Email, Entity, Length, Pattern, PrimaryKey, col } from "metal-orm";
 import { getDtoMeta } from "../../src/core/metadata";
 
 describe("metal-orm helpers", () => {
@@ -240,20 +240,20 @@ describe("metal-orm helpers", () => {
     });
   });
 
-  describe("createMetalCrudDtos", () => {
-    @Entity({ tableName: "crud_dto_entities" })
-    class CrudDtoEntity {
-      @PrimaryKey(col.autoIncrement(col.int()))
+  describe("createMetalCrudDtos", () => {
+    @Entity({ tableName: "crud_dto_entities" })
+    class CrudDtoEntity {
+      @PrimaryKey(col.autoIncrement(col.int()))
       id!: number;
 
       @Column(col.notNull(col.text()))
       name!: string;
 
       @Column(col.text())
-      nickname?: string | null;
-    }
-
-    it("creates CRUD DTO decorators with defaults", () => {
+      nickname?: string | null;
+    }
+
+    it("creates CRUD DTO decorators with defaults", () => {
       const crud = createMetalCrudDtos(CrudDtoEntity, {
         mutationExclude: ["id"]
       });
@@ -277,10 +277,46 @@ describe("metal-orm helpers", () => {
 
       expect(responseMeta?.fields.id).toBeDefined();
       expect(createMeta?.fields.id).toBeUndefined();
-      expect(updateMeta?.fields.name?.optional).toBe(true);
-      expect(Object.keys(paramsMeta?.fields ?? {})).toEqual(["id"]);
-    });
-  });
+      expect(updateMeta?.fields.name?.optional).toBe(true);
+      expect(Object.keys(paramsMeta?.fields ?? {})).toEqual(["id"]);
+    });
+
+    @Entity({ tableName: "transformer_entities" })
+    class TransformerEntity {
+      @PrimaryKey(col.autoIncrement(col.int()))
+      id!: number;
+
+      @Column(col.varchar(50))
+      @Length({ min: 2, max: 10 })
+      name!: string;
+
+      @Column(col.text())
+      @Pattern({ pattern: /^[A-Z]+$/ })
+      code!: string;
+
+      @Column(col.text())
+      @Email()
+      email!: string;
+
+      @Column(col.text())
+      @Alphanumeric({ allowHyphens: true })
+      slug!: string;
+    }
+
+    it("maps transformer validators into string schemas", () => {
+      const crud = createMetalCrudDtos(TransformerEntity);
+
+      @crud.create
+      class CreateTransformerDto {}
+
+      const meta = getDtoMeta(CreateTransformerDto);
+      expect((meta?.fields.email?.schema as any).format).toBe("email");
+      expect((meta?.fields.name?.schema as any).minLength).toBe(2);
+      expect((meta?.fields.name?.schema as any).maxLength).toBe(10);
+      expect((meta?.fields.code?.schema as any).pattern).toBe("^[A-Z]+$");
+      expect((meta?.fields.slug?.schema as any).pattern).toBe("^[a-zA-Z0-9-]*$");
+    });
+  });
 
   describe("createMetalCrudDtoClasses", () => {
     @Entity({ tableName: "crud_dto_class_entities" })