@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

Core API

import { createApiResponse } from '@elysion/response';

// Basic response
const res = createApiResponse({
  data: { id: 1, name: 'Test' },
  status: 201,
  message: 'Created',
  meta: { page: 1, total: 10 }
});

Response Helpers

import { response } from '@elysion/response';

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

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

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

With Options

// With custom headers
response.ok(
  { data: { id: 1 } },
  {
    headers: { 'X-Custom-Header': 'value' },
    meta: { timestamp: new Date().toISOString() }
  }
);

// Override default status/message
response.badRequest(
  { error: 'Validation failed' },
  { status: 422, message: 'Validation Error' }
);

Elysia Integration

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

const app = new Elysia()
  .use(responsePlugin())
  .get('/', ({ response }) => 
    response.ok({ status: 'ok' })
  )
  .post('/users', ({ response }) => 
    response.created({ id: 1, name: 'New User' })
  )
  .get('/users/:id', ({ params: { id }, response }) => {
    if (id === '1') {
      return response.ok({ id: 1, name: 'Test User' });
    }
    return response.notFound({ 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

Core Functions

createApiResponse(options: ApiResponseOptions): Response

Creates a standard API response.

Response Helpers

All helpers accept:

• data: The response data
• options: Optional overrides (status, message, headers, meta)

Available helpers:

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

Types

interface ApiResponseOptions<T = any> {
  data?: T | null;
  status?: number;
  message?: string;
  headers?: Record<string, string>;
  meta?: Record<string, any>;
}

interface ApiResponse<T = any> {
  data: T | null;
  status: number;
  message: string;
  meta?: Record<string, any>;
}

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