zudoku 0.0.2-dev.0

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

@@ -0,0 +1,422 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import SchemaBuilder from "@pothos/core";
+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,
+  type OpenAPIDocument,
+  type OperationObject,
+  type ParameterObject,
+  type PathsObject,
+  type SchemaObject,
+  type TagObject,
+} from "../parser/index.js";
+
+export type {
+  EncodingObject,
+  ExampleObject,
+  OpenAPIDocument,
+  OperationObject,
+  ParameterObject,
+  PathsObject,
+  SchemaObject,
+  TagObject,
+};
+
+type OperationLike = {
+  summary?: string | null;
+  operationId?: string | null;
+  path: string;
+  method: string;
+};
+export const slugifyOperation = (operation: OperationLike, tag?: string) => {
+  return slugify(
+    (tag ? tag + "-" : "") +
+      (operation.summary ??
+        operation.operationId ??
+        `${operation.method}-${operation.path}`),
+    { lower: true, trim: true },
+  );
+};
+
+const cache = new LRUCache<string, OpenAPIDocument>({
+  ttl: 60 * 10 * 1000,
+  ttlAutopurge: true,
+});
+
+const builder = new SchemaBuilder<{
+  Scalars: {
+    JSON: any;
+    JSONObject: any;
+  };
+  Context: {
+    schema: OpenAPIDocument;
+  };
+}>({});
+
+const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
+const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
+
+const getAllOperations = (paths?: PathsObject, tag?: string) => {
+  return Object.entries(paths ?? {}).flatMap(([path, value]) =>
+    HttpMethods.flatMap((method) => {
+      if (!value?.[method]) return [];
+
+      const operation = value[method] as OperationObject;
+      const pathParameters = value?.parameters ?? [];
+      const operationParameters = operation.parameters ?? [];
+
+      // parameters are inherited from the parent path object,
+      // but can be overridden by their `name` and `in` location
+      const parameters = [
+        ...pathParameters.filter(
+          // remove path parameters that are already defined in the operation
+          (pp) =>
+            !operationParameters.some(
+              (op) => op.name === pp.name && op.in === pp.in,
+            ),
+        ),
+        ...operationParameters,
+      ];
+
+      return {
+        ...operation,
+        method,
+        path,
+        parameters,
+        slug: slugifyOperation(
+          {
+            summary: operation.summary,
+            operationId: operation.operationId,
+            path,
+            method,
+          },
+          tag,
+        ),
+      };
+    }),
+  );
+};
+
+const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
+  fields: (t) => ({
+    name: t.exposeString("name", { nullable: true }),
+    description: t.exposeString("description", { nullable: true }),
+    operations: t.field({
+      type: [OperationItem],
+      resolve: (parent, _args, ctx) =>
+        getAllOperations(ctx.schema.paths, parent.name).filter((item) =>
+          parent.name
+            ? item.tags?.includes(parent.name)
+            : !item.tags || item.tags.length === 0,
+        ),
+    }),
+  }),
+});
+
+const PathItem = builder
+  .objectRef<{
+    path: string;
+    methods: typeof HttpMethods;
+  }>("PathItem")
+  .implement({
+    fields: (t) => ({
+      path: t.exposeString("path"),
+      methods: t.exposeStringList("methods"),
+    }),
+  });
+
+const TagItem = builder.objectRef<TagObject>("TagItem").implement({
+  fields: (t) => ({
+    name: t.exposeString("name"),
+    description: t.exposeString("description", { nullable: true }),
+  }),
+});
+
+const EncodingItem = builder
+  .objectRef<EncodingObject & { name: string }>("EncodingItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      contentType: t.exposeString("contentType", { nullable: true }),
+      headers: t.expose("headers", { type: JSONObjectScalar, nullable: true }),
+      style: t.exposeString("style", { nullable: true }),
+      explode: t.exposeBoolean("explode", { nullable: true }),
+      allowReserved: t.exposeBoolean("allowReserved", { nullable: true }),
+    }),
+  });
+
+const ExampleItem = builder
+  .objectRef<ExampleObject & { name: string }>("ExampleItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      summary: t.exposeString("summary", { nullable: true }),
+      description: t.exposeString("description", { nullable: true }),
+      value: t.exposeString("value", { nullable: true }),
+      externalValue: t.exposeString("externalValue", { nullable: true }),
+    }),
+  });
+
+const ParameterIn = builder.enumType("ParameterIn", {
+  values: ["query", "header", "path", "cookie"] as const,
+});
+
+const ParameterItem = builder
+  .objectRef<ParameterObject>("ParameterItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      in: t.field({
+        type: ParameterIn,
+        resolve: (parent) => parent.in as typeof ParameterIn.$inferType,
+      }),
+      description: t.exposeString("description", { nullable: true }),
+      required: t.exposeBoolean("required", { nullable: true }),
+      deprecated: t.exposeBoolean("deprecated", { nullable: true }),
+      allowEmptyValue: t.exposeBoolean("allowEmptyValue", { nullable: true }),
+      style: t.exposeString("style", { nullable: true }),
+      explode: t.exposeBoolean("explode", { nullable: true }),
+      allowReserved: t.exposeBoolean("allowReserved", { nullable: true }),
+      examples: t.field({
+        type: [ExampleItem],
+        resolve: (parent) =>
+          Object.entries(parent.examples ?? {}).map(([name, value]) => ({
+            name,
+            ...value,
+          })),
+        nullable: true,
+      }),
+      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+    }),
+  });
+
+const MediaTypeItem = builder
+  .objectRef<{
+    mediaType: string;
+    schema: any;
+    examples: Array<ExampleObject & { name: string }>;
+    encoding?: Array<EncodingObject & { name: string }>;
+  }>("MediaTypeObject")
+  .implement({
+    fields: (t) => ({
+      mediaType: t.exposeString("mediaType"),
+      schema: t.expose("schema", { type: JSONScalar }),
+      examples: t.expose("examples", { type: [ExampleItem], nullable: true }),
+      encoding: t.expose("encoding", { type: [EncodingItem], nullable: true }),
+    }),
+  });
+
+const RequestBodyObject = builder
+  .objectRef<{
+    description?: string;
+    required?: boolean;
+    content: Array<{
+      mediaType: string;
+      schema: any;
+      examples: Array<ExampleObject & { name: string }>;
+      encoding?: Array<EncodingObject & { name: string }>;
+    }>;
+  }>("RequestBodyObject")
+  .implement({
+    fields: (t) => ({
+      description: t.exposeString("description", { nullable: true }),
+      content: t.expose("content", { type: [MediaTypeItem], nullable: true }),
+      required: t.exposeBoolean("required", { nullable: true }),
+    }),
+  });
+
+const ResponseItem = builder
+  .objectRef<{
+    statusCode: string;
+    description: string;
+    content: Array<{
+      mediaType: string;
+      schema: any;
+      examples: Array<ExampleObject & { name: string }>;
+    }>;
+    headers?: any;
+    links?: any;
+  }>("ResponseItem")
+  .implement({
+    fields: (t) => ({
+      statusCode: t.exposeString("statusCode"),
+      description: t.exposeString("description"),
+      content: t.expose("content", { type: [MediaTypeItem], nullable: true }),
+      headers: t.expose("headers", { type: JSONScalar, nullable: true }),
+      links: t.expose("links", { type: JSONScalar, nullable: true }),
+    }),
+  });
+
+const OperationItem = builder
+  .objectRef<
+    OperationObject & { path: string; method: string; slug: string }
+  >("OperationItem")
+  .implement({
+    fields: (t) => ({
+      slug: t.exposeString("slug"),
+      path: t.exposeString("path"),
+      method: t.exposeString("method"),
+      operationId: t.exposeString("operationId", { nullable: true }),
+      summary: t.exposeString("summary", { nullable: true }),
+      description: t.exposeString("description", { nullable: true }),
+      contentTypes: t.stringList({
+        resolve: (parent) => Object.keys(parent.requestBody?.content ?? {}),
+      }),
+      parameters: t.expose("parameters", {
+        type: [ParameterItem],
+        nullable: true,
+      }),
+      requestBody: t.field({
+        type: RequestBodyObject,
+        resolve: (parent) => ({
+          description: parent.requestBody?.description,
+          required: parent.requestBody?.required,
+          content: Object.entries(parent.requestBody?.content ?? {}).map(
+            ([mediaType, content]) => ({
+              mediaType,
+              schema: content.schema,
+              examples: Object.entries(content.examples ?? {}).map(
+                ([name, value]) => ({ name, ...value }),
+              ),
+              encoding: Object.entries(content.encoding ?? {}).map(
+                ([name, value]) => ({ name, ...value }),
+              ),
+            }),
+          ),
+        }),
+        nullable: true,
+      }),
+      responses: t.field({
+        type: [ResponseItem],
+        resolve: (parent) => {
+          return Object.entries(parent.responses ?? {}).map(
+            ([statusCode, response]) => ({
+              statusCode,
+              description: response.description,
+              content: Object.entries(response.content ?? {}).map(
+                ([mediaType, mediaTypeObject]) => ({
+                  mediaType,
+                  schema: mediaTypeObject.schema,
+                  examples: Object.entries(mediaTypeObject.examples ?? {}).map(
+                    ([name, value]) => ({ name, ...value }),
+                  ),
+                }),
+              ),
+              headers: response.headers,
+              links: response.links,
+            }),
+          );
+        },
+      }),
+      tags: t.field({
+        type: [TagItem],
+        resolve: (parent, _, ctx) =>
+          parent.tags?.map((tag) => ({
+            name: tag,
+            description: ctx.schema.tags?.find((t) => t.name === tag)
+              ?.description,
+          })),
+        nullable: true,
+      }),
+      deprecated: t.exposeBoolean("deprecated", { 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 ?? "/" }),
+    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,
+    }),
+    paths: t.field({
+      type: [PathItem],
+      resolve: (root) =>
+        Object.entries(root.paths ?? {}).map(([path, value]) => ({
+          path,
+          methods: Object.keys(value!) as typeof HttpMethods,
+        })),
+    }),
+    tags: t.field({
+      args: {
+        name: t.arg.string(),
+      },
+      type: [SchemaTag],
+      resolve: (root, args) =>
+        [...(root.tags ?? []), { name: "" }].filter(
+          (tag) => !args.name || args.name === tag.name,
+        ),
+    }),
+    operations: t.field({
+      type: [OperationItem],
+      args: {
+        path: t.arg.string(),
+        method: t.arg.string(),
+        operationId: t.arg.string(),
+        tag: t.arg.string(),
+      },
+      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)),
+        ),
+    }),
+  }),
+});
+
+const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
+  const hash = hashit(input);
+
+  if (cache.has(hash)) {
+    return cache.get(hash)!;
+  }
+
+  const schema = await validate(input);
+
+  cache.set(hash, schema);
+
+  return schema;
+};
+
+const SchemaSource = builder.enumType("SchemaType", {
+  values: ["url", "json", "yaml"] 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;
+      },
+    }),
+  }),
+});
+
+export const schema = builder.toSchema();
+
+export const createGraphQLServer = (
+  options?: Omit<YogaServerOptions<any, any>, "schema">,
+) => createYoga({ schema, ...options });

