vaden library

Vaden Framework

A modern, annotation-driven backend framework for Dart applications.

Vaden is designed to simplify backend development by providing a structured, declarative approach to building REST APIs with built-in dependency injection, middleware support, and OpenAPI documentation capabilities.

Core Features

  • Annotation-driven development: Define controllers, routes, and components using annotations
  • Dependency injection: Built-in DI system powered by auto_injector
  • Middleware support: Easy-to-use middleware system for request/response processing
  • OpenAPI integration: Automatic API documentation generation
  • Type-safe serialization: Robust data transfer object (DTO) handling
  • Security: Guards for route protection and authentication
  • Validation: Input validation through lucid_validation integration

Framework Architecture

Vaden is built on top of the Shelf ecosystem, providing a robust foundation for handling HTTP requests and responses. The framework follows a modular architecture with clear separation of concerns:

  • Controllers: Handle incoming HTTP requests and define API endpoints
  • Services: Contain business logic and application workflows
  • Repositories: Manage data access and persistence
  • DTOs: Define data transfer objects for request/response serialization
  • Guards: Protect routes with authentication and authorization logic
  • Middlewares: Process requests/responses for cross-cutting concerns

Getting Started

To use Vaden, import this library and start defining your application components using the provided annotations. See the documentation for each component for detailed usage instructions.

Classes

Api
Provides OpenAPI documentation for a controller.
ApiClient
ApiContent
Describes the content type and schema of a request or response body.
ApiOperation
Provides OpenAPI documentation for an endpoint operation.
ApiParam
Provides OpenAPI documentation for a path parameter.
ApiQuery
Provides OpenAPI documentation for a query parameter.
ApiResponse
Describes a possible response from an API endpoint.
ApiSecurity
Specifies the security schemes required for an API endpoint.
ApplicationRunner
Defines a contract for components that should execute automatically during application startup.
ApplicationSettings
A class for loading and accessing application configuration from YAML files.
AutoInjector
Automatic Dependency Injection System, but without build_runner :)
[tag]: AutoInject instance identity.
[on]: Helps with instance registration.
[paramObservers]: List of functions that listen and transform parameters while they are being parsed when requested by the get() method.

