Hello World API

import { Card, CardContent, CardHeader, CardTitle } from ‘@astrojs/starlight/components’; import { Tabs } from ‘@astrojs/starlight/components’;

Hello World API

A comprehensive Hello World API example that demonstrates the fundamental features of Veloce-TS framework.

Overview

This example showcases the core capabilities of Veloce-TS through a simple but feature-rich API that includes:

Decorator-based routing with @Controller, @Get, @Post
Request validation using Zod schemas
Query parameter extraction with the @Query decorator
Path parameters with @Param
Request body validation with @Body
OpenAPI documentation generation
TypeScript support with full type safety

Features Demonstrated

🎯 Core Decorators

@Controller('/hello') - Defines the controller base path
@Get('/') - HTTP GET endpoint
@Get('/:name') - Path parameter extraction
@Post('/') - HTTP POST endpoint with body validation

📝 Parameter Handling

@Param('name') - Extracts path parameters
@Query() - Extracts query parameters (NEW in v0.2.6)
@Body(Schema) - Validates request body with Zod

📚 Documentation

@ApiDoc() - Adds OpenAPI documentation
Automatic schema generation
Interactive API documentation

Project Structure

hello_world/
├── src/
│   ├── controllers/
│   │   └── hello.controller.ts    # Main controller
│   └── index.ts                   # Application entry point
├── public/
│   └── docs.html                  # API documentation
├── package.json
├── tsconfig.json
└── README.md

API Endpoints

1. Simple Hello World

GET /hello

Response:

{
  "message": "Hello World!",
  "timestamp": "2025-10-15T19:12:09.119Z",
  "version": "1.0.0"
}

2. Personalized Greeting

GET /hello/:name?language=es&format=text

Parameters:

name (path): The name to greet
language (query): Language for greeting (en, es, fr)
format (query): Response format (json, text)

Examples:

GET /hello/Alfredo → "Hello, Alfredo!"
GET /hello/Alfredo?language=es → "¡Hola, Alfredo!"
GET /hello/Alfredo?language=fr&format=text → "Bonjour, Alfredo!"

3. Create Custom Greeting

POST /hello
Content-Type: application/json

{
  "name": "World",
  "message": "Custom greeting",
  "language": "en"
}

4. List All Greetings

GET /hello/greetings

5. Get Greeting by ID

GET /hello/greetings/:id

6. API Information

GET /hello/api/info

Key Code Examples

Controller Setup

import {
  Controller,
  Get,
  Post,
  Body,
  Param,
  Query,
  ApiDoc
} from 'veloce-ts';
import { z } from 'zod';

const GreetingSchema = z.object({
  name: z.string().min(1, 'Name is required').max(50, 'Name too long'),
  message: z.string().optional(),
  language: z.enum(['en', 'es', 'fr']).optional().default('en'),
});

@Controller('/hello')
export class HelloController {
  private greetings: any[] = [];

  @Get('/')
  @ApiDoc({
    summary: 'Say Hello World',
    description: 'Returns a simple hello message'
  })
  async hello() {
    return {
      message: 'Hello World!',
      timestamp: new Date().toISOString(),
      version: '1.0.0'
    };
  }

  @Get('/:name')
  @ApiDoc({
    summary: 'Say Hello to someone',
    description: 'Returns a personalized greeting message'
  })
  async helloName(
    @Param('name') name: string,
    @Query() query: any
  ) {
    const language = query?.language || 'en';
    const format = query?.format || 'json';

    const greeting = this.getGreeting(name, language);

    if (format === 'text') {
      return greeting;
    }

    return {
      message: greeting,
      name: name,
      language: language,
      timestamp: new Date().toISOString(),
      format: format
    };
  }

  @Post('/')
  @ApiDoc({
    summary: 'Create a custom greeting',
    description: 'Store a custom greeting message'
  })
  async createGreeting(@Body(GreetingSchema) greeting: any) {
    const newGreeting = {
      ...greeting,
      id: this.greetings.length + 1,
      createdAt: new Date().toISOString()
    };

    this.greetings.push(newGreeting);

    return {
      message: 'Greeting created successfully',
      id: newGreeting.id,
      greeting: newGreeting
    };
  }

  private getGreeting(name: string, language: string = 'en'): string {
    const greetings = {
      en: `Hello, ${name}!`,
      es: `¡Hola, ${name}!`,
      fr: `Bonjour, ${name}!`
    };

    return greetings[language as keyof typeof greetings] || greetings.en;
  }
}

import 'reflect-metadata';
import { VeloceTS } from 'veloce-ts';
import { HelloController } from './controllers/hello.controller';

const app = new VeloceTS({
  title: 'Veloce-TS Hello World API',
  version: '1.0.0',
  description: 'A simple Hello World API demonstrating Veloce-TS basics'
});

// Enable CORS for all origins
app.use('*', (c, next) => {
  c.header('Access-Control-Allow-Origin', '*');
  c.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  c.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  return next();
});

// Serve static files
app.static('/public', './public');

// Include OpenAPI plugin for documentation
app.install('openapi');

// Include controllers
app.include(HelloController);

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log('🚀 Veloce-TS Hello World API is running!');
  console.log('');
  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
  console.log(`🌐 Server:          http://localhost:${PORT}`);
  console.log(`📖 API Docs:        http://localhost:${PORT}/docs.html`);
  console.log(`📄 OpenAPI Spec:    http://localhost:${PORT}/openapi.json`);
  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
  console.log('');
  console.log('💡 Try these endpoints:');
  console.log('  • GET  /hello');
  console.log('  • GET  /hello/:name');
  console.log('  • POST /hello');
  console.log('  • GET  /api/info');
  console.log('');
  console.log('🎉 Happy coding!');
});

What’s New in v0.2.6

This example demonstrates the fixed @Query decorator that now works correctly:

Before (v0.2.5 and earlier):

// Had to use @Ctx() to manually extract query parameters
async helloName(@Param('name') name: string, @Ctx() c: any) {
  const query = c.req.query();
  const language = query?.language || 'en';
}

Now (v0.2.6):

// Clean and simple with @Query() decorator
async helloName(@Param('name') name: string, @Query() query: any) {
  const language = query?.language || 'en';
}

Quick Start

Create a new project:

bun veloce-ts new hello_world --template rest
cd hello_world

Install dependencies:
Terminal window
```
bun install
```
Replace the generated controller with the HelloController code above

Update package.json to use the latest version:

{
  "dependencies": {
    "veloce-ts": "^0.2.6"
  }
}

Run the server:
Terminal window
```
bun run dev
```

Test the API:

# Simple hello
curl http://localhost:3000/hello

# Personalized greeting in Spanish
curl "http://localhost:3000/hello/Alfredo?language=es"

# Text format greeting in French
curl "http://localhost:3000/hello/World?language=fr&format=text"

Learning Path

This example is perfect for:

Beginners learning Veloce-TS fundamentals
Understanding decorators and their usage
Learning parameter extraction with @Query, @Param, @Body
Exploring validation with Zod schemas
Understanding OpenAPI documentation generation

Next Steps

After mastering this example, explore:

TaskMaster Example - Full-featured application with authentication, RBAC, and database
Decorators Guide - Comprehensive decorator reference
Dependency Injection - Advanced DI patterns
Plugins Guide - Extending Veloce-TS functionality

API Documentation

Once running, visit:

Interactive Docs: http://localhost:3000/docs.html
OpenAPI Spec: http://localhost:3000/openapi.json

This example provides a solid foundation for building more complex Veloce-TS applications!