package/src/app/oas/graphql/server.ts

@@ -0,0 +1,10 @@
+import { createServer } from "node:http";
+import { createGraphQLServer } from "./index.js";
+
+const yoga = createGraphQLServer();
+
+const server = createServer(yoga);
+
+server.listen(4000, () => {
+  console.log(`🚀 Server ready at  http://localhost:4000/graphql`);
+});

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

@@ -0,0 +1,59 @@
+import type { JSONSchema4, JSONSchema6 } from "json-schema";
+import { resolveLocalRef } from "./resolveRef.js";
+
+export type JSONSchema = JSONSchema4 | JSONSchema6;
+
+type CustomResolver = (ref: string) => Promise<JSONSchema | undefined>;
+
+const cache = new Map<JSONSchema, JSONSchema>();
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const isIndexableObject = (obj: any): obj is Record<string, any> =>
+  obj !== null && typeof obj === "object";
+
+// Taken and inspired from `dereference-json-schema` package.
+export const dereference = async (
+  schema: JSONSchema,
+  resolvers: CustomResolver[] = [],
+) => {
+  if (cache.has(schema)) {
+    return cache.get(schema)!;
+  }
+
+  const cloned = structuredClone(schema);
+  const visited = new Set();
+
+  const resolve = async (current: unknown, path: string) => {
+    if (isIndexableObject(current)) {
+      if (visited.has(current)) {
+        return current;
+      }
+
+      visited.add(current);
+
+      if (Array.isArray(current)) {
+        for (let index = 0; index < current.length; index++) {
+          current[index] = await resolve(current[index], `${path}/${index}`);
+        }
+      } else {
+        if ("$ref" in current && typeof current.$ref === "string") {
+          for (const resolver of resolvers) {
+            const resolved = await resolver(current.$ref);
+            if (resolved) return resolved;
+          }
+          return await resolveLocalRef(cloned, current.$ref);
+        }
+
+        for (const key in current) {
+          current[key] = await resolve(current[key], `${path}/${key}`);
+        }
+      }
+    }
+
+    return current;
+  };
+
+  const result = (await resolve(cloned, "#")) as JSONSchema;
+  cache.set(schema, result);
+  return result;
+};

