@supacloud/elysia 0.7.0 → 0.8.1

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,15 @@ 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.
+Handlers returning a native `Response` must validate their JSON payload before
+constructing it. 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
@@ -116,6 +124,15 @@ once is rejected.
 Executes a compiler-emitted Job descriptor with its static aspect list and
 compiler-generated job scope.
 
+### `assertFeatureTransition(spec, state, event)`
+
+Checks a declared feature transition against an authoritative state and returns
+the destination state. Unknown events, stale/illegal states and inherited object
+members fail with HTTP 409 / `FEATURE_TRANSITION_CONFLICT`; malformed destinations
+fail with `FEATURE_SPEC_INVALID`. The helper is a matrix assertion, not a workflow
+engine, persistence or authorization layer. Call it inside the application's
+transaction and persist with a row lock or expected-version check.
+
 ### `ApplicationError`
 
 Lightweight error class carrying HTTP `status`, machine-readable `code`, and
@@ -134,3 +151,10 @@ adapters. The memory harness is limited to deterministic HTTP, key-value
 transaction and object-storage contract tests.
 `policy` supplies explicit permission grants/revocations and idempotency claims;
 `storage.failNext()` makes storage failure paths deterministic.
+
+Set `memoryGovernance: true` to enable test-only authorization, transaction,
+idempotency and audit adapters; permissions still require explicit grants.
+HTTP receipt fingerprints include route, body, params, query and business
+headers, not mutable request scopes/services or identity/tracing transport.
+Authorization runs again on a replay. Use durable application-owned adapters
+for production receipts, transactions and audits.

package/dist/feature.d.ts

@@ -0,0 +1,15 @@
+/** Structural contract: the runtime does not import the compiler or discover metadata. */
+export interface FeatureTransitionSpec {
+    name: string;
+    states: readonly string[];
+    transitions: Readonly<Record<string, {
+        from: string;
+        to: string;
+    }>>;
+}
+/**
+ * Check a declared transition against an authoritative state read by the caller.
+ * This is a matrix assertion, not persistence, authorization, or an FSM engine.
+ * Call inside the application's transaction and persist with a version check.
+ */
+export declare function assertFeatureTransition<Spec extends FeatureTransitionSpec>(spec: Spec, state: string, event: string): Spec["states"][number];

package/dist/index.d.ts

@@ -90,6 +90,8 @@ export interface CommandInvocation {
     services: Record<string, unknown>;
 }
 export type CommandExecutor = (invocation: CommandInvocation, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
+export { assertFeatureTransition } from "./feature";
+export type { FeatureTransitionSpec } from "./feature";
 export interface ApplicationAspectContext {
     kind: "route" | "command" | "job";
     name: string;

package/dist/index.js

@@ -1,6 +1,22 @@
 // src/index.ts
 import { Elysia } from "elysia";
 
+// src/feature.ts
+function assertFeatureTransition(spec, state, event) {
+  const transition = Object.hasOwn(spec.transitions, event) ? spec.transitions[event] : undefined;
+  if (!transition || !spec.states.includes(state) || transition.from !== state) {
+    throw new ApplicationError("Feature transition is not allowed", {
+      status: 409,
+      code: "FEATURE_TRANSITION_CONFLICT"
+    });
+  }
+  if (!spec.states.includes(transition.to)) {
+    throw new ApplicationError("Feature transition references an undeclared state", {
+      code: "FEATURE_SPEC_INVALID"
+    });
+  }
+  return transition.to;
+}
 // src/memory.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -240,7 +256,7 @@ function createMemorySandbox(options = {}) {
       }
     },
     idempotency(invocation, next) {
-      return policy.runOnce(policy.subject(invocation.requestContext), invocation.command.name, requireIdempotencyKey(invocation), invocation.input, next);
+      return policy.runOnce(policy.subject(invocation.requestContext), invocation.command.name, requireIdempotencyKey(invocation), memoryCommandInput(invocation), next);
     },
     transaction(_invocation, next) {
       const count = audit.length;
@@ -297,6 +313,21 @@ function createMemorySandbox(options = {}) {
     }
   };
 }
+function memoryCommandInput(invocation) {
+  const input = invocation.input;
+  if (typeof input !== "object" || input === null)
+    return input;
+  const ignoredHeaders = new Set(["authorization", "idempotency-key", "x-request-id", "traceparent", "tracestate"]);
+  const headers = Object.fromEntries([...invocation.request.headers.entries()].filter(([name]) => !ignoredHeaders.has(name)));
+  return {
+    method: invocation.request.method,
+    path: new URL(invocation.request.url).pathname,
+    body: "body" in input ? input.body : undefined,
+    params: "params" in input ? input.params : undefined,
+    query: "query" in input ? input.query : undefined,
+    headers
+  };
+}
 function storageKey(bucket, key) {
   return JSON.stringify([bucket, key]);
 }
@@ -541,6 +572,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);
@@ -652,15 +692,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) {
@@ -707,6 +738,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",
@@ -756,6 +794,7 @@ export {
   EXECUTION_ID_HEADER,
   IDEMPOTENCY_KEY_HEADER,
   VERIFIED_JWT_SUBJECT_HEADER,
+  assertFeatureTransition,
   composeAspects,
   composeCommandExecutors,
   createApplication,

package/package.json

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