TypeScript

Category Theory for APIs

An HTTP/handler layer modeled as a category — objects are request/response types, morphisms are handlers, composition is middleware chaining — with the relevant laws enforced by property-based tests.

category-api banner
category-api — HTTP layer as a category

The idea

Category theory is often described as “abstract nonsense” — useful for mathematicians but irrelevant to software. This package tests that claim: can the HTTP request/response pipeline be usefully modeled as a category, and do the category laws actually tell you something useful about middleware correctness?

The answer: yes. Modeling handlers as morphisms and middleware composition as categorical composition immediately reveals associativity as a correctness requirement (the order of middleware application must not depend on parenthesization) and identity handlers as the category’s unit elements. Both laws are enforced by property-based tests using fast-check.

What is a category?

A category is one of the most economical structures in mathematics. It consists of objects and, between them, morphisms (also called arrows or maps). You do not look inside the objects; all the content lives in how the arrows connect and combine. To qualify as a category, three things must hold.

  • Composition. If f : A → B and g : B → C are morphisms, there is a composite g ∘ f : A → C. Arrows that line up can always be joined end to end.
  • Identity. Every object A has an identity morphism idₐ : A → A that does nothing when composed: id ∘ f = f and f ∘ id = f.
  • Associativity. Composition does not care how you group it: (h ∘ g) ∘ f = h ∘ (g ∘ f).

Those two equations — the identity law and the associativity law — are the category laws. They sound almost too obvious to state, but that is exactly why they are useful: any system that genuinely satisfies them inherits the entire toolbox of categorical reasoning, and any system that violates them has a concrete bug you can point at.

How this project demonstrates it

The mapping is direct. Objects are the request and response types. Morphisms are handlers, each a function (req: Req) → Promise<Res>. Composition is middleware chaining, (g ∘ f)(req) = g(f(req)), and the identity is a pass-through handler that returns its input untouched.

Written out this way, the two laws stop being abstract. Associativity becomes the requirement that a middleware chain behaves the same no matter how it is grouped — you can refactor logging(auth(handler)) into a pre-composed (logging ∘ auth) stage without changing behaviour. Identity becomes the guarantee that inserting a no-op middleware is always safe. The project encodes both as executable properties and hands them to fast-check, which generates random handler triples and random single handlers and searches for any input that breaks a law, shrinking failures to a minimal counterexample when it finds one.

Honest caveat: real HTTP handlers can perform side effects and are not pure functions, so “handlers form a category” is an idealization that holds for the composition behaviour being tested, not a claim that every possible handler is a well-behaved morphism. The value is that writing the laws down as property tests turns a vague sense of “middleware should be well-behaved” into checks that actually fail when composition misbehaves.

Category theory for APIs questions

What is a category in category theory?

A category is a collection of objects together with morphisms (arrows) between them, subject to two laws: morphisms compose associatively, and every object has an identity morphism that acts as a unit for composition. In this project the objects are request/response types and the morphisms are HTTP handlers.

How do the category laws apply to HTTP handlers?

Middleware chaining is composition: (g ∘ f)(req) = g(f(req)). A pass-through handler is the identity. Associativity means the outcome cannot depend on how the middleware chain is parenthesized, and identity means inserting a no-op handler changes nothing. Both are real correctness requirements, not just abstractions.

How are the category laws enforced?

With property-based tests using fast-check. Random handler triples check that (h ∘ g) ∘ f is equivalent to h ∘ (g ∘ f), and random handlers check that id ∘ f and f ∘ id both equal f. Instead of a few hand-picked cases, the tests probe many generated inputs to expose violations.

The mathematics

Category laws for HTTP handlers
Objects: Request types, Response types
Morphisms: Handler  =  (req: Req) → Promise<Res>

Composition:
  (g ∘ f)(req) = g(f(req))   (middleware chaining)

Identity morphism:
  id(req) = req   (pass-through middleware)

Category laws:
  1. Associativity: (h ∘ g) ∘ f  ≡  h ∘ (g ∘ f)
     → verified by property-based tests over random handler triples

  2. Left identity:   id ∘ f  ≡  f
  3. Right identity:  f ∘ id  ≡  f
     → verified by property-based tests over random handlers

Run it

git clone https://github.com/caelum0x/awesome-mad-projects.git
cd category-api

npm install
npm test        # property-based tests via fast-check
npm run build   # TypeScript compile check