API Bridge

The runHandlerBridge (found in features/shared/bridge.ts) is the final step in the server logic. It takes a purely functional Effect and executes it, converting the result into a standardized JSON response.

Bridge responsibilities

1. Execution: It uses Effect.runPromise to execute the program.
2. Success Shaping: On success, it returns a 200 OK (default) wrapped in the APIResponse object which includes metadata like requestId.
3. Error Mapping: On failure, it extracts the error and uses getHttpStatus(error) to determine the correct HTTP status code (e.g., 404 for NotFoundError, 400 for ValidationError).
4. Consistency: It ensures that every response from the server follows the same JSON structure, making it easier for the frontend to parse.

Example usage in a Hono route

app.get("/:id", async (c) => {
  const context = getHandlerContext(c);
  const program = MyService.findById(c.req.param("id"));

  return await runHandlerBridge(program, context, {
    successMessage: "Record retrieved successfully"
  });
});

Standard response shape

{
  "success": true,
  "data": { ... },
  "message": "Record retrieved successfully",
  "meta": {
    "requestId": "...",
    "path": "..."
  }
}

Determining HTTP status

The bridge relies on the lib/errors/http.ts mapping utility. It looks at the custom Error classes (usually defined via Data.TaggedError in Effect) and maps them:

• NotFoundError → 404
• ValidationError → 400
• UnauthorizedError → 401
• DatabaseError → 503
• All others → 500