@supacloud/elysia 0.20.2 → 0.22.0

package/NOTICE

@@ -1,22 +1,17 @@
 SupaCloud
 Copyright 2025 SupaCloud Contributors
 
-SupaCloud project-owned code in this revision is licensed under the GNU
-Affero General Public License, version 3 only (AGPL-3.0-only). The complete
-license is provided in LICENSE. This is not an "or later" grant.
+SupaCloud project-owned code in this revision is licensed under the Apache
+License, Version 2.0 (Apache-2.0). The complete license is provided in
+LICENSE.
 
 This program is distributed without any warranty; without even the implied
 warranty of merchantability or fitness for a particular purpose.
 
 Third-party components, incorporated upstream code, and their copyright,
-license and attribution notices retain their original terms. This notice
-does not replace those terms or claim ownership of third-party work.
+license and attribution notices retain their original terms. This notice does
+not replace those terms or claim ownership of third-party work.
 
-Earlier SupaCloud code was distributed under Apache-2.0 or MIT as indicated
-in its original files and package metadata. Previously granted permissions
-are not revoked by this change. The historical Apache-2.0 text is preserved
-in LICENSE-APACHE-2.0.txt. Retain any applicable upstream MIT notices as well.
-
-Before publishing this licensing change, maintainers must confirm authority
-to license the affected contributions and compatibility of incorporated
-third-party code. This notice is not evidence of contributor consent.
+Previously released SupaCloud versions retain the permissions granted with
+those versions. See the historical license files and release notices where
+applicable.

package/README.md

@@ -562,9 +562,32 @@ with those statuses. The default content type is
 is for bounded JSON payloads, not files or streams. Existing native `Response`
 passthrough is unchanged.
 
-### `createApplication(options: ApplicationOptions): Elysia`
+### `createApplication(options: ApplicationOptions): Elysia & ApplicationLifecycle`
 
-Creates the root Elysia application from compiled modules.
+Creates the root Elysia application from compiled modules. The returned app
+also exposes explicit `initialize()` and `destroy()` controls for
+application-scoped resources. Initialization runs compiled modules in their
+topological order; destruction runs in reverse order and is idempotent. A
+startup failure triggers best-effort cleanup of all modules that were created,
+and shutdown continues across modules before reporting an `AggregateError`.
+
+The controls are intentionally explicit so hosts can await startup before
+accepting traffic and await shutdown from their process signal handler:
+
+```ts
+const app = createApplication({ modules: createCompiledModules() });
+await app.initialize();
+const server = app.listen(3000);
+process.once("SIGTERM", async () => {
+  server.stop();
+  await app.destroy();
+});
+```
+
+The compiler emits `initializeServices` and `destroyServices` for
+application-scoped providers and controllers that declare `onInit()` or
+`onDestroy()`/`ngOnDestroy()`. Borrowed `useExisting` providers are never
+destroyed by the owning module.
 
 ### `createModulePlugin(compiled, services, ctxFactory?, options?, imported?): Elysia`
 

package/dist/examples/framework-catalog.d.ts

