@n2js/elysia-module

简体中文 | English

@n2js/elysia-module 是面向 Elysia 的模块化路由适配包。它适合想把 Elysia routes 拆成独立模块，同时完整保留 route tuple、Eden RPC 和 handler 上下文类型推断的项目。defineElysiaModule() 会把多段 Elysia 路由合并成只读 router artifact，并挂到 @n2js/container 的模块实例上，让 Elysia 模块化路由、依赖解析和类型推断一起工作。

当前包提供 ESM-only 构建产物，运行入口为 ./dist/index.js，类型声明入口为 ./dist/index.d.ts。

为什么适合 Elysia 模块化

• 保留路由类型推断： 合并 route tuple 后仍保留 Eden RPC 类型，不把 router 降级成宽泛的运行时对象。
• 按模块组织路由： 每个模块可以拥有自己的 routes、Provider、imports、features 和 lifecycle。
• handler 内可解析依赖： handler 上下文中的 module 指向当前模块实例，业务 route 可以直接解析本模块可见的 Provider。
• 子模块自动组合： 使用 mount() 组合子模块时，会按 mount path 合并子模块 router。
• 搜索友好定位： 如果你在找 Elysia module、Elysia modular routing 或 Elysia route type inference，这个包就是为这类场景准备的。

安装

npm install @n2js/elysia-module @n2js/container elysia

@n2js/container 和 elysia 是 peer dependencies。请在使用侧安装它们，并尽量保持单实例，避免模块 token 与 router 类型来自不同依赖副本。若需要 Eden RPC client，请额外安装 @elysia/eden。

快速开始

import { Container } from '@n2js/container';
import { Elysia } from 'elysia';
import {
  defineElysiaModule,
  type TElysiaModuleSingleton,
} from '@n2js/elysia-module';

class GreetingService {
  getMessage(): string {
    return 'Hello from DI';
  }
}

const greetingRoute = new Elysia<'', TElysiaModuleSingleton>().get(
  '/greeting',
  async ({ module }) => {
    const greetingService = await module.resolve(GreetingService);

    return greetingService?.getMessage() ?? 'missing';
  },
);

const ElysiaExampleModule = defineElysiaModule({
  displayName: 'ElysiaExampleModule',
  routes: [greetingRoute] as const,
  providers: [GreetingService],
});

const container = new Container(ElysiaExampleModule);
const response = await container.root.router.handle(
  new Request('http://localhost/greeting'),
);

console.log(await response.text());

核心能力

• defineElysiaModule()：定义带 Elysia router artifact 的模块，并保留 route tuple 类型推断。
• mergeElysiaRoutes()：合并 route tuple 和 mounted child routers。
• TElysiaModuleSingleton：为 Elysia handler 增加 module 上下文类型。
• TMergedElysiaRouter：保留 route tuple 推导出的 Eden RPC 类型。
• mount() 子模块时，会按 mount path 自动组合子模块 router。

使用说明

defineElysiaModule() 接收与 defineModule() 相同的 Provider、imports、features 和 lifecycle 选项，同时增加 routes。返回的模块可以直接传给 new Container()，并通过 container.root.router.handle() 处理请求。

业务 route 中的 module 是当前模块实例。你可以在 handler 中调用 resolve()、resolveOwn() 或 resolveWithScope()，也可以读取模块 Feature 附加的只读 artifact。

类型导出

| 导出 | 说明 | | --- | --- | | defineElysiaModule() | 定义 Elysia 模块并生成合并后的 router。 | | mergeElysiaRoutes() | 独立合并 Elysia route tuple。 | | TElysiaModuleSingleton | Elysia singleton 类型，包含当前模块实例。 | | TElysiaModuleOptions | defineElysiaModule() 的选项类型。 | | TMergedElysiaRouter | 合并后 router 的类型工具。 |

许可证

MIT