@aklinker1/zeta 2.0.0 → 2.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aklinker1/zeta",
   "description": "Composable, testable, OpenAPI-first backend framework with validation built-in",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "license": "MIT",
   "packageManager": "bun@1.3.5",
@@ -53,9 +53,16 @@
   },
   "devDependencies": {
     "@aklinker1/check": "^2.2.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.5.0",
+    "@opentelemetry/sdk-node": "^0.211.0",
+    "@opentelemetry/sdk-trace-node": "^2.5.0",
+    "@opentelemetry/semantic-conventions": "^1.39.0",
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20251114.1",
     "changelogen": "^0.6.2",
+    "cookie": "^1.1.1",
+    "dedent": "^1.7.1",
     "elysia": "^1.4.19",
     "expect-type": "^1.2.1",
     "hono": "^4.11.2",

package/src/app.ts

@@ -1,23 +1,23 @@
+import type { OpenAPI, OpenAPIV3_1 } from "openapi-types";
+import { addRoute, createRouter } from "rou3";
+import { compileRouter } from "rou3/compiler";
+import { compileFetchFunction } from "./internal/compile-fetch-function";
+import { compileRouteHandler } from "./internal/compile-route-handler";
+import { detectTransport } from "./internal/utils";
+import { buildOpenApiDocs, buildScalarHtml } from "./open-api";
 import type {
   App,
-  RouterData,
-  RouteDef,
   BasePath,
-  ServerSideFetch,
-  LifeCycleHook,
-  DefaultAppData,
   BasePrefix,
+  DefaultAppData,
+  LifeCycleHook,
+  LifeCycleHookName,
+  RouteDef,
+  RouterData,
   SchemaAdapter,
+  ServerSideFetch,
   Transport,
-  LifeCycleHookName,
 } from "./types";
-import { addRoute, createRouter } from "rou3";
-import { compileRouter } from "rou3/compiler";
-import { detectTransport } from "./internal/utils";
-import type { OpenAPIV3_1 } from "openapi-types";
-import { buildOpenApiDocs, buildScalarHtml } from "./open-api";
-import { compileRouteHandler } from "./internal/compile-route-handler";
-import { compileFetchFunction } from "./internal/compile-fetch-function";
 
 let appIdInc = 0;
 const nextAppId = () => `app-${appIdInc++}`;
@@ -243,10 +243,15 @@ export function createApp<TPrefix extends BasePrefix = "">(
       app.method.apply(app, [Method.Any, ...args] as any) as any,
 
     method(method: string, path: BasePath, ...args: any[]) {
-      const def: RouteDef = args.length === 2 ? args[0] : undefined;
+      const routeDef: RouteDef | undefined =
+        args.length === 2 ? args[0] : undefined;
       const handler = args[1] ?? args[0];
       const route = `${prefix}${path}`;
       const hooks = cloneHooks();
+
+      // Merge app-level tags and security into route definition
+      const def: RouteDef | undefined = mergeAppDefaults(routeDef, options);
+
       const compiledHandler = compileRouteHandler({
         schemaAdapter: options?.schemaAdapter,
         def,
@@ -267,7 +272,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
 
     mount(...args: any[]) {
       let path = "";
-      let def = {};
+      let routeDef: RouteDef = {};
       let fetch: ServerSideFetch;
 
       if (args.length === 1) {
@@ -277,12 +282,16 @@ export function createApp<TPrefix extends BasePrefix = "">(
         fetch = args[1];
       } else {
         path = args[0];
-        def = args[1];
+        routeDef = args[1];
         fetch = args[2];
       }
 
       const route = `${prefix}${path}/**`;
       const hooks = cloneHooks();
+
+      // Merge app-level tags and security into route definition
+      const def = mergeAppDefaults(routeDef, options);
+
       const compiledHandler = compileRouteHandler({
         schemaAdapter: options?.schemaAdapter,
         hooks,
@@ -403,6 +412,38 @@ export type CreateAppOptions<TPrefix extends BasePrefix = ""> = {
 
   /** Configure how your application's OpenAPI docs are generated. */
   openApi?: Partial<OpenAPIV3_1.Document> & {};
+
+  /**
+   * OpenAPI tags to apply to all routes in this app. Route-level tags will
+   * override these app-level tags.
+   *
+   * @example
+   * ```ts
+   * const usersApp = createApp({
+   *   prefix: "/users",
+   *   tags: ["Users"],
+   * })
+   *   .get("/", {}, () => [...])  // Will have ["Users"] tag
+   *   .get("/:id", { tags: ["Admin"] }, () => {...})  // Will have ["Admin"] tag (overrides app-level)
+   * ```
+   */
+  tags?: string[];
+
+  /**
+   * OpenAPI security requirements to apply to all routes in this app.
+   * Route-level security will override these app-level security requirements.
+   *
+   * @example
+   * ```ts
+   * const authApp = createApp({
+   *   prefix: "/auth",
+   *   security: [{ bearerAuth: [] }],
+   * })
+   *   .get("/profile", {}, () => {...})  // Will require bearerAuth
+   *   .get("/admin", { security: [{ adminKey: [] }] }, () => {...})  // Will require adminKey (overrides app-level)
+   * ```
+   */
+  security?: OpenAPI.Document["security"];
   /**
    * Configure [Scalar](https://scalar.com/) UI docs.
    * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md#list-of-all-attributes
@@ -410,6 +451,25 @@ export type CreateAppOptions<TPrefix extends BasePrefix = ""> = {
   scalar?: any;
 };
 
+/**
+ * Apply app-level defaults (tags, security) to a route definition.
+ * Route-level values override app-level defaults.
+ */
+function mergeAppDefaults(
+  routeDef: RouteDef | undefined,
+  options: CreateAppOptions<any> | undefined,
+): RouteDef | undefined {
+  if (!options?.tags?.length && !options?.security?.length) {
+    return routeDef;
+  }
+
+  return {
+    tags: options.tags,
+    security: options.security,
+    ...routeDef,
+  };
+}
+
 enum Method {
   Get = "GET",
   Post = "POST",

package/src/errors.ts

@@ -411,7 +411,7 @@ export class NotImplementedHttpError extends HttpError {
     options?: ErrorOptions,
   ) {
     super(HttpStatus.NotImplemented, message, additionalInfo, options);
-    this.name = "NotImplementedError";
+    this.name = "NotImplementedHttpError";
   }
 }
 

package/src/internal/compile-fetch-function.ts

@@ -1,13 +1,13 @@
 import type { MatchedRoute } from "rou3";
+import { HttpError, NotFoundHttpError } from "../errors";
+import { HttpStatus } from "../status";
 import type { LifeCycleHooks, RouterData, ServerSideFetch } from "../types";
+import { Context } from "./context";
 import {
   cleanupCompiledWhitespace,
   getRawPathname,
   serializeErrorResponse,
 } from "./utils";
-import { Context } from "./context";
-import { HttpError, NotFoundHttpError } from "../errors";
-import { HttpStatus } from "../status";
 
 export function compileFetchFunction(options: CompileOptions): ServerSideFetch {
   const onGlobalRequestCount = options.hooks.onGlobalRequest?.length;
@@ -19,6 +19,7 @@ export function compileFetchFunction(options: CompileOptions): ServerSideFetch {
 return (request) => {
   const path = utils.getRawPathname(request);
   const ctx = new utils.Context(request, path, utils.origin);
+  ${onGlobalAfterResponseCount ? "let handlerReturnedPromise = false;" : ""}
 
   try {
 ${onGlobalRequestCount ? compileOnGlobalRequestHook(onGlobalRequestCount) : ""}
@@ -36,6 +37,7 @@ ${onGlobalRequestCount ? compileOnGlobalRequestHook(onGlobalRequestCount) : ""}
     ctx.response = matchedRoute.data.compiledHandler(request, ctx);
     if (typeof ctx.response.then !== utils.FUNCTION) return ctx.response;
 
+    ${onGlobalAfterResponseCount ? "handlerReturnedPromise = true;" : ""}
     return ctx.response.catch(error => {
 ${onGlobalErrorCount ? compileOnGlobalErrorHook(onGlobalErrorCount, 3) : ""}
 
@@ -105,7 +107,9 @@ function compileOnGlobalAfterResponseFinally(
 ): string {
   const indent = "  ".repeat(tabs);
   return `finally {
-${compileOnGlobalAfterResponseHook(hookCount, tabs + 1)}
+${indent}  if (!handlerReturnedPromise) {
+${compileOnGlobalAfterResponseHook(hookCount, tabs + 2)}
+${indent}  }
 ${indent}}
 `;
 }
@@ -144,7 +148,12 @@ function compileErrorResponse(tabs: number): string {
 ${indent}  error instanceof utils.HttpError
 ${indent}    ? error.status
 ${indent}    : utils.HttpStatus.InternalServerError;
-${indent}return (ctx.response = Response.json(utils.serializeErrorResponse(error), { status }));`;
+${indent}return (
+${indent}  ctx.response = Response.json(
+${indent}    utils.serializeErrorResponse(error),
+${indent}    { status, headers: ctx.set.headers },
+${indent}  )
+${indent});`;
 }
 
 type CompileOptions = {

package/src/internal/compile-route-handler.ts

@@ -1,8 +1,9 @@
-import type { MaybePromise } from "elysia";
+import { getMeta } from "../meta";
 import type {
   CompiledRouteHandler,
   LifeCycleHookName,
   LifeCycleHooks,
+  MaybePromise,
   OnBeforeHandleContext,
   RouteDef,
   SchemaAdapter,
@@ -15,7 +16,6 @@ import {
   validateInputSchema,
   validateOutputSchema,
 } from "./utils";
-import { getMeta } from "../meta";
 
 export function compileRouteHandler(
   options: CompileOptions,
@@ -57,18 +57,22 @@ ${options.hooks.onAfterHandle?.length ? compileResponseModifierHookCall("onAfter
 ${options.hooks.onMapResponse?.length ? compileResponseModifierHookCall("onMapResponse", options.hooks.onMapResponse.length) : ""}
 
   if (ctx.response == null) {
-    return new Response(undefined, {
-      status: ctx.set.status,
-      headers: ctx.set.headers,
-    })
+    return (
+      ctx.response = new Response(undefined, {
+        status: ctx.set.status,
+        headers: ctx.set.headers,
+      })
+    )
   }
 
   const serialized = utils.smartSerialize(ctx.response);
   if (!ctx.set.headers["Content-Type"]) ctx.set.headers["Content-Type"] = ${responseContentTypeMap ? "responseContentTypeMap[ctx.set.status] ??" : ""} serialized.contentType
-  return new Response(serialized.value, {
-    status: ctx.set.status,
-    headers: ctx.set.headers,
-  })
+  return (
+    ctx.response = new Response(serialized.value, {
+      status: ctx.set.status,
+      headers: ctx.set.headers,
+    })
+  )
 }
 //#sourceURL=${getSourceUrl(options)}
   `;

package/src/internal/context.ts

@@ -11,6 +11,10 @@ export class Context {
 
   matchedRoute: MatchedRoute<RouterData> | undefined;
 
+  // Private storage for overwritten values
+  #params: Record<string, any> | undefined;
+  #query: Record<string, any> | undefined;
+
   constructor(
     public request: Request,
     public path: string,
@@ -21,14 +25,28 @@ export class Context {
     return new URL(this.request.url, this.origin);
   }
 
-  get params(): Record<string, string> {
+  get params(): Record<string, any> {
+    if (this.#params !== undefined) {
+      return this.#params;
+    }
     return this.matchedRoute?.params ? getRawParams(this.matchedRoute) : {};
   }
 
-  get query(): Record<string, string> {
+  set params(value: Record<string, any>) {
+    this.#params = value;
+  }
+
+  get query(): Record<string, any> {
+    if (this.#query !== undefined) {
+      return this.#query;
+    }
     return this.request.url.includes("?") ? getRawQuery(this.request) : {};
   }
 
+  set query(value: Record<string, any>) {
+    this.#query = value;
+  }
+
   get route(): string | undefined {
     return this.matchedRoute?.data.route;
   }

package/src/types.ts

@@ -130,12 +130,7 @@ export interface App<TAppData extends AppData = AppData> {
   onGlobalRequest(
     callback: (
       ctx: OnGlobalRequestContext<GetAppDataCtx<TAppData>>,
-    ) => MaybePromise<void>,
-  ): this;
-  onGlobalRequest(
-    callback: (
-      ctx: OnGlobalRequestContext<GetAppDataCtx<TAppData>>,
-    ) => MaybePromise<Response>,
+    ) => MaybePromise<Response | void>,
   ): this;
   onGlobalRequest<TNewCtx extends Record<string, any>>(
     callback: (
@@ -154,12 +149,7 @@ export interface App<TAppData extends AppData = AppData> {
   onTransform(
     callback: (
       ctx: OnTransformContext<GetAppDataCtx<TAppData>>,
-    ) => MaybePromise<void>,
-  ): this;
-  onTransform(
-    callback: (
-      ctx: OnTransformContext<GetAppDataCtx<TAppData>>,
-    ) => MaybePromise<Response>,
+    ) => MaybePromise<Response | void>,
   ): this;
   onTransform<TNewCtx extends Record<string, any>>(
     callback: (
@@ -178,12 +168,7 @@ export interface App<TAppData extends AppData = AppData> {
   onBeforeHandle(
     callback: (
       ctx: OnBeforeHandleContext<GetAppDataCtx<TAppData>>,
-    ) => MaybePromise<void>,
-  ): this;
-  onBeforeHandle(
-    callback: (
-      ctx: OnBeforeHandleContext<GetAppDataCtx<TAppData>>,
-    ) => MaybePromise<Response>,
+    ) => MaybePromise<Response | void>,
   ): this;
   onBeforeHandle<TNewCtx extends Record<string, any>>(
     callback: (