@@ -0,0 +1,77 @@
+import { type CompiledModule } from "../index";
+export interface CatalogIdentity {
+    tenantId: string;
+    subject: string;
+}
+export interface CatalogItem {
+    id: string;
+    name: string;
+}
+export interface CatalogPorts {
+    /** Resolve credentials using a trusted verifier, never a tenant header alone. */
+    authenticate(request: Request): Promise<CatalogIdentity>;
+    /** The repository must apply this verified identity to its authorization. */
+    read(identity: CatalogIdentity, id: string): Promise<CatalogItem>;
+}
+/**
+ * A handwritten adapter fixture, not compiler output or a new module format.
+ * Real applications can supply the existing compiler's createCompiledModules().
+ */
+export declare function createCatalogModule(ports: CatalogPorts): CompiledModule;
+export declare function createCatalogApplication(ports: CatalogPorts): import("elysia/types").AddRoute<"", "local", {
+    decorator: {
+        clock: () => number;
+    };
+    store: {};
+    derive: {};
+}, {
+    typebox: {};
+    error: [];
+}, import("elysia").DefaultMetadata & {
+    schema: {};
+    schemas: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, import("elysia").DefaultEphemeral, {
+    derive: {};
+    schema: {};
+    schemas: {};
+    response: {};
+    error: [];
+}, "get", "/health", import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<{}, {}, "/health">, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>, {}, ({ clock }: {
+    body: unknown;
+    query: Record<string, string | undefined>;
+    params: {};
+    headers: Record<string, string | undefined>;
+    cookie: Record<string, import("elysia").Cookie<unknown>>;
+    server: import("elysia").Server | null;
+    redirect: import("elysia").redirect;
+    set: {
+        headers: import("elysia").HTTPHeaders;
+        status?: number | keyof import("elysia").StatusMap;
+        cookie?: Record<string, import("elysia").BaseCookie>;
+        redirect?: never;
+    };
+    status: <const Code extends number | keyof import("elysia").StatusMap, const T = import("elysia").StatusResponse<Code>>(code: Code, response?: T) => import("elysia").ElysiaStatus<Code, T, import("elysia").NumericStatus<Code>>;
+    problem: typeof import("elysia").problem;
+    defer: (fn: import("elysia/types").AfterResponseHandler<NoInfer<import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<{}, {}, "/health">, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>>, NoInfer<{
+        decorator: {
+            clock: () => number;
+        };
+        store: {};
+        derive: {};
+    } & {
+        derive: {};
+    }>>) => import("elysia/types").MaybePromise<void>;
+    readonly path: string;
+    route?: string | undefined;
+    rid?: string | undefined;
+    request: Request;
+    store: {};
+    clock: () => number;
+}) => {
+    ok: boolean;
+    time: number;
+}>;

package/dist/execution.d.ts

@@ -1,13 +1,2 @@
-export interface ExecutionEvent {
-    kind: "route" | "command" | "job";
-    operation: string;
-    stage: string;
-    phase: "started" | "succeeded" | "failed";
-    requestId?: string;
-    durationMs?: number;
-}
-/** Metadata only: never receives request bodies, credentials, results or errors. */
-export type ExecutionObserver = (event: Readonly<ExecutionEvent>) => void | Promise<void>;
-export declare function observeExecution<T>(observer: ExecutionObserver | undefined, event: Pick<ExecutionEvent, "kind" | "operation" | "stage" | "requestId">, next: () => T | Promise<T>): Promise<T>;
-export declare function executionRequestId(context: unknown): string | undefined;
-export declare function executionTrace(context: unknown): Pick<ExecutionEvent, "requestId">;
+export { executionRequestId, executionTrace, observeExecution, } from "@supacloud/app/execution";
+export type { ExecutionEvent, ExecutionObserver } from "@supacloud/app/execution";

package/dist/framework.d.ts

@@ -0,0 +1,39 @@
+import type { AnyElysia, Elysia } from "elysia";
+import { type ApplicationOptions, type CompiledModule } from "./index";
+/**
+ * Experimental profile for evaluating SupaCloud application composition.
+ *
+ * This intentionally remains a thin profile over createApplication. It owns
+ * SupaCloud defaults without wrapping or reimplementing Elysia's API.
+ */
+export interface SupaCloudFrameworkOptions<Http extends AnyElysia = Elysia, RequestContext = unknown> extends Omit<ApplicationOptions<Http, RequestContext>, "name" | "normalize" | "modules"> {
+    /** Application modules in compiler-emitted topological order. */
+    modules?: CompiledModule[];
+    /** Public application name used in diagnostics and Elysia plugin identity. */
+    name: string;
+    /**
+     * Reject extra properties rather than silently removing them.
+     */
+    normalize?: false;
+}
+export declare function createSupaCloudFramework<const Http extends AnyElysia = Elysia, RequestContext = unknown>(options: SupaCloudFrameworkOptions<Http, RequestContext>): Elysia<"", "local", {
+    decorator: {} & Http["~Singleton"]["decorator"];
+    store: ({} & Http["~Singleton"]["store"] extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never) extends infer T ? { [K in keyof T]: T[K]; } : never;
+    derive: {} & Http["~Singleton"]["derive"] & Http["~Ephemeral"]["derive"];
+}, {
+    typebox: {} & Http["~Definitions"]["typebox"];
+    error: [...Http["~Definitions"]["error"], ...Http["~Ephemeral"]["error"]];
+}, import("elysia").DefaultMetadata & {
+    schema: import("elysia/types").MergeSchema<import("elysia/types").MergeSchema<{} & Http["~Ephemeral"]["schema"], {}, "", false>, (import("elysia").DefaultMetadata & Http["~Metadata"])["schema"], "", false>;
+    schemas: (import("elysia").DefaultMetadata & Http["~Metadata"])["schemas"] & {} & Http["~Ephemeral"]["schemas"];
+    macro: (import("elysia").DefaultMetadata & Http["~Metadata"])["macro"];
+    macroFn: (import("elysia").DefaultMetadata & Http["~Metadata"])["macroFn"];
+    parser: (import("elysia").DefaultMetadata & Http["~Metadata"])["parser"];
+    response: import("elysia/types").UnionResponseStatus<(import("elysia").DefaultMetadata & Http["~Metadata"])["response"], import("elysia/types").UnionResponseStatus<{} & Http["~Ephemeral"]["response"], {}>>;
+}, import("elysia/types").ResolveRouteErrors<{}, [...Http["~Definitions"]["error"], ...Http["~Ephemeral"]["error"]]> & Http["~Routes"], import("elysia").DefaultEphemeral, {
+    derive: {};
+    schema: {};
+    schemas: {};
+    response: {};
+    error: [];
+}> & import("./index").ApplicationLifecycle;

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export type { ElysiaRouteContext, ElysiaRouteDefinition, ElysiaRouteHandler, Ely
 export { createPersistentCommandAdapter, type PersistentCommandHandler } from "./persistent-command";
 export { createDocumentationPlugin } from "./documentation";
 export type { ApplicationDocumentationOptions, DocumentationSource, GraphqlDocumentationOptions, OpenApiDocumentationOptions, } from "./documentation";
+export { createSupaCloudFramework } from "./framework";
+export type { SupaCloudFrameworkOptions } from "./framework";
 export interface CompiledRoute {
     parse?: "none";
     allowDeleteBody?: true;
@@ -106,6 +108,10 @@ export interface CompiledController {
 export interface CompiledModule {
     name: string;
     createServices(deps: Record<string, unknown>, imported: Record<string, Record<string, unknown>>): Record<string, unknown>;
+    /** Initializes application-scoped instances owned by this module. */
+    initializeServices?(services: Record<string, unknown>): Promise<void>;
+    /** Destroys application-scoped instances owned by this module. */
+    destroyServices?(services: Record<string, unknown>): Promise<void>;
     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>>;
@@ -267,6 +273,13 @@ export interface ApplicationOptions<Http extends AnyElysia = Elysia, RequestCont
     /** Optional read-only OpenAPI and GraphQL documentation endpoints. */
     documentation?: ApplicationDocumentationOptions;
 }
+/** Lifecycle controls exposed by createApplication for explicit host startup/shutdown. */
+export interface ApplicationLifecycle {
+    readonly initialized: boolean;
+    readonly destroyed: boolean;
+    initialize(): Promise<void>;
+    destroy(): Promise<void>;
+}
 export interface JobInvocation {
     job: CompiledJob;
     input: unknown;
@@ -392,7 +405,7 @@ export declare function createApplication<const Http extends AnyElysia = Elysia>
     schemas: {};
     response: {};
     error: [];
-}>;
+}> & ApplicationLifecycle;
 /** Semantic alias of createApplication for readable tests. */
 export declare function createTestApp<const Http extends AnyElysia = Elysia>(options: ApplicationOptions<Http>): Elysia<"", "local", {
     decorator: {} & Http["~Singleton"]["decorator"];
@@ -414,7 +427,7 @@ export declare function createTestApp<const Http extends AnyElysia = Elysia>(opt
     schemas: {};
     response: {};
     error: [];
-}>;
+}> & ApplicationLifecycle;
 export { createMemorySandbox, } from "./memory";
 export type { HandleLike as MemoryHandleLike, MemoryDatabase, MemorySandbox, MemorySandboxOptions, MemoryStorage, MemoryStorageObject, } from "./memory";
 export { createMemoryPolicy } from "./memory_policy";

package/dist/index.js

@@ -662,39 +662,11 @@ function createPostgresHttpPolicyStores(database) {
   };
 }
 // src/execution.ts
-async function observeExecution(observer, event, next) {
-  const emit = (phase, durationMs) => {
-    if (!observer)
-      return;
-    try {
-      Promise.resolve(observer(Object.freeze({
-        ...event,
-        phase,
-        ...durationMs === undefined ? {} : { durationMs }
-      }))).catch(() => {});
-    } catch {}
-  };
-  const started = performance.now();
-  emit("started");
-  try {
-    const result = await next();
-    emit("succeeded", performance.now() - started);
-    return result;
-  } catch (error) {
-    emit("failed", performance.now() - started);
-    throw error;
-  }
-}
-function executionRequestId(context) {
-  if (!context || typeof context !== "object" || !("requestId" in context))
-    return;
-  const value = context.requestId;
-  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
-}
-function executionTrace(context) {
-  const requestId = executionRequestId(context);
-  return requestId === undefined ? {} : { requestId };
-}
+import {
+  executionRequestId,
+  executionTrace,
+  observeExecution
+} from "@supacloud/app/execution";
 
 // src/schema_contract.ts
 import {
@@ -1099,6 +1071,14 @@ function createPersistentCommandAdapter(command, options) {
     }
   };
 }
+// src/framework.ts
+function createSupaCloudFramework(options) {
+  return createApplication({
+    ...options,
+    normalize: options.normalize ?? false,
+    modules: options.modules ?? []
+  });
+}
 // src/feature.ts
 function assertFeatureTransition(spec, state, event) {
   const transition = Object.hasOwn(spec.transitions, event) ? spec.transitions[event] : undefined;
@@ -2716,11 +2696,72 @@ function createApplication(options) {
     return pending;
   };
   const imported = {};
+  const moduleServices = [];
   for (const module of options.modules ?? []) {
     const services = module.createServices(options.deps ?? {}, imported);
     imported[module.name] = services;
+    moduleServices.push({ module, services });
     app.use(createModulePlugin(module, services, ctxFactory, { ...options, http: undefined }, imported));
   }
+  let initialized = false;
+  let destroyed = false;
+  let initializationPromise;
+  let destructionPromise;
+  const lifecycle = {
+    get initialized() {
+      return initialized;
+    },
+    get destroyed() {
+      return destroyed;
+    },
+    initialize() {
+      if (destroyed)
+        return Promise.reject(new Error("Application has already been destroyed"));
+      if (initializationPromise)
+        return initializationPromise;
+      initializationPromise = (async () => {
+        try {
+          for (const { module, services } of moduleServices) {
+            await module.initializeServices?.(services);
+          }
+          initialized = true;
+        } catch (error) {
+          try {
+            await lifecycle.destroy();
+          } catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "Application initialization failed and cleanup failed");
+          }
+          throw error;
+        }
+      })();
+      return initializationPromise;
+    },
+    destroy() {
+      if (destructionPromise)
+        return destructionPromise;
+      destroyed = true;
+      destructionPromise = (async () => {
+        const errors = [];
+        for (const { module, services } of [...moduleServices].reverse()) {
+          try {
+            await module.destroyServices?.(services);
+          } catch (error) {
+            errors.push(error);
+          }
+        }
+        if (errors.length > 0) {
+          throw new AggregateError(errors, "Application destruction failed");
+        }
+      })();
+      return destructionPromise;
+    }
+  };
+  Object.defineProperties(app, {
+    initialized: { enumerable: true, configurable: false, get: () => lifecycle.initialized },
+    destroyed: { enumerable: true, configurable: false, get: () => lifecycle.destroyed },
+    initialize: { enumerable: true, configurable: false, value: lifecycle.initialize },
+    destroy: { enumerable: true, configurable: false, value: lifecycle.destroy }
+  });
   return app;
 }
 function createTestApp(options) {
@@ -2758,6 +2799,7 @@ export {
   createQueueWorkerTransport,
   createSchemaDecoder,
   createSupAuthRequestContext,
+  createSupaCloudFramework,
   createSupaCloudRequestContext,
   createTestApp,
   createWorker,

package/dist/webhook-migration-example.d.ts

@@ -38,6 +38,6 @@ export declare function createWebhookMigrationExample(options: {
         schemas: {};
         response: {};
         error: [];
-    }>;
+    }> & import("./index").ApplicationLifecycle;
     modules: import("./fixtures/webhook-generated/application").CompiledApplicationModule[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build",
     "test": "bun test",
-    "test:conformance": "bun test src/conformance.test.ts",
+    "test:conformance": "bun test src/conformance.test.ts src/application-execution.test.ts ../app/src/execution.test.ts ../app/src/execution_bundle.test.ts",
     "test:runtime-safety": "SUPACLOUD_REQUIRE_RUNTIME_SAFETY=1 bun test src/runtime-safety.test.ts",
     "test:contract-upgrade": "bun test src/contract-upgrade.test.ts",
     "bench:http-policy": "bun bench/http-policy.ts",
@@ -42,32 +42,32 @@
     "dependency-injection",
     "module"
   ],
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/vibeunion/supacloud.git",
     "directory": "packages/elysia"
   },
   "dependencies": {
-    "@supacloud/app": "0.18.1",
-    "@supacloud/contracts": "0.5.1",
+    "@supacloud/app": "0.20.0",
+    "@supacloud/contracts": "0.7.0",
     "exact-mirror": "1.2.6",
     "jose": "^6.2.11",
     "typebox": "1.3.34"
   },
   "overrides": {
-    "@supacloud/delivery": "0.2.1",
-    "@supacloud/contracts": "0.5.1",
-    "@supacloud/commands": "0.7.1"
+    "@supacloud/delivery": "0.4.0",
+    "@supacloud/contracts": "0.7.0",
+    "@supacloud/commands": "0.9.0"
   },
   "peerDependencies": {
     "elysia": "2.0.0-beta.19"
   },
   "devDependencies": {
-    "@supacloud/compiler": "0.27.4",
-    "@supacloud/delivery": "0.2.1",
-    "@supacloud/commands": "0.7.1",
-    "@supacloud/db": "0.9.1",
+    "@supacloud/compiler": "0.29.0",
+    "@supacloud/delivery": "0.4.0",
+    "@supacloud/commands": "0.9.0",
+    "@supacloud/db": "0.11.0",
     "@types/bun": "^1.4.2",
     "elysia": "2.0.0-beta.19",
     "typescript": "^7.0.2"