Effectful Todo API

A modern Todo API built with Effect-TS, Hono, and Drizzle ORM, demonstrating functional programming patterns and robust error handling.

Features

• ✅ Effect-TS Integration - Functional programming with composable effects
• ✅ Type-Safe Database - Drizzle ORM with PostgreSQL
• ✅ Schema Validation - Runtime type checking with Effect Schema
• ✅ Structured Error Handling - Comprehensive error types and responses
• ✅ RESTful API - Complete CRUD operations for todos
• ✅ Health Monitoring - Built-in health check endpoint

Tech Stack

• Runtime: Bun
• Web Framework: Hono
• Effect System: Effect-TS
• Database: PostgreSQL with Drizzle ORM
• Schema Validation: Effect Schema
• Language: TypeScript

Prerequisites

• Bun (latest version)
• PostgreSQL database

Getting Started

1. Clone and Install

git clone https://github.com/novaru/effectful-todo
cd effectful-todo
bun install

2. Environment Setup

Create a .env file based on .env.example:

cp .env.example .env

Configure your database connection:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=hono_todos
DB_USER=postgres
DB_PASSWORD=your_password

3. Database Setup

Generate and run migrations:

# Generate migration files
bun run db:generate

# Run migrations
bun run db:migrate

# Optional: Open Drizzle Studio
bun run db:studio

4. Start Development Server

bun run dev

The API will be available at http://localhost:3000

API Endpoints

Health Check

• GET /health - Server health status

Todos

• GET /todos - Get all todos
• GET /todos/:id - Get a specific todo
• POST /todos - Create a new todo
• PATCH /todos/:id - Mark todo as complete
• PUT /todos/:id - Update todo (limited functionality)
• DELETE /todos/:id - Delete a todo

API Examples

Create a Todo

curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"text": "Buy groceries"}'

Get All Todos

curl http://localhost:3000/todos

Complete a Todo

curl -X PATCH http://localhost:3000/todos/{todo-id}

Response Format

All responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Todo text cannot be empty",
    "field": "text"
  }
}

Project Structure

src/
├── shared/
│   ├── errors.ts          # Custom error classes
│   ├── validation.ts      # Request schemas & parsing
│   ├── effect-handler.ts  # Effect handling logic
│   └── response.ts        # Response utilities
├── routes/
│   ├── health.ts          # Health check endpoint
│   ├── todos.ts           # Todo routes
│   └── index.ts           # Route composition
├── todo/
│   ├── model.ts           # Todo domain models
│   └── repository.ts      # Todo repository layer
├── drizzle/
│   ├── database.ts        # Database configuration
│   └── schema.ts          # Database schema
└── index.ts               # App composition

Development Scripts

# Development
bun run dev          # Start development server with hot reload

# Production
bun run build        # Build optimized bundle using scripts/build.ts
bun run start        # Start development server
bun run start:prod   # Start production server using built bundle

# Database operations
bun run db:generate  # Generate migrations
bun run db:migrate   # Run migrations
bun run db:studio    # Open Drizzle Studio

# Testing
bun run test         # Run tests

Architecture Highlights

Effect-TS Integration

• Composable Effects: All operations are modeled as Effect computations
• Type-Safe Error Handling: Compile-time guarantees for error types
• Dependency Injection: Clean service layer architecture
• Resource Management: Automatic cleanup and resource handling

Modular Design

• Separation of Concerns: Clear boundaries between layers
• Testability: Each module can be tested independently
• Maintainability: Easy to locate and modify functionality
• Scalability: Simple to extend with new features

Error Handling

The API provides comprehensive error handling with specific error types:

• VALIDATION_ERROR - Invalid input data
• NOT_FOUND - Resource not found
• REQUEST_BODY_ERROR - Malformed request body
• INTERNAL_ERROR - Server errors

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License