@aklinker1/zeta 1.0.0

package/src/internal/serialization.ts

@@ -0,0 +1,72 @@
+export function smartSerialize(value: unknown):
+  | {
+      contentType: string;
+      serialized: BodyInit;
+    }
+  | undefined {
+  if (value == null) return undefined;
+
+  if (value instanceof FormData) {
+    return {
+      contentType: "multipart/form-data",
+      serialized: value,
+    };
+  }
+
+  if (value instanceof Blob) {
+    return {
+      contentType: value.type,
+      serialized: value,
+    };
+  }
+
+  switch (typeof value) {
+    case "number":
+    case "boolean":
+    case "bigint":
+    case "string":
+      return { contentType: "text/plain", serialized: String(value) };
+    case "object":
+      return {
+        contentType: "application/json",
+        serialized: JSON.stringify(value),
+      };
+  }
+
+  throw Error(
+    "Could not serialize object for request: " + JSON.stringify(value),
+  );
+}
+
+export async function smartDeserialize(
+  arg: Response | Request,
+): Promise<unknown> {
+  const contentType = arg.headers.get("content-type");
+  if (contentType == null) return;
+
+  // JSON
+  if (contentType.startsWith("application/json")) {
+    return await arg.json();
+  }
+
+  // Forms
+  if (
+    contentType.startsWith("application/x-www-form-urlencoded") ||
+    contentType.startsWith("multipart/form-data")
+  ) {
+    return await arg.formData();
+  }
+
+  // Text
+  if (contentType.startsWith("text/")) {
+    return await arg.text();
+  }
+
+  // Binary
+  if (contentType.startsWith("application/octet-stream")) {
+    return await arg.arrayBuffer();
+  }
+
+  // Unknown
+  throw Error(`Unknown content type: "${contentType}"`);
+}

package/src/internal/utils.ts

@@ -0,0 +1,131 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { HttpError, ValidationGlobalError } from "../errors";
+import { HttpStatus } from "../status";
+import type {
+  App,
+  LifeCycleHook,
+  MaybePromise,
+  RouterData,
+  StatusResult,
+} from "../types";
+import type { MatchedRoute } from "rou3";
+import type { ErrorResponse } from "../custom-responses";
+
+export function validateSchema<T>(
+  schema: StandardSchemaV1<T, T>,
+  input: unknown,
+): T {
+  let res = schema["~standard"].validate(input);
+  if (res instanceof Promise) throw Error("Async validation not supported");
+
+  if (res.issues) throw new ValidationGlobalError(input, res.issues);
+
+  return res.value;
+}
+
+function createHttpSchemaValidator(status: HttpStatus, message: string) {
+  return <T>(schema: StandardSchemaV1<T, T>, input: unknown): T => {
+    try {
+      return validateSchema<T>(schema, input);
+    } catch (err) {
+      if (err instanceof ValidationGlobalError) {
+        throw new HttpError(status, message, {
+          issues: err.issues,
+          input: err.input,
+        });
+      } else {
+        throw err;
+      }
+    }
+  };
+}
+
+export const validateInputSchema = createHttpSchemaValidator(
+  HttpStatus.BadRequest,
+  "Input validation failed",
+);
+export const validateOutputSchema = createHttpSchemaValidator(
+  HttpStatus.UnprocessableEntity,
+  "Output validation failed",
+);
+
+export function isApp(obj: unknown): obj is App<any> {
+  return (obj as any)[Symbol.toStringTag] === "ZetaApp";
+}
+
+export function getRawQuery(url: URL): Record<string, string> {
+  const query: Record<string, string> = {};
+  const params = url.searchParams;
+  const entries = params.entries();
+
+  for (const entry of entries) query[entry[0]] = entry[1];
+  return query;
+}
+
+export function getRawParams(
+  route: MatchedRoute<RouterData>,
+): Record<string, string> {
+  const rawParams = route.params ?? {};
+  // Rename _ to ** for validation and consistency
+  if ("_" in rawParams) {
+    rawParams["**"] = rawParams["_"];
+    delete rawParams["_"];
+  }
+  return rawParams;
+}
+
+export function getErrorStack(err: Error): string[] | undefined {
+  if (process.env.NODE_ENV === "production") return;
+  return err.stack
+    ?.split("\n")
+    .map((line) => line.trim())
+    .slice(1);
+}
+
+export function serializeErrorResponse(err: unknown): ErrorResponse {
+  if (err instanceof HttpError)
+    return {
+      status: err.status,
+      name: err.name,
+      message: err.message,
+      ...err.additionalInfo,
+      stack: getErrorStack(err),
+      cause: err.cause != null ? serializeErrorResponse(err.cause) : undefined,
+    };
+
+  if (err instanceof Error)
+    return {
+      status: HttpStatus.InternalServerError,
+      name: err.name,
+      message: err.message,
+      stack: getErrorStack(err),
+      cause: err.cause != null ? serializeErrorResponse(err.cause) : undefined,
+    };
+
+  return {
+    name: "Unknown Error",
+    message: "An unknown error occurred",
+    status: HttpStatus.InternalServerError,
+    stack: getErrorStack(err as Error),
+  };
+}
+
+export async function callCtxModifierHooks(
+  ctx: any,
+  hooks: LifeCycleHook<
+    (ctx: any) => MaybePromise<Record<string, any> | void>
+  >[],
+): Promise<Response | undefined> {
+  for (const hook of hooks) {
+    let res = hook.callback(ctx);
+    res = res instanceof Promise ? await res : res;
+    if (res instanceof Response) return res;
+    if (res) Object.assign(ctx, res);
+  }
+}
+
+export const IsStatusResult = Symbol("IsStatusResult");
+
+export function isStatusResult(result: any): result is StatusResult {
+  return IsStatusResult in result;
+}

