@asenajs/asena NPM

Asena

Asena is a NestJS-like IoC web framework built on top of Bun. It combines the power of dependency injection with the performance of Bun runtime and the flexibility of Adapter design system.

Documentation

For detailed documentation, please visit not ready yet. Documentation is still in progress, but updates are being made regularly. You can check this project AsenaExample. I am always updating it to latest usages.

Key Features

Dependency Injection: Built-in IoC container for managing dependencies
Decorator-based Development: Similar to NestJS, using TypeScript decorators for routing and DI
High Performance: Leverages Bun runtime for optimal performance
WebSocket Support: Built-in WebSocket handling capabilities
Middleware System: Flexible middleware architecture
HTTP Adapters: Extensible adapter system with Hono as default
Zero Dependencies: Only uses reflect-metadata for dependency injection
TypeScript Support: Full TypeScript support with strict mode
Modular Architecture: Easy to extend and customize

Quick Start

The easiest way to create a new Asena project is using the CLI:

# Create a new project
bun add -D @asenajs/asena-cli
asena create

This will create a new project with the following structure:

├── src/
│ ├── controllers/
│ │ └── AsenaController.ts
│ └── index.ts
├── package.json
├── tsconfig.json
├── .eslintrc.js
├── .eslintignore
└── .prettierrc.js

Alternative start

Alternatively, you can create a project manually:

First, create a new project using Bun:

bun init

For decorators working properly, you need to add some settings to your tsconfig. Here is a recommended file:

{
  "compilerOptions": {
    // Enable latest features
    "lib": ["ESNext", "DOM"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,

    // Bundler mode
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,

    // Best practices
    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,

    // Some stricter flags
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noPropertyAccessFromIndexSignature": true
  }
}

After that you need to make sure to edit your tsConfig.json it should look like this Then, install these packages:

@asenajs/asena: Base package
@asenajs/hono-adapter: For web-server. Asena currently only support hono adapter.
@asenajs/asena-logger: For better logs

bun install @asenajs/asena @asenajs/hono-adapter @asenajs/asena-logger

@asenajs/asena-cli: This package provides a CLI for creating and managing Asena projects.

bun install -D @asenajs/asena-cli

After installation, you need to create asena-config.ts file you can create it with asena-cli

asena init

this will create you asena-config file.

Note: Built options directly copy of bun options, you can check bun documentation for more options. Bun Documentation

Create index.ts file under your src folder:

// src/index.ts
import {AsenaServer} from '@asenajs/asena';
import {createHonoAdapter} from '@asenajs/hono-adapter';
import {logger} from './logger/logger';

const [honoAdapter,asenaLogger] = createHonoAdapter(logger);


await new AsenaServer(honoAdapter, asenaLogger).port(3000).start();

To run asena you need at least one controller. Create a new controller:

// src/controllers/TestController.ts
import type { Context } from '@asenajs/hono-adapter';
import { Controller } from '@asenajs/asena/server';
import { Get } from '@asenajs/asena/web';

@Controller('/hello')
export class TestController {
  @Get('/world')
  public async getHello(context: Context) {
    return context.send('Hello World');
  }
}

Finally, run the project:

## only for fast developing purposes
asena dev start

## or you can simply build then run your bundled project
asena build
## then go to dist folder and run the project this way it will consume less memory and it will be faster.
bun index.asena.js

CLI Commands

For more information about CLI commands and usage, please visit: Asena CLI Documentation

Project Structure

lib/
├── adapter/     # HTTP adapter implementations
├── server/      # Core server functionality
├── ioc/         # Dependency injection container
├── utils/       # Utility functions
├── test/        # Test utilities

Core Concepts

Controllers: Handle incoming requests using decorators
Services: Business logic containers that can be injected
Middleware: Request/Response interceptors
WebSocket: Built-in WebSocket support
HTTP Status: Standard HTTP status codes and utilities

Performance

Built on Bun runtime, Asena provides:

Fast startup time
Low memory footprint
Quick request processing
Efficient WebSocket handling

Here is the benchmark result of Asena with Hono adapter (Basic hello world example) in every test we used bun to run the project:

Performance Comparison (Fastest to Slowest)

Framework	Requests/sec	Latency (avg)	Transfer/sec
Hono	147,031.08	2.69ms	18.09MB
Asena + Hono-adapter	137,148.80	2.89ms	16.74MB
NestJS (Bun + Fastify)	81,652.05	6.01ms	13.78MB
NestJS (Bun)	64,435.83	6.14ms	11.80MB
NestJS (Bun + kiyasov/platform-hono)	45,082.27	8.79ms	5.55MB
NestJS (Node)	17,649.89	24.43ms	4.02MB