AwsS3Storage
Implementation of the Storage interface that uses Amazon S3 for cloud storage.
BaseComponent
Base interface for all component annotations.
Bean
Marks a method in a Configuration class as a bean factory.
Bind<T>
BindConfig<T>
Body
Binds the request body to a method parameter.
Cascade
A helper that calls several handlers in sequence and returns the first acceptable response.
CommandLineRunner
Defines a contract for components that should execute based on command-line arguments during application startup.
CommonModule<T extends VadenApplication>
The CommonModule abstract class defines the structure for creating modules that can register their own dependency injections and route configurations. This allows for modularization and better organization of code in a Vaden-based application.
Component
Marks a class as a general component in the application.
Configuration
Marks a class as a configuration component in the application.
Context
Binds a context value from the request to a method parameter.
Controller
Marks a class as a REST controller in the application.
ControllerAdvice
Marks a class as a controller advice for global exception handling.
Culture
DartVadenApplication
Represents the core application structure in Vaden, managing server startup, dependency injection, and routing.
DefaultLanguageManager
Delete
Marks a method as a handler for HTTP DELETE requests.
Disposable
Interface for classes that need to release resources when they are no longer needed.
DSON
Data Serialization Object Notation (DSON) system for Vaden.
DTO
Marks a class as a Data Transfer Object (DTO).
EnforceJsonContentType
Middleware that ensures all responses have a JSON content type header.
EnglishLanguage
ExceptionHandler
Marks a method in a ControllerAdvice class as an exception handler.
FirebaseStorage
Implementation of the Storage interface that uses Firebase Storage for cloud storage.
FormData
A Multipart subpart with a parsed name and filename values read from its content-disposition header.
Get
Marks a method as a handler for HTTP GET requests.
Marks a method as a handler for HTTP HEAD requests.
Binds a header value from the request to a method parameter.
Injector
Register and get binds
IOServer
A Server backed by a dart:io HttpServer.
JsonIgnore
Excludes a field from JSON serialization and deserialization.
JsonKey
Specifies the JSON key name for a field in a DTO.
Language
LanguageManager
LayersGraph
LocalStorage
Implementation of the Storage interface that uses the local file system.
LucidValidation
LucidValidationBuilder<TProp, Entity>
LucidValidator<E>
Abstract class for creating validation logic for a specific entity type E.
Mount
Mounts a Router instance at the specified path.
Multipart
An entry in a multipart request.
NamedParam
OpenApiConfig
Configuration class for generating OpenAPI documentation in the Vaden framework.
Options
Marks a method as a handler for HTTP OPTIONS requests.
Param
Binds a path parameter from the request URL to a method parameter.
ParamParse<P, R>
Abstract class for parameter parsing and serialization in Vaden.
Parse
Marks a ParamParse class as globally discoverable.
Patch
Marks a method as a handler for HTTP PATCH requests.
Pipeline
A helper that makes it easy to compose a set of Middleware and a Handler.
PositionalParam
Post
Marks a method as a handler for HTTP POST requests.
Put
Marks a method as a handler for HTTP PUT requests.
Query
Binds a query parameter from the request URL to a method parameter.
Repository
Marks a class as a repository in the application.
Request
An HTTP request to be processed by a Shelf application.
ResourceService
A service for serving static files in a Vaden application.
Response
The response returned by a Handler.
ResponseEntity<T>
A class that represents an HTTP response with body, status code, and headers.
Route
Annotation for handler methods that requests should be routed when using package shelf_router_generator.
Router
A shelf Router routes requests to handlers based on HTTP verb and route pattern.
Scope
Specifies the bind type for a component in the dependency injection container. This annotation is used to define how a component should be bound in the dependency injection container, such as whether it should be a singleton, lazy singleton, or instance. Example:
Server
An adapter with a concrete URL.
ServerHandler
A connected pair of a Server and a Handler.
Service
Marks a class as a service in the application.
Storage
Abstract class defining the interface for file storage in the Vaden framework.
UseGuards
Applies guards to a controller or endpoint.
UseMiddleware
Applies middleware to a controller or endpoint.
UseParse
Specifies which custom ParamParse class should be used for a DTO field.
VadenApplication
VadenGuard
Base class for creating guards in the Vaden framework.
VadenMiddleware
Base class for creating middleware in the Vaden framework.
VadenModule
Defines a Vaden module that can import other modules.
ValidationResult
Represents the result of a validation rule.
ValidatorBuilder<T>
Builder class for creating validators in the Vaden framework.

Enums

BindType
CascadeMode
Defines the behavior of rule execution when a validation failure occurs.

Mixins

Validator<T>
Mixin for creating validators in the Vaden framework.

Extension Types

FormDataRequest
A multipart request containing form data.
MultipartRequest
A multipart request.

Extensions

