@hectoday/http

An explicit, standards-first HTTP framework built for learning.

@hectoday/http is a minimal web framework that exposes the real mechanics of HTTP. Nothing is hidden. No magic. Every step is visible and intentional.

It is designed first and foremost as a teaching tool, but it is fully usable for real applications.

---

Why this exists

Most frameworks abstract HTTP away.

@hectoday/http does the opposite.

You work directly with:

• Request and Response (Web Standards)
• Headers, status codes, and URLs
• Explicit routing and validation
• Pure guard functions

So you actually learn how the web works — not just how to use a framework.

---

Quick Example

import { route, setup } from "@hectoday/http";
import { z } from "zod";

const app = setup({
  handlers: [
    route.get("/", {
      resolve: () => new Response("Hello HTTP"),
    }),
    
    route.post("/users", {
      request: {
        body: z.object({
          name: z.string(),
          email: z.string().email(),
        }),
      },
      resolve: (c) => {
        if (!c.input.ok) {
          return Response.json({ error: c.input.issues }, { status: 400 });
        }
        
        const { name, email } = c.input.body; // Fully typed!
        return Response.json({ name, email }, { status: 201 });
      },
    }),
  ],
});

Deno.serve(app.fetch);

No wrappers. No custom response objects. Just HTTP.

---

Design Principles

• Web standards first
  Built on the Fetch API and platform primitives.

• Explicit control flow
  You always decide what happens. No implicit behavior. No hidden responses.

• Minimal surface area
  Small API. Easy to reason about.

• Education-first
  Clarity > convenience. Understanding > shortcuts.

---

What Makes It Different

1. Nothing is Hidden

// Other frameworks
app.get("/user", (req, res) => {
  res.json({ user }); // What status? What headers? Where's the Response?
});

// Hectoday HTTP
route.get("/user", {
  resolve: () => {
    return Response.json({ user }); // Explicit Web Standard Response
  }
});

2. You Control All Decisions

// Validation describes facts, YOU decide what it means
if (!c.input.ok) {
  // Your choice: 400? 422? Custom format?
  return Response.json({ error: c.input.issues }, { status: 400 });
}

// Guards describe authorization, YOU decide the response
const requireAuth: GuardFn = (c) => {
  if (!isAuthorized(c)) {
    return { deny: Response.json({ error: "Unauthorized" }, { status: 401 }) };
  }
  return { allow: true };
};

3. Request Lifecycle is Explicit

Request → onRequest → Route Match → Validate → Guards → Handler → onResponse → Response

Every step is visible. No magic middleware chains.

---

What This Is Great For

• Learning HTTP properly
  Understand requests, responses, headers, status codes

• Teaching web fundamentals
  Show students how the web actually works

• Understanding request lifecycles
  See every step from request to response

• Building APIs
  Production-ready for Deno, Bun, Cloudflare Workers

• Experimenting with HTTP
  Protocol-level control for research and prototyping

---

What This Is Not

• A batteries-included framework
• A "magic" DX-first abstraction
• A framework that makes decisions for you

This project values clarity over convenience.

---

Documentation

Full documentation: https://docs.hectoday.com

Start here:

• How to Read These Docs
• A Mental Model of HTTP
• Your First Server

Core concepts:

• The Web Standard Foundation
• Validation Without Control Flow
• Guards: Making Decisions Explicit
• Hooks: The Three Extension Points

Helpers (copy-paste recipes):

• helpers

---

Installation

# Deno
deno add jsr:@hectoday/http

# Bun
bunx jsr add @hectoday/http

# npm
npx jsr add @hectoday/http

---

Examples

See working examples in example/:

• Deno example - Full-featured API with auth, validation, guards
• Bun example - Basic Bun setup

---

Contributing

Contributions are welcome ❤️

• Code improvements
• Documentation fixes and clarifications
• More examples
• Typos and formatting

See CONTRIBUTING.md.

---

License

• Code: MIT
• Documentation: CC BY 4.0 (see apps/docs/LICENSE)

---

Philosophy

Learn the protocol. Then build the abstractions.

Hectoday HTTP teaches you HTTP by exposing it, not hiding it. Once you understand how HTTP works at the protocol level, you can build any abstraction you need.

---

Monorepo Structure

This repository contains:

• packages/http/ - Core framework
• apps/docs/ - Documentation site
• example/ - Example applications
• benchmarks/ - Performance benchmarks

---

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with clarity in mind. No magic. Just HTTP.