@aponiajs/platform-elysia 0.6.0-alpha.1 → 0.6.0-alpha.14

package/README.md

@@ -41,8 +41,12 @@ import { AponiaFactory, ElysiaPluginModule } from "@aponiajs/platform-elysia";
 @Module({})
 class AppModule {}
 
-const application = await AponiaFactory.create(AppModule);
-await application.listen(3000);
+async function bootstrap(): Promise<void> {
+  const application = await AponiaFactory.create(AppModule);
+  await application.listen(3000);
+}
+
+await bootstrap();
 ```
 
 ## Routes with the native Elysia context
@@ -134,10 +138,131 @@ shared configured module is installed once across diamond imports. A stable
 `key` keeps module diagnostics deterministic and prevents duplicate
 registrations with the same key.
 
+### Typing what a plugin adds
+
+Compiling a decorated controller erases the plugin instances its module imports,
+so no plugin type reaches a handler on its own. Name the plugins in the second
+type argument of `ElysiaRouteContext` and the context types what they add:
+
+```ts
+import { Controller, Ctx, Get } from "@aponiajs/common";
+import { type ElysiaRouteContext } from "@aponiajs/platform-elysia";
+import { Elysia } from "elysia";
+
+export const clock = new Elysia({ name: "clock" })
+  .decorate("now", () => new Date().toISOString())
+  .state("requests", 0)
+  .derive({ as: "global" }, () => ({ traceId: crypto.randomUUID() }));
+
+@Controller("health")
+class HealthController {
+  @Get()
+  read(@Ctx() context: ElysiaRouteContext<typeof clock>) {
+    context.store.requests += 1;
+    return { now: context.now(), traceId: context.traceId };
+  }
+}
+```
+
+The first argument takes either the plugins or a route schema, so a handler
+without a schema never writes an empty one. A tuple covers several plugins, and
+the second argument is only needed when both are typed:
+
+```ts
+ElysiaRouteContext<[typeof clock, typeof cache]>;
+ElysiaRouteContext<typeof createUser, typeof clock>;
+```
+
+An application that always mounts the same plugins declares the pairing once and
+keeps every handler short:
+
+```ts
+// src/app.context.ts
+import { type ElysiaInputSchema, type ElysiaRouteContext } from "@aponiajs/platform-elysia";
+import { cache } from "./cache.plugin.ts";
+import { clock } from "./clock.plugin.ts";
+
+export type AppContext<TSchema extends ElysiaInputSchema = {}> = ElysiaRouteContext<
+  TSchema,
+  [typeof clock, typeof cache]
+>;
+```
+
+```ts
+@Get()
+read(@Ctx() context: AppContext) {}
+
+@Post("/", createUser)
+create(@Ctx() context: AppContext<typeof createUser>) {}
+```
+
+### Dropping `typeof`
+
+`defineElysiaPlugin` converts a native plugin into a module import that also
+carries the plugin type. Export it beside a same-named type and the plugin is
+usable in both a value and a type position:
+
+```ts
+// src/clock.plugin.ts
+import { defineElysiaPlugin } from "@aponiajs/platform-elysia";
+import { Elysia } from "elysia";
+
+export const clock = defineElysiaPlugin(
+  new Elysia({ name: "clock" }).decorate("now", () => new Date().toISOString()),
+  { key: "clock" },
+);
+export type clock = typeof clock;
+```
+
+The import goes straight into `imports`, with no `ElysiaPluginModule.register`
+around it, and the annotation needs no `typeof`. Rename the context type on
+import for the shortest form:
+
+```ts
+import { Controller, Ctx, Get, Module } from "@aponiajs/common";
+import { type ElysiaRouteContext as e } from "@aponiajs/platform-elysia";
+import { cache } from "./cache.plugin.ts";
+import { clock } from "./clock.plugin.ts";
+
+@Controller("health")
+class HealthController {
+  @Get()
+  read(@Ctx() context: e<clock>) {
+    return { now: context.now() };
+  }
+
+  @Get("cached")
+  readCached(@Ctx() context: e<[clock, cache]>) {
+    return { cached: context.cache.read("health") };
+  }
+}
+
+@Module({ imports: [clock, cache], controllers: [HealthController] })
+class HealthModule {}
+```
+
+`ElysiaPluginModule.register` and `registerAsync` stay available and unchanged;
+`defineElysiaPlugin` is `register` plus the plugin it installs, and the context
+type accepts either form. The plugin instance itself remains reachable as
+`clock.plugin`.
+
+The mapping follows Elysia's own `.use()` rule, so what is typed is exactly what
+arrives at runtime: `decorate`, `state`, `resolve`, and `derive` declared
+`global`, plus `scoped` derives and resolves. A plugin-local derive stays inside
+the plugin and is absent from both the type and the context. Naming no plugin
+costs nothing at runtime — the values are still there, only untyped.
+
 `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.
