@aklinker1/zeta 1.0.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@aklinker1/zeta",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "MIT",
+  "packageManager": "bun@1.2.17",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./client": "./src/client.ts",
+    "./testing": "./src/testing.ts",
+    "./adapters/zod-schema-adapter": "./src/adapters/zod-schema-adapter.ts"
+  },
+  "files": [
+    "src/*.ts",
+    "src/adapters/*.ts",
+    "src/internal/*.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/aklinker1/zeta"
+  },
+  "scripts": {
+    "dev": "bun test --watch",
+    "bench": "bun run src/__tests__/bench.ts",
+    "example": "bun --watch run example.ts",
+    "example:prod": "NODE_ENV=production bun run example",
+    "publish": "bun run scripts/publish.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "rou3": "^0.7.1"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^2.1.0",
+    "@types/bun": "latest",
+    "changelogen": "^0.6.2",
+    "elysia": "^1.3.5",
+    "expect-type": "^1.2.1",
+    "hono": "^4.8.3",
+    "jsr": "^0.13.5",
+    "mermaid": "^11.12.0",
+    "openapi-types": "^12.1.3",
+    "oxlint": "^1.2.0",
+    "prettier": "^3.5.3",
+    "publint": "^0.3.12",
+    "tinybench": "^4.0.1",
+    "typescript": "^5.8.3",
+    "vitepress": "^2.0.0-alpha.12",
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "zod": "^4.1.11"
+  }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Contains a schema adapter for app's using [`zod`](https://npmjs.com/package/zod).
+ * @module
+ */
+import type { SchemaAdapter } from "../types";
+
+const zod = "zod";
+const { z } = await import(zod);
+
+/**
+ * Usage:
+ *
+ * ```ts
+ * import { zodSchemaAdapter } from "@aklinker1/zeta/adapters/zod-schema-adapter";
+ *
+ * const app = createApp({
+ *   schemaAdapter: zodSchemaAdapter,
+ * });
+ * ```
+ */
+export const zodSchemaAdapter: SchemaAdapter = {
+  toJsonSchema: (schema) => {
+    if (!("_zod" in schema)) throw Error("input schema is not a Zod schema");
+    const res = z.toJSONSchema(schema, { target: "draft-7" });
+    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

@@ -0,0 +1,453 @@
+import { callHandler } from "./internal/call-handler";
+import { HttpError } from "./errors";
+import { HttpStatus } from "./status";
+import type {
+  App,
+  RouterData,
+  RouteDef,
+  BasePath,
+  ServerSideFetch,
+  OnGlobalRequestContext,
+  LifeCycleHooks,
+  LifeCycleHook,
+  DefaultAppData,
+  BasePrefix,
+  SchemaAdapter,
+} from "./types";
+import { addRoute, createRouter, findRoute } from "rou3";
+import { callCtxModifierHooks, serializeErrorResponse } from "./internal/utils";
+import type { OpenAPIV3_1 } from "openapi-types";
+import { buildOpenApiDocs, buildScalarHtml } from "./open-api";
+
+let appIdInc = 0;
+const nextAppId = () => `app-${appIdInc++}`;
+
+let _hookIdInc = 0;
+const nextHookId = (appId: string) => `${appId}/hook-${_hookIdInc++}`;
+
+/**
+ * Create a server-side, Zeta application.
+ *
+ * Zeta provides simple support for serving applications using `Bun.serve` and
+ * `Deno.serve` by calling `app.listen(3000)`.
+ *
+ * If you need more customization, you can use the `build` method to create a
+ * `fetch` function and serve it however you like.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from "@aklinker1/zeta";
+ *
+ * const app = createApp({ prefix: "/api" })
+ *   .get("/health", () => "OK")
+ *   .get("/users", () => ["user1", "user2"]);
+ *
+ * app.listen(3000);
+ *
+ * // Or serve the app yourself
+ * const fetch = app.build();
+ * Bun.serve({ fetch, ... });
+ * Deno.serve({ fetch, ... });
+ * ```
+ *
+ * @param options Configure application behavior.
+ */
+export function createApp<TPrefix extends BasePrefix = "">(
+  options?: CreateAppOptions<TPrefix>,
+): App<{
+  ctx: {};
+  exported: false;
+  prefix: TPrefix;
+  routes: {};
+}> {
+  const appId = nextAppId();
+
+  const { origin = "http://localhost", prefix = "" } = options ?? {};
+  const hooks: App["~zeta"]["hooks"] = {
+    onAfterHandle: [],
+    onGlobalAfterResponse: [],
+    onBeforeHandle: [],
+    onMapResponse: [],
+    onGlobalError: [],
+    onGlobalRequest: [],
+    onTransform: [],
+  };
+  const routes: App["~zeta"]["routes"] = {};
+
+  const addRoutesEntry = (method: string, route: string, data: RouterData) => {
+    routes[method] ??= {};
+    if (routes[method][route]) {
+      console.warn(`Route ${route} already exists`);
+    }
+    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 app: App<DefaultAppData> = {
+    // @ts-expect-error
+    [Symbol.toStringTag]: "ZetaApp",
+
+    "~zeta": {
+      id: appId,
+      prefix,
+      routes,
+      hooks,
+    },
+
+    build: () => {
+      const jsonRoute = options?.openApiRoute ?? "/openapi.json";
+      const scalarRoute = options?.scalarRoute ?? "/scalar";
+      const docs = buildOpenApiDocs(options, app);
+      if (docs.type === "error") {
+        console.error("Failed to build OpenAPI docs:", docs.error);
+      }
+
+      app.get(jsonRoute, () => {
+        if (docs.type === "error") {
+          console.error("Failed to build OpenAPI docs:", docs.error);
+          throw docs.error;
+        }
+        return docs.spec;
+      });
+      if (docs.type === "success") {
+        const scalarHtml = buildScalarHtml(jsonRoute, options);
+        app.get(
+          scalarRoute,
+          () =>
+            new Response(scalarHtml, {
+              headers: { "content-type": "text/html;charset=utf-8" },
+            }),
+        );
+      }
+
+      const router = createRouter<RouterData>();
+      for (const [method, methodValue] of Object.entries(routes)) {
+        for (const [path, data] of Object.entries(methodValue)) {
+          addRoute(
+            router,
+            method === Method.Any ? undefined : method,
+            path,
+            data,
+          );
+        }
+      }
+
+      // 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);
+          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);
+          }
+        }
+      };
+    },
+
+    getOpenApiSpec: () => {
+      const res = buildOpenApiDocs(options, app);
+      if (res.type === "error") throw res.error;
+
+      return res.spec;
+    },
+
+    export: () => {
+      app["~zeta"].exported = true;
+      return app as any;
+    },
+
+    listen: (port, cb) => {
+      if (typeof Bun !== "undefined") {
+        Bun.serve({ port, fetch: app.build() });
+        if (cb) setTimeout(cb, 0);
+      } else if (
+        // @ts-expect-error: Deno types not installed.
+        typeof Deno !== "undefined"
+      ) {
+        // @ts-expect-error: Deno types not installed.
+        Deno.serve({ port, fetch: app.build() });
+        if (cb) setTimeout(cb, 0);
+      }
+      return app;
+    },
+
+    decorate: (...args: any[]) => {
+      const obj: Record<string, any> =
+        args.length === 2 ? { [args[0]]: args[1] } : args[0];
+
+      hooks.onTransform.push({
+        id: nextHookId(appId),
+        applyTo: "local",
+        callback: () => obj,
+      });
+
+      return app;
+    },
+
+    onGlobalRequest(callback: any) {
+      hooks.onGlobalRequest.push({
+        id: nextHookId(appId),
+        applyTo: "global",
+        callback,
+      });
+      return app;
+    },
+    onTransform(callback: any) {
+      hooks.onTransform.push({
+        id: nextHookId(appId),
+        applyTo: "local",
+        callback,
+      });
+      return app;
+    },
+    onBeforeHandle(callback: any) {
+      hooks.onBeforeHandle.push({
+        id: nextHookId(appId),
+        applyTo: "local",
+        callback,
+      });
+      return app;
+    },
+    onAfterHandle(callback: any) {
+      hooks.onAfterHandle.push({
+        id: nextHookId(appId),
+        applyTo: "local",
+        callback,
+      });
+      return app;
+    },
+    onMapResponse(callback: any) {
+      hooks.onMapResponse.push({
+        id: nextHookId(appId),
+        applyTo: "local",
+        callback,
+      });
+      return app;
+    },
+    onGlobalError(callback: any) {
+      hooks.onGlobalError.push({
+        id: nextHookId(appId),
+        applyTo: "global",
+        callback,
+      });
+      return app;
+    },
+    onGlobalAfterResponse(callback: any) {
+      hooks.onGlobalAfterResponse.push({
+        id: nextHookId(appId),
+        applyTo: "global",
+        callback,
+      });
+      return app;
+    },
+
+    get: (...args: any[]) =>
+      app.method.apply(app, [Method.Get, ...args] as any) as any,
+    post: (...args: any[]) =>
+      app.method.apply(app, [Method.Post, ...args] as any) as any,
+    put: (...args: any[]) =>
+      app.method.apply(app, [Method.Put, ...args] as any) as any,
+    delete: (...args: any[]) =>
+      app.method.apply(app, [Method.Delete, ...args] as any) as any,
+    any: (...args: any[]) =>
+      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 handler = args[1] ?? args[0];
+      const route = `${prefix}${path}`;
+      addRoutesEntry(method, route, {
+        def,
+        handler,
+        route,
+        hooks: cloneHooks(),
+      });
+      return app;
+    },
+
+    mount(...args: any[]) {
+      let path = "";
+      let def = {};
+      let fetch: ServerSideFetch;
+
+      if (args.length === 1) {
+        fetch = args[0];
+      } else if (args.length === 2) {
+        path = args[0];
+        fetch = args[1];
+      } else {
+        path = args[0];
+        def = args[1];
+        fetch = args[2];
+      }
+
+      const route = `${prefix}${path}/**`;
+      addRoutesEntry(Method.Any, route, {
+        def,
+        fetch,
+        route,
+        hooks: cloneHooks(),
+      });
+
+      return app as any;
+    },
+
+    use: (childApp) => {
+      // Bring in routes
+      for (const [method, methodValue] of Object.entries(
+        childApp["~zeta"].routes,
+      )) {
+        for (const [subRoute, routeValue] of Object.entries(methodValue)) {
+          const route = `${prefix}${subRoute}`;
+          addRoutesEntry(method, route, { ...routeValue, route });
+        }
+      }
+
+      // 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>);
+          }
+        }
+        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;
+    },
+  };
+
+  return app as any;
+}
+
+/**
+ * Configure how the app is created.
+ */
+export type CreateAppOptions<TPrefix extends BasePrefix = ""> = {
+  /**
+   * The origin to use when constructing URLs.
+   * @default "http://localhost"
+   */
+  origin?: string;
+
+  /**
+   * Add a prefix to the beginning of all routes in the app.
+   */
+  prefix?: TPrefix;
+
+  /**
+   * Tell Zeta which library you're using for validation. OpenAPI docs cannot
+   * be served without a schema adapter.
+   *
+   * @example
+   * ```ts
+   * import { zodSchemaAdapter } from "@aklinker1/zeta/adapters/zod-schema-adapter"
+   *
+   * const app = createApp({
+   *   openApi: {
+   *     schemaAdapter: zodSchemaAdapter,
+   *   },
+   * });
+   * ```
+   */
+  schemaAdapter?: SchemaAdapter;
+
+  /**
+   * Where the OpenAPI JSON docs is hosted.
+   * @default "/openapi.json"
+   */
+  openApiRoute?: BasePath;
+  /**
+   * Where the Scalar UI is hosted.
+   * @default "/scalar"
+   */
+  scalarRoute?: BasePath;
+
+  /** Configure how your application's OpenAPI docs are generated. */
+  openApi?: Partial<OpenAPIV3_1.Document> & {};
+  /**
+   * Configure [Scalar](https://scalar.com/) UI docs.
+   * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md#list-of-all-attributes
+   */
+  scalar?: any;
+};
+
+enum Method {
+  Get = "GET",
+  Post = "POST",
+  Put = "PUT",
+  Delete = "DELETE",
+  Any = "ANY",
+}