@supacloud/elysia 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# @supacloud/elysia
+
+Elysia runtime adapter for SupaCloud applications: it adapts the plain-data
+`CompiledModule` produced by `@supacloud/compiler` into Elysia plugins and
+manages the `application` / `request` scopes at runtime.
+
+This package does **not** depend on the compiler. The contract below is
+declared and re-exported locally; any object matching it works.
+
+## Compiled module contract
+
+```ts
+interface CompiledRoute {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  handler: string;   // method name on the controller instance
+  body?: unknown;    // TypeBox schema; validation enabled only when present
+  params?: unknown;
+  query?: unknown;
+  response?: unknown;
+}
+
+interface CompiledController {
+  path: string;                       // controller prefix, e.g. "/cases"
+  serviceKey: string;                 // key on services or the request scope
+  scope: "application" | "request" | "job";
+  routes: CompiledRoute[];
+}
+
+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,
+  ): Record<string, unknown>;
+  controllers: CompiledController[];
+}
+```
+
+Controller methods are invoked as
+`controller[handler]({ body, params, query, request, scope })`; non-`Response`
+return values are serialized to JSON by Elysia. Validation failures use
+Elysia's default behavior (422).
+
+## Usage
+
+```ts
+import { createApplication } from "@supacloud/elysia";
+import AuditModule from "./.generated/audit.module";
+import CaseModule from "./.generated/case.module";
+
+const app = createApplication({
+  name: "case-service",
+  modules: [AuditModule, CaseModule], // topological import order
+  deps: { db: createDbClient() },     // platform deps, passed to createServices
+  requestContext: (request) => ({
+    requestId: request.headers.get("x-request-id") ?? crypto.randomUUID(),
+    request,
+  }),
+});
+
+export default app;
+```
+
+- Each module is instantiated in order: `createServices(deps, imported)`
+  receives platform `deps` plus the services of all previously created
+  modules, keyed by module name.
+- Each module becomes a named Elysia plugin (`supacloud:<module.name>`) that
+  decorates the context with `services`.
+- When a module defines `createRequestScope`, a **fresh** request scope is
+  resolved per request and exposed on the `scope` context key — never reused
+  across requests. Request-scoped controller instances are looked up on
+  `scope`; application-scoped instances on `services`.
+- Full route paths are `controller.path + route.path` (slashes normalized);
+  schema options (`body` / `params` / `query` / `response`) are passed to
+  Elysia only when the corresponding field exists.
+
+Lower-level building blocks:
+
+- `createModulePlugin(compiled, services, ctxFactory?)` — adapt a single
+  module into an Elysia plugin (useful for tests and embedding).
+- `createTestApp(options)` — semantic alias of `createApplication`.
+- `testRequest(app, path, init?)` (from `@supacloud/elysia` source
+  `src/testing.ts`) — in-process `app.handle(new Request(...))` helper.
+
+## Edge runtime integration
+
+SupaCloud's edge runtime (`@supacloud/edge-runtime`) supports Elysia as a
+first-class function framework. Default-export the Elysia instance from your
+function entrypoint and set the activation manifest to:
+
+```json
+{ "framework": "elysia" }
+```
+
+The runtime then routes requests through `app.handle(request)` instead of a
+plain `fetch` handler.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { Elysia } from "elysia";
+export interface CompiledRoute {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    /** Method name on the controller instance. */
+    handler: string;
+    /** TypeBox schema; validation is enabled only when the field is present. */
+    body?: unknown;
+    params?: unknown;
+    query?: unknown;
+    response?: unknown;
+}
+export interface CompiledController {
+    /** Controller path prefix, e.g. "/cases". */
+    path: string;
+    /** Key of the controller instance on `services` or the request scope. */
+    serviceKey: string;
+    scope: "application" | "request" | "job";
+    routes: CompiledRoute[];
+}
+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): Record<string, unknown>;
+    controllers: CompiledController[];
+}
+export type RequestContextFactory = (request: Request) => unknown | Promise<unknown>;
+export interface ApplicationOptions {
+    name?: string;
+    /** Modules in topological import order. */
+    modules: CompiledModule[];
+    /** Platform-level dependencies (db client etc.), passed to createServices. */
+    deps?: Record<string, unknown>;
+    /** Builds the per-request context object. Defaults to { requestId, request }. */
+    requestContext?: RequestContextFactory;
+}
+/**
+ * Adapt a single compiled module into an Elysia plugin.
+ *
+ * The plugin decorates the context with `services`; when the module defines
+ * `createRequestScope`, a fresh request scope is resolved per request and
+ * exposed on the `scope` context key. Request-scoped controller instances are
+ * looked up on `scope`, everything else on `services`.
+ */
+export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory): Elysia;
+/**
+ * Create the root Elysia application from compiled modules.
+ *
+ * Modules are instantiated in the given (topological) order: each module's
+ * `createServices` receives `deps` plus the services of all previously
+ * created modules, keyed by module name.
+ */
+export declare function createApplication(options: ApplicationOptions): Elysia;
+/** Semantic alias of createApplication for readable tests. */
+export declare function createTestApp(options: ApplicationOptions): Elysia;