package/src/open-api.ts

@@ -0,0 +1,234 @@
+import type { OpenAPI } from "openapi-types";
+import type { App, BasePath, SchemaAdapter } from "./types";
+import type { CreateAppOptions } from "./app";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { getHttpStatusName } from "./status";
+import { ErrorResponseJsonSchema, type ZetaSchema } from "./custom-responses";
+
+export function buildOpenApiDocs(
+  options: CreateAppOptions<any> | undefined,
+  app: App,
+): { type: "success"; spec: any } | { type: "error"; error: unknown } {
+  try {
+    if (!options?.schemaAdapter)
+      return { type: "error", error: "OpenAPI docs require a schema adapter" };
+    const adapter = options.schemaAdapter;
+
+    const userDoc = options.openApi ?? {};
+    const docs: OpenAPI.Document = {
+      openapi: "3.1.0",
+      ...userDoc,
+      info: {
+        title: "Zeta Application",
+        version: "1.0.0",
+        ...userDoc.info,
+      },
+      paths: {},
+      components: {
+        ...userDoc.components,
+        schemas: {
+          ...userDoc.components?.schemas,
+          ErrorResponse: ErrorResponseJsonSchema,
+        },
+      },
+    };
+    for (const [method, methodEntry] of Object.entries(app["~zeta"].routes)) {
+      for (const [path, routerData] of Object.entries(methodEntry)) {
+        const openApiPath = path.replace(/\/:([^/]+)/g, "/{$1}");
+        const { headers, params, query, body, responses, ...openApiOperation } =
+          routerData.def ?? {};
+        docs.paths ??= {};
+        docs.paths[openApiPath] ??= {};
+
+        (docs.paths[openApiPath] as any)[method.toLowerCase()] = {
+          ...openApiOperation,
+          requestBody: body
+            ? {
+                content: {
+                  [adapter.getMeta(body)?.contentType ?? "application/json"]: {
+                    schema: adapter.toJsonSchema(body),
+                  },
+                },
+              }
+            : undefined,
+          parameters: [
+            ...mapParameters(adapter, params, "path"),
+            ...mapParameters(adapter, query, "query"),
+            ...mapParameters(adapter, headers, "header"),
+          ] as OpenAPI.Parameters,
+          responses: {
+            ...(!responses
+              ? {}
+              : "~standard" in responses
+                ? {
+                    200: buildResponse(200, responses, adapter),
+                  }
+                : Object.fromEntries(
+                    Object.entries(responses).map(([status, response]) => [
+                      status,
+                      buildResponse(Number(status), response, adapter),
+                    ]),
+                  )),
+            ...((params || query || headers || body) && {
+              400: {
+                description: "Bad Request",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/ErrorResponse",
+                    },
+                  },
+                },
+              },
+            }),
+          },
+        } as OpenAPI.Operation;
+      }
+    }
+
+    return { type: "success", spec: optimizeSpec(docs) };
+  } catch (error) {
+    return { type: "error", error };
+  }
+}
+
+export function buildScalarHtml(
+  jsonRoute: BasePath,
+  options: CreateAppOptions<any> | undefined,
+): string {
+  const scalarConfig = {
+    // Aaron's preferences
+    defaultOpenAllTags: true,
+
+    // User options
+    ...options?.scalar,
+
+    // Required config
+    url: jsonRoute,
+  };
+  return `<!doctype html>
+<html>
+  <head>
+    <title>API Reference</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      const config = ${JSON.stringify(scalarConfig)};
+      if (${process.env.NODE_ENV !== "production"}) {
+        config.servers ??= [];
+        config.servers.unshift({ url: location.origin })
+      }
+      Scalar.createApiReference('#app', config)
+    </script>
+  </body>
+</html>
+`;
+}
+
+function mapParameters(
+  adapter: SchemaAdapter,
+  schema: StandardSchemaV1 | undefined,
+  _in: "query" | "path" | "header",
+): OpenAPI.Parameters {
+  if (!schema) return [];
+
+  return adapter
+    .parseParamsRecord(schema)
+    .map(({ schema, optional, ...param }) => ({
+      ...param,
+      in: _in,
+      schema: adapter.toJsonSchema(schema),
+      required: !optional,
+    }));
+}
+
+function buildResponse(
+  status: number,
+  schema: StandardSchemaV1 | ZetaSchema,
+  adapter: SchemaAdapter,
+): NonNullable<OpenAPI.Operation["responses"]>[string] {
+  if ("~zeta" in schema) {
+    const description =
+      schema["~zeta"].meta?.responseDescription ??
+      getHttpStatusName(status) ??
+      "";
+    if (schema["~zeta"].type === "NoResponse") {
+      return {
+        description,
+      };
+    }
+    if (schema["~zeta"].type === "ErrorResponse") {
+      return {
+        description,
+        content: {
+          "application/json": {
+            schema: {
+              $ref: "#/components/schemas/ErrorResponse",
+            },
+          },
+        },
+      };
+    }
+  }
+
+  const meta = adapter.getMeta(schema);
+  return {
+    description: meta?.responseDescription ?? getHttpStatusName(status),
+    content: {
+      [meta?.contentType ?? "application/json"]: {
+        schema: adapter.toJsonSchema(schema),
+      },
+    },
+  };
+}
+
+function optimizeSpec(spec: OpenAPI.Document): OpenAPI.Document {
+  const optimized = structuredClone(spec);
+
+  // Optimizations
+  addModelRefs(optimized);
+
+  return optimized;
+}
+
+/**
+ * Look for `ref` properties from schema metadata and move those models to
+ * `components.schemas`.
+ */
+function addModelRefs(spec: any): void {
+  const recurse = (obj: any): void => {
+    if (obj == null) return;
+    if (typeof obj !== "object") return;
+
+    // Recursively update array items
+    if (Array.isArray(obj)) {
+      for (let i = 0, il = obj.length; i < il; i++) recurse(obj[i]);
+      return;
+    }
+
+    // Recursively update object properties
+    const values = Object.values(obj);
+    for (let i = 0, il = values.length; i < il; i++) recurse(values[i]);
+
+    // Move model if it includes a ref
+    if (typeof obj.ref === "string") {
+      const ref = obj.ref;
+      spec.components ??= {};
+      spec.components.schemas ??= {};
+      spec.components.schemas[ref] = {
+        ...structuredClone(obj),
+        // Remove any zeta-only properties OpenAPI doesn't support
+        ref: undefined,
+      };
+      for (const key of Object.keys(obj)) delete obj[key];
+      obj.$ref = `#/components/schemas/${ref}`;
+    }
+  };
+
+  // Process the "paths" object
+  recurse(spec.paths);
+}