EqualValidation on LucidValidationBuilder<T, E>
Extension on LucidValidationBuilder for T properties to add an equality validation.
ExclusiveBetweenDatetimeNullableValidation on SimpleValidationBuilder<DateTime?>
ExclusiveBetweenDatetimeOrNullableValidation on SimpleValidationBuilder<DateTime?>
ExclusiveBetweenDatetimeValidation on SimpleValidationBuilder<DateTime>
Extension on LucidValidationBuilder for DateTime properties to add a exclusive between validation.
GreaterThanDateTimeNullableValidation on SimpleValidationBuilder<DateTime?>
GreaterThanDateTimeOrNullableValidation on SimpleValidationBuilder<DateTime?>
GreaterThanDateTimeValidation on SimpleValidationBuilder<DateTime>
Extension on LucidValidationBuilder for DateTime properties to add a greater than validation.
GreaterThanNullablealidation on SimpleValidationBuilder<num?>
GreaterThanOrEqualToDateTimeNullableValidation on SimpleValidationBuilder<DateTime?>
GreaterThanOrEqualToDateTimeOrNullableValidation on SimpleValidationBuilder<DateTime?>
GreaterThanOrEqualToDateTimeValidation on SimpleValidationBuilder<DateTime>
Extension on LucidValidationBuilder for DateTime properties to add a greater than validation.
GreaterThanOrNullableValidation on SimpleValidationBuilder<num?>
GreaterThanValidation on SimpleValidationBuilder<num>
Extension on LucidValidationBuilder for num properties to add a greater than validation.
InclusiveBetweenDatetimeNullableValidation on SimpleValidationBuilder<DateTime?>
InclusiveBetweenDatetimeOrNullableValidation on SimpleValidationBuilder<DateTime?>
InclusiveBetweenDatetimeValidation on SimpleValidationBuilder<DateTime>
Extension on LucidValidationBuilder for DateTime properties to add a inclusive between validation.
IsEmptyNullableValidation on SimpleValidationBuilder<String?>
IsEmptyOrNullableValidation on SimpleValidationBuilder<String?>
IsEmptyValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add an empty string validation.
IsNotNullValidation on SimpleValidationBuilder<T?>
Extension on LucidValidationBuilder for T? properties to add a not null validation.
IsNullValidation on SimpleValidationBuilder<T?>
Extension on LucidValidationBuilder for T? properties to add a null validation.
LessThanDatetimeNullableValidation on SimpleValidationBuilder<DateTime?>
LessThanDatetimeOrNullableValidation on SimpleValidationBuilder<DateTime?>
LessThanDatetimeValidation on SimpleValidationBuilder<DateTime>
Extension on LucidValidationBuilder for DateTime properties to add a less than validation.
LessThanNullableValidation on SimpleValidationBuilder<num?>
LessThanOrEqualToDatetimeNullableValidation on SimpleValidationBuilder<DateTime?>
LessThanOrEqualToDatetimeOrNullableValidation on SimpleValidationBuilder<DateTime?>
LessThanOrEqualToDatetimeValidation on SimpleValidationBuilder<DateTime>
Extension on LucidValidationBuilder for DateTime properties to add a less than validation.
LessThanOrNullableValidation on SimpleValidationBuilder<num?>
LessThanValidation on SimpleValidationBuilder<num>
Extension on LucidValidationBuilder for num properties to add a less than validation.
MatchesPatternNullableValidation on SimpleValidationBuilder<String?>
MatchesPatternOrNullableValidation on SimpleValidationBuilder<String?>
MatchesPatternValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a regex pattern match validation.
MaxLengthNullableValidation on SimpleValidationBuilder<String?>
MaxLengthOrNullableValidation on SimpleValidationBuilder<String?>
MaxLengthValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a maximum length validation.
MaxNullableValidation on SimpleValidationBuilder<num?>
MaxOrNullableValidation on SimpleValidationBuilder<num?>
MaxValidation on SimpleValidationBuilder<num>
Extension on LucidValidationBuilder for num properties to add a maximum value validation.
MiddlewareExtensions on Middleware
Extensions on Middleware to aid in composing Middleware and Handlers.
MinLengthNullableValidation on SimpleValidationBuilder<String?>
MinLengthOrNullableValidation on SimpleValidationBuilder<String?>
MinLengthValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a minimum length validation.
MinNullableValidation on SimpleValidationBuilder<num?>
MinOrNullableValidation on SimpleValidationBuilder<num?>
MinValidation on SimpleValidationBuilder<num>
Extension on LucidValidationBuilder for num properties to add a minimum value validation.
MultipartFromRequest on Request
Extensions that call MultipartRequest.of and FormDataRequest.of as an extension on Request.
MustHaveLowercaseNullableValidation on SimpleValidationBuilder<String?>
MustHaveLowercaseOrNullableValidation on SimpleValidationBuilder<String?>
MustHaveLowercaseValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a lowercase letter validation.
MustHaveNumbersNullableValidation on SimpleValidationBuilder<String?>
MustHaveNumbersOrNullableValidation on SimpleValidationBuilder<String?>
MustHaveNumbersValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a numeric character validation.
MustHaveSpecialCharacterNullableValidation on SimpleValidationBuilder<String?>
MustHaveSpecialCharacterOrNullableValidation on SimpleValidationBuilder<String?>
MustHaveSpecialCharacterValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a special character validation.
MustHaveUppercaseNullableValidation on SimpleValidationBuilder<String?>
MustHaveUppercaseOrNullableValidation on SimpleValidationBuilder<String?>
MustHaveUppercaseValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add an uppercase letter validation.
NotEmptyNullableValidation on SimpleValidationBuilder<String?>
NotEmptyOrNullableValidation on SimpleValidationBuilder<String?>
NotEmptyValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a not empty validation.
NotEqualValidation on LucidValidationBuilder<T, E>
Extension on LucidValidationBuilder for T properties to add a non-equality validation.
PipelineExtension on Pipeline
Extension on the shelf Pipeline class to provide convenient methods for adding Vaden-specific middleware and guards.
RangeNullableValidation on SimpleValidationBuilder<num?>
RangeOrNullableValidation on SimpleValidationBuilder<num?>
RangeValidation on SimpleValidationBuilder<num>
Extension on LucidValidationBuilder for num properties to add a range validation.
RepeatedCharactersNullableValidator on SimpleValidationBuilder<String?>
Extension on SimpleValidationBuilder for nullable String? properties to add validation against sequential repeated characters.
RepeatedCharactersOrNullValidator on SimpleValidationBuilder<String?>
Extension on SimpleValidationBuilder for nullable String? properties that allows either a valid string with no repeated characters or null.
RepeatedCharactersValidator on SimpleValidationBuilder<String>
Extension on SimpleValidationBuilder for String properties to add validation against sequential repeated characters.
RouterParams on Request
SequentialCharactersNullableValidator on SimpleValidationBuilder<String?>
Extension on SimpleValidationBuilder for nullable String? properties to add validation against sequential characters.
SequentialCharactersOrNullValidator on SimpleValidationBuilder<String?>
Extension on SimpleValidationBuilder for nullable String? properties that allows either a valid string with no sequential characters or null.
SequentialCharactersValidator on SimpleValidationBuilder<String>
Extension on SimpleValidationBuilder for String properties to add validation against sequential characters.
ValidCEPNullableValidation on SimpleValidationBuilder<String?>
ValidCEPOrNullableValidation on SimpleValidationBuilder<String?>
ValidCEPValidation on SimpleValidationBuilder<String>
ValidCnpjNullableValidation on SimpleValidationBuilder<String?>
ValidCnpjOrNullableValidation on SimpleValidationBuilder<String?>
ValidCnpjValidation on SimpleValidationBuilder<String>
ValidCPFNullableValidation on SimpleValidationBuilder<String?>
ValidCpfOrCnpjNullableValidation on SimpleValidationBuilder<String?>
ValidCpfOrCnpjOrNullableValidation on SimpleValidationBuilder<String?>
ValidCpfOrCnpjValidation on SimpleValidationBuilder<String>
ValidCPFOrNullableValidation on SimpleValidationBuilder<String?>
ValidCPFValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a valid CPF validation.
ValidCreditCardNullableValidation on SimpleValidationBuilder<String?>
ValidCreditCardOrNullableValidation on SimpleValidationBuilder<String?>
ValidCreditCardValidation on SimpleValidationBuilder<String>
ValidEmailNullableValidation on SimpleValidationBuilder<String?>
ValidEmailOrNullableValidation on SimpleValidationBuilder<String?>
ValidEmailValidation on SimpleValidationBuilder<String>
Extension on LucidValidationBuilder for String properties to add a valid email validation.
ValidPhoneNullableValidation on SimpleValidationBuilder<String?>
ValidPhoneOrNullableValidation on SimpleValidationBuilder<String?>
ValidPhoneValidation on SimpleValidationBuilder<String>
A validation extension for SimpleValidationBuilder<String> that provides methods to validate Brazilian phone numbers, both with and without country code.

