effect-ontology: Skill for Claude Code

HTTP & Routing

When to use

• Adding HTTP routes, path params, JSON responses
• Wiring handlers to services via layers
• Implementing small proxy/adapter endpoints

Minimal Handler

import * as HttpRouter from "@effect/platform/HttpRouter"
import * as HttpServer from "@effect/platform/HttpServer"
import * as HttpResponse from "@effect/platform/HttpServerResponse"

const app = HttpRouter.empty.pipe(
  HttpRouter.get("/ping", Effect.succeed(HttpResponse.text("pong")))
)

JSON

const userHandler = Effect.flatMap(HttpRouter.params, (p) =>
  Effect.flatMap(UserRepo, (r) => r.get(p["id"] ?? "")).pipe(
    Effect.flatMap(HttpResponse.json)
  )
)

Serve (Node)

const server = HttpServer.serve(app)
// provide NodeHttpServer.layer(...) and dependencies

Guidance

• Keep handlers thin: decode/validate, call service, encode response
• Use Schema for body/param validation; return structured errors
• Provide dependencies once via composed App layer

Pitfalls

• Skipping validation on inputs → use Schema
• Doing heavy work in handler → push into services (layers)

Cross-links

• Config & Schema for validation
• Layers & Services for DI wiring

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/. Always search the actual implementation before writing Effect code.

Key Source Files

• HttpRouter: docs/effect-source/platform/src/HttpRouter.ts
• HttpServer: docs/effect-source/platform/src/HttpServer.ts
• HttpServerResponse: docs/effect-source/platform/src/HttpServerResponse.ts
• HttpServerRequest: docs/effect-source/platform/src/HttpServerRequest.ts

Example Searches

# Find routing patterns
grep -F "HttpRouter.get" docs/effect-source/platform/src/HttpRouter.ts
grep -F "HttpRouter.post" docs/effect-source/platform/src/HttpRouter.ts

# Study response helpers
grep -F "json" docs/effect-source/platform/src/HttpServerResponse.ts
grep -F "text" docs/effect-source/platform/src/HttpServerResponse.ts
grep -F "html" docs/effect-source/platform/src/HttpServerResponse.ts

# Find server setup
grep -F "serve" docs/effect-source/platform/src/HttpServer.ts
grep -F "listen" docs/effect-source/platform/src/HttpServer.ts

# Look at request handling
grep -F "params" docs/effect-source/platform/src/HttpServerRequest.ts
grep -F "body" docs/effect-source/platform/src/HttpServerRequest.ts
grep -F "headers" docs/effect-source/platform/src/HttpServerRequest.ts