Referencia API

Referencia API

Referencia API completa para el framework Veloce-TS.

Tabla de Contenidos

• Clases Principales
• Decoradores
• Sistema de Plugins
• Utilidades de Prueba
• Clases de Error
• Tipos

---

Clases Principales

Veloce

La clase principal de la aplicación.

Constructor

new Veloce(config?: VeloceConfig)

Parámetros:

• config (opcional): Objeto de configuración

Interfaz VeloceConfig:

interface VeloceConfig {
  adapter?: 'hono' | 'express' | 'native';
  title?: string;
  version?: string;
  description?: string;
  docs?: boolean | { path?: string; openapi?: string };
  cors?: CorsOptions | boolean;
  plugins?: Plugin[];
}

Ejemplo:

const app = new Veloce({
  title: 'Mi API',
  version: '1.0.0',
  description: 'API para mi aplicación',
  docs: true,
  cors: true,
});

Métodos Principales

include(controller: Class): void

Registra una clase controlador con la aplicación.

@Controller('/users')
class UserController {
  @Get('/')
  async list() {
    return [];
  }
}

app.include(UserController);

get/post/put/delete/patch(path: string, config: RouteConfig): void

Registra rutas usando la API funcional.

app.get('/users', {
  handler: async (c) => {
    return [{ id: 1, name: 'John' }];
  },
});

usePlugin(plugin: Plugin): void

Registra un plugin con la aplicación.

import { OpenAPIPlugin } from 'veloce-ts';

app.usePlugin(new OpenAPIPlugin({
  path: '/openapi.json',
  docsPath: '/docs',
}));

listen(port: number, callback?: () => void): Server

Inicia el servidor en el puerto especificado.

app.listen(3000, () => {
  console.log('Servidor ejecutándose en http://localhost:3000');
});

getContainer(): DIContainer

Obtiene el contenedor de inyección de dependencias.

const container = app.getContainer();
container.register(DatabaseService, { scope: 'singleton' });

---

Decoradores

Decoradores de Clase

@Controller(prefix?: string)

Marca una clase como controlador y opcionalmente establece un prefijo de ruta.

@Controller('/api/users')
class UserController {
  @Get('/')
  async list() {
    return [];
  }
}

@WebSocket(path: string)

Marca una clase como manejador de WebSocket.

@WebSocket('/chat')
class ChatHandler {
  @OnConnect()
  handleConnect(client: WebSocketConnection) {
    console.log('Conectado');
  }
}

@Resolver()

Marca una clase como resolver de GraphQL.

@Resolver()
class UserResolver {
  @Query()
  async users() {
    return [];
  }
}

Decoradores de Método

Decoradores de Métodos HTTP

• @Get(path?: string) - Registra una ruta GET
• @Post(path?: string) - Registra una ruta POST
• @Put(path?: string) - Registra una ruta PUT
• @Delete(path?: string) - Registra una ruta DELETE
• @Patch(path?: string) - Registra una ruta PATCH
• @All(path?: string) - Responde a todos los métodos HTTP

Ejemplo:

@Get('/users')
async getUsers() {
  return [];
}

@Post('/users')
async createUser(@Body(UserSchema) user: User) {
  return user;
}

Decoradores de GraphQL

• @Query() - Define una consulta GraphQL
• @Mutation() - Define una mutación GraphQL
• @Subscription() - Define una suscripción GraphQL

Decoradores de WebSocket

• @OnConnect() - Maneja eventos de conexión
• @OnMessage(schema?: ZodSchema) - Maneja eventos de mensaje
• @OnDisconnect() - Maneja eventos de desconexión

Decoradores de Parámetro

@Body(schema?: ZodSchema)

Extrae y valida el cuerpo de la petición.

const UserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

@Post('/users')
async createUser(@Body(UserSchema) user: z.infer<typeof UserSchema>) {
  return user;
}

@Query(schema?: ZodSchema)

Extrae y valida parámetros de consulta.

const SearchSchema = z.object({
  q: z.string(),
  page: z.string().transform(Number).default('1'),
});

