@supacloud/elysia 0.8.1 → 0.9.0

package/README.md

@@ -91,8 +91,9 @@ 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.
-Handlers returning a native `Response` must validate their JSON payload before
-constructing it. The adapter does not consume or parse binary/streaming 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
@@ -101,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;
@@ -807,5 +829,6 @@ export {
   defaultErrorResponse,
   executeJob,
   requireIdempotencyKey,
-  requireTrustedIdentity
+  requireTrustedIdentity,
+  validatedJsonResponse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.8.1",
+  "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",