@aponiajs/platform-elysia 0.3.17 → 0.3.19

package/README.md

@@ -20,19 +20,19 @@ The first Elysia platform slice for Aponia:
 - `handle`, `listen`, and `close` application methods.
 
 This package intentionally does not yet implement request scopes, lifecycle
-enhancers, schema aggregation, or the complete native-plugin compatibility
+enhancers, schema aggregation, or the complete module-level native-plugin
 contract from the roadmap.
 
-The decorator API is the default application authoring surface. The
-`defineElysiaController` API remains available as a low-level escape hatch for
-composing existing Elysia plugins without rewriting them.
+The decorator API is the default application authoring surface.
+`defineElysiaController` remains available as a low-level escape hatch for
+controller factories.
 
 See `docs/logging.md` for logger configuration, JSON output, level filtering,
 and custom logger integration.
 
 ```ts
 import { Module } from "@aponiajs/common";
-import { AponiaFactory } from "@aponiajs/platform-elysia";
+import { AponiaFactory, ElysiaPluginModule } from "@aponiajs/platform-elysia";
 
 @Module({})
 class AppModule {}
@@ -41,5 +41,58 @@ const application = await AponiaFactory.create(AppModule);
 await application.listen(3000);
 ```
 
+## Native Elysia plugins
+
+Use existing Elysia plugins through Nest-style module imports:
+
+```bash
+bun add @elysiajs/cors @elysiajs/jwt
+```
+
+```ts
+import { cors } from "@elysiajs/cors";
+import { jwt } from "@elysiajs/jwt";
+
+@Module({
+  imports: [
+    ElysiaPluginModule.register(cors(), {
+      key: "cors",
+    }),
+  ],
+})
+class AppModule {}
+```
+
+The plugin is passed unchanged to Elysia's native `.use()` implementation. For
+plugins that depend on an injectable service, use an async registration:
+
+```ts
+@Module({
+  imports: [
+    ElysiaPluginModule.registerAsync({
+      key: "jwt",
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) =>
+        jwt({
+          name: "jwt",
+          secret: config.get("JWT_SECRET"),
+        }),
+    }),
+  ],
+})
+class AuthModule {}
+```
+
+Imported plugins are installed in dependency order before controllers and a
+shared configured module is installed once across diamond imports. A stable
+`key` keeps module diagnostics deterministic and prevents duplicate
+registrations with the same key.
+
+`configureNative` remains available as an application-level escape hatch. It
+preserves Elysia's accumulated plugin types on `getNativeApplication()`.
+Module-imported plugin state and decorators are available at runtime, but do
+not yet flow into decorated controller parameter types.
+
 [npm package](https://www.npmjs.com/package/@aponiajs/platform-elysia) ·
 [complete package catalog](../../docs/packages.md)

package/dist/index.d.mts

@@ -1,23 +1,29 @@
-import { Constructor, ControllerDefinition, LogLevel, LoggerService, ModuleClass, ModuleDefinition, Token, TokenValues } from "@aponiajs/common";
+import { Constructor, ControllerDefinition, DynamicModule, LogLevel, LoggerService, ModuleDefinition, ModuleImport, Token, TokenValues } from "@aponiajs/common";
+import "@aponiajs/core";
 import { AnyElysia, Elysia } from "elysia";
 //#region src/decorated-module.d.ts
-type AponiaRootModule = ModuleClass | ModuleDefinition;
+type AponiaRootModule = ModuleImport;
 declare function compileRootModule(rootModule: AponiaRootModule): ModuleDefinition;
 //#endregion
 //#region src/application.d.ts
-declare class AponiaElysiaApplication {
+declare class AponiaElysiaApplication<TNativeApplication extends AnyElysia = Elysia> {
   #private;
-  constructor(nativeApplication: Elysia, logger: LoggerService | undefined);
-  getNativeApplication(): Elysia;
+  constructor(nativeApplication: TNativeApplication, logger: LoggerService | undefined);
+  getNativeApplication(): TNativeApplication;
   handle(request: Request): Response | Promise<Response>;
   listen(port: number): Promise<void>;
   getUrl(): string;
   close(): Promise<void>;
 }
+type NativeElysiaConfigurator<TNativeApplication extends AnyElysia> = (application: Elysia) => TNativeApplication;
 interface AponiaApplicationOptions {
   readonly logger?: false | LoggerService | readonly LogLevel[];
 }
+interface ConfiguredAponiaApplicationOptions<TNativeApplication extends AnyElysia> extends AponiaApplicationOptions {
+  readonly configureNative: NativeElysiaConfigurator<TNativeApplication>;
+}
 declare class AponiaFactory {
+  static create<const TNativeApplication extends AnyElysia>(rootModule: AponiaRootModule, options: ConfiguredAponiaApplicationOptions<TNativeApplication>): Promise<AponiaElysiaApplication<TNativeApplication>>;
   static create(rootModule: AponiaRootModule, options?: AponiaApplicationOptions): Promise<AponiaElysiaApplication>;
 }
 //#endregion
@@ -34,4 +40,19 @@ declare function defineElysiaController<TController, const TDependencies extends
   readonly buildPlugin: (controller: TController) => TPlugin;
 }): ElysiaControllerDefinition<TController, TDependencies, TPlugin>;
 //#endregion
