Request & Response

Harpia provides extended versions of the native standard Request and Response objects. These wrappers add convenient methods and properties for building web applications while maintaining full compatibility with Bun’s native HTTP ecosystem.

Request

The Request object in Harpia inherits from the standard Web API Request, which means you can use all standard methods like req.json(), req.text(), and req.headers.get(). Harpia augments it with additional parsed data.

Properties

• req.params: An object containing the dynamic route parameters.
• req.query: An object containing the parsed URL query string parameters.
• req.method: The HTTP method in uppercase (e.g., "GET", "POST").

Cookies

Harpia provides a convenient API for reading incoming cookies.

• req.cookies.get(name: string): Returns the value of a specific cookie, or undefined if not found.
• req.cookies.getAll(): Returns an object containing all parsed cookies.

Example

app.post("/search/:category", async (req, res) => {
  // Accessing route parameters
  const category = req.params.category;
  
  // Accessing query parameters (?q=keyword)
  const searchQuery = req.query.q;
  
  // Accessing headers and standard Request methods
  const userAgent = req.headers.get("user-agent");
  const body = await req.json(); // Parse JSON body
  
  // Reading cookies
  const sessionId = req.cookies.get("session_id");

  res.json({ category, searchQuery, body });
});

Response

The Response wrapper in Harpia provides a fluent, chainable API for constructing HTTP responses.

Chainable Methods

• res.status(code: number): Sets the HTTP status code (defaults to 200).
• res.send(data: any): Sends raw data, text, or buffers.
• res.json(data: any): Sends a JSON response and automatically sets the Content-Type header to application/json.
• res.html(data: string): Sends an HTML string and sets the Content-Type to text/html.
• res.redirect(url: string, status?: number): Redirects the client to a different URL (defaults to 302).

Headers

You can manipulate response headers directly using the res.headers instance (which is a standard Web API Headers object).

res.headers.set("X-Custom-Header", "Harpia");

Cookies

Setting and deleting cookies is simple with the res.cookies API.

• res.cookies.set(name: string, value: string, options?: CookiesOptions)
• res.cookies.delete(name: string, options?: CookiesOptions)

app.post("/login", (req, res) => {
  res.cookies.set("token", "jwt-token-here", {
    httpOnly: true,
    secure: true,
    maxAge: 3600
  });
  
  res.status(200).json({ message: "Logged in" });
});

Template Rendering

If you have configured a Template Engine (like Edge.js), you can render views directly from the response.

• res.render(view: string, data?: object): Renders a template file and sends the resulting HTML.
• res.module(name: string): Scopes the view resolution to a specific module directory.

app.get("/profile", async (req, res) => {
  const user = { name: "Lucas", role: "Admin" };
  
  // Renders the 'profile' view passing the user object
  await res.render("profile", { user });
});

For more details about template engines, see the Template Engine documentation.