# Alado

> A fast, lightweight, zero-dependency Node.js HTTP framework with built-in routing, validation, authentication, file uploads, and automatic OpenAPI 3.0 documentation.

## Key facts

- Package: `alado` on npm, current version 3.2.3. Install with `npm install alado`. Requires Node.js >=18.0.0.
- TypeScript-first. Alado uses legacy TypeScript decorators, so the consuming project needs `"experimentalDecorators": true` in tsconfig.json.
- Everything is imported from `'alado'`: route decorators (`get`, `query`, `post`, `put`, `patch`, `del`, `head`), `defineRequest`, `defineResponse`, `withAuth`, `accessControl`, DTO property decorators (`validateProperty`, `documentProperty`, `transformProperty`, `fileUploadProperty`), the `validate` builder, and `initializeApplication`.
- `del` is the DELETE decorator. `query` is the HTTP QUERY method.
- Handlers receive a `Request` and return a plain `Response` object `{ statusCode, headers?, body? }`. There is no `res.send()`. `body` can be an object, a string or a readable stream.
- Request order: routing, body parsing (JSON, XML, multipart), `@withAuth`, `@accessControl`, DTO validation (request parts, then files), handler. A failed step returns its configured `{ statusCode, message }` and the handler does not run.
- DTOs are classes whose properties carry decorators; `@defineRequest({ headers, query, path, body, files, auth })` binds DTO classes to request parts.
- OpenAPI 3.0 and Swagger UI are generated from the same decorators when `serverOptions.openApiDoc.enable` is true.
- License: MIT, Data Bikers Limited. Source: https://github.com/databikers/alado

## Getting Started

- [Introduction](docs/introduction.md): What Alado is and how it compares with Express, Fastify and NestJS feature by feature.
- [Installation](docs/installation.md): Install the alado package from npm.
- [Quick Start](docs/quick-start.md): A minimal decorator-based API: one controller with @post, @defineRequest and @defineResponse, started with initializeApplication.
- [Project Structure](docs/project-structure.md): A suggested folder layout for a decorator-based Alado project.

## Application

- [Application Setup](docs/application-setup.md): initializeApplication options: port, appId, logger, passing constructor options to controllers, and HTTPS via ssl.

## Controllers

- [HTTP Method Decorators](docs/http-methods.md): @get, @query, @post, @put, @patch, @del and @head route decorators and their HttpDecoratorOptions (appId, title, description, isHidden, tags).
- [@defineRequest](docs/define-request.md): @defineRequest declares and validates headers, query, path, body, files and auth using DTO classes.
- [@defineResponse](docs/define-response.md): @defineResponse documents status code, headers and body shape for the OpenAPI output.
- [@withAuth](docs/with-auth.md): @withAuth attaches a RequestAuthentication pipeline to a route; the result is available on req.auth.
- [@accessControl](docs/access-control-decorator.md): @accessControl attaches access-control rules to a route, e.g. auth.user.id must equal path.id.
- [Full Controller Example](docs/controller-example.md): A complete CRUD controller combining route, request, response and auth decorators.

## DTOs

- [@validateProperty](docs/validate-property.md): @validateProperty runs a boolean or async handler on a DTO property and returns the configured error on failure; handler `this` is the Request.
- [@documentProperty](docs/document-property.md): @documentProperty adds OpenAPI schema, description and example metadata to a DTO property (full PropertyDefinitionSchema).
- [@transformProperty](docs/transform-property.md): @transformProperty converts a property value (e.g. string to number, trim/lowercase) before the handler runs.
- [@fileUploadProperty](docs/file-upload-property.md): @fileUploadProperty declares an upload field with MIME types, max size and per-case error responses.
- [Combining Decorators](docs/combining-decorators.md): Stacking @validateProperty and @documentProperty on one DTO property.

## Validation

- [Validator Basics](docs/validator.md): The built-in chainable validator: entry points (string, number, boolean, array, object, custom), required/optional, build() vs buildSync().
- [Available Rules](docs/validator-rules.md): Every validator rule: type, string (min, max, length, regex, email, uuid, objectId, url, trim), number, enum/custom, object and array rules.
- [Objects & Shapes](docs/object-validation.md): Object shape validation, nesting, and key constraints: minKeys, maxKeys, or (at least one) and xor (exactly one).
- [Cross-Property Conditionals](docs/conditionals.md): Cross-property rules: .when(key, is, then, otherwise) and switch-style .match(key, cases, fallback).
- [Array Items](docs/array-validation.md): Array validation with items(), minItems, maxItems and unique, including arrays of object shapes.
- [Async & Sync Modes](docs/async-sync.md): Async rules via custom(), rule execution order, buildSync() and its error on async rules, and using validators inside @validateProperty.

## Features

- [Authentication](docs/authentication.md): RequestAuthentication config: inputProperty (dot path into the request), outputProperty, handler, error, and optional auth with required: false.
- [Access Control](docs/access-control.md): AccessControlConfig: inputProperty, transformInputProperty, compareWithProperty, expectedValue, accessControlHandler, statusCode, message; multiple rules must all pass.
- [File Uploads](docs/file-uploads.md): End-to-end file uploads: files DTO, reading req.files streams, and responding with a ReadStream body.
- [XML Request Body](docs/xml-body.md): Automatic XML body parsing (v2.6.0+): element-to-key mapping, repeated tags to arrays, @attrs, CDATA, and namespace resolution.
- [OpenAPI / Swagger](docs/openapi.md): Enable OpenAPI 3.0 / Swagger UI with openApiDoc options and what each decorator contributes to the generated spec.

## Reference

- [API Reference](docs/api-reference.md): Reference tables for initializeApplication, AladoServerOptions, Request and Response<T>.

## Optional

- [License](license.md): MIT license text.
- [Example API](https://github.com/databikers/alado-decorators-api-example): a complete decorator-based API built with Alado.
- [Source code](https://github.com/databikers/alado): GitHub repository and issue tracker.
- [npm package](https://www.npmjs.com/package/alado): published releases.
- [Full documentation in one file](llms-full.txt): every page above, concatenated.