package/dist/index.js

@@ -0,0 +1,85 @@
+// src/index.ts
+import { Elysia } from "elysia";
+var defaultRequestContext = (request) => ({
+  requestId: crypto.randomUUID(),
+  request
+});
+function joinPaths(prefix, path) {
+  const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
+  return joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
+}
+function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext) {
+  const plugin = new Elysia({ name: `supacloud:${compiled.name}` }).decorate("services", services);
+  if (compiled.createRequestScope) {
+    const createRequestScope = compiled.createRequestScope;
+    plugin.resolve(async ({ request }) => ({
+      scope: createRequestScope(services, await ctxFactory(request))
+    }));
+  }
+  for (const controller of compiled.controllers) {
+    for (const route of controller.routes) {
+      const path = joinPaths(controller.path, route.path);
+      const schema = {};
+      if (route.body !== undefined)
+        schema.body = route.body;
+      if (route.params !== undefined)
+        schema.params = route.params;
+      if (route.query !== undefined)
+        schema.query = route.query;
+      if (route.response !== undefined)
+        schema.response = route.response;
+      const handler = async (ctx) => {
+        const source = controller.scope === "request" ? ctx.scope : services;
+        const instance = 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}"`);
+        }
+        return method.call(instance, {
+          body: ctx.body,
+          params: ctx.params,
+          query: ctx.query,
+          request: ctx.request,
+          scope: ctx.scope
+        });
+      };
+      switch (route.method) {
+        case "GET":
+          plugin.get(path, handler, schema);
+          break;
+        case "POST":
+          plugin.post(path, handler, schema);
+          break;
+        case "PUT":
+          plugin.put(path, handler, schema);
+          break;
+        case "PATCH":
+          plugin.patch(path, handler, schema);
+          break;
+        case "DELETE":
+          plugin.delete(path, handler, schema);
+          break;
+      }
+    }
+  }
+  return plugin;
+}
+function createApplication(options) {
+  const app = new Elysia({ name: options.name ?? "supacloud:app" });
+  const ctxFactory = options.requestContext ?? defaultRequestContext;
+  const imported = {};
+  for (const module of options.modules) {
+    const services = module.createServices(options.deps ?? {}, imported);
+    imported[module.name] = services;
+    app.use(createModulePlugin(module, services, ctxFactory));
+  }
+  return app;
+}
+function createTestApp(options) {
+  return createApplication(options);
+}
+export {
+  createApplication,
+  createModulePlugin,
+  createTestApp
+};

package/dist/testing.d.ts

@@ -0,0 +1,3 @@
+import type { Elysia } from "elysia";
+/** Issue an in-process request against an Elysia app. */
+export declare function testRequest(app: Elysia, path: string, init?: RequestInit): Promise<Response>;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@supacloud/elysia",
+  "version": "0.1.0",
+  "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts --outdir dist --target node --external elysia",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit"
+  },
+  "keywords": [
+    "supacloud",
+    "elysia",
+    "adapter",
+    "dependency-injection",
+    "module"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeunion/supacloud.git",
+    "directory": "packages/elysia"
+  },
+  "peerDependencies": {
+    "elysia": "^1.4.30"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "elysia": "^1.4.30",
+    "typescript": "^7.0.2"
+  }
+}