Why Choose farrow-http?

🎯 A modern tutorial that makes you fall in love with type-safe web development 🚀 From zero to hero, master the TypeScript web framework

---

Introduction: Why Use farrow-http?

Imagine you're developing an API with Express.js. There's a route like this:

// 😱 Daily struggles with Express.js
app.get('/users/:id', (req, res) => {
  const id = req.params.id  // Is this string or number? Who knows!
  const user = getUserById(id)

  if (user) {
    res.json(user)
  }
  // 💀 Oops, forgot to handle case where user doesn't exist
  // Client will wait forever for response...
})

Now, let farrow-http save you:

// ✨ farrow-http's elegant approach
app.get('/users/<id:int>').use((req) => {
  const user = getUserById(req.params.id)  // id automatically inferred as number type!

  if (!user) {
    return Response.status(404).json({ error: 'User does not exist' })
  }

  return Response.json(user)  // Compiler forces you to return response!
})

Three Killer Features:

1. Type Safety to the Teeth - URL patterns automatically infer types, compiler helps you catch errors
2. Auto Validation - Schema definition is validation rule, say goodbye to manual checks
3. Forced Return - Functional middleware must return Response, never forget to respond again

---

Hello World (30 seconds to get started)

Install Dependencies

npm install farrow-http farrow-schema farrow-pipeline
# or
pnpm add farrow-http farrow-schema farrow-pipeline

Your First API

import { Http, Response } from 'farrow-http'

const app = Http()

app.get('/').use(() => {
  return Response.json({ message: 'Hello farrow-http! 🎉' })
})

app.listen(3000, () => {
  console.log('🚀 Server started: http://localhost:3000')
})

Visit http://localhost:3000, you'll see:

{ "message": "Hello farrow-http! 🎉" }

That's it? Yes! 3 lines of code, an API service is running.

Core Advantages

1. Type-Safe Routing

// Path parameters automatically infer types
app.get('/users/<id:int>').use((req) => {
  req.params.id  // Type: number, validated as integer
  return Response.json({ userId: req.params.id })
})

// Query parameters automatically infer
app.get('/search?<q:string>&<page?:int>').use((req) => {
  req.query.q     // Type: string (required)
  req.query.page  // Type: number | undefined (optional)
  return Response.json({ query: req.query.q })
})

2. Schema Auto Validation

import { ObjectType, String, Int } from 'farrow-schema'

class CreateUserInput extends ObjectType {
  name = String
  age = Int
}

app.post('/users', { body: CreateUserInput }).use((req) => {
  // req.body is validated, type-safe!
  const { name, age } = req.body
  return Response.status(201).json({ name, age })
})

3. Functional Middleware

// Onion model, must return Response
app.use((req, next) => {
  console.log('Before request')
  const response = next(req)
  console.log('After request')
  return response  // Must return!
})

Comparison with Express

Feature	Express	farrow-http
Type Safety	❌ Manual assertion	✅ Auto inference
Runtime Validation	❌ Manual validation	✅ Schema auto validation
Forced Return	❌ Easy to forget	✅ Compiler enforced
URL Parameter Types	❌ All strings	✅ Supports int/float/boolean etc.
Middleware Model	Callback hell	Pure function + onion model
Async Support	async/await	async/await + Pipeline

Quick Examples

import { Http, Response } from 'farrow-http'
import { ObjectType, String, Int } from 'farrow-schema'

const app = Http()

// 1. Simple route
app.get('/').use(() => {
  return Response.json({ message: 'Welcome' })
})

// 2. Path parameters
app.get('/users/<id:int>').use((req) => {
  return Response.json({ userId: req.params.id })
})

// 3. Query parameters
app.get('/search?<q:string>').use((req) => {
  return Response.json({ query: req.query.q })
})

// 4. Request body validation
class CreatePostInput extends ObjectType {
  title = String
  content = String
}

app.post('/posts', { body: CreatePostInput }).use((req) => {
  return Response.status(201).json(req.body)
})

app.listen(3000)

Next Steps

Now you understand the core advantages of farrow-http, let's dive deeper:

1. Routing and Type Magic - Master URL patterns and type inference
2. Request Body Validation - Use Schema to validate data
3. Response Building - Build various response types