@Get('/search')
async search(@Query(SearchSchema) query: z.infer<typeof SearchSchema>) {
  return { query: query.q, page: query.page };
}

@Param(name?: string)

Extrae parámetros de ruta.

@Get('/users/:id')
async getUser(@Param('id') id: string) {
  return { id };
}

@Header(name?: string, schema?: ZodSchema)

Extrae y valida encabezados.

@Get('/protected')
async getProtected(@Header('authorization') auth: string) {
  return { auth };
}

@Cookie(name?: string, schema?: ZodSchema)

Extrae y valida cookies.

@Get('/profile')
async getProfile(@Cookie('session') sessionId: string) {
  return { sessionId };
}

@Depends(provider: Provider, scope?: Scope)

Inyecta dependencias.

class UserService {
  async getUsers() {
    return [];
  }
}

@Controller('/users')
class UserController {
  @Get('/')
  async list(@Depends(UserService) userService: UserService) {
    return await userService.getUsers();
  }
}

---

Sistema de Plugins

Interfaz de Plugin

interface Plugin {
  name: string;
  version?: string;
  dependencies?: string[];
  install(app: Veloce): void | Promise<void>;
}

Creando un Plugin

class MyPlugin implements Plugin {
  name = 'my-plugin';
  version = '1.0.0';

  install(app: Veloce) {
    // Agregar rutas
    app.get('/plugin-route', {
      handler: async (c) => {
        return { message: 'Desde el plugin' };
      },
    });
  }
}

Plugins Integrados

OpenAPIPlugin

import { OpenAPIPlugin } from 'veloce-ts';

app.usePlugin(new OpenAPIPlugin({
  path: '/openapi.json',
  docsPath: '/docs',
  title: 'Mi API',
  version: '1.0.0',
}));

GraphQLPlugin

import { GraphQLPlugin } from 'veloce-ts';

app.usePlugin(new GraphQLPlugin({
  path: '/graphql',
  playground: true,
}));

---

Utilidades de Prueba

createTestApp(config?: VeloceConfig): Veloce

Crea una instancia de prueba de la aplicación.

import { createTestApp } from 'veloce-ts/testing';

const app = createTestApp();
app.include(UserController);

TestClient

Cliente HTTP para hacer peticiones de prueba.

import { TestClient } from 'veloce-ts/testing';

const client = new TestClient(app);

const response = await client.get('/users');
const data = await response.json();

expect(response.status).toBe(200);

mockDependency(provider: Class, mock: any): void

Simula una dependencia en el contenedor DI.

import { mockDependency } from 'veloce-ts/testing';

const mockUserService = {
  getUsers: async () => [{ id: 1, name: 'Prueba' }],
};

mockDependency(UserService, mockUserService);

---

Clases de Error

HTTPException

Clase de excepción base para errores HTTP.

import { HTTPException } from 'veloce-ts';

@Get('/users/:id')
async getUser(@Param('id') id: string) {
  const user = await db.getUserById(id);

  if (!user) {
    throw new HTTPException(404, 'Usuario no encontrado');
  }

  return user;
}

Otras Excepciones

• ValidationException - Errores de validación (422)
• NotFoundException - No encontrado (404)
• UnauthorizedException - No autorizado (401)
• ForbiddenException - Prohibido (403)

---

Tipos

VeloceConfig

interface VeloceConfig {
  adapter?: 'hono' | 'express' | 'native';
  title?: string;
  version?: string;
  description?: string;
  docs?: boolean | { path?: string; openapi?: string };
  cors?: CorsOptions | boolean;
  plugins?: Plugin[];
}

Middleware

type Middleware = (c: Context, next: () => Promise<void>) => Promise<void> | void;

Scope

type Scope = 'singleton' | 'request' | 'transient';

WebSocketConnection

interface WebSocketConnection {
  id: string;
  send(data: any): void;
  broadcast(data: any, includeSelf?: boolean): void;
  join(room: string): void;
  leave(room: string): void;
  close(): void;
}

---

Próximos Pasos

• Lee la Guía de Decoradores
• Aprende sobre Inyección de Dependencias
• Explora Plugins
• Revisa la Guía de Pruebas
• Ve la Guía de Inicio