zudoku 0.0.0-eff6f9b → 0.0.0-f06d326

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,22 +1,25 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import SchemaBuilder from "@pothos/core";
+import {
+  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 slugify from "../../util/slugify.js";
 import {
-  HttpMethods,
-  validate,
   type EncodingObject,
   type ExampleObject,
+  HttpMethods,
   type OpenAPIDocument,
   type OperationObject,
   type ParameterObject,
   type PathsObject,
   type SchemaObject,
+  type ServerObject,
   type TagObject,
+  validate,
 } from "../parser/index.js";
+import { GraphQLJSONSchema } from "./circular.js";
 
 export type {
   EncodingObject,
@@ -35,60 +38,124 @@ type OperationLike = {
   path: string;
   method: string;
 };
-export const slugifyOperation = (operation: OperationLike, tag?: string) => {
+
+export const createOperationSlug = (
+  slugify: CountableSlugify,
+  operation: OperationLike,
+) => {
   const summary =
-    (operation.summary ?? "") +
-    (operation.operationId
-      ? "-" +
-        operation.operationId.slice(0, operation.summary ? Infinity : Infinity)
-      : "");
-
-  return slugify(
-    (tag ? tag + "-" : "") +
-      (summary || `${operation.method}-${operation.path}`),
-    { lower: true, trim: true },
-  );
+    operation.summary ||
+    operation.operationId ||
+    `${operation.method}-${operation.path}`;
+
+  return slugify(summary);
 };
 
-const cache = new LRUCache<string, Promise<OpenAPIDocument>>({
-  ttl: 60 * 10 * 1000,
-  ttlAutopurge: true,
-});
+export type SchemaImport = () => Promise<{
+  schema: OpenAPIDocument;
+  slugs: ReturnType<typeof getAllSlugs>;
+}>;
+
+export type SchemaImports = Record<string, SchemaImport>;
+
+type Context = {
+  schema: OpenAPIDocument;
+  operations: GraphQLOperationObject[];
+  schemaImports?: SchemaImports;
+  tags: ReturnType<typeof getAllTags>;
+  slugs: ReturnType<typeof getAllSlugs>;
+};
 
 const builder = new SchemaBuilder<{
+  DefaultFieldNullability: false;
   Scalars: {
     JSON: any;
     JSONObject: any;
+    JSONSchema: any;
   };
-  Context: {
-    schema: OpenAPIDocument;
-  };
-}>({});
+  Context: Context;
+}>({
+  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 JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
+
+const resolveExtensions = (obj: Record<string, any>) =>
+  Object.fromEntries(
+    Object.entries(obj).filter(([key]) => key.startsWith("x-")),
+  );
 
-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),
+export const getAllTags = (
+  schema: OpenAPIDocument,
+  slugs: ReturnType<typeof getAllSlugs>["tags"],
+): Array<Omit<TagObject, "name"> & { name?: string; slug?: string }> => {
+  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 hasUntaggedOperations = Object.values(schema.paths ?? {}).some((path) =>
+    Object.values(path ?? {}).some(
+      (op) => !(op as OperationObject).tags?.length,
+    ),
+  );
+
+  return [
+    // Keep root tags that are actually used in operations
+    ...rootTags
+      .filter((tag) => operationTags.has(tag.name))
+      .map((tag) => ({ ...tag, slug: slugs[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, slug: slugs[tag] })),
+    // Add untagged operations if there are any
+    ...(hasUntaggedOperations ? [{ name: undefined, slug: undefined }] : []),
+  ];
 };
 
-const getAllOperations = (paths?: PathsObject, tag?: string) => {
-  return Object.entries(paths ?? {}).flatMap(([path, value]) =>
+export const getAllSlugs = (
+  ops: GraphQLOperationObject[],
+  schemaTags: TagObject[] = [],
+) => {
+  const slugify = slugifyWithCounter();
+
+  const tags = Array.from(
+    new Set([
+      ...ops.flatMap((op) => op.tags ?? []),
+      ...schemaTags.map((tag) => tag.name),
+    ]),
+  );
+
+  return {
+    operations: Object.fromEntries(
+      ops.map((op) => [
+        getOperationSlugKey(op),
+        createOperationSlug(slugify, op),
+      ]),
+    ),
+    tags: Object.fromEntries(tags.map((tag) => [tag, slugify(tag)])),
+  };
+};
+
+const getOperationSlugKey = (op: GraphQLOperationObject) =>
+  [op.path, op.method, op.operationId, op.summary].filter(Boolean).join("-");
+
+export const getAllOperations = (
+  paths?: PathsObject,
+): GraphQLOperationObject[] => {
+  const operations = Object.entries(paths ?? {}).flatMap(([path, value]) =>
     HttpMethods.flatMap((method) => {
       if (!value?.[method]) return [];
 
@@ -115,38 +182,67 @@ const getAllOperations = (paths?: PathsObject, tag?: string) => {
         path,
         parameters,
         tags: operation.tags ?? [],
-        slug: slugifyOperation(
-          {
-            summary: operation.summary,
-            operationId: operation.operationId,
-            path,
-            method,
-          },
-          tag,
-        ),
-      };
+      } satisfies GraphQLOperationObject;
     }),
   );
+
+  return operations;
 };
 
-const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
+const SchemaTag = builder.objectRef<
+  Omit<TagObject, "name"> & { name?: string; slug?: string }
+>("SchemaTag");
+
+SchemaTag.implement({
   fields: (t) => ({
     name: t.exposeString("name", { nullable: true }),
+    slug: t.exposeString("slug", { nullable: true }),
+    isUntagged: t.field({ type: "Boolean", resolve: (parent) => !parent.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 }));
       },
     }),
+    prev: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index - 1];
+      },
+    }),
+    next: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index + 1];
+      },
+    }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
+  }),
+});
+
+const ServerItem = builder.objectRef<ServerObject>("Server").implement({
+  fields: (t) => ({
+    url: t.exposeString("url"),
+    description: t.exposeString("description", { nullable: true }),
   }),
 });
 
