adorn-api 1.0.31 → 1.0.33

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/dist/adapter/express/coercion.d.ts

@@ -1,6 +1,6 @@
 import { type InputMeta } from "../../core/metadata";
 import type { InputCoercionMode } from "./types";
-export type InputLocation = "params" | "query";
+export type InputLocation = "params" | "query" | "body";
 interface CoerceInputOptions {
     mode: InputCoercionMode;
     location: InputLocation;

package/dist/adapter/express/coercion.js

@@ -57,7 +57,7 @@ function coerceValue(value, schema, mode) {
             return coerceBoolean(value);
         }
         case "string": {
-            return coerceString(value);
+            return coerceString(value, schema);
         }
         case "array":
             return coerceArrayValue(value, schema, mode);
@@ -101,13 +101,37 @@ function coerceBoolean(value) {
     }
     return { value: parsed, ok: true, changed: parsed !== value };
 }
-function coerceString(value) {
+function coerceString(value, schema) {
+    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_1.coerce.string(value);
     if (parsed === undefined) {
         return { value, ok: true, changed: false };
     }
     return { value: parsed, ok: true, changed: parsed !== value };
 }
+function parseDateValue(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    }
+    const text = coerce_1.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, schema, mode) {
     if (value === undefined || value === null) {
         return { value, ok: true, changed: false };
@@ -241,7 +265,13 @@ function isPresent(value) {
     return coerce_1.coerce.string(value) !== undefined;
 }
 function buildInvalidMessage(location, fields) {
-    const label = location === "params" ? "path parameter" : "query parameter";
+    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(", ")}.`;
 }

package/dist/adapter/express/controllers.js

@@ -4,6 +4,7 @@ exports.attachControllers = attachControllers;
 const metadata_1 = require("../../core/metadata");
 const errors_1 = require("../../core/errors");
 const coercion_1 = require("./coercion");
+const response_serializer_1 = require("./response-serializer");
 const multipart_1 = require("./multipart");
 const lifecycle_1 = require("../../core/lifecycle");
 const streaming_1 = require("../../core/streaming");
@@ -38,6 +39,9 @@ async function attachControllers(app, controllers, inputCoercion = "safe", multi
             const coerceQuery = inputCoercion === false
                 ? undefined
                 : (0, coercion_1.createInputCoercer)(route.query, { mode: inputCoercion, location: "query" });
+            const coerceBody = inputCoercion === false
+                ? undefined
+                : (0, coercion_1.createInputCoercer)(route.body, { mode: inputCoercion, location: "body" });
             // Build middleware chain
             const middlewares = [];
             // Add multipart middleware if route has file uploads
@@ -54,7 +58,7 @@ async function attachControllers(app, controllers, inputCoercion = "safe", multi
                     const ctx = {
                         req,
                         res,
-                        body: req.body,
+                        body: coerceBody ? coerceBody(req.body) : req.body,
                         query: coerceQuery ? coerceQuery(req.query) : req.query,
                         params: coerceParams ? coerceParams(req.params) : req.params,
                         headers: req.headers,
@@ -94,7 +98,9 @@ async function attachControllers(app, controllers, inputCoercion = "safe", multi
                         res.status(defaultStatus(route)).end();
                         return;
                     }
-                    res.status(defaultStatus(route)).json(result);
+                    const responseSchema = getResponseSchema(route);
+                    const output = responseSchema ? (0, response_serializer_1.serializeResponse)(result, responseSchema) : result;
+                    res.status(defaultStatus(route)).json(output);
                 }
                 catch (error) {
                     if ((0, validation_errors_1.isValidationErrors)(error)) {
@@ -118,6 +124,11 @@ function defaultStatus(route) {
     const success = responses.find((response) => !response.error && response.status < 400);
     return success?.status ?? 200;
 }
+function getResponseSchema(route) {
+    const responses = route.responses ?? [];
+    const success = responses.find((response) => !response.error && response.status < 400);
+    return success?.schema;
+}
 function sendValidationError(res, error) {
     if (res.headersSent) {
         return;

package/dist/adapter/express/response-serializer.d.ts

@@ -0,0 +1,2 @@
+import type { SchemaSource } from "../../core/schema";
+export declare function serializeResponse(value: unknown, schema: SchemaSource): unknown;

package/dist/adapter/express/response-serializer.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeResponse = serializeResponse;
+const metadata_1 = require("../../core/metadata");
+function serializeResponse(value, schema) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (isSchemaNode(schema)) {
+        return serializeWithSchema(value, schema);
+    }
+    return serializeWithDto(value, schema);
+}
+function serializeWithDto(value, dto) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => serializeWithDto(entry, dto));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const meta = (0, metadata_1.getDtoMeta)(dto);
+    if (!meta) {
+        return value;
+    }
+    const output = { ...value };
+    for (const [name, field] of Object.entries(meta.fields)) {
+        if (name in value) {
+            output[name] = serializeWithSchema(value[name], field.schema);
+        }
+    }
+    return output;
+}
+function serializeWithSchema(value, schema) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    switch (schema.kind) {
+        case "string":
+            return serializeString(value, schema.format);
+        case "array":
+            if (!Array.isArray(value)) {
+                return value;
+            }
+            return value.map((entry) => serializeWithSchema(entry, schema.items));
+        case "object":
+            return serializeObject(value, schema.properties);
+        case "record":
+            if (!isPlainObject(value)) {
+                return value;
+            }
+            return serializeRecord(value, schema.values);
+        case "ref":
+            return serializeWithDto(value, schema.dto);
+        case "union":
+            return serializeUnion(value, schema.anyOf);
+        default:
+            return value;
+    }
+}
+function serializeString(value, format) {
+    if (!(value instanceof Date)) {
+        return value;
+    }
+    if (Number.isNaN(value.getTime())) {
+        return value;
+    }
+    if (format === "date") {
+        return value.toISOString().slice(0, 10);
+    }
+    if (format === "date-time") {
+        return value.toISOString();
+    }
+    return value;
+}
+function serializeObject(value, properties) {
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const output = { ...value };
+    if (!properties) {
+        return output;
+    }
+    for (const [key, schema] of Object.entries(properties)) {
+        if (key in value) {
+            output[key] = serializeWithSchema(value[key], schema);
+        }
+    }
+    return output;
+}
+function serializeRecord(value, schema) {
+    const output = { ...value };
+    for (const [key, entry] of Object.entries(value)) {
+        output[key] = serializeWithSchema(entry, schema);
+    }
+    return output;
+}
+function serializeUnion(value, options) {
+    for (const option of options) {
+        const serialized = serializeWithSchema(value, option);
+        if (serialized !== value) {
+            return serialized;
+        }
+    }
+    return value;
+}
+function isSchemaNode(value) {
+    return !!value && typeof value === "object" && "kind" in value;
+}
+function isPlainObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}

package/dist/adapter/metal-orm/field-builder.d.ts

@@ -1,3 +1,4 @@
+import { type TransformerMetadata } from "metal-orm";
 import type { FieldMeta } from "../../core/metadata";
 import type { FieldOverride } from "../../core/decorators";
 export type MetalDtoMode = "response" | "create" | "update";
@@ -13,7 +14,7 @@ export interface MetalDtoOptions {
     strict?: boolean;
 }
 export declare function buildFields(target: any, options: MetalDtoOptions): Record<string, FieldMeta>;
-export declare function buildFieldMeta(col: any, mode: MetalDtoMode): FieldMeta;
+export declare function buildFieldMeta(col: any, mode: MetalDtoMode, transformer?: TransformerMetadata): FieldMeta;
 /**
  * Validates that an entity has properly loaded metadata (columns).
  * Throws an error with helpful message if validation fails.