alado 2.2.0 → 2.2.2

package/README.md

@@ -1,184 +1,361 @@
-Alado is an extremely fast, simple, robust, and lightweight (no-dependency)
-for creating server applications written in Node.js and running over the HTTP protocol.
+# Alado
 
-Its main difference from most similar well-known frameworks is that with a minimum of external dependencies
-it provides out-of-the-box such fully-functioning features as routing, CORS, automatic API documentation (Open API 3.0),
-parsing query and path parameters, and the request body, file uploading, request authentication, etc.
+> A fast, lightweight, zero-dependency Node.js HTTP framework with built-in routing, validation, authentication, file uploads, and automatic OpenAPI 3.0 documentation.
 
-# Documentation for version 2.0.0 and above:
+[![npm](https://img.shields.io/npm/v/alado)](https://www.npmjs.com/package/alado)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-Version 2.0.0 comes with decorators that simplify the project structure and minimize the amount of code you need to write.
+---
+
+## Table of Contents
+
+- [Why Alado](#why-alado)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Project Structure](#project-structure)
+- [tsconfig Setup](#tsconfig-setup)
+- [Application Setup](#application-setup)
+- [Controllers](#controllers)
+  - [HTTP Method Decorators](#http-method-decorators)
+  - [defineRequest](#definerequest)
+  - [defineResponse](#defineresponse)
+  - [withAuth](#withauth)
+- [DTOs](#dtos)
+  - [validateProperty](#validateproperty)
+  - [documentProperty](#documentproperty)
+  - [transformProperty](#transformproperty)
+  - [fileUploadProperty](#fileuploadproperty)
+- [Authentication](#authentication)
+- [File Uploads](#file-uploads)
+- [OpenAPI / Swagger](#openapi--swagger)
+- [API Reference](#api-reference)
 
-There is an example of the API creating with Alado (version >= 2.0.0):
-[https://github.com/databikers/alado-decorators-api-example](https://github.com/databikers/alado-decorators-api-example)
+---
 
-## Use inside controllers the next decorators:
+## Why Alado
 
-### HTTP Method Decorators
+Alado sits in a unique position — it has the **simplicity of Express**, the **performance focus of Fastify**, and the **decorator-based structure of NestJS**, but with **zero external dependencies** and a much smaller surface area.
+
+---
+
+### Feature Comparison
+
+| Feature                     | Alado      | Express               | Fastify               | NestJS      |
+| --------------------------- | ---------- | --------------------- | --------------------- | ----------- |
+| Zero dependencies           | ✅         | ❌                    | ❌                    | ❌          |
+| Decorator-based routing     | ✅         | ❌                    | ❌                    | ✅          |
+| Built-in request validation | ✅         | ❌                    | ✅ (schemas)          | ✅ (pipes)  |
+| Built-in auth pipeline      | ✅         | ❌                    | ❌                    | ✅ (guards) |
+| Auto OpenAPI 3.0 docs       | ✅         | ❌                    | ✅ (plugin)           | ✅ (plugin) |
+| Built-in file upload        | ✅         | ❌                    | ❌                    | ❌          |
+| Built-in body parsing       | ✅         | ❌ (body-parser)      | ✅                    | ✅          |
+| Built-in CORS               | ✅         | ❌ (cors)             | ❌ (plugin)           | ✅          |
+| TypeScript-first            | ✅         | ⚠️ types via `@types` | ⚠️ types via `@types` | ✅          |
+| Learning curve              | 🟢 Low     | 🟢 Low                | 🟡 Medium             | 🔴 High     |
+| Boilerplate                 | 🟢 Minimal | 🟡 Medium             | 🟡 Medium             | 🔴 Heavy    |
+| Ecosystem / plugins         | 🟡 Small   | 🟢 Massive            | 🟢 Large              | 🟢 Large    |
+
+---
+
+## Installation
+
+```bash
+npm install alado
+```
+
+---
+
+## Quick Start
+
+A minimal API in under 30 lines:
+
+```ts
+// src/modules/user/user.controller.ts
+import { post, defineRequest, defineResponse } from 'alado';
+import { CredentialsDto } from './dto/credentials.dto';
+
+export class UserController {
+  @post('/user', { tags: ['User'] })
+  @defineResponse({
+    statusCode: 201,
+    title: 'Created',
+    headers: { 'Content-Type': 'application/json' },
+    body: { id: '123', email: 'user@example.com' },
+  })
+  @defineRequest({ body: CredentialsDto })
+  async create(req) {
+    const user = { id: '123', ...req.body };
+    return {
+      statusCode: 201,
+      headers: { 'Content-Type': 'application/json' },
+      body: user,
+    };
+  }
+}
+```
 
 ```ts
-get(path: string, options: HttpDecoratorOptions = {})
-post(path: string, options: HttpDecoratorOptions = {})
-put(path: string, options: HttpDecoratorOptions = {})
-patch(path: string, options: HttpDecoratorOptions = {})
-del(path: string, options: HttpDecoratorOptions = {})
-head(path: string, options: HttpDecoratorOptions = {})
+// src/main.ts
+import { initializeApplication } from 'alado';
+import { UserController } from './user/user.controller';
+
+const app = initializeApplication({
+  serverOptions: { port: 3000 },
+  controllers: [UserController],
+});
+
+app.start(() => console.log('Running on http://localhost:3000'));
+```
+
+---
+
+## Project Structure
+
+Possible layout for a decorator-based Alado project:
+
+```
+src/
+├── main.ts                     # App entry point
+├── config/
+│   └── server.options.ts       # AladoServerOptions
+├── auth/
+│   └── bearer.auth.ts          # RequestAuthentication config
+└── modules/
+    └── user/
+        ├── index.ts
+        ├── user.controller.ts
+        └── dto/
+            ├── credentials.dto.ts
+            ├── user.dto.ts
+            ├── user-files.dto.ts
+            └── id.dto.ts
 ```
 
-#### Arguments
+---
 
-- **path**: Route string (e.g., `/users/:id`).
-- **options**: `HttpDecoratorOptions` object, may include:
-  - `appId`: Identifier of the application instance.
-  - `title`: A descriptive name of the endpoint.
-  - `description`: Documentation text for the endpoint.
-  - `tags`: Array of tags for grouping in OpenAPI docs.
-  - `isHidden`: Boolean flag to hide the endpoint from OpenAPI output
+## tsconfig Setup
+
+Decorators require these compiler options:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "ES2017",
+    "module": "commonjs",
+    "strict": false,
+    "baseUrl": "./src",
+    "paths": {
+      "@user": ["modules/user/index.ts"],
+      "@config": ["config/index.ts"]
+    }
+  }
+}
+```
 
 ---
 
-### `defineRequest` decorator
+## Application Setup
+
+### `initializeApplication`
 
 ```ts
-defineRequest(request: Partial<Record<keyof [Request](#request), AnyClass>>)
+import { initializeApplication } from 'alado';
+import { UserController } from '@user';
+
+const app = initializeApplication({
+  serverOptions: {
+    port: 3000,
+    appId: 'my-api', // optional — used to scope multi-app setups
+    logger: {
+      log: console.log,
+      error: console.error,
+    },
+  },
+  controllers: [UserController],
+});
+
+app.start(() => console.log('Started'));
+app.stop(() => console.log('Stopped'));
 ```
 
-#### Arguments
+### Passing options to controller constructors
 
-- **request**: A partial mapping of keys from [Request](#request) to your DTO classes.
-  - Keys can include:
-    - `headers`, `query`, `path`, `body`: each a record of property definitions.
-    - `files`: mapping of [FilePropertyDefinition](#filepropertydefinition).
-    - `auth`: authentication data mapping.
-  - Each value points to a class that uses specific DTO decorators to define how that part of the request should be validated and documented.
+```ts
+initializeApplication({
+  serverOptions: { port: 3000 },
+  controllers: [
+    {
+      controller: UserController,
+      options: [{ service: UserService }], // passed to new UserController(...)
+    },
+  ],
+});
+```
 
-#### `Request`
+### HTTPS
 
 ```ts
-interface Request {
-  request: IncomingMessage;
-  ip?: string;
-  origin?: string;
-  method?: HttpMethod;
-  url?: string;
-  auth?: Record<string, any>;
-  path?: Record<string, string>;
-  headers?: IncomingHttpHeaders;
-  query?: Record<string, any>;
-  body?: Record<string, any>;
-  rawBody?: string;
-  files?: Record<string, { stream: Readable; size: number; mimetype: string }>;
-}
+import { readFileSync } from 'fs';
+
+const app = initializeApplication({
+  serverOptions: {
+    port: 443,
+    ssl: {
+      cert: readFileSync('/path/to/cert.pem'),
+      key: readFileSync('/path/to/key.pem'),
+    },
+  },
+  controllers: [UserController],
+});
 ```
 
 ---
 
-### `defineResponse` decorator
+## Controllers
+
+Controllers are plain TypeScript classes decorated with HTTP method decorators.
+
+### HTTP Method Decorators
 
 ```ts
-defineResponse(response: [Response](#response)<any>)
+import { get, post, put, patch, del, head } from 'alado';
 ```
 
-#### Arguments
+| Decorator                | Method |
+| ------------------------ | ------ |
+| `@get(path, options?)`   | GET    |
+| `@post(path, options?)`  | POST   |
+| `@put(path, options?)`   | PUT    |
+| `@patch(path, options?)` | PATCH  |
+| `@del(path, options?)`   | DELETE |
+| `@head(path, options?)`  | HEAD   |
 
-- **response**: Response schema definition, including:
-  - `title`: Short descriptive title.
-  - `description`: Explanation of the response.
-  - `statusCode`: HTTP status code.
-  - `headers`: Mapping of header names to values.
-  - `body`: Response body object (may be an instance of some DTO or class).
+**Options:**
 
-#### `Response`
+```ts
+interface HttpDecoratorOptions {
+  appId?: string; // scope to a specific app instance
+  title?: string; // endpoint name in OpenAPI
+  description?: string; // endpoint description in OpenAPI
+  tags?: string[]; // grouping tags in OpenAPI
+  isHidden?: boolean; // exclude from OpenAPI output
+}
+```
+
+**Example:**
 
 ```ts
-interface Response<T> {
-  title?: string;
-  description?: string;
-  statusCode: number;
-  headers?: Record<string, string>;
-  body?: T;
+@get('/users', { tags: ['User'], title: 'List users' })
+async list(req: Request) {
+  return {
+    statusCode: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: [],
+  };
 }
 ```
 
 ---
 
-### `withAuth` decorator
+### `defineRequest`
+
+Declares and validates the incoming request shape.
 
 ```ts
-withAuth(requestAuthentication: [RequestAuthentication](#requestauthentication))
+@defineRequest({
+  headers: AnyClass,
+  query:   AnyClass,
+  path:    AnyClass,
+  body:    AnyClass,
+  files:   AnyClass,
+  auth:    AnyClass,
+})
 ```
 
-#### Arguments
-
-- **requestAuthentication**: Defines authentication requirements, including:
-  - `inputProperty`: Field name in request used for auth input.
-  - `outputProperty`: Field name in request to store auth result.
-  - `handler`: Function to transform/verify authentication value.
-  - `handlerContext`: Optional context object passed to handler.
-  - `required`: Boolean indicating if authentication is mandatory.
-  - `error`: Error object to use when authentication fails.
+Each value is a DTO class whose properties carry `@validateProperty`, `@documentProperty`, etc.
 
-#### `RequestAuthentication`
+**Example:**
 
 ```ts
-interface RequestAuthentication {
-  inputProperty: string;
-  outputProperty: string;
-  handler: (value: any) => any | Promise<any>;
-  handlerContext?: any;
-  required: boolean;
-  error: AladoServerError;
+@post('/user', { tags: ['User'] })
+@defineRequest({ body: CredentialsDto })
+async create(req: Request) {
+  console.log(req.body); // typed, validated CredentialsDto fields
 }
 ```
 
-```typescript
-import { RequestAuthentication } from 'alado';
-import { DataStore } from '@data-store';
+---
 
-export const bearerAuth: RequestAuthentication = {
-  required: true,
-  inputProperty: 'headers.x-api-key',
-  outputProperty: 'auth.user',
-  handler(value: string) {
-    return DataStore.bearerAuth(value);
-  },
-  error: {
-    statusCode: 401,
-    message: 'Unauthorized',
-  },
-};
+### `defineResponse`
+
+Documents the expected response shape for OpenAPI output.
+
+```ts
+@defineResponse({
+  statusCode: 201,
+  title: 'Created',
+  entity: 'User',
+  description: 'User was created successfully',
+  headers: { 'Content-Type': 'application/json' },
+  body: exampleUserDto,   // an instance of your DTO class
+})
 ```
 
-#### `AladoServerError`
+---
+
+### `withAuth`
+
+Attaches an authentication pipeline to a route.
 
 ```ts
-type AladoServerError = {
-  statusCode: number;
-  message: string;
-};
+@patch('/user/:id', { tags: ['User'] })
+@withAuth(bearerAuth)
+@defineRequest({ path: Id, body: UserDto })
+async update(req: Request) {
+  console.log(req.auth.user); // injected by the auth handler
+}
 ```
 
+See [Authentication](#authentication) for full config details.
+
 ---
 
-Example of controller:
+### Full controller example
 
 ```ts
+import { get, post, patch, del, defineRequest, defineResponse, withAuth } from 'alado';
+import { bearerAuth } from './auth/bearer.auth';
+import { CredentialsDto, UserDto, Id } from './dto';
+
 export class UserController {
+  @get('/users', { tags: ['User'] })
+  @defineResponse({
+    statusCode: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: [],
+  })
+  async list(req) {
+    return {
+      statusCode: 200,
+      headers: { 'Content-Type': 'application/json' },
+      body: [],
+    };
+  }
+
   @post('/user', { tags: ['User'] })
   @defineResponse({
     statusCode: 201,
-    title: 'User',
     headers: { 'Content-Type': 'application/json' },
-    body: exampleUserDto,
+    body: {},
   })
   @defineRequest({ body: CredentialsDto })
-  public async create(req: Request) {
-    const { body } = req;
-    const user = DataStore.signUp(body as CredentialsDto);
+  async create(req) {
     return {
       statusCode: 201,
       headers: { 'Content-Type': 'application/json' },
-      body: user,
+      body: req.body,
     };
   }
 
@@ -186,68 +363,29 @@ export class UserController {
   @withAuth(bearerAuth)
   @defineResponse({
     statusCode: 200,
-    title: 'User',
     headers: { 'Content-Type': 'application/json' },
-    body: exampleUserDto,
+    body: {},
   })
-  @defineRequest({ body: UserDto, path: Id })
-  public async update(req: Request) {
-    const isMyId = this.isMyId(req);
-    if (!isMyId) {
-      return {
-        statusCode: 403,
-        headers: { 'Content-Type': 'application/json' },
-        body: { message: 'Access denied' },
-      };
-    }
-    const { path, body } = req;
-    const user = DataStore.getUser(path.id);
-    if (user) {
-      DataStore.setUser(path.id, body as UserDto);
-    }
+  @defineRequest({
+    path: Id,
+    body: UserDto,
+  })
+  async update(req) {
     return {
-      statusCode: user ? 200 : 404,
+      statusCode: 200,
       headers: { 'Content-Type': 'application/json' },
-      body: DataStore.getUser(path.id) || { message: 'Not Found' },
+      body: req.body,
     };
   }
 
-  @post('/user/:id/avatar', { tags: ['User'] })
+  @del('/user/:id', { tags: ['User'] })
   @withAuth(bearerAuth)
-  @defineResponse({
-    statusCode: 200,
-    title: 'User',
-    headers: { 'Content-Type': 'application/json' },
-    body: exampleUserDto,
-  })
-  @defineRequest({ path: Id, files: UserFilesDto })
-  public setAvatar(req: Request) {
-    const isMyId = this.isMyId(req);
-    if (!isMyId) {
-      return {
-        statusCode: 403,
-        headers: { 'Content-Type': 'application/json' },
-        body: { message: 'Access denied' },
-      };
-    }
-    const { path, files } = req;
-    const user = DataStore.getUser(path.id);
-    if (!user) {
-      return {
-        statusCode: 404,
-        headers: { 'Content-Type': 'application/json' },
-        body: { message: 'Not Found' },
-      };
-    }
-    const { avatar } = files;
-    const writeStream = createWriteStream(`${process.cwd()}/uploads/user-${path.id}-avatar.png`, {
-      encoding: 'latin1',
-    });
-    avatar.stream.pipe(writeStream);
+  @defineRequest({ path: Id })
+  async remove(req) {
     return {
-      statusCode: 202,
-      headers: { 'Content-Type': 'application/json' },
-      body: {},
+      statusCode: 204,
+      headers: {},
+      body: null,
     };
   }
 }
@@ -255,93 +393,77 @@ export class UserController {
 
 ---
 
-## Use these decorators inside DTO classes:
+## DTOs
 
-### `fileUploadProperty`
+DTOs are plain TypeScript classes with decorated properties. They define how request data is validated, transformed, and documented.
 
-```ts
-fileUploadProperty(filePropertyDefinition: [FilePropertyDefinition](#filepropertydefinition))
-```
-
-#### Arguments
-
-- **filePropertyDefinition**: Object describing file upload rules, including:
-  - `mimetypes`: Array of allowed MIME types.
-  - `maxSize`: Maximum file size (bytes).
-  - `required`: Whether the file must be provided.
-  - `mimetypeError`, `maxSizeError`, `requiredError`: Error objects describing validation failures.
+### `validateProperty`
 
-#### `FilePropertyDefinition`
+Validates an incoming property value. Runs before your handler.
 
 ```ts
-interface FilePropertyDefinition {
-  mimetypes: string[];
-  maxSize: number;
-  required: boolean;
-  mimetypeError: AladoServerError;
-  maxSizeError: AladoServerError;
-  requiredError: AladoServerError;
+import { validateProperty } from 'alado';
+
+class CredentialsDto {
+  @validateProperty({
+    required: true,
+    handler: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+    error: {
+      statusCode: 400,
+      message: 'Invalid email address',
+    },
+  })
+  email: string = 'user@example.com';
 }
 ```
 
+- `handler` receives the raw value and must return `boolean | Promise<boolean>`
+- returning `false` → framework returns the configured `error` automatically
+- `handler` is called with `this` bound to the full `Request` object — you can access `this.auth`, `this.query`, etc.
+- **do not use arrow functions** if you need access to `this`
+
 ---
 
 ### `documentProperty`
 
-```ts
-documentProperty(propertyDocumentation: [PropertyDocumentation](#propertydocumentation))
-```
-
-#### Arguments
-
-- **propertyDocumentation**: Documentation metadata for a property, including:
-  - `schema`: JSON Schema–like definition (`type`, `format`, validation structure).
-  - `description`: Human-readable explanation.
-  - `example`: Example value.
-
-#### `PropertyDocumentation`
+Adds OpenAPI/Swagger metadata to a property.
 
 ```ts
-interface PropertyDocumentation {
-  schema: PropertyDefinitionSchema;
-  description?: string;
-  example?: any;
+import { documentProperty } from 'alado';
+
+class UserDto {
+  @documentProperty({
+    schema: {
+      type: 'string',
+      minLength: 2,
+      maxLength: 50,
+    },
+    description: 'The user display name',
+    example: 'John Doe',
+  })
+  name: string = 'John Doe';
 }
 ```
 
-#### `PropertyDefinitionSchema`
+Supports the full OpenAPI `PropertyDefinitionSchema`:
 
 ```ts
 interface PropertyDefinitionSchema {
-  type?: string;
-  format?: string;
+  type?: string; // 'string' | 'number' | 'boolean' | 'object' | 'array'
+  format?: string; // 'email' | 'uuid' | 'date-time' | ...
   default?: any;
-  $ref?: string;
   nullable?: boolean;
-  readOnly?: boolean;
-  writeOnly?: boolean;
-  deprecated?: boolean;
   enum?: any[];
-  oneOf?: Array<PropertyDefinitionSchema>;
-  anyOf?: Array<PropertyDefinitionSchema>;
-  allOf?: Array<PropertyDefinitionSchema>;
-  not?: Array<PropertyDefinitionSchema>;
-  properties?: Record<string, PropertyDefinitionSchema>;
-  additionalProperties?: PropertyDefinitionSchema;
-  minProperties?: number;
-  maxProperties?: number;
   minimum?: number;
   maximum?: number;
-  exclusiveMinimum?: number;
-  exclusiveMaximum?: number;
-  multipleOf?: number;
   minLength?: number;
   maxLength?: number;
   pattern?: string;
-  items?: PropertyDefinitionSchema;
-  minItems?: number;
-  maxItems?: number;
-  uniqueItems?: boolean;
+  items?: PropertyDefinitionSchema; // for arrays
+  properties?: Record<string, PropertyDefinitionSchema>; // for objects
+  oneOf?: PropertyDefinitionSchema[];
+  anyOf?: PropertyDefinitionSchema[];
+  allOf?: PropertyDefinitionSchema[];
 }
 ```
 
@@ -349,350 +471,100 @@ interface PropertyDefinitionSchema {
 
 ### `transformProperty`
 
-```ts
-transformProperty(propertyTransformer: (value:any) => any | Promise<any>)
-
-```
-
-### `validateProperty`
+Transforms a property value before it reaches your handler.
 
 ```ts
-validateProperty(propertyValidation: [PropertyValidation](#propertyvalidation))
-```
-
-#### Arguments
+import { transformProperty } from 'alado';
 
-- **propertyValidation**: Validation rules, including:
-  - `required`: Whether the property is mandatory.
-  - `handler`: Function to validate the property value (sync or async).
-  - `error`: Error object returned when validation fails.
+class QueryDto {
+  @transformProperty((value) => parseInt(value.toString(), 10))
+  page: number = 1;
 
-#### `PropertyValidation`
-
-```ts
-interface PropertyValidation {
-  required?: boolean;
-  handler: (value: any) => boolean | Promise<boolean>; // throws error when returns false
-  error: AladoServerError;
+  @transformProperty((value) => value.trim().toLowerCase())
+  email: string = '';
 }
 ```
 
 ---
 
-DTOs examples:
-
-```typescript
-import { validateProperty, documentProperty } from 'alado';
+### `fileUploadProperty`
 
-export class Id {
-  @validateProperty({
-    required: true,
-    handler: async (value: any) => idValidator(value),
-    error: {
-      statusCode: 400,
-      message: 'Invalid id',
-    },
-  })
-  @documentProperty({
-    schema: {
-      type: 'string',
-    },
-    example: '7ef5ed25-53b1-432f-96ec-8e35d830eb9c',
-    description: 'User Id',
-  })
-  id: string = '7ef5ed25-53b1-432f-96ec-8e35d830eb9c';
-}
-```
+Marks a DTO property as a file upload field with MIME type and size validation.
 
-```typescript
+```ts
 import { fileUploadProperty } from 'alado';
 
 export class UserFilesDto {
   @fileUploadProperty({
-    mimetypes: ['image/png'],
-    maxSize: 1048576,
+    mimetypes: [
+      'image/png',
+      'image/jpeg',
+    ],
+    maxSize: 2 * 1024 * 1024, // 2MB in bytes
     required: true,
     maxSizeError: {
       statusCode: 413,
-      message: 'The avatar should not be larger than 1MB',
+      message: 'File must not exceed 2MB',
     },
     mimetypeError: {
       statusCode: 415,
-      message: 'The avatar should be a PNG image',
+      message: 'Only PNG and JPEG images are allowed',
     },
     requiredError: {
       statusCode: 400,
-      message: 'The avatar file is required',
+      message: 'Avatar file is required',
     },
   })
-  avatar: string = '/path/to/image.png';
+  avatar: string = '/path/to/avatar.png';
 }
 ```
 
-```typescript
-import { validateProperty, documentProperty } from 'alado';
+---
 
-export class CredentialsDto {
-  @validateProperty({
-    required: true,
-    handler: async (value: any) => emailValidator(value),
-    error: {
-      statusCode: 400,
-      message: 'Invalid email',
-    },
-  })
-  @documentProperty({
-    schema: {
-      type: 'string',
-    },
-    example: 'example@example.com',
-    description: 'User email',
-  })
-  email: string = 'example@example.com';
+### Combining decorators
 
+Decorators stack — use them together for full validation + documentation:
+
+```ts
+export class Id {
   @validateProperty({
     required: true,
-    handler: async (value: any) => passwordValidator(value),
+    handler: (value) => /^[0-9a-f-]{36}$/.test(value),
     error: {
       statusCode: 400,
-      message: 'Invalid password',
+      message: 'Invalid UUID',
     },
   })
   @documentProperty({
     schema: {
       type: 'string',
+      format: 'uuid',
     },
-    example: 'securePassword',
-    description: 'User password',
+    example: '7ef5ed25-53b1-432f-96ec-8e35d830eb9c',
+    description: 'Resource identifier',
   })
-  password: string = 'securePassword';
+  id: string = '7ef5ed25-53b1-432f-96ec-8e35d830eb9c';
 }
-
-export const credentialsDto = new CredentialsDto();
 ```
 
 ---
 
-## Initialize the application
-
-Finally, use the `initializeApplication` function to get an instance you would like to run:
-
-```ts
-import { initializeApplication } from 'alado';
-import { aladoServerOptions } from '@config';
-import { UserController } from '@user';
-
-export const app = initializeApplication({
-  serverOptions: aladoServerOptions,
-  controllers: [UserController],
-});
-
-app.start(() => console.log('Application has been successfully started'));
-```
-
-There's ability to pass args to controller`s constructor:
-
-```ts
-import { initializeApplication } from 'alado';
-import { aladoServerOptions } from '@config';
-import { UserController } from '@user';
-
-export const app = initializeApplication({
-  serverOptions: aladoServerOptions,
-  controllers: [{ controller: UserController, options: [{ service: SomeService }] }],
-});
-
-app.start(() => console.log('Application has been successfully started'));
-```
-
-#### Arguments
-
-- **initializeApplicationOptions**: Object containing:
-  - **serverOptions** ([AladoServerOptions](#aladoserveroptions)): Configuration for starting the server (e.g., `appId`, port, logger).
-  - **controllers**: Array of controller classes to initialize at startup.
-
-#### `InitializeApplicationOptions`
+## Authentication
 
-```ts
-interface InitializeApplicationOptions {
-  serverOptions: AladoServerOptions;
-  controllers: AnyClass[];
-}
-```
-
-#### `AladoServerOptions`
+Define a `RequestAuthentication` config object and pass it to `@withAuth`.
 
 ```ts
-interface AladoServerOptions {
-  appId?: string;
-  port?: number;
-  logger?: AladoServerLogger;
-}
-```
-
-#### `AladoServerLogger`
-
-```ts
-interface AladoServerLogger {
-  log: (...args: any[]) => void;
-  error: (error: Error) => void;
-}
-```
-
-There is an example of the API creating with Alado (version < 2.0.0):
-
-The basis of use is a combination of interface simplicity and separation of the “routine” part of writing API
-from business logic implementation - due to a declarative approach to describing all request parameters
-in the form of static reusable structures.
-
-[https://github.com/databikers/alado-api-example](https://github.com/databikers/alado-api-example)
-
-1. Installation
-
-```shell
-npm i -s alado
-```
-
-2. Instancing
-
-```typescript
-import { AladoServer } from 'alado';
-
-const app: AladoServer = new AladoServer({
-  port: 3000,
-  cors: {
-    enable: true,
-    allowedOrigin: '*',
-    allowedHeaders: ['Authorization'],
-    exposeHeaders: ['x-total-count'],
-  },
-  documentProperty: {
-    enable: true,
-    route: '/open-api',
-    info: {
-      title: 'My API title',
-      description: 'My API description',
-      version: '1.0.0',
-    },
-  },
-  verbose: true,
-  maxBodySizeBytes: 1024,
-});
-```
-
-In case you want to run an HTTPs server (even though normally a Node.js app runs behind nginx/ingress etc.)
-You can do it using the ssl parameter (look at SecureContextOptions in the "tls" module -
-[Node.js TLS module](https://nodejs.org/api/tls.html#tlscreateserveroptions-secureconnectionlistener):
-
-```typescript
-import { readFileSync } from 'fs';
-import { AladoServer } from 'alado';
-
-const app = new AladoServer({
-  port: 3000,
-  ssl: {
-    cert: readFileSync('/path/to/cert'),
-    key: readFileSync('/path/to/key'),
-  },
-  // https://nodejs.org/api/http.html#httpcreateserveroptions-requestlistener
-  serverOptions: {
-    keepAliveTimeout: 5000,
-  },
-  cors: {
-    enable: true,
-    allowedOrigin: '*',
-    allowedHeaders: ['Authorization'],
-    exposeHeaders: ['x-total-count'],
-    allowedCredentials: true,
-    maxAge: 3600,
-  },
-  headers: {
-    a: 'b', //any additional header
-  },
-  openApiDoc: {
-    enable: true,
-    route: '/',
-    info: {
-      title: 'My API title',
-      description: 'My API description',
-      version: '1.0.0',
-    },
-  },
-  verbose: true,
-  maxBodySizeBytes: 1024,
-});
-```
-
-3. Defining routes
-
-Here is how you define routes in Alado:
-
-```typescript
-app.get('/user/:id', context, (request: Request): Response<UserDto> => {
-  const user = {
-    name: 'John Doe',
-    id: request.path.id,
-  };
-  return {
-    statusCode: 200,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: user,
-  };
-});
-
-app.start(() => console.log(`[API]: application has been launched successfully`));
-```
-
-The application provides "get", "post", "delete", "patch", "put" and "head" methods for defining routes.
-These methods accept three required arguments:
-
-- route or path: A string that may contain variables to specify the route.
-- context: An aggregating object that fully describes the request.
-- handler: A function that handles the request.
-
-  3.1 Route or path.
-
-Path variables defining works in the same way as it works in other frameworks: You just define a part of your route (means part separated by slashes)
-as ":id" and receive the passed value as request.path.id).
-
-3.2 Context
-
-Here's the contract of the request context:
-
-```typescript
-interface Context<T> {
-  title: string;
-  auth?: RequestAuthentication;
-  isHidden?: boolean; //Just exclude some route from Your API specification
-  options: ContextOptions;
-  request: ContextRequest;
-  response: Response<T>;
-}
-```
-
-Unlike context.title, which is simply a unique string, the other properties may not be immediately clear.
-However, once explained, they become quite obvious and extremely logical.
-
-**Note that all parts of the context and its nested properties can be reused**
-
-3.2.1 Context.auth
-
-```typescript
+// src/modules/user/auth/bearer.auth.ts
 import { RequestAuthentication } from 'alado';
+import { DataStore } from '@data-store';
 
-const bearerAuth: RequestAuthentication = {
-  inputProperty: 'headers.authorization',
-  outputProperty: 'auth.user',
-  handler: async (bearer: string) => {
-    // validateProperty header, return user
-    return {
-      name: 'John Doe',
-      id: 1,
-    };
+export const bearerAuth: RequestAuthentication = {
+  required: true,
+  inputProperty: 'headers.x-api-key', // where to read the token from
+  outputProperty: 'auth.user', // where to write the result on req
+  handler(value: string) {
+    return DataStore.findUserByToken(value); // return user or null/undefined
   },
-  required: true, // false You want "soft" checking
   error: {
     statusCode: 401,
     message: 'Unauthorized',
@@ -700,43 +572,26 @@ const bearerAuth: RequestAuthentication = {
 };
 ```
 
-This means that the application takes an "Authorization" header
-(or "api_token" query parameter if you provide "query.api_token" as an inputProperty,
-"body.someThing" and "path.token" work also)
-use the provided handler to get the user and set the received user to request.auth.user,
-(and the mentioned "request" here is the request argument in your route handler)
-Or just returns 401 Unauthorized.
-This means that the application can authenticate using an "Authorization" header, or alternatively,
-using an "api_token" query parameter (if specified as "query.api_token" in the inputProperty).
-It can also authenticate using values like "body.someThing" or "path.token".
-In the example the provided handler retrieves the user and assigns it to request.auth.user
-(where request is the argument in your route handler).
-If authentication fails, it returns a 401 Unauthorized response.
-
-This also works:
-
-```typescript
-import { RequestAuthentication } from 'alado';
+The `inputProperty` supports dot-notation and can point to any part of the request:
 
-const bearerAuth: RequestAuthentication = {
-  inputProperty: 'header.x-api-token',
-  outputProperty: 'auth',
-  handler: async (xApiToken: string) => {
-    // You will receive user and company as nested properties in request auth
-    return {
-      user: {
-        name: 'John Doe',
-        id: 1,
-      },
-      company: {
-        name: 'Databikers Limited',
-        id: 2,
-      },
-    };
-  },
-  //optional property if You want to specify execution context for the auth handler
-  handlerContext: {},
-  required: true, // false You want "soft" checking
+| `inputProperty`         | Reads from           |
+| ----------------------- | -------------------- |
+| `headers.x-api-key`     | Request header       |
+| `headers.authorization` | Authorization header |
+| `query.api_token`       | Query parameter      |
+| `body.token`            | Request body field   |
+| `path.token`            | Path parameter       |
+
+The resolved value from `handler` is set at `outputProperty` on the request object, making it available as `req.auth.user` in your handler.
+
+**Optional auth** — set `required: false` for soft checking (handler runs but failure doesn't block the request):
+
+```ts
+export const optionalAuth: RequestAuthentication = {
+  required: false, // won't return 401 if token is missing or invalid
+  inputProperty: 'headers.authorization',
+  outputProperty: 'auth.user',
+  handler: (token) => UserService.findByToken(token),
   error: {
     statusCode: 401,
     message: 'Unauthorized',
@@ -744,310 +599,145 @@ const bearerAuth: RequestAuthentication = {
 };
 ```
 
-3.2.2 Context.options
-
-```typescript
-interface ContextOptions {
-  allowUnknownFields?: boolean;
-  documentProperty?: {
-    description?: string;
-    operationId: string;
-    tags?: string[];
-  };
-}
-```
-
-Setting "allowUnknownFields" to false protects your application from receiving unexpected properties in the request body, query, and files. It does not affect request.path, as path variables are defined at the routing level, nor does it affect request headers. Conversely, you can receive { name: 'John Doe', role: 'Admin' } when only expecting name.
-
-The "documentProperty" property is part of the Open API route definition and is optional.
-
-3.2.3 Context.request
+---
 
-Context.request is aggregating object that describes all HTTP request properties You expect
+## File Uploads
 
-```typescript
-interface ContextRequest {
-  headers?: Record<string, PropertyDefinition>;
-  query?: Record<string, PropertyDefinition>;
-  path?: Record<string, PropertyDefinition>;
-  body?: Record<string, PropertyDefinition>;
-  files?: Record<string, FilePropertyDefinition>;
-  auth?: Record<string, any>;
-}
-```
+1. Define a files DTO:
 
-There's an example for request with path property only:
-
-```typescript
-const request: ContextRequest = {
-  path: {
-    id: {
-      documentProperty: {
-        schema: {
-          type: 'string',
-        },
-        example: '123456',
-        description: 'User id',
-      },
-      validation: {
-        required: true,
-        handler(value) {
-          return /^\d+$/.test(value);
-        },
-        transform(value) {
-          return parseInt(value, 10);
-        },
-        error: {
-          statusCode: 400,
-          message: '400.1.0',
-        },
-      },
-    },
-  },
-};
-```
+```ts
+// src/modules/user/dto/user-files.dto.ts
+import { fileUploadProperty } from 'alado';
 
-Validation.handler returns boolean (any => boolean | any => Promise<boolean>) if received value fits to provided requirements,
-and in falsy case it throws an error and app returns 400 Bad Request with a json body contains specified message
-Handler can be async and can use complex logic under the hood; it allows to use
-Avoid using an arrow functions as handlers - in this case You can lose execution context,
-The execution context of validation.handler (and validation transform) is the request
-(aggregating object - the argument used at the route handler)
-
-```typescript
-const request: ContextRequest = {
-  body: {
-    role: {
-      documentProperty: {
-        schema: {
-          type: 'string',
-        },
-        example: 'admin',
-        description: 'User role',
-      },
-      validation: {
-        required: true,
-        async handler(value) {
-          if (this.auth.user.role === 'admin') {
-            return true;
-          }
-          await userService.makeSomeChecking(this.query.scope);
-          return value === 'customer';
-        },
-        error: {
-          statusCode: 400,
-          message: '400.1.0',
-        },
-      },
+export class UserFilesDto {
+  @fileUploadProperty({
+    mimetypes: ['image/png'],
+    maxSize: 1048576, // 1MB
+    required: true,
+    maxSizeError: {
+      statusCode: 413,
+      message: 'Max size is 1MB',
     },
-  },
-};
-```
-
-In the same way You can describe the request headers, query, body. Remember, if context.options.allowUnknownFields
-is set to false, all non-described request properties (or non-described nested properties in the described request properties) never be accessible.
-
-```typescript
-const request: ContextRequest = {
-  query: {
-    sortBy: {
-      documentProperty: {
-        schema: {
-          type: 'string',
-        },
-        example: 'createdAt',
-        description: 'Sort by field',
-      },
-      validation: {
-        required: true,
-        handler(value) {
-          return [
-            'createdAt',
-            'updatedAt',
-          ].includes(value);
-        },
-        error: {
-          statusCode: 400,
-          message: 'sortBy should be createdAt or updatedAt',
-        },
-      },
+    mimetypeError: {
+      statusCode: 415,
+      message: 'Only PNG allowed',
     },
-    sortOrder: {
-      documentProperty: {
-        schema: {
-          type: 'string',
-        },
-        example: 'asc',
-        description: 'Sort order',
-      },
-      validation: {
-        required: true,
-        handler(value) {
-          return [
-            'asc',
-            'desc',
-          ].includes(value);
-        },
-        error: {
-          statusCode: 400,
-          message: 'sortOrder should be asc or desc',
-        },
-      },
+    requiredError: {
+      statusCode: 400,
+      message: 'File is required',
     },
-  },
-};
+  })
+  avatar: string = '';
+}
 ```
 
-Now, if you send GET /user?sortBy=updateAt&sortOrder=desc&limit=10, the limit parameter will be ignored since it wasn't described:
-
-```typescript
-app.post('/user', context, (request: Request) => {
-  console.log(request.query);
+2. Use in controller:
 
-  // {
-  //   sortBy: 'updatedAt',
-  //   sortOrder: 'desc'
-  // }
+```ts
+import { createWriteStream } from 'fs';
 
-  console.log(request.ip);
+@post('/user/:id/avatar', { tags: ['User'] })
+@withAuth(bearerAuth)
+@defineRequest({ path: Id, files: UserFilesDto })
+setAvatar(req) {
+  const { avatar } = req.files;
+  // avatar = { stream: Readable, size: number, mimetype: string }
 
-  // 127.0.0.1
+  const writeStream = createWriteStream(`./uploads/user-${req.path.id}.png`);
+  avatar.stream.pipe(writeStream);
 
   return {
-    statusCode: 200,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: [],
+    statusCode: 202,
+    headers: { 'Content-Type': 'application/json' },
+    body: { message: 'Upload accepted' },
   };
-});
+}
 ```
 
-Regarding the request body even it described properly it will be available only for POST, PUT and PATCH HTTP requests.
-If You want dealing with uploaded files You just should to describe it in the request:
-
-```typescript
-const request: ContextRequest = {
-  files: {
-    avatar: {
-      mimetypes: ['image/png'],
-      maxSize: 1048576,
-      required: true,
-      maxSizeError: {
-        statusCode: 413,
-        message: 'The avatar should not be larger than 1MB',
-      },
-      mimetypeError: {
-        statusCode: 415,
-        message: 'The avatar should be a PNG image',
-      },
-      requiredError: {
-        statusCode: 400,
-        message: 'The avatar file is required',
+---
+
+## OpenAPI / Swagger
+
+Alado generates OpenAPI 3.0 documentation automatically from your decorators. No extra config needed — just enable it in server options:
+
+```ts
+const app = initializeApplication({
+  serverOptions: {
+    port: 3000,
+    openApiDoc: {
+      enable: true,
+      route: '/', // serve Swagger UI at this path
+      info: {
+        title: 'My API',
+        description: 'Auto-generated with Alado',
+        version: '1.0.0',
       },
     },
   },
-};
+  controllers: [UserController],
+});
 ```
 
-and uploaded file will be acceptable in the request:
+Open `http://localhost:3000/` to view the Swagger UI.
 
-```typescript
-import { createWriteStream } from 'fs';
-
-app.post('/user/:id/avatar', context, (request: Request) => {
-  console.log(request.files);
-  // {
-  //   avatar: {
-  //     stream: Readable,
-  //     size: 65025,
-  //     mimetype: 'image/png'
-  //   }
-  // }
+Documentation is built from:
 
-  // You can play with request.files.avatar.stream as You want e.g. save it locally
+- `@get`, `@post`, etc. → endpoint paths and methods
+- `tags`, `title`, `description` in decorator options → grouping and descriptions
+- `@defineRequest` + DTO `@documentProperty` → request schema
+- `@defineResponse` → response schema
+- `isHidden: true` → excludes endpoint from docs
 
-  const writeStream = createWriteStream(`/path/to/user/avatars/${req.path.id}.png`);
-  request.files.avatar.stream.pipe(writeStream);
-  return {
-    statusCode: 200,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: user,
-  };
-});
-```
-
-3.2.4 Context response
+---
 
-Context.response is always the same as the return type of the route handler
+## API Reference
 
-```typescript
-interface Response<T> {
-  title?: string;
-  description?: string;
-  statusCode: number;
-  headers?: Record<string, string>;
-  body?: T;
-}
-```
+### `initializeApplication(options)`
 
-3.3 Route handler
+| Property        | Type                               | Description                    |
+| --------------- | ---------------------------------- | ------------------------------ |
+| `serverOptions` | `AladoServerOptions`               | Server configuration           |
+| `controllers`   | `AnyClass[] \| ControllerConfig[]` | Controller classes to register |
 
-The route handler is the function that implements the following contract:
+### `AladoServerOptions`
 
-```typescript
-(request: Request) => Response<T> | Promise<Response<T>>;
-```
+| Property | Type                   | Default | Description                         |
+| -------- | ---------------------- | ------- | ----------------------------------- |
+| `port`   | `number`               | `3000`  | HTTP port                           |
+| `appId`  | `string`               | —       | App identifier for multi-app setups |
+| `logger` | `AladoServerLogger`    | —       | Custom logger                       |
+| `ssl`    | `SecureContextOptions` | —       | TLS/HTTPS options                   |
 
-Despite having a strict contract for the return type,
-the response body can be an object (for application/json content-type), text, or even a stream
+### `Request`
 
-```typescript
-interface UserDto {
-  id: number;
-  name: string;
-}
+The object received in every route handler:
 
-const handlerWithJSONBody = (request: Request): Response<UserDto> => {
-  const body: UserDto = {
-    id: 1,
-    name: 'John Doe',
-  };
-  return {
-    statusCode: 200,
-    headers: { 'Content-Type': 'application/json' },
-    body,
-  };
-};
+| Property  | Type                         | Description                        |
+| --------- | ---------------------------- | ---------------------------------- |
+| `request` | `IncomingMessage`            | Raw Node.js request                |
+| `ip`      | `string`                     | Client IP address                  |
+| `method`  | `string`                     | HTTP method                        |
+| `url`     | `string`                     | Request URL                        |
+| `headers` | `IncomingHttpHeaders`        | Request headers                    |
+| `path`    | `Record<string, string>`     | Path parameters                    |
+| `query`   | `Record<string, any>`        | Query parameters                   |
+| `body`    | `Record<string, any>`        | Request body (POST/PUT/PATCH only) |
+| `rawBody` | `string`                     | Unparsed body string               |
+| `files`   | `Record<string, FileResult>` | Uploaded files                     |
+| `auth`    | `Record<string, any>`        | Auth handler output                |
 
-const handlerWithStringBody = (request: Request): Response<string> => {
-  const body: string = 'Not Found';
-  return {
-    statusCode: 404,
-    headers: { 'Content-Type': 'text/plain' },
-    body,
-  };
-};
+### `Response<T>`
 
-const handlerWithStreamBody = (request: Request): Response<ReadStream> => {
-  const body = createReadStream('/path/to/image.png');
-  return {
-    statusCode: 200,
-    headers: { 'Content-Type': 'image/png' },
-    body,
-  };
-};
-```
+The object your handler must return:
 
-4. Running
+| Property     | Type                     | Required | Description                                     |
+| ------------ | ------------------------ | -------- | ----------------------------------------------- |
+| `statusCode` | `number`                 | required | HTTP status code                                |
+| `headers`    | `Record<string, string>` | —        | Response headers                                |
+| `body`       | `T`                      | —        | Response body — object, string, or `ReadStream` |
 
-```typescript
-app.start(() => console.log('Your awesome application has been successfully launched'));
+---
 
-// And stop the application when needed
-app.stop(() => console.log('Your awesome application has been successfully launched'));
-```
+## License
 
-Don't forget to check swagger at the defined above options.documentProperty.route
+MIT © [Databikers Limited](https://databikers.com)