zudoku 0.0.0-e5be921 → 0.0.0-e614aaa

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,
@@ -46,60 +45,71 @@ export const createOperationSlug = (
   tag?: string,
 ) => {
   const summary =
-    (operation.summary ?? "") +
-    (operation.operationId
-      ? "-" +
-        operation.operationId.slice(0, operation.summary ? Infinity : Infinity)
-      : "");
-
-  return slugify(
-    (tag ? tag + "-" : "") +
-      (summary || `${operation.method}-${operation.path}`),
-  );
+    operation.summary ||
+    operation.operationId ||
+    `${operation.method}-${operation.path}`;
+  const prefix = tag ? `${tag}-` : "";
+
+  return slugify(prefix + summary);
 };
 
-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<{
+  DefaultFieldNullability: false;
   Scalars: {
     JSON: any;
     JSONObject: any;
+    JSONSchema: any;
   };
   Context: {
     schema: OpenAPIDocument;
+    operations: GraphQLOperationObject[];
+    tags: TagObject[];
+    schemaImports?: SchemaImports;
+    currentTag?: string;
+    slugify: CountableSlugify;
   };
-}>({});
+}>({
+  defaultFieldNullability: false,
+});
+
+type GraphQLOperationObject = OperationObject & {
+  path: string;
+  method: string;
+  slug?: string;
+  parentTag?: string;
+};
 
 const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
-
-const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
-  const tags = schema.tags ?? [];
-
-  // Extract tags from operations
-  const operationTags = Object.values(schema.paths ?? {})
-    .flatMap((path) => Object.values(path ?? {}))
-    .flatMap((operation) =>
-      typeof operation === "object" && "tags" in operation
-        ? (operation.tags ?? [])
-        : [],
-    );
-
-  // Remove duplicates and tags that appear in the schema
-  const uniqueOperationTags = [...new Set(operationTags)].filter(
-    (tag) => !tags.some((rootTag) => rootTag.name === tag),
+const JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
+
+export const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
+  const rootTags = schema.tags ?? [];
+  const operationTags = new Set(
+    Object.values(schema.paths ?? {})
+      .flatMap((path) => Object.values(path ?? {}))
+      .flatMap((op) => (op as OperationObject).tags ?? []),
   );
-  return [...tags, ...uniqueOperationTags.map((tag) => ({ name: tag }))];
-};
 
-const getAllOperations = (paths?: PathsObject, tag?: string) => {
-  const slugify = slugifyWithCounter();
+  return [
+    // Keep root tags that are actually used in operations
+    ...rootTags.filter((tag) => operationTags.has(tag.name)),
+    // Add tags found in operations but not defined in root tags
+    ...[...operationTags]
+      .filter((tag) => !rootTags.some((rt) => rt.name === tag))
+      .map((tag) => ({ name: tag })),
+  ];
+};
 
-  return Object.entries(paths ?? {}).flatMap(([path, value]) =>
+export const getAllOperations = (
+  paths?: PathsObject,
+): GraphQLOperationObject[] => {
+  const operations = Object.entries(paths ?? {}).flatMap(([path, value]) =>
     HttpMethods.flatMap((method) => {
       if (!value?.[method]) return [];
 
@@ -120,41 +130,39 @@ 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),
-      };
+      } satisfies GraphQLOperationObject;
     }),
   );
+
+  return operations;
 };
 
 const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
   fields: (t) => ({
-    name: t.exposeString("name", { nullable: true }),
+    name: t.exposeString("name"),
     description: t.exposeString("description", { nullable: true }),
     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,
+          }));
       },
     }),
   }),
@@ -240,7 +248,7 @@ const ParameterItem = builder
           })),
         nullable: true,
       }),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
     }),
   });
 
@@ -254,7 +262,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 +310,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 +349,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 }),
               ),
@@ -351,9 +374,12 @@ const OperationItem = builder
                 ([mediaType, { schema, examples }]) => ({
                   mediaType,
                   schema,
-                  examples: Object.entries(examples ?? {}).map(
-                    ([name, value]) => ({ name, ...value }),
-                  ),
+                  examples: examples
+                    ? Object.entries(examples).map(([name, value]) => ({
+                        name,
+                        ...(typeof value === "string" ? { value } : value),
+                      }))
+                    : [],
                 }),
               ),
               headers: response.headers,
@@ -379,7 +405,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 ?? [],
@@ -407,9 +436,10 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         name: t.arg.string(),
       },
       type: [SchemaTag],
