@aklinker1/zeta 2.1.2 → 2.2.0

package/src/meta.ts

@@ -1,14 +0,0 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { SchemaAdapter } from "./types";
-import { isZetaSchema, type ZetaSchema } from "./schema";
-
-/** Get metadata for either a ZetaSchema or a StandardSchemaV1. */
-export function getMeta(
-  adapter: SchemaAdapter | undefined,
-  schema: StandardSchemaV1 | ZetaSchema,
-): Record<string, any> {
-  if (isZetaSchema(schema)) return schema["~zeta"].meta;
-
-  if (!adapter) return {};
-  return adapter.getMeta(schema) ?? {};
-}

package/src/open-api.ts

@@ -1,273 +0,0 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { OpenAPI } from "openapi-types";
-import { titleCase } from "scule";
-import type { CreateAppOptions } from "./app";
-import { getMeta } from "./meta";
-import {
-  ErrorResponseJsonSchema,
-  isZetaSchema,
-  type ZetaSchema,
-} from "./schema";
-import { getHttpStatusName } from "./status";
-import type { App, BasePath, SchemaAdapter } from "./types";
-
-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 parameters with OpenAPI format
-            .replace(/\/:([^/]+)/g, "/{$1}")
-            // Remove trailing slash
-            .replace(/\/$/, "") ||
-          // Convert "" -> "/"
-          "/";
-        const { headers, params, query, body, responses, ...openApiOperation } =
-          routerData.def ?? {};
-        docs.paths ??= {};
-        docs.paths[openApiPath] ??= {};
-
-        (docs.paths[openApiPath] as any)[method.toLowerCase()] = {
-          ...openApiOperation,
-          summary:
-            openApiOperation.summary ??
-            (openApiOperation.operationId
-              ? titleCase(openApiOperation.operationId)
-              : undefined),
-          requestBody: body
-            ? {
-                content: {
-                  [getMeta(adapter, body)?.contentType ?? "application/json"]: {
-                    schema: isZetaSchema(body)
-                      ? body.toJsonSchema?.()
-                      : 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 [];
-
-  const openApiSchema = adapter.toJsonSchema(schema);
-  if (openApiSchema.type !== "object")
-    throw Error(
-      `Param in ${in_} must have { "type": "object", ... }, but got ${JSON.stringify(openApiSchema, null, 2)}`,
-    );
-
-  return Object.entries(openApiSchema.properties).map(
-    ([name, def]: [string, any]) => ({
-      name,
-      in: in_,
-      description: def.description,
-      schema: def,
-      required: !!openApiSchema.required?.includes(name),
-    }),
-  );
-}
-
-function buildResponse(
-  status: number,
-  schema: StandardSchemaV1 | ZetaSchema,
-  adapter: SchemaAdapter,
-): NonNullable<OpenAPI.Operation["responses"]>[string] {
-  const meta = getMeta(adapter, schema);
-
-  if (isZetaSchema(schema)) {
-    const description =
-      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",
-            },
-          },
-        },
-      };
-    }
-  }
-
-  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);
-  sortComponentSchemas(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);
-}
-
-function sortComponentSchemas(spec: any): void {
-  if (!spec?.components?.schemas) return;
-
-  spec.components.schemas = Object.fromEntries(
-    Object.entries(spec.components.schemas).sort((a, b) =>
-      a[0].toLowerCase().localeCompare(b[0].toLowerCase()),
-    ),
-  );
-}

package/src/schema.ts