+
+## Bootstrap diagnostics
+
+A controller descriptor with a platform kind other than
+`aponia.elysia.controller` fails with `UNSUPPORTED_CONTROLLER`. A recognized
+Elysia controller whose `buildPlugin` factory returns something other than an
+Elysia instance fails with `INVALID_CONTROLLER`. Both are reported during
+`AponiaFactory.create`, before the application can listen.
 
 [npm package](https://www.npmjs.com/package/@aponiajs/platform-elysia) ·
+[native plugin guide](../../docs/native-plugins.md) ·
 [complete package catalog](../../docs/packages.md)

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Constructor, ControllerDefinition, DynamicModule, LogLevel, LoggerService, ModuleDefinition, ModuleImport, Token, TokenValues } from "@aponiajs/common";
 import "@aponiajs/core";
-import { AnyElysia, Context, Elysia, InputSchema, UnwrapRoute } from "elysia";
+import { AnyElysia, Context, Elysia, InputSchema, SingletonBase, UnwrapRoute } from "elysia";
 //#region src/decorated-module.d.ts
 type AponiaRootModule = ModuleImport;
 declare function compileRootModule(rootModule: AponiaRootModule): ModuleDefinition;
@@ -28,13 +28,75 @@ declare class AponiaFactory {
 }
 //#endregion
 //#region src/route-context.d.ts
+/**
+ * One plugin a handler reads from: a native Elysia instance, or the module
+ * import `defineElysiaPlugin` produces for it.
+ */
+type ElysiaPluginSource = AnyElysia | {
+  readonly plugin: AnyElysia;
+};
+/**
+ * One plugin, or every plugin whose types a handler depends on.
+ */
+type ElysiaPluginTypes = ElysiaPluginSource | readonly ElysiaPluginSource[];
+type ResolvePlugin<TSource> = TSource extends {
+  readonly plugin: infer TPlugin extends AnyElysia;
+} ? TPlugin : TSource;
+type PluginUnion<TPlugins extends ElysiaPluginTypes> = ResolvePlugin<TPlugins extends readonly (infer TSource)[] ? TSource : TPlugins>;
+type UnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends ((value: infer TIntersection) => void) ? TIntersection : never;
+type MergeRecords<TUnion> = UnionToIntersection<TUnion> extends (infer TMerged extends Record<string, unknown>) ? TMerged : {};
+/**
+ * The singleton a controller sees once the plugins are mounted. `use()` merges
+ * a plugin's global `~Singleton` into its parent, and its `scoped` `~Ephemeral`
+ * derives and resolves reach the routes mounted alongside it, so both are part
+ * of the context. Plugin-local derives stay inside the plugin and are excluded.
+ */
+type MountedSingleton<TPlugins extends ElysiaPluginTypes> = {
+  decorator: MergeRecords<PluginUnion<TPlugins>["~Singleton"]["decorator"]>;
+  store: MergeRecords<PluginUnion<TPlugins>["~Singleton"]["store"]>;
+  derive: MergeRecords<PluginUnion<TPlugins>["~Singleton"]["derive"] | PluginUnion<TPlugins>["~Ephemeral"]["derive"]>;
+  resolve: MergeRecords<PluginUnion<TPlugins>["~Singleton"]["resolve"] | PluginUnion<TPlugins>["~Ephemeral"]["resolve"]>;
+} extends (infer TSingleton extends SingletonBase) ? TSingleton : never;
 /**
  * The native Elysia request context for a declared route schema. Handlers that
  * take the whole context — through `@Ctx()` or a single unannotated parameter —
  * keep `status`, `set`, `cookie`, `store`, `redirect`, and plugin decorators
  * fully typed.
+ *
+ * Compiling a decorated controller erases the plugin instances a module
+ * imports, so name the plugins a handler reads from. The first argument takes
+ * either a route schema or the plugins, so a handler without a schema never
+ * writes an empty one:
+ *
+ * ```ts
+ * read(@Ctx() context: ElysiaRouteContext<typeof clock>) {}
+ * read(@Ctx() context: ElysiaRouteContext<[typeof clock, typeof cache]>) {}
+ * create(@Ctx() context: ElysiaRouteContext<typeof createUser, typeof clock>) {}
+ * ```
+ *
+ * A plugin exported through `defineElysiaPlugin` alongside a same-named type
+ * drops the `typeof`, which reads best under a short import alias:
+ *
+ * ```ts
+ * import { type ElysiaRouteContext as e } from "@aponiajs/platform-elysia";
+ *
+ * read(@Ctx() context: e<clock>) {}
+ * ```
+ *
+ * An application that always mounts the same plugins declares the pairing once
+ * and keeps its handlers short:
+ *
+ * ```ts
+ * export type AppContext<TSchema extends ElysiaInputSchema = {}> =
+ *   ElysiaRouteContext<TSchema, [typeof clock, typeof cache]>;
+ * ```
  */
