Nelysia

NestJS-style modular framework built natively on ElysiaJS + Bun.

---

Features

• 🧩 @Plugin — NestJS-style @Module powered by native Elysia .use()
• 💉 @Service + @Inject — Lightweight DI container
• 🌐 @Controller + HTTP verbs — @Get, @Post, @Put, @Patch, @Delete
• 🔌 @WsController + @Ws — Native WebSocket support with pub/sub
• 🎯 Context decorators — @Body, @Query, @Params, @Path, @Headers, @Cookie
• 🛡️ @BeforeHandle — Per-route guards
• 📋 @Schema — Elysia t validation per route
• 📖 @Detail — OpenAPI / Swagger metadata
• ⚙️ @Macro — Elysia .macro() as class-based decorators
• 🔁 Lifecycle hooks — onRequest, onError, onAfterResponse, etc. in @Plugin

---

Install

bun add @byteholic/nelysia elysia
bun add -d bun-types

tsconfig.json requirements

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "strict": true
  }
}

---

Quick Start

// main.ts
import { Elysia } from "elysia";
import { buildPlugin } from "@byteholic/nelysia";
import { AppPlugin } from "./app.plugin";

new Elysia()
  .use(buildPlugin(AppPlugin))
  .listen(3000);

---

Core Concepts

@Service — Injectable class

Register a class in the DI container. Pass deps as an explicit array.

import { Service } from "@byteholic/nelysia";

@Service()
export class UserRepo {
  private users = [{ id: 1, name: "Alice" }];
  findAll() { return this.users; }
}

@Service([UserRepo])
export class UsersService {
  constructor(private repo: UserRepo) {}
  all() { return this.repo.findAll(); }
}

@Inject — Per-parameter injection

Use on constructor parameters instead of (or alongside) @Service([]).

import { Inject, Controller, Get } from "@byteholic/nelysia";

@Controller("/users")
export class UsersController {
  constructor(@Inject(UsersService) private svc: UsersService) {}

  @Get("/")
  getAll() { return this.svc.all(); }
}

Both styles are equivalent:

// Style A — class-level deps
@Service([UsersService])
@Controller("/users")
export class UsersController {
  constructor(private svc: UsersService) {}
}

// Style B — per-param @Inject
@Controller("/users")
export class UsersController {
  constructor(@Inject(UsersService) private svc: UsersService) {}
}

@Plugin — Feature module

Composes services, controllers, sub-plugins, guards and hooks.

import { Plugin } from "@byteholic/nelysia";

@Plugin({
  name:        "users",
  imports:     [OtherPlugin],          // sub-plugins (shared DI)
  services:    [UserRepo, UsersService],
  controllers: [UsersController],
  wsControllers: [UsersWsController],  // WebSocket controllers
  guard: {
    beforeHandle: requireAuth,         // applied to ALL routes
  },
  hooks: {
    onRequest: ({ request }) =>
      console.log(request.method, request.url),
    onError: ({ error }) =>
      console.error(error.message),
  },
})
export class UsersPlugin {}

Then in main.ts:

new Elysia().use(buildPlugin(UsersPlugin)).listen(3000);

---

HTTP Routes

import { t } from "elysia";
import {
  Controller, Get, Post, Delete,
  Schema, BeforeHandle, Detail,
  Body, Path, Query, Set,
} from "@byteholic/nelysia";

const adminOnly = ({ headers, status }: any) => {
  if (headers["x-role"] !== "admin") return status(403);
};

@Controller("/users")
export class UsersController {
  constructor(@Inject(UsersService) private svc: UsersService) {}

  @Detail({ tags: ["Users"], summary: "List users" })
  @Schema({ query: t.Object({ page: t.Optional(t.Numeric({ default: 1 })) }) })
  @Get("/")
  getAll(@Query() query: { page?: number }) {
    return this.svc.all();
  }

  @Detail({ tags: ["Users"], summary: "Get user by id" })
  @Schema({ params: t.Object({ id: t.Numeric() }) })
  @Get("/:id")
  getOne(@Path("id") id: number, @Set() set: any) {
    const user = this.svc.byId(id);
    if (!user) { set.status = 404; return { error: "Not found" }; }
    return user;
  }

  @Detail({ tags: ["Users"], summary: "Create user" })
  @Schema({ body: t.Object({ name: t.String({ minLength: 1 }) }) })
  @Post("/")
  create(@Body() body: { name: string }, @Set() set: any) {
    set.status = 201;
    return this.svc.create(body);
  }

