zudoku 0.0.0-f3858d6 → 0.0.0-f3f6db5

package/src/lib/oas/graphql/circular.ts

@@ -0,0 +1,50 @@
+import { GraphQLJSON } from "graphql-type-json";
+import { GraphQLScalarType } from "graphql/index.js";
+import { RecordAny } from "../../util/traverse.js";
+
+export const CIRCULAR_REF = "$[Circular Reference]";
+
+const handleCircularRefs = (
+  obj: any,
+  visited = new Map<string, string[]>(),
+  path: string[] = [],
+): any => {
+  if (obj === CIRCULAR_REF) return CIRCULAR_REF;
+  if (obj === null || typeof obj !== "object") return obj;
+
+  const currentPath = path.join(".");
+
+  if (obj.type === "object" && obj.properties) {
+    const schemaKey = Object.keys(obj.properties).sort().join("-");
+
+    if (visited.has(schemaKey)) {
+      const prevPaths = visited.get(schemaKey)!;
+      if (prevPaths.some((prev) => currentPath.startsWith(prev))) {
+        return CIRCULAR_REF;
+      }
+      visited.set(schemaKey, [...prevPaths, currentPath]);
+    } else {
+      visited.set(schemaKey, [currentPath]);
+    }
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item, index) =>
+      handleCircularRefs(item, visited, [...path, `${index}`]),
+    );
+  }
+
+  const result: RecordAny = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = handleCircularRefs(value, visited, [...path, key]);
+  }
+  return result;
+};
+
+export const GraphQLJSONSchema = new GraphQLScalarType({
+  ...GraphQLJSON,
+  name: "JSONSchema",
+  description: "OpenAPI schema scalar type that handles circular references",
+  serialize: (value: unknown) =>
+    GraphQLJSON.serialize(handleCircularRefs(value)),
+});

package/src/lib/oas/graphql/index.ts

@@ -1,18 +1,15 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import SchemaBuilder from "@pothos/core";
 import {
-  slugifyWithCounter,
   type CountableSlugify,
+  slugifyWithCounter,
 } from "@sindresorhus/slugify";
 import { GraphQLJSON, GraphQLJSONObject } from "graphql-type-json";
 import { createYoga, type YogaServerOptions } from "graphql-yoga";
