@supacloud/elysia 0.24.1 → 0.26.0

package/README.md

@@ -630,6 +630,16 @@ transaction and persist with a row lock or expected-version check.
 Lightweight error class carrying HTTP `status`, machine-readable `code`, and
 optional structured `details`.
 
+The adapter registers `ApplicationError` and `SchemaContractError` in Elysia
+2.0's native error dictionary (`app.error(ErrorClass, handler)`). Typed entries
+keep these classes out of the generic catch-all, so route response inference
+stays precise while Elysia (and Eden Treaty) knows the errors are handled. The
+dictionary is exported as `applicationErrorDictionary`, and
+`frameworkErrorCode(error)` exposes the same code normalization (`ParseError` →
+`PARSE`, `ValidationError` → `VALIDATION`, otherwise the error's own `code`)
+used by the generic lane. A configured `errorMapper` remains authoritative for
+every lane and still receives the request context.
+
 ### `createMemorySandbox(options): MemorySandbox`
 
 Creates an in-process application harness with `request()`, `db`, `storage`,
@@ -693,9 +703,18 @@ const app = registerElysiaRoute(new Elysia(), route);
 
 The callback is typed from the contract (including decoded transforms and
 declared response statuses). Cookie values retain Elysia's native shape, so a
-declared `session: t.String()` is read as `cookie.session.value`. This helper
-does not add Eden-style client inference to an existing Elysia instance; the
-compiler-generated client remains the source of transport types.
+declared `session: t.String()` is read as `cookie.session.value`.
+`registerElysiaRoute` returns the same instance and preserves its existing type.
+Chaining registers routes at runtime but does not add those routes to Eden's
+static route tree. Use the contract's typed client or the compiler-generated
+client for transport types.
+
+When no schema declares `query` or `headers`, the handler context falls back to
+Elysia's native `Record<string, string | undefined>` (not a narrower `string`),
+and `params` resolves from the path exactly as Elysia does. TypeBox transforms
+(`t.Numeric`, `t.Transform`, `Type.Codec`) are decoded before the handler runs,
+so `query.page` from `t.Object({ page: t.Numeric() })` is a `number`, not a
+string.
 
 Response maps may use concrete statuses, `1XX`-`5XX` families, and `default`.
 The adapter expands family/default entries to concrete validators before

package/dist/fixtures/webhook-generated/application.d.ts

@@ -92,6 +92,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>>): Promise<Record<string, unknown>>;
     destroyRequestScope?(scope: Record<string, unknown>): Promise<void>;
     createJobScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Promise<Record<string, unknown>>;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { HttpPolicyDatabase } from "./http-policy-postgres";
 export { createHttpTelemetry } from "./http-telemetry";
 export type { HttpTelemetryEvent, HttpTelemetryObserver } from "./http-telemetry";
 import { type ExecutionObserver } from "./execution";
+import { SchemaContractError } from "./schema_contract";
 import { type ApplicationDocumentationOptions } from "./documentation";
 export type { ExecutionEvent, ExecutionObserver } from "./execution";
 export { bindCompiledCommand } from "./command-binding";
@@ -242,6 +243,28 @@ export interface ErrorContext {
     requestContext: unknown;
     frameworkCode: string | number | undefined;
 }