-      resolve: (root, args) => {
-        const tags = [...getAllTags(root), { name: "" }];
-        return args.name ? tags.filter((tag) => tag.name === args.name) : tags;
+      resolve: (root, args, ctx) => {
+        return args.name
+          ? ctx.tags.filter((tag) => tag.name === args.name)
+          : ctx.tags;
       },
     }),
     operations: t.field({
@@ -419,24 +449,22 @@ 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,
 });
@@ -450,9 +478,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

@@ -41,13 +41,29 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
   });
 
   schema = traverse(schema, (sub) => {
-    if (sub.example !== undefined) {
-      sub.examples = {
-        default: sub.example,
-      };
+    // may be null or undefined
+    if (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;
   });
 

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

@@ -1,122 +1,74 @@
-import slugify from "@sindresorhus/slugify";
-import { Fragment } from "react";
-import { Head, Link } from "zudoku/components";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { useMatch } from "react-router";
+import { Link } from "zudoku/components";
+import { useAuthState } from "../../authentication/state.js";
+import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
-import { useExposedProps } from "../../util/useExposedProps.js";
-import type { ApiCatalogItem, CatalogCategory } from "./index.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { type ApiCatalogPluginOptions, getKey } from "./index.js";
 
 export const Catalog = ({
   items,
-  categories,
+  filterCatalogItems = (items) => items,
   label = "API Library",
-}: {
-  label: string;
-  items: ApiCatalogItem[];
-  categories: CatalogCategory[];
+  categoryLabel,
+}: Omit<ApiCatalogPluginOptions, "navigationId"> & {
+  categoryLabel?: string;
 }) => {
-  const { searchParams, setSearchParams } = useExposedProps();
-  const activeCategory = searchParams.get("category");
+  const auth = useAuthState();
+  const match = useMatch({ path: "/catalog/:category" });
+  const activeCategory = match?.params.category;
+
+  const catalogItems = useSuspenseQuery({
+    queryFn: () => filterCatalogItems(items, { auth }),
+    queryKey: ["catalogItems", auth],
+  });
+
+  // Only index the overview page, ignore the rest
+  const dataSet = activeCategory ? { "data-pagefind-ignore": "all" } : {};
+
   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 px-4 not-prose sticky top-48">
-          <div className="justify-between">
-            {categories.map((category, idx) => (
-              <Fragment 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 mr-8 text-foreground/60 hover:text-foreground"
-                      onClick={() => setSearchParams({})}
-                    >
-                      Clear
-                    </button>
-                  )}
+    <section
+      className="pt-[--padding-content-top] pb-[--padding-content-bottom]"
+      {...dataSet}
+    >
+      <Helmet>
+        <title>
+          {categoryLabel ? `${categoryLabel} - ` : ""}
+          {label}
+        </title>
+      </Helmet>
+      <div className="grid gap-4">
+        <Heading level={2}>
+          {label}
+          {categoryLabel && ` - ${categoryLabel}`}
+        </Heading>
+
+        <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={joinUrl(api.path)}
+                className="no-underline hover:!text-foreground"
+                key={api.path}
+              >
+                <div className="border h-full rounded-lg 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>
-                <ul className="space-y-1 [&>li]:py-2">
-                  {Array.from(
-                    new Set(
-                      category.tags
-                        .map((tag) => ({
-                          tag,
-                          count: items.filter((api) =>
-                            api.categories.find((c) => c.tags.includes(tag)),
-                          ).length,
-                        }))
-                        .map(({ tag, count }) => (
-                          <li
-                            key={slugify(category.label + " " + tag)}
-                            className={`flex px-4 rounded-lg -translate-x-4 justify-between text-sm cursor-pointer hover:text-primary transition ${
-                              slugify(tag) === activeCategory
-                                ? "font-medium bg-border/30 rounded"
-                                : ""
-                            }`}
-                            onClick={() =>
-                              setSearchParams({
-                                category: slugify(category.label + " " + tag),
-                              })
-                            }
-                          >
-                            <span>{tag}</span>
-                            <span
-                              className={`flex items-center justify-center border rounded-md w-8 text-xs font-semibold ${
-                                slugify(tag) === activeCategory
-                                  ? "bg-primary border-primary text-primary-foreground"
-                                  : ""
-                              }`}
-                            >
-                              {count}
-                            </span>
-                          </li>
-                        )),
-                    ),
-                  )}
-                </ul>
-              </Fragment>
+              </Link>
             ))}
-          </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">
-            {items
-              .filter(
-                (api) =>
-                  !activeCategory ||
-                  api.categories.find((c) =>
-                    c.tags.find(
-                      (t) => slugify(c.label + " " + t) === activeCategory,
-                    ),
-                  ),
-              )
-              .map((api, i) => (
-                <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"
-                    key={i}
-                  >
-                    <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>