-import { LRUCache } from "lru-cache";
-import hashit from "object-hash";
 import {
-  HttpMethods,
-  validate,
   type EncodingObject,
   type ExampleObject,
+  HttpMethods,
   type OpenAPIDocument,
   type OperationObject,
   type ParameterObject,
@@ -20,7 +17,9 @@ import {
   type SchemaObject,
   type ServerObject,
   type TagObject,
+  validate,
 } from "../parser/index.js";
+import { GraphQLJSONSchema } from "./circular.js";
 
 export type {
   EncodingObject,
@@ -47,10 +46,7 @@ export const createOperationSlug = (
 ) => {
   const summary =
     (operation.summary ?? "") +
-    (operation.operationId
-      ? "-" +
-        operation.operationId.slice(0, operation.summary ? Infinity : Infinity)
-      : "");
+    (operation.operationId ? "-" + operation.operationId : "");
 
   return slugify(
     (tag ? tag + "-" : "") +
@@ -58,26 +54,39 @@ export const createOperationSlug = (
   );
 };
 
-const cache = new LRUCache<string, OpenAPIDocument>({
-  ttl: 60 * 10 * 1000,
-  ttlAutopurge: true,
-  fetchMethod: (_key, _oldValue, { context }) => validate(context as string),
-});
+export type SchemaImports = Record<
+  string,
+  () => Promise<{ schema: OpenAPIDocument }>
+>;
 
 const builder = new SchemaBuilder<{
   Scalars: {
     JSON: any;
     JSONObject: any;
+    JSONSchema: any;
   };
   Context: {
     schema: OpenAPIDocument;
+    operations: GraphQLOperationObject[];
+    tags: TagObject[];
+    schemaImports?: SchemaImports;
+    currentTag?: string;
+    slugify: CountableSlugify;
   };
 }>({});
 
+type GraphQLOperationObject = OperationObject & {
+  path: string;
+  method: string;
+  slug?: string;
+  parentTag?: string;
+};
+
 const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
+const JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
 
-const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
+export const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
   const tags = schema.tags ?? [];
 
   // Extract tags from operations
@@ -96,10 +105,10 @@ const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
   return [...tags, ...uniqueOperationTags.map((tag) => ({ name: tag }))];
 };
 
-const getAllOperations = (paths?: PathsObject, tag?: string) => {
-  const slugify = slugifyWithCounter();
+const getAllOperations = (paths?: PathsObject) => {
+  const start = performance.now();
 
-  return Object.entries(paths ?? {}).flatMap(([path, value]) =>
+  const operations = Object.entries(paths ?? {}).flatMap(([path, value]) =>
     HttpMethods.flatMap((method) => {
       if (!value?.[method]) return [];
 
@@ -120,23 +129,17 @@ const getAllOperations = (paths?: PathsObject, tag?: string) => {
         ...operationParameters,
       ];
 
-      const slugData = {
-        summary: operation.summary,
-        operationId: operation.operationId,
-        path,
-        method,
-      };
-
       return {
         ...operation,
         method,
         path,
         parameters,
         tags: operation.tags ?? [],
-        slug: createOperationSlug(slugify, slugData, tag),
       };
     }),
   );
+
+  return operations;
 };
 
 const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
@@ -146,15 +149,19 @@ const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
     operations: t.field({
       type: [OperationItem],
       resolve: (parent, _args, ctx) => {
-        const rootTags = getAllTags(ctx.schema).map((tag) => tag.name);
-
-        return getAllOperations(ctx.schema.paths, parent.name).filter((item) =>
-          parent.name
-            ? item.tags.includes(parent.name)
-            : item.tags.length === 0 ||
-              // If none of the tags are present in the root tags, then show them here
-              item.tags.every((tag) => !rootTags.includes(tag)),
-        );
+        const rootTags = ctx.tags.map((tag) => tag.name);
+        return ctx.operations
+          .filter((item) =>
+            parent.name
+              ? item.tags?.includes(parent.name)
+              : item.tags?.length === 0 ||
+                // If none of the tags are present in the root tags, then show them here
+                item.tags?.every((tag) => !rootTags.includes(tag)),
+          )
+          .map((item) => ({
+            ...item,
+            parentTag: parent.name,
+          }));
       },
     }),
   }),
@@ -206,7 +213,7 @@ const ExampleItem = builder
       name: t.exposeString("name"),
       summary: t.exposeString("summary", { nullable: true }),
       description: t.exposeString("description", { nullable: true }),
-      value: t.exposeString("value", { nullable: true }),
+      value: t.expose("value", { type: JSONScalar, nullable: true }),
       externalValue: t.exposeString("externalValue", { nullable: true }),
     }),
   });
@@ -240,7 +247,7 @@ const ParameterItem = builder
           })),
         nullable: true,
       }),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
     }),
   });
 
@@ -254,7 +261,7 @@ const MediaTypeItem = builder
   .implement({
     fields: (t) => ({
       mediaType: t.exposeString("mediaType"),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
       examples: t.expose("examples", { type: [ExampleItem], nullable: true }),
       encoding: t.expose("encoding", { type: [EncodingItem], nullable: true }),
     }),
@@ -302,12 +309,24 @@ const ResponseItem = builder
   });
 
 const OperationItem = builder
