@omer-x/next-openapi-json-generator 1.0.1 → 1.1.0

package/dist/index.cjs

@@ -0,0 +1,394 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  default: () => src_default
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/core/generateOpenApiSpec.ts
+var import_package_metadata = __toESM(require("@omer-x/package-metadata"), 1);
+
+// src/core/dir.ts
+var import_fs = require("fs");
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_minimatch = require("minimatch");
+async function directoryExists(dirPath) {
+  try {
+    await import_promises.default.access(dirPath, import_fs.constants.F_OK);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+async function getDirectoryItems(dirPath, targetFileName) {
+  const collection = [];
+  const files = await import_promises.default.readdir(dirPath);
+  for (const itemName of files) {
+    const itemPath = import_node_path.default.resolve(dirPath, itemName);
+    const stats = await import_promises.default.stat(itemPath);
+    if (stats.isDirectory()) {
+      const children = await getDirectoryItems(itemPath, targetFileName);
+      collection.push(...children);
+    } else if (itemName === targetFileName) {
+      collection.push(itemPath);
+    }
+  }
+  return collection;
+}
+function filterDirectoryItems(rootPath, items, include, exclude) {
+  const includedPatterns = include.map((pattern) => new import_minimatch.Minimatch(pattern));
+  const excludedPatterns = exclude.map((pattern) => new import_minimatch.Minimatch(pattern));
+  return items.filter((item) => {
+    const relativePath = import_node_path.default.relative(rootPath, item);
+    const isIncluded = includedPatterns.some((pattern) => pattern.match(relativePath));
+    const isExcluded = excludedPatterns.some((pattern) => pattern.match(relativePath));
+    return (isIncluded || !include.length) && !isExcluded;
+  });
+}
+
+// src/core/next.ts
+var import_promises2 = __toESM(require("fs/promises"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/core/middleware.ts
+function detectMiddlewareName(code2) {
+  const match = code2.match(/middleware:\s*(\w+)/);
+  return match ? match[1] : null;
+}
+
+// src/core/transpile.ts
+var import_typescript = require("typescript");
+function removeImports(code2) {
+  return code2.replace(/^import\s.+\sfrom\s.+;?$/gm, "").trim();
+}
+function fixExports(code2) {
+  const validMethods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+  const exportFixer1 = validMethods.map((method) => `exports.${method} = void 0;
+`);
+  const exportFixer2 = `module.exports = { ${validMethods.map((m) => `${m}: exports.${m}`).join(", ")} }`;
+  return `${exportFixer1}
+${code2}
+${exportFixer2}`;
+}
+function injectMiddlewareFixer(middlewareName) {
+  return `const ${middlewareName} = (handler) => handler;`;
+}
+function transpile(rawCode, routeDefinerName, middlewareName) {
+  const code2 = fixExports(removeImports(rawCode));
+  const parts = [
+    `import ${routeDefinerName} from '@omer-x/next-openapi-route-handler';`,
+    "import z from 'zod';",
+    middlewareName ? injectMiddlewareFixer(middlewareName) : "",
+    code2
+  ];
+  return (0, import_typescript.transpile)(parts.join("\n"));
+}
+
+// src/core/next.ts
+async function findAppFolderPath() {
+  const inSrc = import_node_path2.default.resolve(process.cwd(), "src", "app");
+  if (await directoryExists(inSrc)) {
+    return inSrc;
+  }
+  const inRoot = import_node_path2.default.resolve(process.cwd(), "app");
+  if (await directoryExists(inRoot)) {
+    return inRoot;
+  }
+  return null;
+}
+function injectSchemas(code2, refName) {
+  return code2.replace(new RegExp(`\\b${refName}\\.`, "g"), `global.schemas[${refName}].`).replace(new RegExp(`\\b${refName}\\b`, "g"), `"${refName}"`);
+}
+function safeEval(code, routePath) {
+  try {
+    return eval(code);
+  } catch (error) {
+    console.log(`An error occured while evaluating the route exports from "${routePath}"`);
+    throw error;
+  }
+}
+async function getRouteExports(routePath2, routeDefinerName, schemas) {
+  const rawCode = await import_promises2.default.readFile(routePath2, "utf-8");
+  const middlewareName = detectMiddlewareName(rawCode);
+  const code2 = transpile(rawCode, routeDefinerName, middlewareName);
+  const fixedCode = Object.keys(schemas).reduce(injectSchemas, code2);
+  global.schemas = schemas;
+  if (middlewareName) {
+  }
+  const result = safeEval(fixedCode, routePath2);
+  delete global.schemas;
+  if (middlewareName) {
+  }
+  return result;
+}
+
+// src/core/options.ts
+function verifyOptions(include, exclude) {
+  if (process.env.NODE_ENV === "development") {
+    for (const item of include) {
+      if (!item.endsWith("/route.ts")) {
+        console.log(`${item} is not a valid route handler path`);
+      }
+    }
+    for (const item of exclude) {
+      if (!item.endsWith("/route.ts")) {
+        console.log(`${item} is not a valid route handler path`);
+      }
+    }
+  }
+  return {
+    include: include.filter((item) => item.endsWith("/route.ts")),
+    exclude: exclude.filter((item) => item.endsWith("/route.ts"))
+  };
+}
+
+// src/utils/deepEqual.ts
+function deepEqual(a, b) {
+  if (typeof a !== typeof b) return false;
+  switch (typeof a) {
+    case "object": {
+      if (!a || !b) return a === b;
+      if (Array.isArray(a) && Array.isArray(b)) {
+        return a.every((item, index) => deepEqual(item, b[index]));
+      }
+      if (Object.keys(a).length !== Object.keys(b).length) return false;
+      return Object.entries(a).every(([key, value]) => {
+        return deepEqual(value, b[key]);
+      });
+    }
+    case "function":
+    case "symbol":
+      return false;
+    default:
+      return a === b;
+  }
+}
+
+// src/core/zod-to-openapi.ts
+var import_zod_to_json_schema = __toESM(require("zod-to-json-schema"), 1);
+
+// src/utils/zod-schema.ts
+function isFile(schema) {
+  const result = schema.safeParse(new File([], "nothing.txt"));
+  return result.success;
+}
+
+// src/core/zod-to-openapi.ts
+function convertToOpenAPI(schema, isArray) {
+  const result = (0, import_zod_to_json_schema.default)(isArray ? schema.array() : schema, {
+    target: "openApi3",
+    $refStrategy: "none"
+  });
+  if (result.type === "object" && result.properties) {
+    for (const [propName, prop] of Object.entries(schema.shape)) {
+      if (isFile(prop)) {
+        result.properties[propName] = {
+          type: "string",
+          format: "binary",
+          description: prop.description
+          // contentEncoding: "base64", // swagger-ui-react doesn't support this
+        };
+      }
+    }
+  }
+  return result;
+}
+
+// src/core/mask.ts
+function maskWithReference(schema, storedSchemas, self) {
+  if (self) {
+    for (const [schemaName, zodSchema] of Object.entries(storedSchemas)) {
+      if (deepEqual(schema, convertToOpenAPI(zodSchema, false))) {
+        return {
+          $ref: `#/components/schemas/${schemaName}`
+        };
+      }
+    }
+  }
+  if ("$ref" in schema) return schema;
+  if (schema.oneOf) {
+    return {
+      ...schema,
+      oneOf: schema.oneOf.map((i) => maskWithReference(i, storedSchemas, true))
+    };
+  }
+  if (schema.anyOf) {
+    return {
+      ...schema,
+      anyOf: schema.anyOf.map((i) => maskWithReference(i, storedSchemas, true))
+    };
+  }
+  switch (schema.type) {
+    case "object":
+      return {
+        ...schema,
+        properties: Object.entries(schema.properties ?? {}).reduce((props, [propName, prop]) => ({
+          ...props,
+          [propName]: maskWithReference(prop, storedSchemas, true)
+        }), {})
+      };
+    case "array":
+      if (Array.isArray(schema.items)) {
+        return {
+          ...schema,
+          items: schema.items.map((i) => maskWithReference(i, storedSchemas, true))
+        };
+      }
+      return {
+        ...schema,
+        items: maskWithReference(schema.items, storedSchemas, true)
+      };
+  }
+  return schema;
+}
+
+// src/core/operation-mask.ts
+function maskSchema(storedSchemas, schema) {
+  if (!schema) return schema;
+  return maskWithReference(schema, storedSchemas, true);
+}
+function maskParameterSchema(param, storedSchemas) {
+  if ("$ref" in param) return param;
+  return { ...param, schema: maskSchema(storedSchemas, param.schema) };
+}
+function maskContentSchema(storedSchemas, bodyContent) {
+  if (!bodyContent) return bodyContent;
+  return Object.entries(bodyContent).reduce((collection, [contentType, content]) => ({
+    ...collection,
+    [contentType]: {
+      ...content,
+      schema: maskSchema(storedSchemas, content.schema)
+    }
+  }), {});
+}
+function maskRequestBodySchema(storedSchemas, body) {
+  if (!body || "$ref" in body) return body;
+  return { ...body, content: maskContentSchema(storedSchemas, body.content) };
+}
+function maskResponseSchema(storedSchemas, response) {
+  if ("$ref" in response) return response;
+  return { ...response, content: maskContentSchema(storedSchemas, response.content) };
+}
+function maskSchemasInResponses(storedSchemas, responses) {
+  if (!responses) return responses;
+  return Object.entries(responses).reduce((collection, [key, response]) => ({
+    ...collection,
+    [key]: maskResponseSchema(storedSchemas, response)
+  }), {});
+}
+function maskOperationSchemas(operation, storedSchemas) {
+  return {
+    ...operation,
+    parameters: operation.parameters?.map((p) => maskParameterSchema(p, storedSchemas)),
+    requestBody: maskRequestBodySchema(storedSchemas, operation.requestBody),
+    responses: maskSchemasInResponses(storedSchemas, operation.responses)
+  };
+}
+
+// src/core/route.ts
+function getRoutePathName(filePath, rootPath) {
+  return filePath.replace(rootPath, "").replace("[", "{").replace("]", "}").replaceAll("\\", "/").replace("/route.ts", "");
+}
+function createRouteRecord(method, filePath, rootPath, apiData) {
+  return {
+    method: method.toLocaleLowerCase(),
+    path: getRoutePathName(filePath, rootPath),
+    apiData
+  };
+}
+function bundlePaths(source, storedSchemas) {
+  source.sort((a, b) => a.path.localeCompare(b.path));
+  return source.reduce((collection, route) => ({
+    ...collection,
+    [route.path]: {
+      ...collection[route.path],
+      [route.method]: maskOperationSchemas(route.apiData, storedSchemas)
+    }
+  }), {});
+}
+
+// src/core/schema.ts
+function bundleSchemas(schemas) {
+  const bundledSchemas = Object.keys(schemas).reduce((collection, schemaName) => {
+    return {
+      ...collection,
+      [schemaName]: convertToOpenAPI(schemas[schemaName], false)
+    };
+  }, {});
+  return Object.entries(bundledSchemas).reduce((bundle, [schemaName, schema]) => ({
+    ...bundle,
+    [schemaName]: maskWithReference(schema, schemas, false)
+  }), {});
+}
+
+// src/core/generateOpenApiSpec.ts
+async function generateOpenApiSpec(schemas, {
+  include: includeOption = [],
+  exclude: excludeOption = [],
+  routeDefinerName = "defineRoute"
+} = {}) {
+  const verifiedOptions = verifyOptions(includeOption, excludeOption);
+  const appFolderPath = await findAppFolderPath();
+  if (!appFolderPath) throw new Error("This is not a Next.js application!");
+  const routes = await getDirectoryItems(appFolderPath, "route.ts");
+  const verifiedRoutes = filterDirectoryItems(appFolderPath, routes, verifiedOptions.include, verifiedOptions.exclude);
+  const validRoutes = [];
+  for (const route of verifiedRoutes) {
+    const exportedRouteHandlers = await getRouteExports(route, routeDefinerName, schemas);
+    for (const [method, routeHandler] of Object.entries(exportedRouteHandlers)) {
+      if (!routeHandler || !routeHandler.apiData) continue;
+      validRoutes.push(createRouteRecord(
+        method.toLocaleLowerCase(),
+        route,
+        appFolderPath,
+        routeHandler.apiData
+      ));
+    }
+  }
+  const metadata = (0, import_package_metadata.default)();
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: metadata.serviceName,
+      version: metadata.version
+    },
+    paths: bundlePaths(validRoutes, schemas),
+    components: {
+      schemas: bundleSchemas(schemas)
+    },
+    tags: []
+  };
+}
+
+// src/index.ts
+var src_default = generateOpenApiSpec;

package/dist/index.d.cts

@@ -0,0 +1,11 @@
+import { OpenApiDocument } from '@omer-x/openapi-types';
+import { ZodType } from 'zod';
+
+type GeneratorOptions = {
+    include?: string[];
+    exclude?: string[];
+    routeDefinerName?: string;
+};
+declare function generateOpenApiSpec(schemas: Record<string, ZodType>, { include: includeOption, exclude: excludeOption, routeDefinerName, }?: GeneratorOptions): Promise<Omit<OpenApiDocument, "components"> & Required<Pick<OpenApiDocument, "components">>>;
+
+export { generateOpenApiSpec as default };

package/dist/index.js

@@ -44,6 +44,12 @@ function filterDirectoryItems(rootPath, items, include, exclude) {
 import fs2 from "node:fs/promises";
 import path2 from "node:path";
 
+// src/core/middleware.ts
+function detectMiddlewareName(code2) {
+  const match = code2.match(/middleware:\s*(\w+)/);
+  return match ? match[1] : null;
+}
+
 // src/core/transpile.ts
 import { transpile as tsTranspile } from "typescript";
 function removeImports(code2) {
@@ -58,11 +64,15 @@ function fixExports(code2) {
 ${code2}
 ${exportFixer2}`;
 }
-function transpile(rawCode, routeDefinerName) {
+function injectMiddlewareFixer(middlewareName) {
+  return `const ${middlewareName} = (handler) => handler;`;
+}
+function transpile(rawCode, routeDefinerName, middlewareName) {
   const code2 = fixExports(removeImports(rawCode));
   const parts = [
     `import ${routeDefinerName} from '@omer-x/next-openapi-route-handler';`,
     "import z from 'zod';",
+    middlewareName ? injectMiddlewareFixer(middlewareName) : "",
     code2
   ];
   return tsTranspile(parts.join("\n"));
@@ -92,12 +102,17 @@ function safeEval(code, routePath) {
   }
 }
 async function getRouteExports(routePath2, routeDefinerName, schemas) {
-  const content = await fs2.readFile(routePath2, "utf-8");
-  const code2 = transpile(content, routeDefinerName);
+  const rawCode = await fs2.readFile(routePath2, "utf-8");
+  const middlewareName = detectMiddlewareName(rawCode);
+  const code2 = transpile(rawCode, routeDefinerName, middlewareName);
   const fixedCode = Object.keys(schemas).reduce(injectSchemas, code2);
   global.schemas = schemas;
+  if (middlewareName) {
+  }
   const result = safeEval(fixedCode, routePath2);
   delete global.schemas;
+  if (middlewareName) {
+  }
   return result;
 }
 
@@ -130,7 +145,10 @@ function deepEqual(a, b) {
       if (Array.isArray(a) && Array.isArray(b)) {
         return a.every((item, index) => deepEqual(item, b[index]));
       }
-      return Object.entries(a).every(([key, value]) => deepEqual(value, b[key]));
+      if (Object.keys(a).length !== Object.keys(b).length) return false;
+      return Object.entries(a).every(([key, value]) => {
+        return deepEqual(value, b[key]);
+      });
     }
     case "function":
     case "symbol":
@@ -142,11 +160,31 @@ function deepEqual(a, b) {
 
 // src/core/zod-to-openapi.ts
 import zodToJsonSchema from "zod-to-json-schema";
+
+// src/utils/zod-schema.ts
+function isFile(schema) {
+  const result = schema.safeParse(new File([], "nothing.txt"));
+  return result.success;
+}
+
+// src/core/zod-to-openapi.ts
 function convertToOpenAPI(schema, isArray) {
   const result = zodToJsonSchema(isArray ? schema.array() : schema, {
     target: "openApi3",
     $refStrategy: "none"
   });
+  if (result.type === "object" && result.properties) {
+    for (const [propName, prop] of Object.entries(schema.shape)) {
+      if (isFile(prop)) {
+        result.properties[propName] = {
+          type: "string",
+          format: "binary",
+          description: prop.description
+          // contentEncoding: "base64", // swagger-ui-react doesn't support this
+        };
+      }
+    }
+  }
   return result;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omer-x/next-openapi-json-generator",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "a Next.js plugin to generate OpenAPI documentation from route handlers",
   "keywords": [
     "next.js",
@@ -29,11 +29,16 @@
   },
   "license": "MIT",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "files": [
     "dist/"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "scripts": {
     "test": "jest",
     "dev": "tsup --watch",