@aklinker1/zeta 1.3.3 → 2.1.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@aklinker1/zeta",
   "description": "Composable, testable, OpenAPI-first backend framework with validation built-in",
-  "version": "1.3.3",
+  "version": "2.1.0",
   "type": "module",
   "license": "MIT",
-  "packageManager": "bun@1.3.2",
+  "packageManager": "bun@1.3.5",
   "module": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
@@ -41,23 +41,31 @@
     "bench": "bun run src/__tests__/bench.ts",
     "example": "bun --watch run example.ts",
     "example:prod": "NODE_ENV=production bun run example",
-    "docs:dev": "vitepress dev docs",
+    "docs:dev": "zola -r docs serve",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "openapi-types": "^12.1.3",
-    "rou3": "^0.7.1"
+    "rou3": "^0.7.12",
+    "scule": "^1.3.0"
   },
   "devDependencies": {
     "@aklinker1/check": "^2.2.0",
-    "@typescript/native-preview": "^7.0.0-dev.20251114.1",
+    "@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",
-    "elysia": "^1.3.5",
+    "cookie": "^1.1.1",
+    "dedent": "^1.7.1",
+    "elysia": "^1.4.19",
     "expect-type": "^1.2.1",
-    "hono": "^4.8.3",
+    "hono": "^4.11.2",
     "jsr": "^0.13.5",
     "mermaid": "^11.12.0",
     "oxlint": "^1.2.0",

package/src/adapters/zod-schema-adapter.ts

@@ -2,11 +2,9 @@
  * Contains a schema adapter for app's using [`zod`](https://npmjs.com/package/zod).
  * @module
  */
+import { z } from "zod";
 import type { SchemaAdapter } from "../types";
 
-const zod = "zod";
-const { z } = await import(zod);
-
 /**
  * Usage:
  *
@@ -25,21 +23,6 @@ export const zodSchemaAdapter: SchemaAdapter = {
     delete res.$schema;
     return res;
   },
-  parseParamsRecord: (params: any) => {
-    if (params?._zod?.def?.type !== "object")
-      throw Error(
-        "Query, params, and header schemas must be simple Zode objects defined with z.object({ ... })",
-      );
-
-    return Object.entries(params._zod.def.shape).map(
-      ([key, schema]: [string, any]) => ({
-        name: key,
-        schema,
-        optional: schema.safeParse(undefined).success,
-        ...z.globalRegistry.get(schema),
-      }),
-    );
-  },
   getMeta: (schema: any) => {
     return z.globalRegistry.get(schema);
   },

package/src/app.ts

@@ -1,28 +1,23 @@
-import { callHandler } from "./internal/call-handler";
-import { HttpError } from "./errors";
-import { HttpStatus } from "./status";
+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,
-  OnGlobalRequestContext,
-  LifeCycleHooks,
-  LifeCycleHook,
-  DefaultAppData,
   BasePrefix,
+  DefaultAppData,
+  LifeCycleHook,
+  LifeCycleHookName,
+  RouteDef,
+  RouterData,
   SchemaAdapter,
+  ServerSideFetch,
   Transport,
 } from "./types";
-import { addRoute, createRouter, findRoute } from "rou3";
-import {
-  callCtxModifierHooks,
-  detectTransport,
-  serializeErrorResponse,
-} from "./internal/utils";
-import type { OpenAPIV3_1 } from "openapi-types";
-import { buildOpenApiDocs, buildScalarHtml } from "./open-api";
 
 let appIdInc = 0;
 const nextAppId = () => `app-${appIdInc++}`;
@@ -68,15 +63,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
   const appId = nextAppId();
 
   const { origin = "http://localhost", prefix = "" } = options ?? {};
-  const hooks: App["~zeta"]["hooks"] = {
-    onAfterHandle: [],
-    onGlobalAfterResponse: [],
-    onBeforeHandle: [],
-    onMapResponse: [],
-    onGlobalError: [],
-    onGlobalRequest: [],
-    onTransform: [],
-  };
+  const hooks: App["~zeta"]["hooks"] = {};
   const routes: App["~zeta"]["routes"] = {};
 
   const addRoutesEntry = (method: string, route: string, data: RouterData) => {
@@ -87,15 +74,13 @@ export function createApp<TPrefix extends BasePrefix = "">(
     routes[method][route] = data;
   };
 
-  const cloneHooks = () => ({
-    onAfterHandle: [...hooks.onAfterHandle],
-    onGlobalAfterResponse: [...hooks.onGlobalAfterResponse],
-    onBeforeHandle: [...hooks.onBeforeHandle],
-    onMapResponse: [...hooks.onMapResponse],
-    onGlobalError: [...hooks.onGlobalError],
-    onGlobalRequest: [...hooks.onGlobalRequest],
-    onTransform: [...hooks.onTransform],
-  });
+  const cloneHooks = (): App["~zeta"]["hooks"] => {
+    const cloned: App["~zeta"]["hooks"] = {};
+    for (const key of Object.keys(hooks) as LifeCycleHookName[]) {
+      if (hooks[key]) cloned[key] = [...hooks[key]] as any;
+    }
+    return cloned;
+  };
 
   const app: App<DefaultAppData> = {
     // @ts-expect-error
@@ -146,77 +131,8 @@ export function createApp<TPrefix extends BasePrefix = "">(
         }
       }
 
-      // const getRoute = compileRouter(router);
-      const getRoute = (method: string, path: string) =>
-        findRoute(router, method, path);
-
-      return async (request) => {
-        const url = new URL(request.url, origin);
-        const ctx: any = {
-          path: url.pathname,
-          url,
-          request,
-          method: request.method,
-          set: {
-            status: HttpStatus.Ok,
-            headers: {},
-          },
-        } satisfies OnGlobalRequestContext;
-
-        try {
-          const onGlobalRequestResponse = await callCtxModifierHooks(
-            ctx,
-            hooks.onGlobalRequest,
-          );
-          if (onGlobalRequestResponse) {
-            ctx.response = onGlobalRequestResponse;
-            return onGlobalRequestResponse;
-          }
-
-          const response = await callHandler(
-            ctx,
-            getRoute,
-            options?.schemaAdapter,
-          );
-          ctx.response = response;
-
-          return response;
-        } catch (err) {
-          ctx.error = err;
-
-          for (const hook of hooks.onGlobalError) {
-            const res = hook.callback(ctx);
-            res instanceof Promise ? await res : res;
-          }
-
-          const status =
-            err instanceof HttpError
-              ? err.status
-              : HttpStatus.InternalServerError;
-          const res = Response.json(serializeErrorResponse(err), { status });
-          ctx.response = res;
-          return res;
-        } finally {
-          // Defer calls to the `onGlobalAfterResponse` hooks until after the response is sent
-          if (hooks.onGlobalAfterResponse.length > 0) {
-            setTimeout(async () => {
-              try {
-                for (const hook of hooks.onGlobalAfterResponse) {
-                  let res = hook.callback(ctx);
-                  if (res instanceof Promise) await res;
-                }
-              } catch (err) {
-                ctx.error = err;
-
-                for (const hook of hooks.onGlobalError) {
-                  const res = hook.callback(ctx);
-                  res instanceof Promise ? await res : res;
-                }
-              }
-            }, 0);
-          }
-        }
-      };
+      const getRoute = compileRouter(router);
+      return compileFetchFunction({ getRoute, hooks, origin });
     },
 
     getOpenApiSpec: () => {
@@ -241,6 +157,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       const obj: Record<string, any> =
         args.length === 2 ? { [args[0]]: args[1] } : args[0];
 
+      hooks.onTransform ??= [];
       hooks.onTransform.push({
         id: nextHookId(appId),
         applyTo: "local",
@@ -251,6 +168,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
     },
 
     onGlobalRequest(callback: any) {
+      hooks.onGlobalRequest ??= [];
       hooks.onGlobalRequest.push({
         id: nextHookId(appId),
         applyTo: "global",
@@ -259,6 +177,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       return app;
     },
     onTransform(callback: any) {
+      hooks.onTransform ??= [];
       hooks.onTransform.push({
         id: nextHookId(appId),
         applyTo: "local",
@@ -267,6 +186,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       return app;
     },
     onBeforeHandle(callback: any) {
+      hooks.onBeforeHandle ??= [];
       hooks.onBeforeHandle.push({
         id: nextHookId(appId),
         applyTo: "local",
@@ -275,6 +195,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       return app;
     },
     onAfterHandle(callback: any) {
+      hooks.onAfterHandle ??= [];
       hooks.onAfterHandle.push({
         id: nextHookId(appId),
         applyTo: "local",
@@ -283,6 +204,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       return app;
     },
     onMapResponse(callback: any) {
+      hooks.onMapResponse ??= [];
       hooks.onMapResponse.push({
         id: nextHookId(appId),
         applyTo: "local",
@@ -291,6 +213,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       return app;
     },
     onGlobalError(callback: any) {
+      hooks.onGlobalError ??= [];
       hooks.onGlobalError.push({
         id: nextHookId(appId),
         applyTo: "global",
@@ -299,6 +222,7 @@ export function createApp<TPrefix extends BasePrefix = "">(
       return app;
     },
     onGlobalAfterResponse(callback: any) {
+      hooks.onGlobalAfterResponse ??= [];
       hooks.onGlobalAfterResponse.push({
         id: nextHookId(appId),
         applyTo: "global",
@@ -319,21 +243,36 @@ 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}`;
-      addRoutesEntry(method, route, {
+      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,
+        hooks,
+        method,
+        route,
         handler,
+      });
+      addRoutesEntry(method, route, {
+        def,
         route,
-        hooks: cloneHooks(),
+        hooks,
+        compiledHandler,
+        handler,
       });
       return app;
     },
 
     mount(...args: any[]) {
       let path = "";
-      let def = {};
+      let routeDef: RouteDef = {};
       let fetch: ServerSideFetch;
 
       if (args.length === 1) {
@@ -343,16 +282,31 @@ 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,
+        method: "ANY",
+        route,
+        fetch,
+        def,
+      });
+
       addRoutesEntry(Method.Any, route, {
         def,
         fetch,
         route,
-        hooks: cloneHooks(),
+        hooks,
+        compiledHandler,
       });
 
       return app as any;
@@ -369,20 +323,23 @@ export function createApp<TPrefix extends BasePrefix = "">(
         }
       }
 
-      // Add global hooks to parent app's hooks
-      for (const _name of Object.keys(hooks)) {
-        const name = _name as keyof LifeCycleHooks;
-        for (const hook of childApp["~zeta"].hooks[name]) {
-          if (hook.applyTo === "global" || childApp["~zeta"].exported) {
-            hooks[name].push(hook as LifeCycleHook<any>);
+      // Add the child's global hooks to parent
+      for (const hookName of Object.keys(
+        childApp["~zeta"].hooks,
+      ) as LifeCycleHookName[]) {
+        for (const hook of childApp["~zeta"].hooks[
+          hookName
+        ]! as LifeCycleHook<any>[]) {
+          if (hook.applyTo !== "global" && !childApp["~zeta"].exported)
+            continue;
+
+          if (hooks[hookName]) {
+            // Don't add a hook if it's already there
+            if (!hooks[hookName].includes(hook)) hooks[hookName].push(hook);
+          } else {
+            hooks[hookName] = [hook];
           }
         }
-        let seen = new Set<string>();
-        hooks[name] = hooks[name].filter((hook) => {
-          if (seen.has(hook.id)) return false;
-          seen.add(hook.id);
-          return true;
-        }) as LifeCycleHook<any>[];
       }
 
       return app as any;
@@ -455,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
@@ -462,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/client.ts

@@ -99,11 +99,12 @@ export function createAppClient<TApp extends App>(
         headers: { ...headers } as Record<string, string>,
       } satisfies RequestInit;
 
-      const body =
+      const serializedBody =
         inputs.body == null ? undefined : smartSerialize(inputs.body);
-      if (body) {
-        init.body = body.serialized;
-        if (body.contentType) init.headers["Content-Type"] = body.contentType;
+      if (serializedBody) {
+        init.body = serializedBody.value;
+        if (serializedBody.contentType)
+          init.headers["Content-Type"] = serializedBody.contentType;
       }
 
       try {

package/src/errors.ts

@@ -1,19 +1,5 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { HttpStatus } from "./status";
 
-/**
- * Thrown when validation fails. Refer to `.issues` for details on what went wrong.
- */
-export class ValidationGlobalError extends Error {
-  constructor(
-    readonly input: any,
-    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>,
-  ) {
-    super("Validation error");
-    this.name = "ValidationGlobalError";
-  }
-}
-
 /**
  * Base class of all HTTP errors. You can throw this error or throw any of the
  * subclasses. Zeta will automatically detect and handle these errors, setting
@@ -425,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

@@ -0,0 +1,166 @@
+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";
+
+export function compileFetchFunction(options: CompileOptions): ServerSideFetch {
+  const onGlobalRequestCount = options.hooks.onGlobalRequest?.length;
+  const onGlobalAfterResponseCount =
+    options.hooks.onGlobalAfterResponse?.length;
+  const onGlobalErrorCount = options.hooks.onGlobalError?.length;
+
+  const js = `
+return (request) => {
+  const path = utils.getRawPathname(request);
+  const ctx = new utils.Context(request, path, utils.origin);
+  ${onGlobalAfterResponseCount ? "let handlerReturnedPromise = false;" : ""}
+
+  try {
+${onGlobalRequestCount ? compileOnGlobalRequestHook(onGlobalRequestCount) : ""}
+
+    const matchedRoute = utils.getRoute(request.method, path);
+    if (matchedRoute == null) {
+      throw new utils.NotFoundHttpError(undefined, {
+        method: request.method,
+        path,
+      });
+    } else {
+      ctx.matchedRoute = matchedRoute;
+    }
+
+    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) : ""}
+
+${compileErrorResponse(3)}
+    })${onGlobalAfterResponseCount ? compileOnGlobalAfterResponsePromiseFinally(onGlobalAfterResponseCount, 2) : ""};
+  } catch (error) {
+${onGlobalErrorCount ? compileOnGlobalErrorHook(onGlobalErrorCount, 2) : ""}
+
+${compileErrorResponse(2)}
+  } ${onGlobalAfterResponseCount ? compileOnGlobalAfterResponseFinally(onGlobalAfterResponseCount, 1) : ""}
+}
+//#sourceURL=zeta-jit-generated://zeta-fetch-fn.js
+  `;
+  return new Function("utils", cleanupCompiledWhitespace(js))({
+    FUNCTION: "function",
+    getRawPathname,
+    hooks: options.hooks,
+    Context,
+    getRoute: options.getRoute,
+    NotFoundHttpError,
+    origin: options.origin,
+    HttpError,
+    HttpStatus,
+    serializeErrorResponse,
+  });
+}
+
+function compileOnGlobalRequestHook(hookCount: number): string {
+  const lines: string[] = [];
+
+  for (let i = 0; i < hookCount; i++) {
+    const resultVar = `onGlobalRequestRes${i}`;
+    lines.push(
+      `    const ${resultVar} = utils.hooks.onGlobalRequest[${i}].callback(ctx);`,
+      ...(process.env.NODE_ENV !== "production"
+        ? [
+            `    if (${resultVar} instanceof Promise)`,
+            `      console.warn("Warning: Promise returned from onGlobalRequest hook. Promises returned from onGlobalRequest are not awaited, ignoring the return value.");`,
+          ]
+        : []),
+      `    if (${resultVar})`,
+      `      if (typeof ${resultVar}.body?.bytes === utils.FUNCTION)`,
+      `        return ${resultVar};`,
+      `      else`,
+      `        for (const key of Object.keys(${resultVar}))`,
+      `          ctx[key] = ${resultVar}[key];`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function compileOnGlobalErrorHook(hookCount: number, tabs: number): string {
+  const indent = "  ".repeat(tabs);
+  const lines: string[] = [`${indent}ctx.error = error;`];
+
+  for (let i = 0; i < hookCount; i++) {
+    lines.push(`${indent}utils.hooks.onGlobalError[${i}].callback(ctx);`);
+  }
+
+  return lines.join("\n");
+}
+
+function compileOnGlobalAfterResponseFinally(
+  hookCount: number,
+  tabs: number,
+): string {
+  const indent = "  ".repeat(tabs);
+  return `finally {
+${indent}  if (!handlerReturnedPromise) {
+${compileOnGlobalAfterResponseHook(hookCount, tabs + 2)}
+${indent}  }
+${indent}}
+`;
+}
+
+function compileOnGlobalAfterResponsePromiseFinally(
+  hookCount: number,
+  tabs: number,
+): string {
+  const indent = "  ".repeat(tabs);
+  return `.finally(() => {
+${compileOnGlobalAfterResponseHook(hookCount, tabs + 1)}
+${indent}})`;
+}
+
+function compileOnGlobalAfterResponseHook(
+  hookCount: number,
+  tabs: number,
+): string {
+  const indent = "  ".repeat(tabs);
+  const lines: string[] = [`${indent}setTimeout(() => {`];
+
+  for (let i = 0; i < hookCount; i++) {
+    lines.push(
+      `${indent}  utils.hooks.onGlobalAfterResponse[${i}].callback(ctx);`,
+    );
+  }
+
+  lines.push(`${indent}})`);
+
+  return lines.join("\n");
+}
+
+function compileErrorResponse(tabs: number): string {
+  const indent = "  ".repeat(tabs);
+  return `${indent}const status =
+${indent}  error instanceof utils.HttpError
+${indent}    ? error.status
+${indent}    : utils.HttpStatus.InternalServerError;
+${indent}return (
+${indent}  ctx.response = Response.json(
+${indent}    utils.serializeErrorResponse(error),
+${indent}    { status, headers: ctx.set.headers },
+${indent}  )
+${indent});`;
+}
+
+type CompileOptions = {
+  hooks: LifeCycleHooks;
+  getRoute: (
+    method: string,
+    path: string,
+  ) => MatchedRoute<RouterData> | undefined;
+  origin: string;
+};