@supacloud/elysia 0.4.0 → 0.5.1

package/README.md

@@ -8,13 +8,19 @@ Runtime adapter that turns `@supacloud/compiler` output into a production-ready
 - **Decoupled compilation**: takes the output of `@supacloud/compiler` directly.
 - **Topological initialization**: modules are registered in dependency order,
   passing exported services downstream via Elysia plugins.
-- **Request-scoped providers**: creates a fresh scope per HTTP request via
-  `createRequestScope`, mapping request-scoped controllers and services.
+- **Request-scoped providers**: creates a fresh scope per HTTP request via the
+  asynchronous compiler-generated `createRequestScope`, mapping request-scoped
+  controllers and services.
+- **Request-scope teardown**: invokes the compiler-generated
+  `destroyRequestScope` after the response, including when the handler fails.
 - **TypeBox schema binding**: attaches compiled parameter, query, body, and
   response TypeBox schemas directly to Elysia route definitions.
 - **Unified Command Pipeline**: runs `@Command`-decorated handlers through a
   structured `commandGovernance` adapter chain or a custom `composeCommandExecutors`
   pipeline (fail-closed if command routes lack an executor).
+- **Static AOP pipeline**: executes compiler-emitted module, route, command, and
+  job aspects with `composeAspects`; no runtime discovery or registration is
+  performed.
 - **Public error mapping**: transforms framework / application errors via
   `errorMapper` with standard `ApplicationError` envelope support, preserving
   Elysia's default behavior (422) for schema validation errors.