-export { type AponiaApplicationOptions, AponiaElysiaApplication, AponiaFactory, type AponiaRootModule, ELYSIA_CONTROLLER, type ElysiaControllerDefinition, compileRootModule, defineElysiaController };
+//#region src/plugin-module.d.ts
+type NativeElysiaPlugin = Parameters<Elysia["use"]>[0];
+interface ElysiaPluginModuleOptions {
+  readonly key?: string;
+}
+interface AsyncElysiaPluginModuleOptions<TDependencies extends readonly Token<unknown>[], TPlugin extends NativeElysiaPlugin> extends ElysiaPluginModuleOptions {
+  readonly imports?: readonly ModuleImport[];
+  readonly inject: TDependencies;
+  readonly useFactory: (...dependencies: TokenValues<TDependencies>) => TPlugin;
+}
+declare class ElysiaPluginModule {
+  static register<const TPlugin extends NativeElysiaPlugin>(plugin: TPlugin, options?: ElysiaPluginModuleOptions): DynamicModule;
+  static registerAsync<const TDependencies extends readonly Token<unknown>[], const TPlugin extends NativeElysiaPlugin>(options: AsyncElysiaPluginModuleOptions<TDependencies, TPlugin>): DynamicModule;
+}
+//#endregion
+export { type AponiaApplicationOptions, AponiaElysiaApplication, AponiaFactory, type AponiaRootModule, type AsyncElysiaPluginModuleOptions, type ConfiguredAponiaApplicationOptions, ELYSIA_CONTROLLER, type ElysiaControllerDefinition, ElysiaPluginModule, type ElysiaPluginModuleOptions, type NativeElysiaConfigurator, type NativeElysiaPlugin, compileRootModule, defineElysiaController };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { AponiaError, Logger, getConstructorDependencies, getControllerMetadata, getModuleMetadata, getRouteMetadata, tokenName } from "@aponiajs/common";
+import { AponiaError, Logger, Module, createToken, getConstructorDependencies, getControllerMetadata, getModuleMetadata, getRouteMetadata, provideFactory, provideValue, tokenName } from "@aponiajs/common";
 import { createContainer } from "@aponiajs/core";
 import { Elysia } from "elysia";
 //#region src/controller.ts