Properties

addChunkedEncoding → Middleware
Middleware that adds chunked transfer coding to a responses if none of the following conditions are true:
final

Functions

changeParam<T>(T newValue) → ParamTransform
cors({List<String> allowedOrigins = const ['*'], List<String> allowMethods = const ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], List<String> allowHeaders = const ['Origin', 'Content-Type', 'Accept']}) → Middleware
Creates a middleware that handles Cross-Origin Resource Sharing (CORS).
createMiddleware({FutureOr<Response?> requestHandler(Request)?, FutureOr<Response> responseHandler(Response)?, FutureOr<Response> errorHandler(Object error, StackTrace)?}) → Middleware
Creates a Middleware using the provided functions.
extractClassName(String input) → String
handleRequest(HttpRequest request, Handler handler, {String? poweredByHeader = 'Dart with package:shelf'}) → Future<void>
Uses handler to handle request.
logRequests({void logger(String message, bool isError)?}) → Middleware
Middleware which prints the time of the request, the elapsed time for the inner handlers, the response's status code and the request URI.
params(Request request, String name) → String
Get a URL parameter captured by the Router.
serve(Handler handler, Object address, int port, {SecurityContext? securityContext, int? backlog, bool shared = false, String? poweredByHeader = 'Dart with package:shelf'}) → Future<HttpServer>
Starts an HttpServer that listens on the specified address and port and sends requests to handler.
serveRequests(Stream<HttpRequest> requests, Handler handler, {String? poweredByHeader = 'Dart with package:shelf'}) → void
Serve a Stream of HttpRequests.