@@ -1,271 +0,0 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { HttpStatus } from "./status";
-
-export type ZetaSchema<Input = unknown, Output = Input> = StandardSchemaV1<
-  Input,
-  Output
-> & {
-  "~zeta": {
-    type: string;
-    meta: Record<string, any>;
-  };
-  toJsonSchema?(): any;
-  meta(meta?: Record<string, any>): ZetaSchema<Input, Output>;
-};
-
-function createZetaSchema<Input = unknown, Output = Input>(
-  name: string,
-  validate: (value: unknown) => StandardSchemaV1.Result<Output>,
-  toJsonSchema?: () => any,
-  meta: Record<string, string> = {},
-): ZetaSchema<Input, Output> {
-  const parentMeta = meta;
-  return {
-    "~zeta": {
-      type: name,
-      meta,
-    },
-    "~standard": {
-      vendor: "@aklinker/zeta",
-      version: 1,
-      validate,
-    },
-    meta(meta) {
-      return createZetaSchema(name, validate, undefined, {
-        ...parentMeta,
-        ...meta,
-      });
-    },
-    toJsonSchema,
-  };
-}
-
-/**
- * A schema for an error response. Use when defining additional status codes
- * that an operation might return with:
- *
- * ```ts
- * import { ErrorResponse } from '@aklinker/zeta';
- *
- * app.get(
- *   "/api/item/:itemId",
- *   {
- *     responses: {
- *       200: Item.optional(),
- *       404: ErrorResponse,
- *     }
- *   },
- *   () => {
- *     // ...
- *   }
- * );
- * ```
- */
-export const ErrorResponse: ZetaSchema<unknown, ErrorResponse> =
-  createZetaSchema<unknown, ErrorResponse>(
-    "ErrorResponse",
-    (value: unknown): StandardSchemaV1.Result<ErrorResponse> => {
-      if (value == null)
-        return {
-          issues: [{ message: `Expected an object, received ${value}` }],
-        };
-
-      if (typeof value !== "object")
-        return {
-          issues: [{ message: `Expected an object, received ${typeof value}` }],
-        };
-
-      const issues: StandardSchemaV1.Issue[] = [];
-      if (typeof (value as any).name !== "string") {
-        issues.push({
-          message: `Expected a string, received ${typeof (value as any).name}`,
-          path: ["name"],
-        });
-      }
-      if (typeof (value as any).message !== "string") {
-        issues.push({
-          message: `Expected a string, received ${typeof (value as any).message}`,
-          path: ["message"],
-        });
-      }
-      if (typeof (value as any).status !== "number") {
-        issues.push({
-          message: `Expected a number, received ${typeof (value as any).status}`,
-          path: ["status"],
-        });
-      }
-      if (issues.length > 0) return { issues };
-
-      return { value: value as ErrorResponse };
-    },
-  );
-
-export function isZetaSchema(schema: any): schema is ZetaSchema {
-  return schema?.["~standard"]?.vendor === "@aklinker/zeta";
-}
-
-/**
- * The actual type an error response conforms to.
- */
-export type ErrorResponse = {
-  [additionalInfo: string]: any;
-  name: string;
-  message: string;
-  status: HttpStatus;
-  stack?: string[];
-  cause?: ErrorResponse;
-};
-
-export const ErrorResponseJsonSchema = {
-  type: "object" as const,
-  properties: {
-    status: {
-      type: "number" as const,
-      description: "HTTP status code",
-      example: 400,
-    },
-    name: {
-      type: "string" as const,
-      description: "The error's name",
-      example: "Bad Request",
-    },
-    message: {
-      type: "string" as const,
-      description: "User-facing error message",
-      example: "Property 'name' is required",
-    },
-  },
-  required: ["status", "name", "message"],
-};
-
-/**
- * A schema for when you want to not return a response. Use when defining
- * additional status codes that an operation might return with:
- *
- * ```ts
- * import { NoResponse } from '@aklinker/zeta';
- *
- * app.get(
- *   "/api/item/:itemId",
- *   {
- *     responses: {
- *       [HttpStatus.Accepted]: NoResponse,
- *     }
- *   },
- *   () => {
- *     // ...
- *   }
- * );
- * ```
- */
-export const NoResponse: ZetaSchema<undefined | null | void, void> =
-  createZetaSchema<undefined | null | void, void>(
-    "NoResponse",
-    (value: unknown): StandardSchemaV1.Result<void> => {
-      return value != null
-        ? {
-            issues: [
-              { message: `Expected undefined or null, got ${typeof value}` },
-            ],
-          }
-        : { value: undefined };
-    },
-  );
-
-export const FormDataBody: ZetaSchema<FormData> = createZetaSchema<FormData>(
-  "FormDataBody",
-  (value: unknown): StandardSchemaV1.Result<FormData> => {
-    return value instanceof FormData
-      ? { value }
-      : {
-          issues: [{ message: `Expected FormData, got ${typeof value}` }],
-        };
-  },
-  () => ({
-    type: "object",
-    additionalProperties: true,
-  }),
-  {
-    contentType: "multipart/form-data",
-  },
-);
-
-export const UploadFileBody: ZetaSchema<File> = createZetaSchema<File>(
-  "UploadFileBody",
-  (value: unknown): StandardSchemaV1.Result<File> => {
-    if (!(value instanceof FormData)) {
-      return {
-        issues: [{ message: `Expected FormData, got ${typeof value}` }],
-      };
-    }
-
-    const file = value.get("file");
-    if (!(file instanceof File)) {
-      return {
-        issues: [{ message: `Expected File, got ${typeof file}` }],
-      };
-    }
-
-    return { value: file };
-  },
-  () => ({
-    type: "object",
-    properties: {
-      file: {
-        type: "string",
-        format: "binary",
-      },
-    },
-  }),
-  {
-    contentType: "multipart/form-data",
-  },
-);
-
-export const UploadFilesBody: ZetaSchema<FileList, File[]> = createZetaSchema<
-  FileList,
-  File[]
->(
-  "UploadFilesBody",
-  (value): StandardSchemaV1.Result<File[]> => {
-    if (!(value instanceof FormData)) {
-      return {
-        issues: [{ message: `Expected FormData, got ${typeof value}` }],
-      };
-    }
-
-    const files = value.getAll("files");
-    if (!Array.isArray(files)) {
-      return {
-        issues: [{ message: `Expected array of Files, got ${typeof files}` }],
-      };
-    }
-
-    const issues: string[] = [];
-    for (const file of files) {
-      if (!(file instanceof File)) {
-        issues.push(`Expected File, got ${typeof file}`);
-      }
-    }
-    if (issues.length > 0) {
-      return { issues: issues.map((message) => ({ message })) };
-    }
-
-    return { value: files as File[] };
-  },
-  () => ({
-    type: "object",
-    properties: {
-      files: {
-        type: "array",
-        items: {
-          type: "string",
-          format: "binary",
-        },
-      },
-    },
-  }),
-  {
-    contentType: "multipart/form-data",
-  },
-);

package/src/status.ts

@@ -1,143 +0,0 @@
-/**
- * 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];
-}