  @BeforeHandle(adminOnly)
  @Schema({ params: t.Object({ id: t.Numeric() }) })
  @Delete("/:id")
  remove(@Path("id") id: number) {
    return this.svc.remove(id);
  }
}

---

WebSocket

import { t } from "elysia";
import { WsController, Ws, WsSchema, WsHandlers, Inject } from "@byteholic/nelysia";

@WsController()
export class ChatWsController {
  constructor(@Inject(ChatService) private chat: ChatService) {}

  @WsSchema({
    body:   t.Object({ user: t.String(), text: t.String() }),
    params: t.Object({ room: t.String() }),
  })
  @Ws("/chat/:room")
  chat(): WsHandlers {
    const svc = this.chat;
    return {
      open(ws) {
        ws.subscribe(ws.data.params.room);
        ws.send("Welcome!");
      },
      message(ws, body) {
        const msg = svc.format(body.user, body.text, ws.data.params.room);
        svc.save(msg);
        ws.publish(ws.data.params.room, JSON.stringify(msg));
      },
      close(ws) {
        ws.unsubscribe(ws.data.params.room);
      },
    };
  }
}

// Register in @Plugin:
@Plugin({
  name:          "chat",
  services:      [ChatService],
  wsControllers: [ChatWsController],
})
export class ChatPlugin {}

Connect with:

bun add -g wscat
wscat -c "ws://localhost:3000/chat/general"
# send: {"user":"Alice","text":"Hello!"}

---

Context Decorators

Decorator	Extracts
@Ctx()	Full Elysia context
@Body()	ctx.body
@Query()	ctx.query (all)
@Params()	ctx.params (all)
@Headers()	ctx.headers
@Cookie()	ctx.cookie
@Set()	ctx.set (status/headers)
@Path("id")	ctx.params.id (single)
@Q("page")	ctx.query.page (single)

---

Lifecycle Hooks

Available in hooks: inside @Plugin:

Hook	Fires when
onRequest	Every incoming request
onParse	Body parsing
onTransform	Before validation
onBeforeHandle	Before route handler
onAfterHandle	After route handler
onAfterResponse	After response is sent
onError	On any error
mapResponse	Transform response before send

---

Macro

Wraps Elysia's native .macro() API:

import { Macro, MacroHandler } from "@byteholic/nelysia";

@Macro({ name: "auth" })
export class AuthMacro {
  @MacroHandler("roles")
  roles(required: string[]) {
    return {
      beforeHandle({ cookie, status }: any) {
        if (!required.includes(cookie.session?.value?.role))
          return status(403);
      },
    };
  }
}

// Register in @Plugin:
@Plugin({ macros: [AuthMacro], controllers: [AdminController] })
export class AdminPlugin {}

---

Full Decorator Reference

DI

Decorator	Description
@Service(deps?)	Register class in DI container
@Inject(Token)	Per-parameter dependency injection

Plugin

Decorator / Function	Description
@Plugin(meta)	Define a feature module
buildPlugin(MyPlugin)	Convert to native Elysia instance

HTTP

Decorator	Description
@Controller(prefix)	HTTP controller class
@Get / @Post / @Put / @Patch / @Delete / @Options / @Head / @All	Route method
@Schema({ body, query, params, headers, response })	Elysia t validation
@BeforeHandle(fn)	Per-route guard / hook
@AfterHandle(fn)	Per-route after hook
@OnError(fn)	Per-route error handler
@Detail({ tags, summary })	OpenAPI metadata

WebSocket

Decorator	Description
@WsController(prefix?)	WebSocket controller class
@Ws(path?)	WebSocket endpoint (returns WsHandlers)
@WsSchema({ body, query, params })	WS message validation

---

Project Structure

src/
  core/
    container.ts   — DI Container
    service.ts     — @Service, @Inject
    controller.ts  — @Controller, @Get, @Post, @Schema ...
    context.ts     — @Body, @Query, @Path, @Headers ...
    websocket.ts   — @WsController, @Ws, @WsSchema
    plugin.ts      — @Plugin, buildPlugin()
    macro.ts       — @Macro, @MacroHandler
  index.ts         — Public API barrel

---

With Swagger

bun add @elysiajs/swagger

import { swagger } from "@elysiajs/swagger";

new Elysia()
  .use(swagger({ documentation: { info: { title: "My API", version: "1.0.0" } } }))
  .use(buildPlugin(AppPlugin))
  .listen(3000);

// Docs at: http://localhost:3000/swagger

---

Requirements

• Bun ≥ 1.0
• ElysiaJS ≥ 1.0
• "experimentalDecorators": true in tsconfig.json

---

License

MIT © byteholic