@@ -52,6 +58,11 @@ const app = createApplication({
 export default app;
 ```
 
+Jobs are executed explicitly with `executeJob(compiledModule, services, job,
+input, requestContext)`. The asynchronous compiler-generated job scope is
+destroyed after execution, including when the job throws or scope construction
+fails partway through.
+
 ## API
 
 ### `createApplication(options: ApplicationOptions): Elysia`
@@ -67,6 +78,16 @@ directly onto an existing Elysia app.
 
 Composes multiple `CommandExecutor` middleware functions into an onion-style pipeline.
 
+### `composeAspects(...aspects): ApplicationAspect`
+
+Composes static `around(context, next)` functions. Calling `next()` more than
+once is rejected.
+
+### `executeJob(...)`
+
+Executes a compiler-emitted Job descriptor with its static aspect list and
+compiler-generated job scope.
+
 ### `ApplicationError`
 
 Lightweight error class carrying HTTP `status`, machine-readable `code`, and

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export interface CompiledRoute {
     response?: unknown;
     /** Class name of the @Command explicitly bound to this route. */
     command?: string;
+    /** Statically generated route aspects. */
+    aspects?: ApplicationAspect[];
 }
 export interface CompiledCommand {
     className: string;
@@ -19,6 +21,15 @@ export interface CompiledCommand {
     transaction?: "required" | "none" | string;
     audit?: string;
     idempotency?: "required" | "none" | string;
+    /** Statically generated command aspects. */
+    aspects?: ApplicationAspect[];
+}
+export interface CompiledJob {
+    className: string;
+    name: string;
+    serviceKey: string;
+    scope: "application" | "request" | "job";
+    aspects?: ApplicationAspect[];
 }
 export interface CompiledController {
     /** Controller path prefix, e.g. "/cases". */
@@ -31,9 +42,15 @@ export interface CompiledController {
 export interface CompiledModule {
     name: string;
     createServices(deps: Record<string, unknown>, imported: Record<string, Record<string, unknown>>): Record<string, unknown>;
-    createRequestScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Record<string, unknown>;
+    createRequestScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Record<string, unknown> | Promise<Record<string, unknown>>;
+    destroyRequestScope?(scope: Record<string, unknown>): Promise<void>;
+    createJobScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Record<string, unknown> | Promise<Record<string, unknown>>;
+    destroyJobScope?(scope: Record<string, unknown>): Promise<void>;
     controllers: CompiledController[];
     commands?: CompiledCommand[];
+    jobs?: CompiledJob[];
+    /** Statically generated module aspects. */
+    aspects?: ApplicationAspect[];
 }
 export type RequestContextFactory = (request: Request) => unknown | Promise<unknown>;
 export declare const VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
@@ -65,6 +82,23 @@ export interface CommandInvocation {
     services: Record<string, unknown>;
 }
 export type CommandExecutor = (invocation: CommandInvocation, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
+export interface ApplicationAspectContext {
+    kind: "route" | "command" | "job";
+    name: string;
+    input: unknown;
+    request?: Request;
+    requestContext?: unknown;
+    scope?: Record<string, unknown>;
+    services?: Record<string, unknown>;
+    metadata?: unknown;
+}
+export type ApplicationAspect = (context: ApplicationAspectContext, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
+/**
+ * Compose the compiler-emitted aspect list into a deterministic onion chain.
+ * The runtime only executes the functions it receives; it never discovers or
+ * registers aspects.
+ */
+export declare function composeAspects(...aspects: (ApplicationAspect | undefined | null)[]): ApplicationAspect;
 export type CommandAuthorizer = (invocation: CommandInvocation) => void | Promise<void>;
 export type CommandMiddleware = (invocation: CommandInvocation, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
 export interface CommandAudit {
@@ -121,6 +155,14 @@ export interface ApplicationOptions {
     /** Maps framework or application failures to the public HTTP contract. */
     errorMapper?: ErrorMapper;
 }
+export interface JobInvocation {
+    job: CompiledJob;
+    input: unknown;
+    requestContext: unknown;
+    scope?: Record<string, unknown>;
+    services: Record<string, unknown>;
+}
+export type JobExecutor = (invocation: JobInvocation, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
 /**
  * Build the standard request context for applications behind SupaCloud Edge
  * Runtime. The runtime strips incoming x-supacloud-jwt-sub values and writes
@@ -144,6 +186,14 @@ export declare function requireIdempotencyKey(invocation: CommandInvocation): st
  * looked up on `scope`, everything else on `services`.
  */
 export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory, options?: Pick<ApplicationOptions, "commandGovernance" | "commandExecutor" | "errorMapper">, imported?: Record<string, Record<string, unknown>>): Elysia;
+/**
+ * Execute one compiler-emitted Job descriptor.
+ *
+ * Job classes use `run(input)` as their entry method; `execute(input)` is also
+ * accepted for command-like job implementations. The scope factory and
+ * destruction hooks are generated statically by the compiler.
+ */
+export declare function executeJob(compiled: CompiledModule, services: Record<string, unknown>, job: CompiledJob, input: unknown, requestContext: unknown, imported?: Record<string, Record<string, unknown>>, executor?: JobExecutor): Promise<unknown>;
 export declare function defaultErrorResponse(error: unknown, frameworkCode?: string | number): Response;
 /**
  * Create the root Elysia application from compiled modules.

package/dist/index.js

@@ -3,6 +3,22 @@ import { Elysia } from "elysia";
 var VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
 var EXECUTION_ID_HEADER = "x-sb-execution-id";
 var IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+function composeAspects(...aspects) {
+  const active = aspects.filter((aspect) => typeof aspect === "function");
+  return (context, next) => {
+    let index = -1;
+    const dispatch = (current) => {
+      if (current <= index) {
+        return Promise.reject(new Error("next() called multiple times"));
+      }
+      index = current;
+      if (current === active.length)
+        return Promise.resolve(next());
+      return Promise.resolve(active[current](context, () => dispatch(current + 1)));
+    };
+    return dispatch(0);
+  };
+}
 function composeCommandExecutors(...executors) {
   const active = executors.filter((e) => typeof e === "function");
   if (active.length === 0)
@@ -46,6 +62,15 @@ function safeHeaderValue(value, maxLength) {
   }
   return value;
 }
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isTrustedIdentity(value) {
+  return isRecord(value) && typeof value.authenticated === "boolean" && (value.subject === undefined || typeof value.subject === "string") && (value.accessToken === undefined || typeof value.accessToken === "string");
+}
+function isAuthenticatedTrustedIdentity(value) {
+  return value?.authenticated === true && typeof value.subject === "string" && value.subject.length > 0 && typeof value.accessToken === "string" && value.accessToken.length > 0;
+}
 function bearerToken(request) {
   const authorization = request.headers.get("authorization");
   const match = authorization?.match(/^Bearer\s+(.+)$/i);
@@ -89,43 +114,50 @@ function missingGovernanceAdapter(command, adapter) {
 function createCommandExecutor(governance) {
   return async (invocation, next) => {
     const { command } = invocation;
-    if (command.audit && !governance.audit) {
+    const audit = command.audit ? governance.audit : undefined;
+    const transaction = command.transaction === "required" ? governance.transaction : undefined;
+    const idempotency = command.idempotency === "required" ? governance.idempotency : undefined;
+    if (command.audit && !audit) {
       throw missingGovernanceAdapter(command, "audit");
     }
-    if (command.transaction === "required" && !governance.transaction) {
+    if (command.transaction === "required" && !transaction) {
       throw missingGovernanceAdapter(command, "transaction");
     }
-    if (command.idempotency === "required" && !governance.idempotency) {
+    if (command.idempotency === "required" && !idempotency) {
       throw missingGovernanceAdapter(command, "idempotency");
     }
     try {
       await governance.authorize(invocation);
       let execute = async () => {
         const result = await next();
-        if (command.audit)
-          await governance.audit.succeeded(invocation, result);
+        if (audit)
+          await audit.succeeded.call(audit, invocation, result);
         return result;
       };
       if (command.transaction === "required") {
+        if (!transaction)
+          throw missingGovernanceAdapter(command, "transaction");
         const inner = execute;
-        execute = () => Promise.resolve(governance.transaction(invocation, inner));
+        execute = () => Promise.resolve(transaction.call(governance, invocation, inner));
       }
       if (command.idempotency === "required") {
+        if (!idempotency)
+          throw missingGovernanceAdapter(command, "idempotency");
         const inner = execute;
-        execute = () => Promise.resolve(governance.idempotency(invocation, inner));
+        execute = () => Promise.resolve(idempotency.call(governance, invocation, inner));
       }
       return await execute();
     } catch (error) {
-      if (command.audit)
-        await governance.audit.failed(invocation, error);
+      if (audit)
+        await audit.failed.call(audit, invocation, error);
       throw error;
     }
   };
 }
 function requireTrustedIdentity(requestContext) {
-  const context = requestContext;
-  const identity = context?.identity;
-  if (!identity?.authenticated || !identity.subject || !identity.accessToken) {
+  const context = isRecord(requestContext) ? requestContext : {};
+  const identity = isTrustedIdentity(context.identity) ? context.identity : undefined;
+  if (!isAuthenticatedTrustedIdentity(identity)) {
     throw new ApplicationError("Authenticated user context is required", {
       status: 401,
       code: "AUTHENTICATION_REQUIRED"
@@ -134,8 +166,8 @@ function requireTrustedIdentity(requestContext) {
   return identity;
 }
 function requireIdempotencyKey(invocation) {
-  const context = invocation.requestContext;
-  const key = context?.idempotencyKey ?? safeHeaderValue(invocation.request.headers.get(IDEMPOTENCY_KEY_HEADER), 512);
+  const context = isRecord(invocation.requestContext) ? invocation.requestContext : {};
+  const key = (typeof context.idempotencyKey === "string" ? context.idempotencyKey : undefined) ?? safeHeaderValue(invocation.request.headers.get(IDEMPOTENCY_KEY_HEADER), 512);
   if (!key) {
     throw new ApplicationError("Idempotency-Key header is required", {
       status: 400,
@@ -148,6 +180,9 @@ function joinPaths(prefix, path) {
   const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
   return joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
 }
+function controllerInstance(value) {
+  return isRecord(value) ? value : undefined;
+}
 function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext, options = {}, imported = {}) {
   const hasCommandRoutes = compiled.controllers.some((controller) => controller.routes.some((route) => route.command !== undefined));
   if (hasCommandRoutes && !options.commandGovernance && !options.commandExecutor) {
@@ -168,6 +203,21 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
   const commandExecutor = options.commandExecutor && governanceExecutor ? composeCommandExecutors(options.commandExecutor, governanceExecutor) : options.commandExecutor ?? governanceExecutor;
   const plugin = new Elysia({ name: `supacloud:${compiled.name}` }).decorate("services", services);
   const createRequestScope = compiled.createRequestScope;
+  const requestScopes = new WeakMap;
+  if (compiled.destroyRequestScope) {
+    const destroyRequestScope = compiled.destroyRequestScope;
+    plugin.onAfterResponse(async ({ request }) => {
+      const scope = requestScopes.get(request);
+      if (!scope)
+        return;
+      requestScopes.delete(request);
+      try {
+        await destroyRequestScope(scope);
+      } catch (error) {
+        console.error(`supacloud: request scope cleanup failed for "${compiled.name}"`, error);
+      }
+    });
+  }
   plugin.resolve(async ({ request }) => {
     const requestContext = await ctxFactory(request);
     requestContexts.set(request, requestContext);
@@ -187,9 +237,11 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
         schema.response = route.response;
       const handler = async (ctx) => {
         const requestContext = ctx.requestContext ?? await ctxFactory(ctx.request);
-        const requestScope = createRequestScope ? createRequestScope(services, requestContext, imported) : undefined;
+        const requestScope = createRequestScope ? await createRequestScope(services, requestContext, imported) : undefined;
+        if (requestScope && compiled.destroyRequestScope)
+          requestScopes.set(ctx.request, requestScope);
         const source = controller.scope === "request" ? requestScope : services;
-        const instance = source?.[controller.serviceKey];
+        const instance = controllerInstance(source?.[controller.serviceKey]);
         const method = instance?.[route.handler];
         if (typeof method !== "function") {
           throw new Error(`supacloud: controller "${controller.serviceKey}" has no handler "${route.handler}" in scope "${controller.scope}"`);
@@ -202,24 +254,58 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
           scope: requestScope,
           requestContext
         };
-        const invoke = () => method.call(instance, input);
-        if (!route.command)
-          return invoke();
-        const command = commandsByClassName.get(route.command);
-        if (!commandExecutor) {
-          throw new ApplicationError(`Command "${command.name}" has no executor`, {
-            status: 501,
-            code: "COMMAND_EXECUTOR_UNAVAILABLE"
-          });
-        }
-        return commandExecutor({
-          command,
+        const invoke = () => Reflect.apply(method, instance, [input]);
+        const routeContext = {
+          kind: "route",
+          name: `${route.method} ${path}`,
+          input,
+          request: ctx.request,
+          requestContext,
+          scope: requestScope,
+          services,
+          metadata: route
+        };
+        const command = route.command ? commandsByClassName.get(route.command) : undefined;
+        const commandContext = {
+          kind: "command",
+          name: command?.name ?? route.command ?? `${route.method} ${path}`,
           input,
           request: ctx.request,
           requestContext,
           scope: requestScope,
-          services
-        }, invoke);
+          services,
+          metadata: command ?? route
+        };
+        const commandAspects = route.command ? commandsByClassName.get(route.command)?.aspects ?? [] : [];
+        const routePipeline = composeAspects(...route.aspects ?? []);
+        const commandPipeline = composeAspects(...commandAspects);
+        const modulePipeline = composeAspects(...compiled.aspects ?? []);
+        const invokeRoute = () => routePipeline(routeContext, () => route.command ? commandPipeline(commandContext, () => invokeCommand()) : invoke());
+        const invokeCommand = () => {
+          if (!route.command)
+            return invoke();
+          if (!command) {
+            throw new ApplicationError(`Command "${route.command}" is not registered`, {
+              code: "COMMAND_NOT_REGISTERED"
+            });
+          }
+          if (!commandExecutor) {
+            throw new ApplicationError(`Command "${command.name}" has no executor`, {
+              status: 501,
+              code: "COMMAND_EXECUTOR_UNAVAILABLE"
+            });
+          }
+          const invocation = {
+            command,
+            input,
+            request: ctx.request,
+            requestContext,
+            scope: requestScope,
+            services
+          };
+          return commandExecutor(invocation, invoke);
+        };
+        return modulePipeline(route.command ? commandContext : routeContext, invokeRoute);
       };
       switch (route.method) {
         case "GET":
@@ -257,6 +343,40 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
   });
   return plugin;
 }
+async function executeJob(compiled, services, job, input, requestContext, imported = {}, executor) {
+  const jobScope = job.scope === "job" && compiled.createJobScope ? await compiled.createJobScope(services, requestContext, imported) : undefined;
+  try {
+    const source = job.scope === "job" ? jobScope : services;
+    const instance = controllerInstance(source?.[job.serviceKey]);
+    const method = instance?.run ?? instance?.execute;
+    if (typeof method !== "function") {
+      throw new ApplicationError(`Job "${job.name}" has no run(input) or execute(input) handler`, { code: "JOB_HANDLER_UNAVAILABLE" });
+    }
+    const invocation = {
+      job,
+      input,
+      requestContext,
+      scope: jobScope,
+      services
+    };
+    const context = {
+      kind: "job",
+      name: job.name,
+      input,
+      requestContext,
+      scope: jobScope,
+      services,
+      metadata: job
+    };
+    const invoke = () => Reflect.apply(method, instance, [input]);
+    const pipeline = composeAspects(...compiled.aspects ?? [], ...job.aspects ?? []);
+    return await pipeline(context, executor ? () => executor(invocation, invoke) : invoke);
+  } finally {
+    if (jobScope && compiled.destroyJobScope) {
+      await compiled.destroyJobScope(jobScope);
+    }
+  }
+}
 function defaultErrorResponse(error, frameworkCode) {
   if (isPublicApplicationError(error)) {
     return Response.json({
@@ -280,10 +400,9 @@ function defaultErrorResponse(error, frameworkCode) {
   }, { status: 500 });
 }
 function isPublicApplicationError(error) {
-  if (!(error instanceof Error))
+  if (!(error instanceof Error) || !isRecord(error))
     return false;
-  const candidate = error;
-  return candidate.expose === true && typeof candidate.status === "number" && Number.isInteger(candidate.status) && candidate.status >= 400 && candidate.status <= 599 && typeof candidate.code === "string" && candidate.code.length > 0;
+  return error.expose === true && typeof error.status === "number" && Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 && typeof error.code === "string" && error.code.length > 0;
 }
 function createApplication(options) {
   const app = new Elysia({ name: options.name ?? "supacloud:app" });
@@ -317,6 +436,7 @@ export {
   EXECUTION_ID_HEADER,
   IDEMPOTENCY_KEY_HEADER,
   VERIFIED_JWT_SUBJECT_HEADER,
+  composeAspects,
   composeCommandExecutors,
   createApplication,
   createCommandExecutor,
@@ -324,6 +444,7 @@ export {
   createSupaCloudRequestContext,
   createTestApp,
   defaultErrorResponse,
+  executeJob,
   requireIdempotencyKey,
   requireTrustedIdentity
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",