package/src/app/oas/parser/dereference/resolveRef.ts

@@ -0,0 +1,32 @@
+import type { JSONSchema } from "./index.js";
+
+const cache = new Map<JSONSchema, Map<string, unknown>>();
+
+/**
+ * Resolves a $ref pointer in a schema and returns the referenced value.
+ */
+export const resolveLocalRef = (schema: JSONSchema, ref: string): unknown => {
+  if (!cache.has(schema)) {
+    cache.set(schema, new Map<string, unknown>());
+  }
+  const schemaCache = cache.get(schema);
+
+  if (schemaCache!.has(ref)) {
+    return schemaCache!.get(ref);
+  }
+
+  const path = ref.split("/").slice(1);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: any = schema;
+  for (const segment of path) {
+    if (!current || typeof current !== "object") {
+      // we've reached a dead end
+      current = null;
+    }
+    current = current[segment] ?? null;
+  }
+
+  schemaCache!.set(ref, current);
+  return current;
+};

package/src/app/oas/parser/index.ts

@@ -0,0 +1,94 @@
+import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
+import { dereference, type JSONSchema } from "./dereference/index.js";
+import { upgradeSchema } from "./upgrade/index.js";
+
+type ReferenceObject = OpenAPIV3_1.ReferenceObject;
+type DeepOmitReference<T> = T extends ReferenceObject
+  ? never
+  : T extends object
+    ? { [K in keyof T]: DeepOmitReference<T[K]> }
+    : T;
+
+// type Prettify<T> = {
+//   [K in keyof T]: T[K];
+// } & {};
+
+export type OpenAPIDocument = DeepOmitReference<OpenAPIV3_1.Document>;
+export type ResponseObject = DeepOmitReference<OpenAPIV3_1.ResponseObject>;
+export type OperationObject = DeepOmitReference<OpenAPIV3_1.OperationObject>;
+export type PathsObject = DeepOmitReference<OpenAPIV3_1.PathsObject>;
+export type PathItemObject = DeepOmitReference<OpenAPIV3_1.PathItemObject>;
+export type ParameterObject = DeepOmitReference<OpenAPIV3_1.ParameterObject>;
+export type TagObject = DeepOmitReference<OpenAPIV3_1.TagObject>;
+export type ExampleObject = DeepOmitReference<OpenAPIV3_1.ExampleObject>;
+export type EncodingObject = DeepOmitReference<OpenAPIV3_1.EncodingObject>;
+export type SchemaObject = DeepOmitReference<OpenAPIV3_1.SchemaObject>;
+
+export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
+
+// class ValidationError extends Error {
+//   constructor(public errors: OutputUnit[]) {
+//     super("Validation error");
+//   }
+// }
+
+// const getValidator = async (openApiVersion: string) => {
+//   if (openApiVersion.startsWith("3.0")) {
+//     const schema = (await import("./schemas/v3.0.json")) as any;
+//     return new Validator(schema, "4");
+//   }
+//   if (openApiVersion.startsWith("3.1")) {
+//     const schema = (await import("./schemas/v3.1.json")) as any;
+//     return new Validator(schema as any, "2020-12");
+//   }
+
+//   throw new Error(`Unsupported OpenAPI version: ${openApiVersion}`);
+// };
+
+const parseSchemaInput = async (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schemaInput: any,
+): Promise<JSONSchema & { openapi?: string }> => {
+  if (typeof schemaInput === "string") {
+    if (schemaInput.trim().startsWith("{")) {
+      return JSON.parse(schemaInput);
+    }
+    if (schemaInput.includes("://")) {
+      const response = await fetch(schemaInput);
+      return (await response.json()) as JSONSchema;
+    }
+    const yaml = await import("yaml");
+    return yaml.parse(schemaInput);
+  }
+
+  if (typeof schemaInput === "object") return schemaInput;
+
+  throw new Error("Unsupported schema input");
+};
+
+/**
+ * Validates, dereferences and upgrades the OpenAPI schema (to v3.1) if necessary.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const validate = async (schemaInput: any) => {
+  const schema = await parseSchemaInput(schemaInput);
+
+  if (!schema.openapi) {
+    throw new Error("OpenAPI version is not defined");
+  }
+
+  // const validator = await getValidator(schema.openapi);
+  // const result = validator.validate(schema);
+  //
+  // if (!result.valid) {
+  //   throw new ValidationError(result.errors);
+  // }
+
+  const dereferenced = await dereference(schema);
+
+  const upgraded = upgradeSchema(
+    dereferenced as OpenAPIV3_1.Document | OpenAPIV3.Document,
+  );
+
+  return upgraded;
+};