@@ -166,6 +262,11 @@ const TagItem = builder.objectRef<TagObject>("TagItem").implement({
   fields: (t) => ({
     name: t.exposeString("name"),
     description: t.exposeString("description", { nullable: true }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
   }),
 });
 
@@ -189,7 +290,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 }),
     }),
   });
@@ -223,7 +324,12 @@ const ParameterItem = builder
           })),
         nullable: true,
       }),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
@@ -237,7 +343,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 }),
     }),
@@ -281,16 +387,31 @@ const ResponseItem = builder
       content: t.expose("content", { type: [MediaTypeItem], nullable: true }),
       headers: t.expose("headers", { type: JSONScalar, nullable: true }),
       links: t.expose("links", { type: JSONScalar, nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
 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 slug = ctx.slugs.operations[getOperationSlugKey(parent)];
+
+          if (!slug) {
+            throw new Error(
+              `No slug found for operation: ${getOperationSlugKey(parent)}`,
+            );
+          }
+          return slug;
+        },
+      }),
       path: t.exposeString("path"),
       method: t.exposeString("method"),
       operationId: t.exposeString("operationId", { nullable: true }),
@@ -312,9 +433,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 }),
               ),
@@ -331,12 +455,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,
@@ -356,19 +483,72 @@ const OperationItem = builder
         nullable: true,
       }),
       deprecated: t.exposeBoolean("deprecated", { nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
+const SchemaItem = builder
+  .objectRef<{
+    name: string;
+    schema: SchemaObject;
+    extensions?: Record<string, any>;
+  }>("SchemaItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      schema: t.expose("schema", { type: JSONSchemaScalar }),
+      extensions: t.expose("extensions", {
+        type: JSONObjectScalar,
+        nullable: true,
+      }),
+    }),
+  });
+
+const Components = builder.objectRef<{
+  schemas?: Record<string, SchemaObject>;
+}>("Components");
+
+Components.implement({
+  fields: (t) => ({
+    schemas: t.field({
+      type: [SchemaItem],
+      resolve: (parent) => {
+        return Object.entries(parent.schemas ?? {}).map(([name, schema]) => ({
+          name,
+          schema,
+          extensions: resolveExtensions(schema),
+        }));
+      },
+      nullable: true,
+    }),
+  }),
+});
+
 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 ?? [],
+    }),
     title: t.string({ resolve: (root) => root.info.title }),
     version: t.string({ resolve: (root) => root.info.version }),
     description: t.string({
       resolve: (root) => root.info.description,
       nullable: true,
     }),
+    summary: t.string({
+      resolve: (root) => root.info.summary,
+      nullable: true,
+    }),
     paths: t.field({
       type: [PathItem],
       resolve: (root) =>
@@ -377,16 +557,30 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           methods: Object.keys(value!) as typeof HttpMethods,
         })),
     }),
-    tags: t.field({
+    tag: t.field({
+      type: SchemaTag,
       args: {
+        slug: t.arg.string(),
         name: t.arg.string(),
+        untagged: t.arg.boolean(),
       },
-      type: [SchemaTag],
-      resolve: (root, args) => {
-        const tags = [...getAllTags(root), { name: "" }];
-        return args.name ? tags.filter((tag) => tag.name === args.name) : tags;
+      nullable: true,
+      resolve: (_, args, ctx) => {
+        if (args.untagged) {
+          return ctx.tags.find((tag) => tag.name === undefined);
+        }
+        if (args.slug) {
+          return ctx.tags.find((tag) => tag.slug === args.slug);
+        }
+        if (args.name) {
+          return ctx.tags.find((tag) => tag.name === args.name);
+        }
       },
     }),
+    tags: t.field({
+      type: [SchemaTag],
+      resolve: (_root, _args, ctx) => ctx.tags,
+    }),
     operations: t.field({
       type: [OperationItem],
       args: {
@@ -394,52 +588,64 @@ 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)
+          );
+        }),
+    }),
+    components: t.field({
+      type: Components,
+      resolve: (root) => root.components,
+      nullable: true,
+    }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (root) => resolveExtensions(root),
+      nullable: true,
     }),
   }),
 });
 
-const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
-  const hash = hashit(input);
-
-  if (cache.has(hash)) {
-    return cache.get(hash)!;
-  }
-
-  const schema = validate(input);
-
-  cache.set(hash, schema);
-
-  return schema;
-};
-
 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: {
         type: t.arg({ type: SchemaSource, required: true }),
         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
-        ctx.schema = schema;
-
-        return schema;
+      resolve: async (_parent, args, ctx) => {
+        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 { schema, slugs } = await loadSchema();
+          ctx.schema = schema;
+          ctx.operations = getAllOperations(schema.paths);
+          ctx.slugs = slugs;
+          ctx.tags = getAllTags(schema, ctx.slugs.tags);
+        } else {
+          ctx.schema = await validate(args.input as string);
+          ctx.operations = getAllOperations(ctx.schema.paths);
+          ctx.slugs = getAllSlugs(ctx.operations);
+          ctx.tags = getAllTags(ctx.schema, ctx.slugs.tags);
+        }
+
+        return ctx.schema;
       },
     }),
   }),
@@ -449,4 +655,4 @@ export const schema = builder.toSchema();
 
 export const createGraphQLServer = (
   options?: Omit<YogaServerOptions<any, any>, "schema">,
-) => createYoga({ schema, ...options });
+) => createYoga({ schema, batching: true, ...options });