@mehdad67/apitogo 0.1.24

package/src/lib/util/flattenAllOf.ts

@@ -0,0 +1,72 @@
+import {
+  createComparator,
+  createMerger,
+  createShallowAllOfMerge,
+} from "@x0k/json-schema-merge";
+import {
+  createDeduplicator,
+  createIntersector,
+} from "@x0k/json-schema-merge/lib/array";
+import type { JSONSchema7Definition } from "json-schema";
+
+const { compareSchemaDefinitions, compareSchemaValues } = createComparator();
+const { mergeArrayOfSchemaDefinitions } = createMerger({
+  intersectJson: createIntersector(compareSchemaValues),
+  deduplicateJsonSchemaDef: createDeduplicator(compareSchemaDefinitions),
+});
+
+const shallowAllOfMerge = createShallowAllOfMerge(
+  mergeArrayOfSchemaDefinitions,
+);
+
+// Recursively flattens all `allOf` keywords in a JSON Schema object.
+export const flattenAllOf = (
+  schema: JSONSchema7Definition,
+): JSONSchema7Definition => {
+  const merged = shallowAllOfMerge(schema);
+
+  // Convert boolean schemas to object form for OpenAPI compatibility
+  // true (accepts anything) → {} (empty schema)
+  // false (rejects everything) → { not: {} } (schema that never validates)
+  if (typeof merged === "boolean") {
+    return merged ? {} : { not: {} };
+  }
+
+  if (merged == null || typeof merged !== "object") {
+    return merged;
+  }
+
+  const { properties, items, additionalProperties } = merged;
+
+  if (properties != null && typeof properties === "object") {
+    for (const [name, sub] of Object.entries(properties)) {
+      if (sub && typeof sub === "object") {
+        properties[name] = flattenAllOf(sub);
+      }
+    }
+  }
+
+  if (items != null && typeof items === "object") {
+    if (Array.isArray(items)) {
+      merged.items = items.map((it: JSONSchema7Definition) =>
+        it && typeof it === "object" ? flattenAllOf(it) : it,
+      );
+    } else {
+      merged.items = flattenAllOf(items);
+    }
+  }
+
+  if (additionalProperties && typeof additionalProperties === "object") {
+    merged.additionalProperties = flattenAllOf(additionalProperties);
+  }
+
+  for (const key of ["anyOf", "oneOf"] as const) {
+    const arr = merged[key];
+    if (!Array.isArray(arr)) continue;
+    merged[key] = arr.map((v) =>
+      typeof v === "object" && v != null ? flattenAllOf(v) : v,
+    );
+  }
+
+  return merged;
+};

package/src/lib/util/flattenAllOfProcessor.ts

@@ -0,0 +1,74 @@
+import { $RefParser } from "@apidevtools/json-schema-ref-parser";
+import type { Processor } from "../../config/validators/BuildSchema.js";
+import type { OpenAPIDocument } from "../oas/parser/index.js";
+import { flattenAllOf } from "./flattenAllOf.js";
+import { type RecordAny, traverse } from "./traverse.js";
+
+export const flattenAllOfProcessor: Processor = async ({ schema, file }) => {
+  try {
+    // Resolve refs once - creates a lookup table without modifying the schema
+    const parser = new $RefParser();
+    await parser.resolve(schema);
+    const $refs = parser.$refs;
+
+    // Pre-resolve all $refs inside allOf items throughout the schema before
+    // flattening. flattenAllOf recurses internally into oneOf/anyOf/properties
+    // without going through $ref resolution, so we must ensure all allOf items
+    // are resolved upfront. This prevents stale $ref keys from being merged
+    // into parent schemas when they point to paths removed during flattening.
+    const resolved = traverse(schema, (spec) => {
+      if (
+        !spec ||
+        typeof spec !== "object" ||
+        Array.isArray(spec) ||
+        !("allOf" in spec) ||
+        !Array.isArray(spec.allOf)
+      ) {
+        return spec;
+      }
+
+      const resolvedAllOf = spec.allOf.map((item) => {
+        if (
+          item &&
+          typeof item === "object" &&
+          "$ref" in item &&
+          typeof item.$ref === "string"
+        ) {
+          try {
+            return $refs.get(item.$ref) ?? item;
+          } catch {
+            return item;
+          }
+        }
+        return item;
+      });
+
+      return { ...spec, allOf: resolvedAllOf };
+    }) as OpenAPIDocument;
+
+    const flattened = traverse(resolved, (spec) => {
+      if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+        return spec;
+      }
+
+      const isSchemaObject =
+        "type" in spec ||
+        "properties" in spec ||
+        "allOf" in spec ||
+        "anyOf" in spec ||
+        "oneOf" in spec;
+
+      if (!isSchemaObject) return spec;
+
+      return flattenAllOf(spec) as RecordAny;
+    }) as OpenAPIDocument;
+
+    return flattened;
+  } catch (error) {
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.warn(
+      `Failed to flatten \`allOf\` in ${file}: ${error instanceof Error ? error.message : error}`,
+    );
+    return schema;
+  }
+};