+/**
+ * Elysia 2.0 native error dictionary registered by the adapter.
+ *
+ * Declaring the runtime classes here lets Elysia's type system (and therefore
+ * Eden Treaty / generated clients) know these errors are *handled*: the generic
+ * `.error(handler)` catch-all no longer widens every route's response schema
+ * with an untyped fallback. Each entry also documents the public `code` served
+ * by {@link defaultErrorResponse} when a caller does not install an
+ * `errorMapper`.
+ */
+export declare const applicationErrorDictionary: {
+    readonly ApplicationError: typeof ApplicationError;
+    readonly SchemaContractError: typeof SchemaContractError;
+};
+export type ApplicationErrorDictionary = typeof applicationErrorDictionary;
+export type ApplicationErrorClass = ApplicationErrorDictionary[keyof ApplicationErrorDictionary];
+/**
+ * Normalize the framework's runtime error code the same way the generic error
+ * hook always has: Elysia's built-in `ParseError`/`ValidationError` become
+ * `PARSE`/`VALIDATION`, while domain errors keep their own `code`.
+ */
+export declare function frameworkErrorCode(error: unknown): string;
 export type ErrorMapper = (error: unknown, context: ErrorContext) => Response | undefined | Promise<Response | undefined>;
 export type ApplicationHttpContext<Http extends AnyElysia = Elysia> = Omit<Context<{}, {
     decorator: Http["~Singleton"]["decorator"];

package/dist/index.js

@@ -1978,6 +1978,13 @@ function validatedJsonResponse(validate, value, init) {
     headers.set("content-type", "application/json");
   return new Response(body, { ...init, headers });
 }
+var applicationErrorDictionary = {
+  ApplicationError,
+  SchemaContractError
+};
+function frameworkErrorCode(error) {
+  return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code.toUpperCase().replaceAll("-", "_") : "UNKNOWN";
+}
 var httpPluginIds = new WeakMap;
 var nextHttpPluginId = 0;
 function contextPlugin(http) {
@@ -2409,16 +2416,18 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
       requestCompletions.delete(request);
     }
   });