package/src/status.ts

@@ -0,0 +1,143 @@
+/**
+ * Enum containing all HTTP status codes.
+ */
+export enum HttpStatus {
+  Continue = 100,
+  SwitchingProtocols = 101,
+  ProcessingDeprecated = 102,
+  EarlyHints = 103,
+  Ok = 200,
+  Created = 201,
+  Accepted = 202,
+  NonAuthoritativeInformation = 203,
+  NoContent = 204,
+  ResetContent = 205,
+  PartialContent = 206,
+  MultiStatus = 207,
+  AlreadyReported = 208,
+  ImUsed = 226,
+  MultipleChoices = 300,
+  MovedPermanently = 301,
+  Found = 302,
+  SeeOther = 303,
+  NotModified = 304,
+  UseProxyDeprecated = 305,
+  Unused = 306,
+  TemporaryRedirect = 307,
+  PermanentRedirect = 308,
+  BadRequest = 400,
+  Unauthorized = 401,
+  PaymentRequired = 402,
+  Forbidden = 403,
+  NotFound = 404,
+  MethodNotAllowed = 405,
+  NotAcceptable = 406,
+  ProxyAuthenticationRequired = 407,
+  RequestTimeout = 408,
+  Conflict = 409,
+  Gone = 410,
+  LengthRequired = 411,
+  PreconditionFailed = 412,
+  ContentTooLarge = 413,
+  UriTooLong = 414,
+  UnsupportedMediaType = 415,
+  RangeNotSatisfiable = 416,
+  ExpectationFailed = 417,
+  ImATeapot = 418,
+  MisdirectedRequest = 421,
+  UnprocessableEntity = 422,
+  Locked = 423,
+  FailedDependency = 424,
+  TooEarly = 425,
+  UpgradeRequired = 426,
+  PreconditionRequired = 428,
+  TooManyRequests = 429,
+  RequestHeaderFieldsTooLarge = 431,
+  UnavailableForLegalReasons = 451,
+  InternalServerError = 500,
+  NotImplemented = 501,
+  BadGateway = 502,
+  ServiceUnavailable = 503,
+  GatewayTimeout = 504,
+  HttpVersionNotSupported = 505,
+  VariantAlsoNegotiates = 506,
+  InsufficientStorage = 507,
+  LoopDetected = 508,
+  NotExtended = 510,
+  NetworkAuthenticationRequired = 511,
+}
+
+const STATUS_NAME_MAP: Record<HttpStatus, string> = {
+  [HttpStatus.Continue]: "Continue",
+  [HttpStatus.SwitchingProtocols]: "Switching Protocols",
+  [HttpStatus.ProcessingDeprecated]: "Processing",
+  [HttpStatus.EarlyHints]: "Early Hints",
+  [HttpStatus.Ok]: "OK",
+  [HttpStatus.Created]: "Created",
+  [HttpStatus.Accepted]: "Accepted",
+  [HttpStatus.NonAuthoritativeInformation]: "Non-Authoritative Information",
+  [HttpStatus.NoContent]: "No Content",
+  [HttpStatus.ResetContent]: "Reset Content",
+  [HttpStatus.PartialContent]: "Partial Content",
+  [HttpStatus.MultiStatus]: "Multi-Status",
+  [HttpStatus.AlreadyReported]: "Already Reported",
+  [HttpStatus.ImUsed]: "IM Used",
+  [HttpStatus.MultipleChoices]: "Multiple Choices",
+  [HttpStatus.MovedPermanently]: "Moved Permanently",
+  [HttpStatus.Found]: "Found",
+  [HttpStatus.SeeOther]: "See Other",
+  [HttpStatus.NotModified]: "Not Modified",
+  [HttpStatus.UseProxyDeprecated]: "Use Proxy",
+  [HttpStatus.Unused]: "Unused",
+  [HttpStatus.TemporaryRedirect]: "Temporary Redirect",
+  [HttpStatus.PermanentRedirect]: "Permanent Redirect",
+  [HttpStatus.BadRequest]: "Bad Request",
+  [HttpStatus.Unauthorized]: "Unauthorized",
+  [HttpStatus.PaymentRequired]: "Payment Required",
+  [HttpStatus.Forbidden]: "Forbidden",
+  [HttpStatus.NotFound]: "Not Found",
+  [HttpStatus.MethodNotAllowed]: "Method Not Allowed",
+  [HttpStatus.NotAcceptable]: "Not Acceptable",
+  [HttpStatus.ProxyAuthenticationRequired]: "Proxy Authentication Required",
+  [HttpStatus.RequestTimeout]: "Request Timeout",
+  [HttpStatus.Conflict]: "Conflict",
+  [HttpStatus.Gone]: "Gone",
+  [HttpStatus.LengthRequired]: "Length Required",
+  [HttpStatus.PreconditionFailed]: "Precondition Failed",
+  [HttpStatus.ContentTooLarge]: "Content Too Large",
+  [HttpStatus.UriTooLong]: "URI Too Long",
+  [HttpStatus.UnsupportedMediaType]: "Unsupported Media Type",
+  [HttpStatus.RangeNotSatisfiable]: "Range Not Satisfiable",
+  [HttpStatus.ExpectationFailed]: "Expectation Failed",
+  [HttpStatus.ImATeapot]: "I'm a Teapot",
+  [HttpStatus.MisdirectedRequest]: "Misdirected Request",
+  [HttpStatus.UnprocessableEntity]: "Unprocessable Entity",
+  [HttpStatus.Locked]: "Locked",
+  [HttpStatus.FailedDependency]: "Failed Dependency",
+  [HttpStatus.TooEarly]: "Too Early",
+  [HttpStatus.UpgradeRequired]: "Upgrade Required",
+  [HttpStatus.PreconditionRequired]: "Precondition Required",
+  [HttpStatus.TooManyRequests]: "Too Many Requests",
+  [HttpStatus.RequestHeaderFieldsTooLarge]: "Request Header Fields Too Large",
+  [HttpStatus.UnavailableForLegalReasons]: "Unavailable For Legal Reasons",
+  [HttpStatus.InternalServerError]: "Internal Server Error",
+  [HttpStatus.NotImplemented]: "Not Implemented",
+  [HttpStatus.BadGateway]: "Bad Gateway",
+  [HttpStatus.ServiceUnavailable]: "Service Unavailable",
+  [HttpStatus.GatewayTimeout]: "Gateway Timeout",
+  [HttpStatus.HttpVersionNotSupported]: "HTTP Version Not Supported",
+  [HttpStatus.VariantAlsoNegotiates]: "Variant Also Negotiates",
+  [HttpStatus.InsufficientStorage]: "Insufficient Storage",
+  [HttpStatus.LoopDetected]: "Loop Detected",
+  [HttpStatus.NotExtended]: "Not Extended",
+  [HttpStatus.NetworkAuthenticationRequired]: "Network Authentication Required",
+};
+
+/**
+ * Returns the name of the HTTP status code (200 -> "OK").
+ * @param status The HTTP status code.
+ * @returns The name of the HTTP status code or `undefined` if the status code is not recognized.
+ */
+export function getHttpStatusName(status: number): string | undefined {
+  return STATUS_NAME_MAP[status as HttpStatus];
+}