package/src/lib/util/hastToJsx.tsx

@@ -0,0 +1,67 @@
+import { useMDXComponents } from "@mdx-js/react";
+import type { RootContent } from "hast";
+import { toJsxRuntime } from "hast-util-to-jsx-runtime";
+import type {
+  MdxJsxFlowElementHast,
+  MdxJsxTextElementHast,
+} from "mdast-util-mdx-jsx";
+import type { MDXComponents } from "mdx/types.js";
+import { createElement, Fragment, type ReactNode } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+type MdxJsxElement = MdxJsxFlowElementHast | MdxJsxTextElementHast;
+
+const isMdxJsxElement = (node: RootContent): node is MdxJsxElement =>
+  node.type === "mdxJsxTextElement" || node.type === "mdxJsxFlowElement";
+
+const convertNode = (
+  node: RootContent,
+  components: MDXComponents,
+): ReactNode => {
+  if (isMdxJsxElement(node)) {
+    // Fragment if no name, otherwise look up component or use name as HTML tag
+    const Component = node.name
+      ? (components[node.name] ?? node.name)
+      : Fragment;
+
+    const props = Object.fromEntries(
+      node.attributes.flatMap((attr): [string, unknown][] => {
+        if (attr.type !== "mdxJsxAttribute") return [];
+        const { name, value } = attr;
+
+        if (value == null) return [[name, true]];
+
+        if (["string", "number", "boolean"].includes(typeof value)) {
+          return [[name, value]];
+        }
+
+        return [];
+      }),
+    );
+
+    const children = node.children.map((child) =>
+      convertNode(child, components),
+    );
+
+    return createElement(Component, props, ...children);
+  }
+
+  return toJsxRuntime(node, { Fragment, jsx, jsxs, components });
+};
+
+const HastRichText = ({
+  children,
+  overrides,
+}: {
+  children: RootContent[];
+  overrides?: MDXComponents;
+}) => {
+  const components = useMDXComponents(overrides);
+
+  return children.map((node, i) => (
+    // biome-ignore lint/suspicious/noArrayIndexKey: Stable content from markdown AST
+    <Fragment key={i}>{convertNode(node, components)}</Fragment>
+  ));
+};
+
+export default HastRichText;

package/src/lib/util/humanFileSize.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts a number of bytes to a human-readable file size string
+ * @param bytes - The number of bytes (defaults to 0)
+ * @returns A formatted string like "1.23 MB" or "456 B"
+ */
+export const humanFileSize = (bytes = 0) => {
+  if (bytes === 0) {
+    return "0 B";
+  }
+
+  const exponent = Math.floor(Math.log(bytes) / Math.log(1000.0));
+  const decimal = (bytes / 1000.0 ** exponent).toFixed(exponent ? 2 : 0);
+
+  return `${decimal} ${exponent ? `${"kMGTPEZY"[exponent - 1]}B` : "B"}`;
+};

package/src/lib/util/invariant.ts