Typedefs

AsyncResponseEntity<T> = Future<ResponseEntity<T>>
Represents a Future that resolves to a ResponseEntity
DisposeCallback<T> = void Function(T value)
FromJsonFunction<T> = T Function(Map<String, dynamic> json)
Type definition for a function that converts a JSON map to an object of type T.
Handler = FutureOr<Response> Function(Request request)
A function which handles a Request.
Middleware = Handler Function(Handler innerHandler)
A function which creates a new Handler by wrapping a Handler.
NotifierCallback<T> = dynamic Function(T value)
ParamTransform = Param? Function(Param param)
RuleFunc<Entity> = ValidationException? Function(Entity entity)
Builder class used to define validation rules for a specific property type TProp.
SimpleValidationBuilder<T> = LucidValidationBuilder<T, dynamic>
ToJsonFunction<T> = Map<String, dynamic> Function(T object)
Type definition for a function that converts an object of type T to a JSON map.
ToOpenApiNormalMap = Map<String, dynamic>
Type definition for a map that represents the OpenAPI schema for a type.

Exceptions / Errors

AutoInjectorException
AutoInjection Exception with ToString auto configured
message : message of exception
stackTrace : traces of exception
HijackException
An exception used to indicate that a request has been hijacked.
InjectorAlreadyCommited
AutoInjecton Exception for Injector Already Commited.
Store all parent classNames message : message of exception
stackTrace : traces of exception
injectorTag : tag of the current injector
ResponseException<W>
Exception class for handling HTTP responses with error states.
UnregisteredInstance
AutoInjection Exception for Unregistered instance.
Store all parent classNames message : message of exception
stackTrace : traces of exception
classNames : all parent class names
UnregisteredInstanceByKey
AutoInjection Exception for Unregistered instance.
Store all parent classNames message : message of exception
stackTrace : traces of exception
ValidationException
Represents an error that occurs during validation.