Adapters Overview

Asena uses a pluggable adapter system that allows you to choose the HTTP server implementation that best fits your needs. This architectural decision provides flexibility while maintaining a consistent API across all adapters.

What is an Adapter?

An adapter is a bridge between Asena's core framework and the underlying HTTP server implementation. It handles:

• HTTP request/response processing
• WebSocket connections
• Middleware execution
• Static file serving
• Context wrapping

Available Adapters

Asena currently provides two official adapters:

Ergenecore (Native Bun)

The fastest adapter for production workloads

• ⚡ Performance: ~295k req/sec
• 📦 Dependencies: Zero (except Zod)
• 🔧 Runtime: Bun-exclusive
• 🎯 Use Case: Production APIs, microservices

Hono Adapter

Familiar and battle-tested

• ⚡ Performance: ~233k req/sec
• 📦 Dependencies: Hono framework
• 🔧 Runtime: Bun (can be ported to Node)
• 🎯 Use Case: Projects using Hono, gradual migration

Performance Comparison

Adapter	Requests/sec	Latency (avg)	Memory Usage
Ergenecore	294,962	1.34ms	Low
Hono	233,182	1.70ms	Low
Hono (standalone)	266,476	1.49ms	Low
NestJS (Bun)	100,975	3.92ms	Medium
NestJS (Node)	88,083	5.33ms	High

TIP

Benchmark conditions: 12 threads, 400 connections, 120s duration, Hello World endpoint

Feature Comparison

Feature	Ergenecore	Hono
HTTP Methods	✅	✅
WebSocket Support	✅	✅
Middleware System	✅	✅
Request Validation	✅ (Zod)	✅ (Zod)
Static File Serving	✅	✅
Cookie Support	✅	✅
CORS Middleware	✅	✅
Rate Limiting	✅	✅

Choosing the Right Adapter

Use Ergenecore when:

• ✅ You need maximum performance
• ✅ You're building a Test or Poc project
• ✅ You want zero external dependencies
• ✅ You're using Bun runtime exclusively
• ✅ You want native Bun optimizations

Use Hono when:

• ✅ You're already familiar with Hono
• ✅ You're migrating an existing Hono project
• ✅ You need Hono-specific middleware
• ✅ You want a battle-tested adapter

Quick Start Comparison

Ergenecore Setup

import { AsenaServerFactory } from '@asenajs/asena';
import { createErgenecoreAdapter } from '@asenajs/ergenecore/factory';
import { logger } from './logger';

const adapter = createErgenecoreAdapter();

const server = await AsenaServerFactory.create({
  adapter,
  logger,
  port: 3000
});

await server.start();

Hono Setup

import { AsenaServer } from '@asenajs/asena';
import { createHonoAdapter } from '@asenajs/hono-adapter';
import { DefaultLogger } from '@asenajs/asena/logger';

const [adapter, logger] = createHonoAdapter(new DefaultLogger());

await new AsenaServer(adapter)
  .logger(logger)
  .port(3000)
  .start(true);

Context API Differences

Both adapters provide a similar Context API, but with some differences:

Ergenecore Context

import type { Context } from '@asenajs/ergenecore/types';

// Get parameters
const id = context.getParam('id');
const page = context.getQuery('page');
const body = await context.getBody();

// Send response
return context.send({ data }, 200);

Hono Context

import type { Context } from '@asenajs/hono-adapter';

// Get parameters
const id = context.getParam('id');
const page = context.getQuery('page');
const body = await context.getBody();

// Send response
return context.json({ data }, 200);

Migration Between Adapters

WARNING

Migrating between adapters requires updating your Import and maybe some context calls, but your controllers, services, and business logic remain unchanged.

From Hono to Ergenecore

import { Get } from '@asenajs/asena/web';
import type { Context } from '@asenajs/hono-adapter';

// Before (Hono)
@Get('/:id')
async getUser(context: Context) {
  const id = context.getParam('id');
  return context.json({ id });
}

// After (Ergenecore)
import { Get } from '@asenajs/asena/web';
import type { Context } from '@asenajs/ergenecore';

@Get('/:id')
async getUser(context: Context) {
  const id = context.getParam('id');
  return context.send({ id });
}

Advanced Adapter Configuration

Ergenecore Advanced Setup

import { createErgenecoreAdapter } from '@asenajs/ergenecore/factory';

const adapter = createErgenecoreAdapter({
  hostname: '0.0.0.0',
  enableWebSocket: true,
  // Custom WebSocket adapter if needed
  websocketAdapter: customWebSocketAdapter
});

Hono Advanced Setup

import { createHonoAdapter } from '@asenajs/hono-adapter';
import { logger } from './logger';

const [adapter, asenaLogger] = createHonoAdapter(logger, {
  // Hono-specific options
});

Creating Custom Adapters

You can create your own adapter by implementing the AsenaAdapter interface:

import type { AsenaAdapter } from '@asenajs/asena/adapter';

export class MyCustomAdapter implements AsenaAdapter {
  async start(port: number): Promise<void> {
    // Implementation
  }

  registerRoute(method: string, path: string, handler: Function): void {
    // Implementation
  }

  // ... implement other required methods
}

TIP

Check the Ergenecore source code for a complete implementation example. or Check the Hono-adapter source code for a complete implementation example.

Recommendations

For New Projects

Start with Ergenecore for optimal performance and native Bun features.

bun add @asenajs/ergenecore

For Existing Hono Projects

Use the Hono adapter for seamless migration and reuse of existing middleware.

bun add @asenajs/hono-adapter

For Maximum Performance

Ergenecore provides:

• Native Bun optimizations
• Minimal dependency overhead

Related Documentation

• Ergenecore Adapter
• Hono Adapter
• Context API
• Middleware Guide

---

Next Steps:

• Learn about Ergenecore features
• Explore Hono adapter usage
• Understand Context API