@@ -0,0 +1,52 @@
+export default function invariant(
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  condition: any,
+  // Not providing an inline default argument for message as the result is smaller
+  /**
+   * Can provide a string, or a function that returns a string for cases where
+   * the message takes a fair amount of effort to compute
+   */
+  message?: string | (() => string),
+  options?: ApitogoErrorOptions,
+): asserts condition {
+  if (condition) {
+    return;
+  }
+  // Condition not passed
+
+  const provided: string | undefined =
+    typeof message === "function" ? message() : message;
+
+  throw new ApitogoError(provided ?? "Invariant failed", options);
+}
+
+export type ApitogoErrorOptions = {
+  developerHint?: string;
+  title?: string;
+  cause?: Error;
+};
+
+/**
+ * @deprecated Use {@link ApitogoErrorOptions} instead.
+ */
+export type ZudokuErrorOptions = ApitogoErrorOptions;
+
+export class ApitogoError extends Error {
+  public developerHint: string | undefined;
+  public title: string | undefined;
+
+  constructor(
+    message: string,
+    { developerHint, title, cause }: ApitogoErrorOptions = {},
+  ) {
+    super(message, { cause });
+    this.name = "ApitogoError";
+    this.title = title;
+    this.developerHint = developerHint;
+  }
+}
+
+/**
+ * @deprecated Use {@link ApitogoError} instead.
+ */
+export const ZudokuError = ApitogoError;

package/src/lib/util/joinUrl.ts

@@ -0,0 +1,60 @@
+// Mostly adapted from https://github.com/moxystudio/js-proper-url-join
+const defaultUrlRegExp = /^(\w+:\/\/[^/?]+)?([^?]*)(\?.*)?$/;
+
+const normalizeParts = (
+  parts: (string | number | null | undefined | false)[],
+): string[] =>
+  parts
+    .filter(
+      (part): part is string | number =>
+        part !== null &&
+        part !== undefined &&
+        part !== false &&
+        (typeof part === "string" || typeof part === "number"),
+    )
+    .map((part) => `${part}`)
+    .filter((part) => part);
+
+interface ParsedParts {
+  prefix: string;
+  pathname: string[];
+  query: string;
+}
+
+const parseParts = (parts: string[]): ParsedParts => {
+  const partsStr = parts.join("/");
+  const [, prefix = "", pathname = "", query = ""] =
+    partsStr.match(defaultUrlRegExp) ?? [];
+
+  return {
+    prefix,
+    pathname: pathname.split("/").filter((part) => part !== ""),
+    query,
+  };
+};
+
+const buildUrl = (parsedParts: ParsedParts): string => {
+  const { prefix, pathname, query } = parsedParts;
+  let url = prefix;
+
+  if (pathname.length > 0) {
+    if (url) {
+      url += "/";
+    } else {
+      url = "/";
+    }
+    url += pathname.join("/");
+  } else if (!url) {
+    url = "/";
+  }
+
+  return url + query;
+};
+
+export const joinUrl = (
+  ...parts: Array<string | number | null | undefined | false>
+): string => {
+  const normalizedParts = normalizeParts(parts);
+  const parsedParts = parseParts(normalizedParts);
+  return buildUrl(parsedParts);
+};

package/src/lib/util/logInit.ts

@@ -0,0 +1,9 @@
+import log from "loglevel";
+
+log.setDefaultLevel("silent");
+
+if (import.meta.env.DEV) {
+  log.setLevel("debug");
+} else if (localStorage.getItem("ENABLE_DEBUG_LOGS")) {
+  log.setLevel("debug");
+}

package/src/lib/util/objectEntries.ts

@@ -0,0 +1,5 @@
+type ValueOf<T> = T[keyof T];
+type Entries<T> = [keyof T, ValueOf<T>][];
+
+export const objectEntries = <T extends object>(obj: T): Entries<T> =>
+  Object.entries(obj) as Entries<T>;

package/src/lib/util/os.ts

@@ -0,0 +1,18 @@
+export function getOS(): "apple" | "linux" | "unix" | "windows" | undefined {
+  const notFound = -1;
+  const userAgent = navigator.userAgent.toLowerCase();
+  if (userAgent.indexOf("win") !== notFound) {
+    return "windows";
+  } else if (userAgent.indexOf("mac") !== notFound) {
+    return "apple";
+  } else if (userAgent.indexOf("linux") !== notFound) {
+    return "linux";
+  } else if (userAgent.indexOf("x11") !== notFound) {
+    return "unix";
+  }
+  return;
+}
+
+export function isAppleDevice(): boolean {
+  return getOS() === "apple";
+}

package/src/lib/util/pastellize.ts