-  plugin.error(async ({ error, request }) => {
-    const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code.toUpperCase().replaceAll("-", "_") : "UNKNOWN";
+  const mapError = async (error, frameworkCode, request) => {
     const context = {
       request,
       requestContext: requestContexts.get(request),
-      frameworkCode: code
+      frameworkCode
     };
     const mapped = await options.errorMapper?.(error, context);
-    return mapped ?? defaultErrorResponse(error, code);
-  });
+    return mapped ?? defaultErrorResponse(error, frameworkCode);
+  };
+  plugin.error(ApplicationError, ({ error, request }) => mapError(error, frameworkErrorCode(error), request));
+  plugin.error(SchemaContractError, ({ error, request }) => mapError(error, frameworkErrorCode(error), request));
+  plugin.error(({ error, request }) => mapError(error, frameworkErrorCode(error), request));
   const routeRegistrar = plugin;
   for (const controller of compiled.controllers) {
     for (const route of controller.routes) {
@@ -2828,6 +2837,7 @@ export {
   VERIFIED_JWT_SUBJECT_HEADER,
   WorkerReceiptUnconfirmedError,
   WorkerRegistrationError,
+  applicationErrorDictionary,
   assertFeatureTransition,
   assertResponseStatusDeclared,
   bindCompiledCommand,
@@ -2859,6 +2869,7 @@ export {
   defineRouteContract,
   executeCompiledCommand,
   executeJob,
+  frameworkErrorCode,
   previewCompiledCommand,
   registerElysiaRoute,
   requireIdempotencyKey,

package/dist/schema_contract.d.ts

@@ -70,9 +70,29 @@ type PathParameterNames<Path extends string> = Path extends `${string}:${infer N
 type PathParameters<Path extends string> = [PathParameterNames<Path>] extends [never] ? Record<string, string> : {
     [Name in PathParameterNames<Path>]: string;
 };
+/**
+ * Resolve one declared schema field to the value Elysia hands to the handler.
+ *
+ * Elysia registers the route with the same schema instance, so the handler sees
+ * the *decoded* output of TypeBox transforms (`t.Numeric`, `t.Transform`,
+ * `Type.Codec`). `StaticDecode` mirrors that pipeline exactly, which is why the
+ * decoded type is used here instead of the raw `Static` input type.
+ */
 type DecodedField<Schemas extends RouteContractSchemas, Key extends keyof RouteContractSchemas> = [
     Extract<Schemas[Key], TSchema>
 ] extends [never] ? unknown : UnwrapSchema<Extract<Schemas[Key], TSchema>>;
+/** True when the contract declared a schema for `Key`. */
+type HasField<Schemas extends RouteContractSchemas, Key extends keyof RouteContractSchemas> = [
+    Extract<Schemas[Key], TSchema>
+] extends [never] ? false : true;
+/**
+ * Elysia's native fallback for an undeclared route field.
+ *
+ * The values are copied from Elysia's own `Context` so a contract without a
+ * schema behaves exactly like a hand-written Elysia route (query and headers
+ * stay `string | undefined`, params resolve from the path).
+ */
+type FieldFallback<Schemas extends RouteContractSchemas, Key extends keyof RouteContractSchemas, Path extends string> = HasField<Schemas, Key> extends true ? DecodedField<Schemas, Key> : Key extends "params" ? PathParameters<Path> : Key extends "query" | "headers" ? Record<string, string | undefined> : Record<string, unknown>;
 type DecodedCookie<Schemas extends RouteContractSchemas> = DecodedField<Schemas, "cookie"> extends infer Value ? Value extends Record<string, unknown> ? Record<string, Cookie<unknown>> & {
     [Key in keyof Value]-?: Cookie<Value[Key]>;
 } : Record<string, Cookie<unknown>> : Record<string, Cookie<unknown>>;
@@ -84,9 +104,9 @@ type RouteStatus<Schemas extends RouteContractSchemas> = [StatusCode<Schemas>] e
 /** Elysia-compatible decoded context inferred from one route contract and path. */
 export type ElysiaRouteContext<Schemas extends RouteContractSchemas, Path extends string = ""> = {
     body: DecodedField<Schemas, "body">;
-    params: Schemas["params"] extends TSchema ? DecodedField<Schemas, "params"> : PathParameters<Path>;
-    query: Schemas["query"] extends TSchema ? DecodedField<Schemas, "query"> : Record<string, string>;
-    headers: Schemas["headers"] extends TSchema ? DecodedField<Schemas, "headers"> : Record<string, string | undefined>;
+    params: FieldFallback<Schemas, "params", Path>;
+    query: FieldFallback<Schemas, "query", Path>;
+    headers: FieldFallback<Schemas, "headers", Path>;
     cookie: DecodedCookie<Schemas>;
     request: Request;
     path: string;
@@ -94,7 +114,7 @@ export type ElysiaRouteContext<Schemas extends RouteContractSchemas, Path extend
     server: unknown;
     store: Record<string, unknown>;
     set: {
-        headers: Record<string, string>;
+        headers: Record<string, string | number>;
         status?: number | keyof StatusMap;
         redirect?: string;
         cookie?: Record<string, unknown>;
@@ -127,7 +147,12 @@ export declare function toElysiaRouteSchema<const Schemas extends RouteContractS
  * contextually typed from the same schemas that will be registered at runtime.
  */
 export declare function defineElysiaRoute<const Method extends HTTPMethod, const Path extends string, const Schemas extends RouteContractSchemas>(method: Method, path: Path, contract: Schemas, handler: ElysiaRouteHandler<NoInfer<Schemas>, Path>): ElysiaRouteDefinition<Method, Path, Schemas>;
-/** Register a contract-bound route while preserving Elysia's fluent app API. */
+/**
+ * Register a contract-bound route while preserving Elysia's fluent app API.
+ *
+ * Runtime registration preserves the caller's existing instance type. It does
+ * not add the contract to Eden's static route tree.
+ */
 export declare function registerElysiaRoute<const App extends AnyElysia, const Method extends HTTPMethod, const Path extends string, const Schemas extends RouteContractSchemas>(app: App, route: ElysiaRouteDefinition<Method, Path, Schemas>): App;
 export declare class SchemaContractError extends Error {
     readonly code = "SCHEMA_CONTRACT_INVALID";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",
@@ -65,7 +65,7 @@
     "elysia": "2.0.0-beta.21"
   },
   "devDependencies": {
-    "@supacloud/compiler": "0.38.1",
+    "@supacloud/compiler": "0.39.0",
     "@supacloud/delivery": "0.8.0",
     "@supacloud/commands": "0.9.1",
     "@supacloud/db": "0.13.1",