-  .objectRef<
-    OperationObject & { path: string; method: string; slug: string }
-  >("OperationItem")
+  .objectRef<GraphQLOperationObject>("OperationItem")
   .implement({
     fields: (t) => ({
-      slug: t.exposeString("slug"),
+      slug: t.field({
+        type: "String",
+        resolve: (parent, _, ctx) => {
+          const slugData = {
+            summary: parent.summary,
+            operationId: parent.operationId,
+            path: parent.path,
+            method: parent.method,
+          };
+
+          //TODO: fix parent tag parent.tags
+          return createOperationSlug(ctx.slugify, slugData, parent.parentTag);
+        },
+      }),
+
       path: t.exposeString("path"),
       method: t.exposeString("method"),
       operationId: t.exposeString("operationId", { nullable: true }),
@@ -329,9 +348,12 @@ const OperationItem = builder
             ([mediaType, content]) => ({
               mediaType,
               schema: content.schema,
-              examples: Object.entries(content.examples ?? {}).map(
-                ([name, value]) => ({ name, ...value }),
-              ),
+              examples: content.examples
+                ? Object.entries(content.examples).map(([name, value]) => ({
+                    name,
+                    ...(typeof value === "string" ? { value } : value),
+                  }))
+                : [],
               encoding: Object.entries(content.encoding ?? {}).map(
                 ([name, value]) => ({ name, ...value }),
               ),
@@ -348,12 +370,15 @@ const OperationItem = builder
               statusCode,
               description: response.description,
               content: Object.entries(response.content ?? {}).map(
-                ([mediaType, mediaTypeObject]) => ({
+                ([mediaType, { schema, examples }]) => ({
                   mediaType,
-                  schema: mediaTypeObject.schema,
-                  examples: Object.entries(mediaTypeObject.examples ?? {}).map(
-                    ([name, value]) => ({ name, ...value }),
-                  ),
+                  schema,
+                  examples: examples
+                    ? Object.entries(examples).map(([name, value]) => ({
+                        name,
+                        ...(typeof value === "string" ? { value } : value),
+                      }))
+                    : [],
                 }),
               ),
               headers: response.headers,
@@ -379,7 +404,10 @@ const OperationItem = builder
 const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   fields: (t) => ({
     openapi: t.string({ resolve: (root) => root.openapi }),
-    url: t.string({ resolve: (root) => root.servers?.at(0)?.url ?? "/" }),
+    url: t.string({
+      resolve: (root) => root.servers?.at(0)?.url,
+      nullable: true,
+    }),
     servers: t.field({
       type: [ServerItem],
       resolve: (root) => root.servers ?? [],
@@ -390,6 +418,10 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
       resolve: (root) => root.info.description,
       nullable: true,
     }),
+    summary: t.string({
+      resolve: (root) => root.info.summary,
+      nullable: true,
+    }),
     paths: t.field({
       type: [PathItem],
       resolve: (root) =>
@@ -403,8 +435,8 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         name: t.arg.string(),
       },
       type: [SchemaTag],
-      resolve: (root, args) => {
-        const tags = [...getAllTags(root), { name: "" }];
+      resolve: (root, args, ctx) => {
+        const tags = [...ctx.tags, { name: "" }];
         return args.name ? tags.filter((tag) => tag.name === args.name) : tags;
       },
     }),
@@ -415,31 +447,28 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         method: t.arg.string(),
         operationId: t.arg.string(),
         tag: t.arg.string(),
+        untagged: t.arg.boolean(),
       },
-      resolve: (parent, args) =>
-        getAllOperations(parent.paths).filter(
-          (item) =>
-            (!args.operationId || item.operationId === args.operationId) &&
-            (!args.path || item.path === args.path) &&
-            (!args.method || item.method === args.method) &&
-            (!args.tag || item.tags.includes(args.tag)),
-        ),
+      resolve: (parent, args, ctx) =>
+        ctx.operations.filter((op) => {
+          return (
+            (!args.operationId || op.operationId === args.operationId) &&
+            (!args.path || op.path === args.path) &&
+            (!args.method || op.method === args.method) &&
+            (!args.tag || op.tags?.some((tag) => args.tag?.includes(tag))) &&
+            (!args.untagged || (op.tags ?? []).length === 0)
+          );
+        }),
     }),
   }),
 });
 
-const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
-  const hash = hashit(input);
-  return await cache.forceFetch(hash, { context: input });
-};
-
 const SchemaSource = builder.enumType("SchemaType", {
   values: ["url", "file", "raw"] as const,
 });
 
 builder.queryType({
   fields: (t) => ({
-    // https://tan-cow-main-bce8a06.d2.zuplo.dev/openapi
     schema: t.field({
       type: Schema,
       args: {
@@ -447,9 +476,24 @@ builder.queryType({
         input: t.arg({ type: JSONScalar, required: true }),
       },
       resolve: async (_, args, ctx) => {
-        const schema = await loadOpenAPISchema(args.input!);
-        // for easier access of the whole schema in children resolvers
+        let schema: OpenAPIDocument;
+
+        if (args.type === "file" && typeof args.input === "string") {
+          const loadSchema = ctx.schemaImports?.[args.input];
+
+          if (!loadSchema) {
+            throw new Error(`No schema loader found for path: ${args.input}`);
+          }
+          const module = await loadSchema();
+          schema = module.schema;
+        } else {
+          schema = await validate(args.input as string);
+        }
+
         ctx.schema = schema;
+        ctx.operations = getAllOperations(schema.paths);
+        ctx.slugify = slugifyWithCounter();
+        ctx.tags = getAllTags(schema);
 
         return schema;
       },

package/src/lib/oas/parser/dereference/index.ts

@@ -1,4 +1,5 @@
 import type { JSONSchema4, JSONSchema6 } from "json-schema";
+import { CIRCULAR_REF } from "../../graphql/circular.js";
 import { resolveLocalRef } from "./resolveRef.js";
 
 export type JSONSchema = JSONSchema4 | JSONSchema6;
@@ -21,12 +22,12 @@ export const dereference = async (
   }
 
   const cloned = structuredClone(schema);
-  const visited = new Set();
+  const visited = new Set<unknown>();
 
   const resolve = async (current: unknown, path: string) => {
     if (isIndexableObject(current)) {
       if (visited.has(current)) {
-        return current;
+        return CIRCULAR_REF;
       }
 
       visited.add(current);
@@ -39,15 +40,18 @@ export const dereference = async (
         if ("$ref" in current && typeof current.$ref === "string") {
           for (const resolver of resolvers) {
             const resolved = await resolver(current.$ref);
-            if (resolved) return resolved;
+            if (resolved) return await resolve(resolved, path);
           }
-          return await resolveLocalRef(cloned, current.$ref);
+          const resolved = await resolveLocalRef(cloned, current.$ref);
+          return await resolve(resolved, path);
         }
 
         for (const key in current) {
           current[key] = await resolve(current[key], `${path}/${key}`);
         }
       }
+
+      visited.delete(current);
     }
 
     return current;

package/src/lib/oas/parser/upgrade/index.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { type RecordAny, traverse } from "../../../util/traverse.js";
 import type { OpenAPIDocument } from "../index.js";
 /**
  * Upgrade from OpenAPI 3.0.x to 3.1.0
@@ -6,30 +7,8 @@ import type { OpenAPIDocument } from "../index.js";
  * Taken from https://github.com/scalar/openapi-parser/blob/main/packages/openapi-parser/src/utils/upgradeFromThreeToThreeOne.ts
  * https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
  */
-export function traverse(
-  specification: Record<string, any>,
-  transform: (specification: Record<string, any>) => Record<string, any>,
-) {
-  const result: Record<string, any> = {};
 
-  for (const [key, value] of Object.entries(specification)) {
-    if (Array.isArray(value)) {
-      result[key] = value.map((item) =>
-        typeof item === "object" && item !== null
-          ? traverse(item, transform)
-          : item,
-      );
-    } else if (typeof value === "object" && value !== null) {
-      result[key] = traverse(value, transform);
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return transform(result);
-}
-
-export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
+export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
   if (schema.openapi?.startsWith("3.0")) {
     schema.openapi = "3.1.0";
   }
@@ -63,19 +42,34 @@ export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
 
   schema = traverse(schema, (sub) => {
     if (sub.example !== undefined) {
-      sub.examples = {
-        default: sub.example,
-      };
+      const isExampleObject =
+        typeof sub.example === "object" &&
+        (sub.example.summary !== undefined ||
+          sub.example.description !== undefined ||
+          sub.example.value !== undefined ||
+          sub.example.externalValue !== undefined);
+
+      const exampleValue = isExampleObject
+        ? sub.example
+        : { value: sub.example };
+
+      if (!sub.examples) {
+        sub.examples = { default: exampleValue };
+      } else {
+        sub.examples = {
+          default: exampleValue,
+          ...sub.examples,
+        };
+      }
       delete sub.example;
     }
-
     return sub;
   });
 
   schema = traverse(schema, (sub) => {
     if (sub.type === "object" && sub.properties !== undefined) {
       for (const [, value] of Object.entries(sub.properties)) {
-        const v = (value ?? {}) as Record<string, any>;
+        const v = (value ?? {}) as RecordAny;
         if (v.type === "string" && v.format === "binary") {
           v.contentEncoding = "application/octet-stream";
           delete v.format;

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -0,0 +1,123 @@
+import slugify from "@sindresorhus/slugify";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { useSearchParams } from "react-router";
+import { Head, Link } from "zudoku/components";
+import { useAuthState } from "../../authentication/state.js";
+import { Markdown } from "../../components/Markdown.js";
+import { cn } from "../../util/cn.js";
+import type { ApiCatalogPluginOptions } from "./index.js";
+
+const getKey = (category: string, tag: string) => slugify(`${category}-${tag}`);
+
+export const Catalog = ({
+  items,
+  filterCatalogItems = (items) => items,
+  categories,
+  label = "API Library",
+}: Omit<ApiCatalogPluginOptions, "navigationId">) => {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const activeCategory = searchParams.get("category");
+  const auth = useAuthState();
+
+  const catalogItems = useSuspenseQuery({
+    queryFn: () => filterCatalogItems(items, { auth }),
+    queryKey: ["catalogItems", auth],
+  });
+
+  return (
+    <section className="pt-[--padding-content-top] pb-[--padding-content-bottom]">
+      <Head>
+        <title>{label}</title>
+      </Head>
+      <div className="grid grid-cols-12 gap-12">
+        <div className="flex flex-col gap-4 col-span-3 not-prose sticky top-48">
+          <div className="max-w-[--side-nav-width] flex flex-col gap-4 justify-between">
+            {categories?.map((category, idx) => (
+              <div key={category.label}>
+                <div className="flex justify-between mb-2.5">
+                  <span className="font-medium text-sm">{category.label}</span>
+                  {idx === 0 && activeCategory && (
+                    <button
+                      type="button"
+                      className="text-end text-sm text-foreground/60 hover:text-foreground"
+                      onClick={() => setSearchParams({})}
+                    >
+                      Clear
+                    </button>
+                  )}
+                </div>
+                <ul className="space-y-1 [&>li]:py-2">
+                  {category.tags
+                    .map((tag) => ({
+                      tag,
+                      count: items.filter((api) =>
+                        api.categories.find((c) => c.tags.includes(tag)),
+                      ).length,
+                    }))
+                    .map(({ tag, count }) => {
+                      const slug = getKey(category.label, tag);
+                      const isActive = slug === activeCategory;
+
+                      return (
+                        <li
+                          key={slug}
+                          className={cn(
+                            "flex rounded-lg justify-between text-sm cursor-pointer hover:text-primary transition px-[--padding-nav-item] -mx-[--padding-nav-item]",
+                            isActive && "bg-border/30 rounded",
+                          )}
+                          onClick={() => setSearchParams({ category: slug })}
+                        >
+                          <span>{tag}</span>
+                          <span
+                            className={cn(
+                              "flex items-center justify-center border rounded-md w-8 text-xs font-semibold",
+                              isActive &&
+                                "bg-primary border-primary text-primary-foreground",
+                            )}
+                          >
+                            {count}
+                          </span>
+                        </li>
+                      );
+                    })}
+                </ul>
+              </div>
+            ))}
+          </div>
+        </div>
+        <div className="col-span-9">
+          <h3 className="mt-0 text-2xl font-bold mb-4">{label}</h3>
+
+          <div className="grid grid-cols-2 gap-4">
+            {catalogItems.data
+              .filter(
+                (api) =>
+                  !activeCategory ||
+                  api.categories.find((c) =>
+                    c.tags.find((t) => getKey(c.label, t) === activeCategory),
+                  ),
+              )
+              .map((api) => (
+                <Link
+                  to={{
+                    pathname: `/${api.path}`,
+                    search: activeCategory ? `category=${activeCategory}` : "",
+                  }}
+                  className="no-underline hover:!text-foreground"
+                  key={api.path}
+                >
+                  <div className="border h-full rounded p-4 flex flex-col gap-2 cursor-pointer hover:bg-border/20 font-normal">
+                    <span className="font-semibold">{api.label}</span>
+                    <Markdown
+                      className="text-sm whitespace-pre-wrap mb-6 line-clamp-2"
+                      content={api.description}
+                    />
+                  </div>
+                </Link>
+              ))}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};