-type ElysiaRouteContext<TSchema extends InputSchema = {}> = Context<UnwrapRoute<TSchema, {}, string>>;
+type ElysiaRouteContext<TSchemaOrPlugins extends InputSchema | ElysiaPluginTypes = {}, TPlugins extends ElysiaPluginTypes = never> = TSchemaOrPlugins extends ElysiaPluginTypes ? Context<UnwrapRoute<{}, {}, string>, MountedSingleton<TSchemaOrPlugins>> : Context<UnwrapRoute<TSchemaOrPlugins extends InputSchema ? TSchemaOrPlugins : {}, {}, string>, MountedSingleton<TPlugins>>;
+/**
+ * Elysia's own route schema shape, re-exported so an application can write its
+ * own context alias without importing from `elysia` directly.
+ */
+type ElysiaInputSchema = InputSchema;
 //#endregion
 //#region src/controller.d.ts
 declare const ELYSIA_CONTROLLER = "aponia.elysia.controller";
@@ -63,5 +125,22 @@ 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;
 }
+/**
+ * A module import that carries the native plugin it installs, so the plugin is
+ * both mountable and usable as a context type without a separate reference.
+ */
+interface ElysiaPluginImport<TPlugin extends AnyElysia> extends DynamicModule {
+  readonly plugin: TPlugin;
+}
+/**
+ * Convert a native Elysia plugin into a module import. The result goes straight
+ * into `imports` and doubles as the plugin type an `ElysiaRouteContext` reads:
+ *
+ * ```ts
+ * export const clock = defineElysiaPlugin(new Elysia({ name: "clock" }), { key: "clock" });
+ * export type clock = typeof clock;
+ * ```
+ */
+declare function defineElysiaPlugin<const TPlugin extends AnyElysia>(plugin: TPlugin, options?: ElysiaPluginModuleOptions): ElysiaPluginImport<TPlugin>;
 //#endregion
-export { type AponiaApplicationOptions, AponiaElysiaApplication, AponiaFactory, type AponiaRootModule, type AsyncElysiaPluginModuleOptions, type ConfiguredAponiaApplicationOptions, ELYSIA_CONTROLLER, type ElysiaControllerDefinition, ElysiaPluginModule, type ElysiaPluginModuleOptions, type ElysiaRouteContext, type NativeElysiaConfigurator, type NativeElysiaPlugin, compileRootModule, defineElysiaController };
+export { type AponiaApplicationOptions, AponiaElysiaApplication, AponiaFactory, type AponiaRootModule, type AsyncElysiaPluginModuleOptions, type ConfiguredAponiaApplicationOptions, ELYSIA_CONTROLLER, type ElysiaControllerDefinition, type ElysiaInputSchema, type ElysiaPluginImport, ElysiaPluginModule, type ElysiaPluginModuleOptions, type ElysiaPluginSource, type ElysiaPluginTypes, type ElysiaRouteContext, type NativeElysiaConfigurator, type NativeElysiaPlugin, compileRootModule, defineElysiaController, defineElysiaPlugin };

package/dist/index.mjs

@@ -198,6 +198,21 @@ var ElysiaPluginModule = @Module({}) class {
 		}, options.key);
 	}
 };
+/**
+* Convert a native Elysia plugin into a module import. The result goes straight
+* into `imports` and doubles as the plugin type an `ElysiaRouteContext` reads:
+*
+* ```ts
+* export const clock = defineElysiaPlugin(new Elysia({ name: "clock" }), { key: "clock" });
+* export type clock = typeof clock;
+* ```
+*/
+function defineElysiaPlugin(plugin, options = {}) {
+	return Object.freeze({
+		...ElysiaPluginModule.register(plugin, options),
+		plugin
+	});
+}
 function isElysiaPluginModule(module) {
 	return module.providers.some((provider) => provider.provide === ELYSIA_PLUGIN);
 }
@@ -277,7 +292,7 @@ var AponiaFactory = class {
 			}
 			const instance = container.instantiateController(module, controller);
 			const plugin = Reflect.apply(controller.buildPlugin, void 0, [instance]);
-			if (!(plugin instanceof Elysia)) throw new AponiaError("UNSUPPORTED_CONTROLLER", `Controller "${tokenName(controller.token)}" did not build an Elysia plugin.`, {
+			if (!(plugin instanceof Elysia)) throw new AponiaError("INVALID_CONTROLLER", `Controller "${tokenName(controller.token)}" did not build an Elysia plugin.`, {
 				module: module.id,
 				controller: tokenName(controller.token)
 			});
@@ -306,4 +321,4 @@ function inferControllerPath(plugin) {
 	return plugin.routes[0]?.path ?? "/";
 }
 //#endregion
-export { AponiaElysiaApplication, AponiaFactory, ELYSIA_CONTROLLER, ElysiaPluginModule, compileRootModule, defineElysiaController };
+export { AponiaElysiaApplication, AponiaFactory, ELYSIA_CONTROLLER, ElysiaPluginModule, compileRootModule, defineElysiaController, defineElysiaPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aponiajs/platform-elysia",
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.0-alpha.14",
   "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.6.0-alpha.1",
-    "@aponiajs/core": "0.6.0-alpha.1"
+    "@aponiajs/common": "0.6.0-alpha.14",
+    "@aponiajs/core": "0.6.0-alpha.14"
   },
   "devDependencies": {
     "arktype": "^2.2.3",