@@ -0,0 +1,25 @@
+const c2n = (c: string) =>
+  Math.abs(
+    Number.isNaN(Number(c))
+      ? c.toLowerCase().charCodeAt(0) - 96
+      : Number.isNaN(Number(c))
+        ? 0
+        : Number(c),
+  );
+const s2n = (s: string) =>
+  s.length > 1
+    ? Number(s.split("").reduce((a, c) => `${c2n(a) + c2n(c)}`))
+    : c2n(s);
+
+export const pastellize = (
+  s: string,
+  options: {
+    saturation?: number;
+    lightness?: number;
+  } = {},
+) => {
+  const hue = (3 * s2n(s) + 2 * s2n(s) + s2n(s)) % 360;
+  const { saturation = 75, lightness = 60 } = options;
+
+  return `${hue}deg ${saturation}% ${lightness}%`;
+};

package/src/lib/util/problemJson.ts

@@ -0,0 +1,63 @@
+/**
+ * RFC 9457 - Problem Details for HTTP APIs
+ * https://www.rfc-editor.org/rfc/rfc9457.html
+ */
+
+const PROBLEM_JSON_CONTENT_TYPE = "application/problem+json";
+const DEFAULT_TYPE = "about:blank";
+
+export type ProblemJson = {
+  type: string;
+  title?: string;
+  status?: number;
+  detail?: string;
+  instance?: string;
+  [extension: string]: unknown;
+};
+
+const parseJsonSafe = async (response: Response) => {
+  try {
+    return await response.json();
+  } catch {
+    return;
+  }
+};
+
+const isProblemJsonContentType = (response: Response) => {
+  const contentType = response.headers.get("content-type");
+  return contentType?.includes(PROBLEM_JSON_CONTENT_TYPE) ?? false;
+};
+
+const normalizeProblemJson = (data: unknown): ProblemJson | undefined => {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return;
+  }
+
+  const record = data as Record<string, unknown>;
+
+  return {
+    ...record,
+    type: typeof record.type === "string" ? record.type : DEFAULT_TYPE,
+  } as ProblemJson;
+};
+
+export const getProblemJson = async (
+  response: Response,
+): Promise<ProblemJson | undefined> => {
+  if (!isProblemJsonContentType(response)) {
+    return;
+  }
+
+  const data = await parseJsonSafe(response);
+
+  return normalizeProblemJson(data);
+};
+
+export const throwIfProblemJson = async (response: Response) => {
+  if (!response.ok) {
+    const problem = await getProblemJson(response);
+    if (problem) {
+      throw new Error(problem.detail ?? problem.title ?? "Unknown error");
+    }
+  }
+};

package/src/lib/util/readFrontmatter.ts

@@ -0,0 +1,14 @@
+import { readFile } from "node:fs/promises";
+import matter from "gray-matter";
+import { parse, stringify } from "yaml";
+
+export const yaml = {
+  parse: (input: string) => parse(input) ?? {},
+  stringify: (obj: object) => stringify(obj),
+};
+
+export const readFrontmatter = async (filePath: string) => {
+  const content = await readFile(filePath, "utf-8");
+  const normalizedContent = content.replace(/\r\n/g, "\n");
+  return matter(normalizedContent, { engines: { yaml } });
+};

package/src/lib/util/renderIf.ts

@@ -0,0 +1,4 @@
+export const renderIf = <G, R>(
+  variable: G | undefined | null,
+  callback: (variable: G) => R,
+): R | undefined => (variable ? callback(variable) : undefined);

package/src/lib/util/scrollIntoViewIfNeeded.ts

@@ -0,0 +1,18 @@
+export const scrollIntoViewIfNeeded = (
+  element: Element | null,
+  options: ScrollIntoViewOptions = { block: "center" },
+) => {
+  if (!element) return;
+
+  const rect = element.getBoundingClientRect();
+  const isInView =
+    rect.top >= 0 &&
+    rect.left >= 0 &&
+    rect.bottom <=
+      (window.innerHeight || document.documentElement.clientHeight) &&
+    rect.right <= (window.innerWidth || document.documentElement.clientWidth);
+
+  if (isInView) return;
+
+  element.scrollIntoView(options);
+};

package/src/lib/util/slugify.ts