package/src/testing.ts

@@ -0,0 +1,62 @@
+/**
+ * Utilities for testing your server-side application.
+ *
+ * You don't need to use these utils, you can call the app's `fetch` function directly.
+ *
+ * ```ts
+ * const app = createApp()
+ *   .get("/example", () => "Hello, world!")
+ * const fetch = app.build();
+ *
+ * const res = await fetch("http://test/example");
+ * expect(res.status).toEqual(200);
+ * expect(await res.text()).toEqual("Hello, world!");
+ * ```
+ *
+ * If you just care about the response body or error thrown, you can use the `createTestAppClient`.
+ *
+ * @see {@link createTestAppClient}
+ * @module
+ */
+import {
+  createAppClient,
+  type AppClient,
+  type CreateAppClientOptions,
+  type GetClientRoutes,
+} from "./client";
+import type { App } from "./types";
+
+/**
+ * Create a client for testing your server-side application. When `fetch` is
+ * called, the app's `fetch` function is called instead of using the global
+ * `fetch`.
+ *
+ * @example
+ * ```ts
+ * const app = createApp()
+ *   .get("/example", () => "Hello, world!")
+ *
+ * const client = createTestAppClient(app);
+ *
+ * expect(await client.get("/example")).toEqual("Hello, world!");
+ * ```
+ *
+ * @param app
+ * @param options
+ * @returns An app client used to test your server-side application.
+ */
+export function createTestAppClient<TApp extends App>(
+  app: TApp,
+  options?: Omit<CreateAppClientOptions, "fetch">,
+): AppClient<GetClientRoutes<TApp>> {
+  const { baseUrl = "http://localhost" } = options ?? {};
+
+  const fetch = app.build();
+
+  return createAppClient({
+    baseUrl,
+    ...options,
+    // @ts-expect-error: Fetch type varies between environments
+    fetch: (...args) => fetch(new Request(...args)),
+  });
+}