@supacloud/elysia 0.6.0 → 0.8.0

package/README.md

@@ -15,6 +15,9 @@ Runtime adapter that turns `@supacloud/compiler` output into a production-ready
   `destroyRequestScope` after the response, including when the handler fails.
 - **TypeBox schema binding**: attaches compiled parameter, query, body, and
   response TypeBox schemas directly to Elysia route definitions.
+- **Compiler invoker execution**: uses the compiler-emitted positional invoker
+  after Elysia has decoded route input, while retaining the legacy input-object
+  handler path for hand-written compiled fixtures.
 - **Unified Command Pipeline**: runs `@Command`-decorated handlers through a
   structured `commandGovernance` adapter chain or a custom `composeCommandExecutors`
   pipeline (fail-closed if command routes lack an executor).
@@ -58,6 +61,31 @@ const app = createApplication({
 export default app;
 ```
 
+For deterministic local verification, use the in-memory sandbox. It supplies
+stable request identity, an isolated key-value database with optimistic
+transaction rollback, and an in-memory object store without requiring
+PostgreSQL, GoTrue, or S3:
+
+```ts
+import { createMemorySandbox } from "@supacloud/elysia";
+
+const sandbox = createMemorySandbox({
+  modules: [CaseModule],
+  identity: { authenticated: true, subject: "test-user" },
+  requestId: "test-request",
+});
+
+const response = await sandbox.request("/cases/42");
+sandbox.db.set("cases", "42", { state: "draft" });
+sandbox.storage.put("evidence", "42.txt", "fixture");
+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.
+
 Jobs are executed explicitly with `executeJob(compiledModule, services, job,
 input, requestContext)`. The asynchronous compiler-generated job scope is
 destroyed after execution, including when the job throws or scope construction
@@ -88,7 +116,37 @@ 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
 optional structured `details`.
+
+### `createMemorySandbox(options): MemorySandbox`
+
+Creates an in-process application harness with `request()`, `db`, `storage`,
+`identity`, `policy`, `audit`, and `reset()`. The memory database is a deterministic test adapter,
+not a PostgreSQL emulator; its transaction callback operates on an isolated
+snapshot and detects concurrent commits.
+
+The adapter boundary is intentional: production authorization, RLS, PostgreSQL,
+S3 visibility and failure semantics must be supplied by application governance
+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

@@ -9,6 +9,14 @@ export interface CompiledRoute {
     params?: unknown;
     query?: unknown;
     response?: unknown;
+    /** Compiler-emitted positional invoker; used when available. */
+    invoker?: (controller: unknown, request: {
+        params?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+        body?: unknown;
+        headers?: Record<string, unknown>;
+        context?: unknown;
+    }) => Promise<unknown> | unknown;
     /** Class name of the @Command explicitly bound to this route. */
     command?: string;
     /** Statically generated route aspects. */
@@ -73,7 +81,7 @@ export interface CommandInvocation {
     command: CompiledCommand;
     input: {
         body: unknown;
-        params: Record<string, string>;
+        params: Record<string, unknown>;
         query: Record<string, unknown>;
     };
     request: Request;
@@ -82,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;
@@ -205,3 +215,7 @@ export declare function defaultErrorResponse(error: unknown, frameworkCode?: str
 export declare function createApplication(options: ApplicationOptions): Elysia;
 /** Semantic alias of createApplication for readable tests. */
 export declare function createTestApp(options: ApplicationOptions): Elysia;
+export { createMemorySandbox, } from "./memory";
+export type { HandleLike as MemoryHandleLike, MemoryDatabase, MemorySandbox, MemorySandboxOptions, MemoryStorage, MemoryStorageObject, } from "./memory";
+export { createMemoryPolicy } from "./memory_policy";
+export type { MemoryPolicy } from "./memory_policy";

package/dist/index.js

@@ -1,5 +1,354 @@
 // 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";
+
+// src/memory_policy.ts
+function createMemoryPolicy() {
+  const permissions = new Map;
+  const receipts = new Map;
+  return {
+    grant(subject, permission) {
+      const values = permissions.get(subject) ?? new Set;
+      values.add(permission);
+      permissions.set(subject, values);
+    },
+    revoke(subject, permission) {
+      permissions.get(subject)?.delete(permission);
+    },
+    can(subject, permission) {
+      return permissions.get(subject)?.has(permission) ?? false;
+    },
+    claimIdempotency(subject, key) {
+      const id = JSON.stringify([subject, key]);
+      if (receipts.has(id))
+        return false;
+      receipts.set(id, { input: "", result: Promise.resolve(undefined) });
+      return true;
+    },
+    subject(context) {
+      if (typeof context === "object" && context !== null && "identity" in context) {
+        const identity = context.identity;
+        if (typeof identity === "object" && identity !== null && "authenticated" in identity && identity.authenticated === true && "subject" in identity && typeof identity.subject === "string" && identity.subject.length > 0)
+          return identity.subject;
+      }
+      throw new ApplicationError("Memory authenticated identity required", { status: 401, code: "MEMORY_IDENTITY_REQUIRED" });
+    },
+    async runOnce(subject, command, key, input, work) {
+      if (!subject || !command || !key)
+        throw new Error("Memory receipt requires subject, command and key");
+      const id = JSON.stringify([subject, command, key]);
+      const fingerprint = stableStringify(input);
+      const existing = receipts.get(id);
+      if (existing) {
+        if (existing.input !== fingerprint) {
+          throw new ApplicationError("Idempotency input conflict", { status: 409, code: "MEMORY_IDEMPOTENCY_CONFLICT" });
+        }
+        return structuredClone(await existing.result);
+      }
+      const result = Promise.resolve().then(work).then((value) => structuredClone(value));
+      const entry = { input: fingerprint, result };
+      receipts.set(id, entry);
+      try {
+        return structuredClone(await result);
+      } catch (error) {
+        if (receipts.get(id) === entry)
+          receipts.delete(id);
+        throw error;
+      }
+    },
+    clear() {
+      permissions.clear();
+      receipts.clear();
+    }
+  };
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(stableStringify).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
+
+// src/memory.ts
+class DefaultMemoryDatabase {
+  tables = new Map;
+  version = 0;
+  current = new AsyncLocalStorage;
+  get(table, key) {
+    if (this.current.getStore())
+      return this.current.getStore()?.get(table, key);
+    const value = this.tables.get(table)?.get(key);
+    return value === undefined ? undefined : cloneValue(value);
+  }
+  set(table, key, value) {
+    const current = this.current.getStore();
+    if (current)
+      return current.set(table, key, value);
+    const rows = this.tables.get(table) ?? new Map;
+    rows.set(key, cloneValue(value));
+    this.tables.set(table, rows);
+    this.version += 1;
+  }
+  delete(table, key) {
+    const current = this.current.getStore();
+    if (current)
+      return current.delete(table, key);
+    const deleted = this.tables.get(table)?.delete(key) ?? false;
+    if (deleted)
+      this.version += 1;
+    return deleted;
+  }
+  list(table) {
+    const current = this.current.getStore();
+    if (current)
+      return current.list(table);
+    return [...this.tables.get(table)?.entries() ?? []].map(([key, value]) => ({ key, value: cloneValue(value) })).sort((left, right) => left.key.localeCompare(right.key));
+  }
+  clear() {
+    const current = this.current.getStore();
+    if (current)
+      return current.clear();
+    this.tables.clear();
+    this.version += 1;
+  }
+  async transaction(work) {
+    if (this.current.getStore())
+      throw new Error("Nested memory transactions are not supported");
+    const baseVersion = this.version;
+    const snapshot = cloneTables(this.tables);
+    const transaction = new SnapshotMemoryDatabase(snapshot);
+    try {
+      const result = await this.current.run(transaction, () => work(transaction));
+      if (this.version !== baseVersion) {
+        throw new Error("Memory transaction conflict: state changed during transaction");
+      }
+      const committed = cloneTables(transaction.tables);
+      this.tables.clear();
+      for (const [table, rows] of committed)
+        this.tables.set(table, rows);
+      this.version += 1;
+      return result;
+    } finally {
+      transaction.close();
+    }
+  }
+}
+
+class SnapshotMemoryDatabase {
+  tables;
+  closed = false;
+  constructor(tables) {
+    this.tables = tables;
+  }
+  close() {
+    this.closed = true;
+  }
+  assertOpen() {
+    if (this.closed)
+      throw new Error("Memory transaction is closed");
+  }
+  get(table, key) {
+    this.assertOpen();
+    const value = this.tables.get(table)?.get(key);
+    return value === undefined ? undefined : cloneValue(value);
+  }
+  set(table, key, value) {
+    this.assertOpen();
+    const rows = this.tables.get(table) ?? new Map;
+    rows.set(key, cloneValue(value));
+    this.tables.set(table, rows);
+  }
+  delete(table, key) {
+    this.assertOpen();
+    return this.tables.get(table)?.delete(key) ?? false;
+  }
+  list(table) {
+    this.assertOpen();
+    return [...this.tables.get(table)?.entries() ?? []].map(([key, value]) => ({ key, value: cloneValue(value) })).sort((left, right) => left.key.localeCompare(right.key));
+  }
+  clear() {
+    this.assertOpen();
+    this.tables.clear();
+  }
+  transaction() {
+    return Promise.reject(new Error("Nested memory transactions are not supported"));
+  }
+}
+
+class DefaultMemoryStorage {
+  objects = new Map;
+  pendingFailure;
+  policy;
+  put(bucket, key, body, options = {}) {
+    this.check("put", bucket, key);
+    this.objects.set(storageKey(bucket, key), {
+      bucket,
+      key,
+      body: typeof body === "string" ? new TextEncoder().encode(body) : new Uint8Array(body),
+      contentType: options.contentType,
+      metadata: { ...options.metadata ?? {} }
+    });
+  }
+  get(bucket, key) {
+    this.check("get", bucket, key);
+    const object = this.objects.get(storageKey(bucket, key));
+    return object ? cloneObject(object) : undefined;
+  }
+  delete(bucket, key) {
+    this.check("delete", bucket, key);
+    return this.objects.delete(storageKey(bucket, key));
+  }
+  list(bucket, prefix = "") {
+    this.check("list", bucket, prefix);
+    return [...this.objects.values()].filter((object) => object.bucket === bucket && object.key.startsWith(prefix)).filter((object) => !this.policy || this.policy("get", object.bucket, object.key)).sort((left, right) => left.key.localeCompare(right.key)).map(cloneObject);
+  }
+  clear() {
+    this.objects.clear();
+    this.pendingFailure = undefined;
+  }
+  failNext(error = new Error("Memory storage failure")) {
+    this.pendingFailure = error;
+  }
+  setPolicy(policy) {
+    this.policy = policy;
+  }
+  check(operation, bucket, key) {
+    if (this.pendingFailure) {
+      const error = this.pendingFailure;
+      this.pendingFailure = undefined;
+      throw error;
+    }
+    if (this.policy && !this.policy(operation, bucket, key)) {
+      throw new ApplicationError("Memory storage access denied", { status: 403, code: "MEMORY_STORAGE_DENIED" });
+    }
+  }
+}
+function createMemorySandbox(options = {}) {
+  const db = new DefaultMemoryDatabase;
+  const storage = new DefaultMemoryStorage;
+  const policy = createMemoryPolicy();
+  const audit = [];
+  const governance = {
+    authorize(invocation) {
+      const subject = policy.subject(invocation.requestContext);
+      if (!invocation.command.permission || !policy.can(subject, invocation.command.permission)) {
+        throw new ApplicationError("Memory permission denied", { status: 403, code: "MEMORY_PERMISSION_DENIED" });
+      }
+    },
+    idempotency(invocation, next) {
+      return policy.runOnce(policy.subject(invocation.requestContext), invocation.command.name, requireIdempotencyKey(invocation), memoryCommandInput(invocation), next);
+    },
+    transaction(_invocation, next) {
+      const count = audit.length;
+      return db.transaction(() => next()).catch((error) => {
+        audit.splice(count);
+        throw error;
+      });
+    },
+    audit: {
+      succeeded(invocation) {
+        audit.push({ command: invocation.command.name, outcome: "succeeded" });
+      },
+      failed(invocation) {
+        audit.push({ command: invocation.command.name, outcome: "failed" });
+      }
+    }
+  };
+  const identity = options.identity ?? { authenticated: false };
+  const requestId = options.requestId ?? "memory-request";
+  const configuredContext = options.requestContext;
+  const app = createApplication({
+    ...options,
+    commandGovernance: options.commandGovernance ?? (options.memoryGovernance ? governance : undefined),
+    deps: {
+      ...options.deps ?? {},
+      dbClient: db,
+      memoryDb: db,
+      storage,
+      memoryStorage: storage,
+      memoryPolicy: policy
+    },
+    requestContext: configuredContext ?? ((request) => ({
+      requestId: request.headers.get("x-request-id") ?? requestId,
+      request,
+      identity
+    }))
+  });
+  return {
+    app,
+    db,
+    storage,
+    policy,
+    audit,
+    identity,
+    request(path, init = {}) {
+      const url = path.startsWith("http://") || path.startsWith("https://") ? path : `http://memory.local${path.startsWith("/") ? path : `/${path}`}`;
+      return app.handle(new Request(url, init));
+    },
+    reset() {
+      db.clear();
+      storage.clear();
+      policy.clear();
+      audit.length = 0;
+    }
+  };
+}
+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]);
+}
+function cloneObject(object) {
+  return {
+    ...object,
+    body: new Uint8Array(object.body),
+    metadata: { ...object.metadata }
+  };
+}
+function cloneTables(tables) {
+  return new Map([...tables.entries()].map(([table, rows]) => [
+    table,
+    new Map([...rows.entries()].map(([key, value]) => [key, cloneValue(value)]))
+  ]));
+}
+function cloneValue(value) {
+  return structuredClone(value);
+}
+
+// src/index.ts
 var VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
 var EXECUTION_ID_HEADER = "x-sb-execution-id";
 var IDEMPOTENCY_KEY_HEADER = "idempotency-key";
@@ -250,11 +599,13 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
           body: ctx.body,
           params: ctx.params,
           query: ctx.query,
+          headers: Object.fromEntries(ctx.request.headers.entries()),
+          context: requestContext,
           request: ctx.request,
           scope: requestScope,
           requestContext
         };
-        const invoke = () => Reflect.apply(method, instance, [input]);
+        const invoke = () => route.invoker ? route.invoker(instance, input) : Reflect.apply(method, instance, [input]);
         const routeContext = {
           kind: "route",
           name: `${route.method} ${path}`,
@@ -436,10 +787,13 @@ export {
   EXECUTION_ID_HEADER,
   IDEMPOTENCY_KEY_HEADER,
   VERIFIED_JWT_SUBJECT_HEADER,
+  assertFeatureTransition,
   composeAspects,
   composeCommandExecutors,
   createApplication,
   createCommandExecutor,
+  createMemoryPolicy,
+  createMemorySandbox,
   createModulePlugin,
   createSupaCloudRequestContext,
   createTestApp,

package/dist/memory.d.ts

@@ -0,0 +1,68 @@
+import { type ApplicationOptions, type TrustedRequestIdentity } from "./index";
+import { type MemoryPolicy } from "./memory_policy";
+export interface HandleLike {
+    handle(request: Request): Promise<Response> | Response;
+}
+export interface MemoryDatabase {
+    get(table: string, key: string): unknown;
+    set(table: string, key: string, value: unknown): void;
+    delete(table: string, key: string): boolean;
+    list(table: string): Array<{
+        key: string;
+        value: unknown;
+    }>;
+    clear(): void;
+    transaction<T>(work: (tx: MemoryDatabase) => T | Promise<T>): Promise<T>;
+}
+export interface MemoryStorageObject {
+    bucket: string;
+    key: string;
+    body: Uint8Array;
+    contentType?: string;
+    metadata: Record<string, string>;
+}
+export interface MemoryStorage {
+    put(bucket: string, key: string, body: Uint8Array | string, options?: {
+        contentType?: string;
+        metadata?: Record<string, string>;
+    }): void;
+    get(bucket: string, key: string): MemoryStorageObject | undefined;
+    delete(bucket: string, key: string): boolean;
+    list(bucket: string, prefix?: string): MemoryStorageObject[];
+    clear(): void;
+    failNext(error?: Error): void;
+    setPolicy(policy?: (operation: "put" | "get" | "delete" | "list", bucket: string, key: string) => boolean): void;
+}
+export interface MemorySandboxOptions extends Omit<ApplicationOptions, "deps" | "requestContext"> {
+    /** Stable identity used by every request unless overridden by requestContext. */
+    identity?: TrustedRequestIdentity;
+    /** Stable request id used when the request does not provide x-request-id. */
+    requestId?: string;
+    /** Extend the platform dependency bag without replacing memory dependencies. */
+    deps?: Record<string, unknown>;
+    /** Replace the default deterministic request context factory. */
+    requestContext?: ApplicationOptions["requestContext"];
+    /** Enable the test-only permission, receipt, transaction and audit adapters. */
+    memoryGovernance?: boolean;
+}
+export interface MemorySandbox {
+    app: HandleLike;
+    db: MemoryDatabase;
+    storage: MemoryStorage;
+    policy: MemoryPolicy;
+    audit: Array<{
+        command: string;
+        outcome: "succeeded" | "failed";
+    }>;
+    identity: TrustedRequestIdentity;
+    request(path: string, init?: RequestInit): Promise<Response>;
+    reset(): void;
+}
+/**
+ * Creates a deterministic in-process application harness.
+ *
+ * The database and storage are intentionally small adapter contracts, not
+ * PostgreSQL or S3 emulators. They are sufficient for fast command and HTTP
+ * behavior tests while keeping production adapters replaceable.
+ */
+export declare function createMemorySandbox(options?: MemorySandboxOptions): MemorySandbox;

package/dist/memory_policy.d.ts

@@ -0,0 +1,11 @@
+export interface MemoryPolicy {
+    grant(subject: string, permission: string): void;
+    revoke(subject: string, permission: string): void;
+    can(subject: string, permission: string): boolean;
+    claimIdempotency(subject: string, key: string): boolean;
+    subject(context: unknown): string;
+    runOnce<T>(subject: string, command: string, key: string, input: unknown, work: () => T | Promise<T>): Promise<T>;
+    clear(): void;
+}
+/** Test-only grants and successful-result receipts, scoped by subject and command. */
+export declare function createMemoryPolicy(): MemoryPolicy;

package/package.json

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