@@ -18,29 +18,54 @@ function isElysiaController(controller) {
 //#endregion
 //#region src/decorated-module.ts
 function compileRootModule(rootModule) {
-	if (typeof rootModule !== "function") return rootModule;
-	const compiled = /* @__PURE__ */ new Map();
+	if (isModuleDefinition(rootModule)) return rootModule;
+	const compiledClasses = /* @__PURE__ */ new Map();
+	const compiledDynamicModules = /* @__PURE__ */ new Map();
 	const visiting = [];
-	const compile = (moduleClass) => {
-		const cached = compiled.get(moduleClass);
+	const compile = (moduleImport) => {
+		if (typeof moduleImport === "function") return compileClass(moduleImport);
+		if (isModuleDefinition(moduleImport)) return moduleImport;
+		return compileDynamicModule(moduleImport);
+	};
+	const compileClass = (moduleClass) => {
+		const cached = compiledClasses.get(moduleClass);
 		if (cached) return cached;
-		const cycleIndex = visiting.indexOf(moduleClass);
-		if (cycleIndex >= 0) {
-			const cycle = [...visiting.slice(cycleIndex), moduleClass].map((item) => item.name);
-			throw new AponiaError("MODULE_CYCLE", `Module import cycle detected: ${cycle.join(" -> ")}.`, { cycle });
-		}
+		assertNoModuleCycle(moduleClass, visiting);
 		const metadata = getModuleMetadata(moduleClass);
-		if (!metadata) throw new AponiaError("INVALID_MODULE", `Class "${moduleClass.name}" is missing the @Module() decorator.`, { module: moduleClass.name });
+		if (!metadata) throw missingModuleDecorator(moduleClass);
 		visiting.push(moduleClass);
 		try {
 			const definition = Object.freeze({
 				id: moduleClass.name,
-				imports: Object.freeze((metadata.imports ?? []).map((moduleImport) => typeof moduleImport === "function" ? compile(moduleImport) : moduleImport)),
+				imports: Object.freeze((metadata.imports ?? []).map(compile)),
 				controllers: Object.freeze((metadata.controllers ?? []).map(compileDecoratedController)),
 				providers: Object.freeze((metadata.providers ?? []).map(compileProvider)),
 				exports: Object.freeze([...metadata.exports ?? []])
 			});
-			compiled.set(moduleClass, definition);
+			compiledClasses.set(moduleClass, definition);
+			return definition;
+		} finally {
+			visiting.pop();
+		}
+	};
+	const compileDynamicModule = (dynamicModule) => {
+		const cached = compiledDynamicModules.get(dynamicModule);
+		if (cached) return cached;
+		assertNoModuleCycle(dynamicModule, visiting);
+		const metadata = getModuleMetadata(dynamicModule.module);
+		if (!metadata) throw missingModuleDecorator(dynamicModule.module);
+		const mergedMetadata = mergeModuleMetadata(metadata, dynamicModule);
+		visiting.push(dynamicModule);
+		try {
+			const definition = Object.freeze({
+				id: dynamicModule.id,
+				instanceId: dynamicModule.instanceId,
+				imports: Object.freeze((mergedMetadata.imports ?? []).map(compile)),
+				controllers: Object.freeze((mergedMetadata.controllers ?? []).map(compileDecoratedController)),
+				providers: Object.freeze((mergedMetadata.providers ?? []).map(compileProvider)),
+				exports: Object.freeze([...mergedMetadata.exports ?? []])
+			});
+			compiledDynamicModules.set(dynamicModule, definition);
 			return definition;
 		} finally {
 			visiting.pop();
@@ -48,6 +73,30 @@ function compileRootModule(rootModule) {
 	};
 	return compile(rootModule);
 }
+function isModuleDefinition(moduleImport) {
+	return typeof moduleImport !== "function" && "controllers" in moduleImport && !("module" in moduleImport);
+}
+function moduleImportName(moduleImport) {
+	if (typeof moduleImport === "function") return moduleImport.name;
+	return moduleImport.id;
+}
+function assertNoModuleCycle(moduleImport, visiting) {
+	const cycleIndex = visiting.indexOf(moduleImport);
+	if (cycleIndex < 0) return;
+	const cycle = [...visiting.slice(cycleIndex), moduleImport].map(moduleImportName);
+	throw new AponiaError("MODULE_CYCLE", `Module import cycle detected: ${cycle.join(" -> ")}.`, { cycle });
+}
+function missingModuleDecorator(moduleClass) {
+	return new AponiaError("INVALID_MODULE", `Class "${moduleClass.name}" is missing the @Module() decorator.`, { module: moduleClass.name });
+}
+function mergeModuleMetadata(metadata, dynamicModule) {
+	return Object.freeze({
+		imports: Object.freeze([...metadata.imports ?? [], ...dynamicModule.imports ?? []]),
+		controllers: Object.freeze([...metadata.controllers ?? [], ...dynamicModule.controllers ?? []]),
+		providers: Object.freeze([...metadata.providers ?? [], ...dynamicModule.providers ?? []]),
+		exports: Object.freeze([...metadata.exports ?? [], ...dynamicModule.exports ?? []])
+	});
+}
 function compileProvider(provider) {
 	if (typeof provider !== "function") return provider;
 	const inject = getConstructorDependencies(provider);
@@ -87,6 +136,40 @@ function joinPaths(controllerPath, routePath) {
 	return segments.length === 0 ? "/" : `/${segments.join("/")}`;
 }
 //#endregion
+//#region src/plugin-module.ts
+const ELYSIA_PLUGIN = createToken("aponia.elysia.native-plugin");
+const keyedModuleIdentityPrefix = "aponia.elysia.plugin-module:";
+var ElysiaPluginModule = @Module({}) class {
+	static register(plugin, options = {}) {
+		return createPluginModule({ providers: [provideValue(ELYSIA_PLUGIN, plugin)] }, options.key);
+	}
+	static registerAsync(options) {
+		return createPluginModule({
+			imports: options.imports,
+			providers: [provideFactory(ELYSIA_PLUGIN, options.inject, options.useFactory)]
+		}, options.key);
+	}
+};
+function isElysiaPluginModule(module) {
+	return module.providers.some((provider) => provider.provide === ELYSIA_PLUGIN);
+}
+function getElysiaPlugin(container, module) {
+	return container.resolveModuleProvider(module, ELYSIA_PLUGIN);
+}
+function createPluginModule(metadata, key) {
+	if (key !== void 0 && key.trim().length === 0) throw new TypeError("Elysia plugin module key must not be empty.");
+	const hasStableKey = key !== void 0;
+	const id = hasStableKey ? `ElysiaPluginModule[${key}]` : "ElysiaPluginModule";
+	const instanceId = hasStableKey ? Symbol.for(`${keyedModuleIdentityPrefix}${key}`) : Symbol(id);
+	return Object.freeze({
+		module: ElysiaPluginModule,
+		id,
+		instanceId,
+		imports: Object.freeze([...metadata.imports ?? []]),
+		providers: Object.freeze([...metadata.providers ?? []])
+	});
+}
+//#endregion
 //#region src/application.ts
 var AponiaElysiaApplication = class {
 	#nativeApplication;
@@ -127,9 +210,13 @@ var AponiaFactory = class {
 		logger?.log("Starting Aponia application...", "AponiaFactory");
 		const compiledRootModule = compileRootModule(rootModule);
 		const container = createContainer(compiledRootModule);
-		const nativeApplication = new Elysia({ name: compiledRootModule.id });
+		const baseApplication = new Elysia({ name: compiledRootModule.id });
+		const configureNative = "configureNative" in options ? options.configureNative : void 0;
+		const nativeApplication = configureNative ? configureNative(baseApplication) : baseApplication;
+		if (nativeApplication !== baseApplication) throw new AponiaError("INVALID_NATIVE_APPLICATION", "configureNative must return the Elysia application it receives.");
 		for (const module of container.graph.modules) {
 			container.initializeModule(module);
+			if (isElysiaPluginModule(module)) nativeApplication.use(getElysiaPlugin(container, module));
 			logger?.log(`${module.id} dependencies initialized`, "InstanceLoader");
 		}
 		for (const module of container.graph.modules) for (const controller of module.controllers) {
@@ -146,10 +233,12 @@ var AponiaFactory = class {
 				module: module.id,
 				controller: tokenName(controller.token)
 			});
-			const controllerName = tokenName(controller.token);
-			const controllerPath = controller.path ?? inferControllerPath(plugin);
-			logger?.log(`${controllerName} {${controllerPath}}:`, "RoutesResolver");
-			for (const route of plugin.routes) logger?.log(`Mapped {${route.path}, ${String(route.method).toUpperCase()}} route`, "RouterExplorer");
+			if (logger) {
+				const controllerName = tokenName(controller.token);
+				const controllerPath = controller.path ?? inferControllerPath(plugin);
+				logger.log(`${controllerName} {${controllerPath}}:`, "RoutesResolver");
+				for (const route of plugin.routes) logger.log(`Mapped {${route.path}, ${String(route.method).toUpperCase()}} route`, "RouterExplorer");
+			}
 			nativeApplication.use(plugin);
 		}
 		await nativeApplication.modules;
@@ -169,4 +258,4 @@ function inferControllerPath(plugin) {
 	return plugin.routes[0]?.path ?? "/";
 }
 //#endregion
-export { AponiaElysiaApplication, AponiaFactory, ELYSIA_CONTROLLER, compileRootModule, defineElysiaController };
+export { AponiaElysiaApplication, AponiaFactory, ELYSIA_CONTROLLER, ElysiaPluginModule, compileRootModule, defineElysiaController };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aponiajs/platform-elysia",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Minimal Elysia application platform for Aponia modules and controllers.",
   "homepage": "https://github.com/aponiajs/aponiajs#readme",
   "bugs": {
@@ -33,8 +33,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@aponiajs/common": "0.3.16",
-    "@aponiajs/core": "0.3.16"
+    "@aponiajs/common": "0.3.18",
+    "@aponiajs/core": "0.3.18"
   },
   "devDependencies": {
     "elysia": "^1.4.29"