@elysion/response

Consistent and type-safe API response helpers for Elysia and Web Standard Response.

Features

• 🚀 Type-safe responses with TypeScript
• 🛠️ Consistent response structure
• 🔌 Elysia plugin support
• 🏗️ Framework-agnostic core
• 📦 Zero dependencies (except Elysia for plugin)

Installation

bun add @elysion/response

Basic Usage

Response Helpers

import { res } from "@elysion/response";

// Success responses
res.ok({ data: { id: 1 } });
res.created({ data: { id: 1 } });

// Error responses
res.badRequest({ message: "Invalid input" });
res.unauthorized({ message: "Not logged in" });
res.forbidden({ message: "Insufficient permissions" });
res.notFound({ message: "Resource not found" });
res.serverError({ message: "Something went wrong" });

// No content (204)
res.noContent();

With Options

// With custom meta
res.ok({
  data: { id: 1 },
  meta: { timestamp: new Date().toISOString() },
});

// Override default status/message
res.badRequest({ message: "Validation failed", status: 422 });

Elysia Integration

import { Elysia } from "elysia";
import { responsePlugin } from "@elysion/response";

const app = new Elysia()
  .use(responsePlugin())
  .get("/", ({ res }) => res.ok())
  .post("/users", ({ res }) =>
    res.created({ data: { id: 1, name: "New User" } })
  )
  .get("/users/:id", ({ params: { id }, res }) => {
    if (id === "1") {
      return res.ok({ data: { id: 1, name: "Test User" } });
    }
    return res.notFound({ data: { error: "User not found" } });
  });

Response Structure

All responses follow this structure:

{
  data: T | null;     // Response data
  status: number;     // HTTP status code
  message: string;    // Status message
  meta?: {            // Optional metadata
    [key: string]: any;
  };
}

API Reference

Response Helpers

All helpers accept:

• data: Optional response data
• message: Optional message
• status: Optional status code
• meta: Optional metadata

Available helpers:

• ok(data?, message?, status?, meta?) - 200 OK
• created(data?, message?, status?, meta?) - 201 Created
• noContent(message?, status?, meta?) - 204 No Content
• badRequest(data?, message?, status?, meta?) - 400 Bad Request
• unauthorized(data?, message?, status?, meta?) - 401 Unauthorized
• forbidden(data?, message?, status?, meta?) - 403 Forbidden
• notFound(data?, message?, status?, meta?) - 404 Not Found
• serverError(data?, message?, status?, meta?) - 500 Internal Server Error

Features

• Consistent envelope { data, meta, status, message }
• Predefined helpers for common HTTP statuses
• Optional overrides for status, message, meta
• Works with Elysia or direct Web Response