@supacloud/elysia 0.8.0 → 0.9.0

package/README.md

@@ -26,7 +26,8 @@ Runtime adapter that turns `@supacloud/compiler` output into a production-ready
   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.
+  HTTP 422 for request validation and HTTP 500 / `RESPONSE_VALIDATION_ERROR`
+  for invalid handler output, without exposing payloads or schema internals.
 
 ## Installation
 
@@ -83,8 +84,16 @@ sandbox.reset();
 
 Route `body`, `params`, `query`, and `response` schemas are enforced by
 Elysia before and after the handler. Invalid input returns the standard `422`
-validation response; invalid handler output is rejected before it reaches the
-client.
+validation response; invalid structured handler output returns HTTP 500 with
+`RESPONSE_VALIDATION_ERROR`. A response validation failure can occur **after a
+command has committed**; it does not imply rollback and must not trigger a blind
+write retry. Confirm the outcome using the application's durable receipt or
+read-back protocol. A custom `errorMapper` can override this public envelope.
+
+Native `Response` objects are passed through by Elysia, including JSON responses.
+Use `validatedJsonResponse` to opt into validation when constructing a native
+JSON response. Otherwise handlers must validate their JSON payload themselves.
+The adapter does not consume or parse binary/streaming responses.
 
 Jobs are executed explicitly with `executeJob(compiledModule, services, job,
 input, requestContext)`. The asynchronous compiler-generated job scope is
@@ -93,6 +102,39 @@ fails partway through.
 
 ## API
 
+### `validatedJsonResponse(validate, value, init?): Response`
+
+Constructs a native JSON response after a synchronous, caller-owned type guard
+validates the actual serialized JSON snapshot. The value type is inferred from
+the guard; compatible extra fields are preserved. For a TypeBox contract, the
+guard can delegate to `Value.Check(schema, value)` or a compiled validator.
+No additional schema dependency is required by the adapter.
+
+```ts
+import { validatedJsonResponse } from "@supacloud/elysia";
+import { isReportReceipt } from "./contracts";
+
+return validatedJsonResponse(isReportReceipt, receipt, {
+  status: 201,
+  headers: { "x-request-id": requestId },
+});
+```
+
+The helper serializes once, validates that wire snapshot, and sends those same
+bytes. Validation cannot mutate the outgoing body; it is not a transform or
+coercion hook. Guards must be synchronous and side-effect free. Serialization
+failures and invalid receipts throw a sanitized `ApplicationError` with HTTP 500
+and `RESPONSE_VALIDATION_ERROR`, without retaining payloads or validator causes.
+The application's `errorMapper` can map this to its outcome-confirmation
+protocol. The helper never retries a command or implies rollback.
+
+`init` uses native `Response` options. The helper explicitly rejects null-body
+statuses 204, 205 and 304, including on runtimes that otherwise accept a body
+with those statuses. The default content type is
+`application/json`, and explicitly supplied headers are preserved. This helper
+is for bounded JSON payloads, not files or streams. Existing native `Response`
+passthrough is unchanged.
+
 ### `createApplication(options: ApplicationOptions): Elysia`
 
 Creates the root Elysia application from compiled modules.

package/dist/index.d.ts

@@ -144,6 +144,13 @@ export declare class ApplicationError extends Error implements PublicApplication
     readonly details?: unknown;
     constructor(message: string, options?: ApplicationErrorOptions);
 }
+export type JsonResponseValidator<T> = (value: unknown) => value is T;
+/**
+ * Validate the serialized JSON snapshot before creating a native Response.
+ * Validators must be synchronous and side-effect free; response failures do not
+ * imply that application writes were rolled back.
+ */
+export declare function validatedJsonResponse<T>(validate: JsonResponseValidator<T>, value: NoInfer<T>, init?: ResponseInit): Response;
 export interface ErrorContext {
     request: Request;
     requestContext: unknown;

package/dist/index.js

@@ -405,6 +405,28 @@ class ApplicationError extends Error {
     this.details = options.details;
   }
 }
+function validatedJsonResponse(validate, value, init) {
+  if (init?.status === 204 || init?.status === 205 || init?.status === 304) {
+    throw new TypeError("JSON responses cannot use a null-body status");
+  }
+  let body;
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined || validate(JSON.parse(serialized)) !== true) {
+      throw new Error("Invalid JSON response");
+    }
+    body = serialized;
+  } catch {
+    throw new ApplicationError("Response validation failed", {
+      status: 500,
+      code: "RESPONSE_VALIDATION_ERROR"
+    });
+  }
+  const headers = new Headers(init?.headers);
+  if (!headers.has("content-type"))
+    headers.set("content-type", "application/json");
+  return new Response(body, { ...init, headers });
+}
 function safeHeaderValue(value, maxLength) {
   if (!value || value.length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
     return;
@@ -572,6 +594,15 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
     requestContexts.set(request, requestContext);
     return { requestContext };
   });
+  plugin.onError(async ({ code, error, request }) => {
+    const context = {
+      request,
+      requestContext: requestContexts.get(request),
+      frameworkCode: code
+    };
+    const mapped = await options.errorMapper?.(error, context);
+    return mapped ?? defaultErrorResponse(error, code);
+  });
   for (const controller of compiled.controllers) {
     for (const route of controller.routes) {
       const path = joinPaths(controller.path, route.path);
@@ -683,15 +714,6 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
       }
     }
   }
-  plugin.onError({ as: "global" }, async ({ code, error, request }) => {
-    const context = {
-      request,
-      requestContext: requestContexts.get(request),
-      frameworkCode: code
-    };
-    const mapped = await options.errorMapper?.(error, context);
-    return mapped ?? defaultErrorResponse(error, code);
-  });
   return plugin;
 }
 async function executeJob(compiled, services, job, input, requestContext, imported = {}, executor) {
@@ -738,6 +760,13 @@ function defaultErrorResponse(error, frameworkCode) {
     }, { status: error.status });
   }
   if (frameworkCode === "VALIDATION") {
+    if (isRecord(error) && error.type === "response") {
+      return Response.json({
+        ok: false,
+        code: "RESPONSE_VALIDATION_ERROR",
+        message: "Response validation failed"
+      }, { status: 500 });
+    }
     return Response.json({
       ok: false,
       code: "VALIDATION_ERROR",
@@ -800,5 +829,6 @@ export {
   defaultErrorResponse,
   executeJob,
   requireIdempotencyKey,
-  requireTrustedIdentity
+  requireTrustedIdentity,
+  validatedJsonResponse
 };

package/package.json

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