@@ -0,0 +1,21 @@
+export const slugify = (str: string) =>
+  str
+    .normalize("NFKD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase()
+    .replace(/['\u2018\u2019\u201C\u201D]/g, "")
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "");
+
+export type CountableSlugify = (str: string) => string;
+
+export const slugifyWithCounter = (): CountableSlugify => {
+  const counts = new Map<string, number>();
+
+  return (str) => {
+    const base = slugify(str);
+    const count = counts.get(base) ?? 0;
+    counts.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count + 1}`;
+  };
+};

package/src/lib/util/syncZustandState.ts

@@ -0,0 +1,22 @@
+import type { Mutate, StoreApi } from "zustand";
+
+export type StoreWithPersist<T> = Mutate<
+  StoreApi<T>,
+  [["zustand/persist", unknown]]
+>;
+
+export const syncZustandState = <T>(store: StoreWithPersist<T>) => {
+  const storageEventCallback = (e: StorageEvent) => {
+    if (e.key === store.persist.getOptions().name && e.newValue) {
+      void store.persist.rehydrate();
+    }
+  };
+
+  if (typeof window === "undefined") return;
+
+  window.addEventListener("storage", storageEventCallback);
+
+  return () => {
+    window.removeEventListener("storage", storageEventCallback);
+  };
+};

package/src/lib/util/traverse.ts

@@ -0,0 +1,70 @@
+import type { JsonValue, RecordAny } from "./types.js";
+
+export type { RecordAny };
+
+export const traverse = <T extends JsonValue = RecordAny>(
+  specification: RecordAny,
+  transform: (specification: RecordAny, path?: string[]) => T,
+  path: string[] = [],
+) => {
+  const transformed = transform(specification, path);
+  if (typeof transformed !== "object" || transformed === null) {
+    return transformed;
+  }
+
+  const result: RecordAny = Array.isArray(transformed) ? [] : {};
+
+  for (const [key, value] of Object.entries(transformed)) {
+    const currentPath = [...path, key];
+
+    if (Array.isArray(value)) {
+      result[key] = value.map((item, index) =>
+        typeof item === "object" && item != null
+          ? traverse(item, transform, [...currentPath, index.toString()])
+          : item,
+      );
+    } else if (typeof value === "object" && value != null) {
+      result[key] = traverse(value, transform, currentPath);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};
+
+export const traverseAsync = async <T extends JsonValue = RecordAny>(
+  specification: RecordAny,
+  transform: (specification: RecordAny, path?: string[]) => T | Promise<T>,
+  path: string[] = [],
+) => {
+  const transformed = await transform(specification, path);
+  if (typeof transformed !== "object" || transformed === null) {
+    return transformed;
+  }
+
+  const result: RecordAny = Array.isArray(transformed) ? [] : {};
+
+  for (const [key, value] of Object.entries(transformed)) {
+    const currentPath = [...path, key];
+
+    if (Array.isArray(value)) {
+      result[key] = await Promise.all(
+        value.map(async (item, index) =>
+          typeof item === "object" && item != null
+            ? await traverseAsync(item, transform, [
+                ...currentPath,
+                index.toString(),
+              ])
+            : item,
+        ),
+      );
+    } else if (typeof value === "object" && value != null) {
+      result[key] = await traverseAsync(value, transform, currentPath);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};

package/src/lib/util/types.ts

@@ -0,0 +1,7 @@
+// biome-ignore lint/suspicious/noExplicitAny: Allow any type
+export type RecordAny = Record<string, any>;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonValue[];
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;

package/src/lib/util/url.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalizes a redirect URL by removing the origin and optionally the root path
+ */
+export function normalizeRedirectUrl(
+  redirectTo: string,
+  origin: string,
+  basePath: string = "/",
+): string {
+  if (!redirectTo.startsWith(origin)) {
+    return redirectTo;
+  }
+
+  if (basePath !== "/" && redirectTo.startsWith(origin + basePath)) {
+    return redirectTo.slice(origin.length + basePath.length);
+  }
+
+  return redirectTo.slice(origin.length);
+}

package/src/lib/util/useCopyToClipboard.ts

@@ -0,0 +1,17 @@
+import { useCallback, useState } from "react";
+
+export const useCopyToClipboard = (timeout = 2000) => {
+  const [isCopied, setIsCopied] = useState(false);
+
+  const copyToClipboard = useCallback(
+    (text: string) => {
+      void navigator.clipboard.writeText(text);
+      setIsCopied(true);
+
+      setTimeout(() => setIsCopied(false), timeout);
+    },
+    [timeout],
+  );
+
+  return [isCopied, copyToClipboard] as const;
+};