@scalar/openapi-parser 0.4.1 → 0.6.0

package/dist/src/utils/filter.js

@@ -0,0 +1,17 @@
+import { getEntrypoint } from './getEntrypoint.js';
+import { makeFilesystem } from './makeFilesystem.js';
+import { traverse } from './traverse.js';
+
+function filter(specification, callback) {
+  const filesystem = makeFilesystem(specification);
+  return {
+    specification: traverse(
+      getEntrypoint(filesystem).specification,
+      (schema) => {
+        return callback(schema) ? schema : void 0;
+      }
+    )
+  };
+}
+
+export { filter };

package/dist/src/utils/getEntrypoint.js

@@ -0,0 +1,5 @@
+function getEntrypoint(filesystem) {
+  return filesystem.find((file) => file.isEntrypoint);
+}
+
+export { getEntrypoint };

package/dist/src/utils/getListOfReferences.js

@@ -0,0 +1,17 @@
+import { traverse } from './traverse.js';
+
+function getListOfReferences(specification) {
+  const references = [];
+  if (!specification || typeof specification !== "object") {
+    return references;
+  }
+  traverse(specification, (value) => {
+    if (value.$ref && typeof value.$ref === "string" && !value.$ref.startsWith("#")) {
+      references.push(value.$ref.split("#")[0]);
+    }
+    return value;
+  });
+  return [...new Set(references)];
+}
+
+export { getListOfReferences };

package/dist/src/utils/getSegmentsFromPath.js

@@ -0,0 +1,10 @@
+import { unescapeJsonPointer } from './unescapeJsonPointer.js';
+
+function getSegmentsFromPath(path) {
+  return (
+    // /paths/~1test
+    path.split("/").slice(1).map(unescapeJsonPointer)
+  );
+}
+
+export { getSegmentsFromPath };

package/dist/src/utils/isFilesystem.js

@@ -0,0 +1,5 @@
+function isFilesystem(value) {
+  return typeof value !== void 0 && Array.isArray(value) && value.length > 0 && value.some((file) => file.isEntrypoint === true);
+}
+
+export { isFilesystem };

package/dist/src/utils/isJson.js

@@ -0,0 +1,10 @@
+function isJson(value) {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { isJson };

package/dist/src/utils/isObject.js

@@ -0,0 +1,3 @@
+const isObject = (obj) => typeof obj === "object" && !Array.isArray(obj) && obj !== null;
+
+export { isObject };

package/dist/src/utils/isYaml.js

@@ -0,0 +1,17 @@
+import { parse } from 'yaml';
+
+function isYaml(value) {
+  if (!value.includes("\n")) {
+    return false;
+  }
+  try {
+    parse(value, {
+      maxAliasCount: 1e4
+    });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+export { isYaml };

package/dist/src/utils/load/load.js

@@ -0,0 +1,59 @@
+import { getEntrypoint } from '../getEntrypoint.js';
+import { getListOfReferences } from '../getListOfReferences.js';
+import { makeFilesystem } from '../makeFilesystem.js';
+import { normalize } from '../normalize.js';
+
+async function load(value, options) {
+  if (options?.filesystem && options?.filesystem.find((entry) => entry.filename === value)) {
+    return {
+      filesystem: options.filesystem
+    };
+  }
+  const plugin = options?.plugins?.find((plugin2) => plugin2.check(value));
+  const content = normalize(plugin ? await plugin.get(value) : value);
+  if (content === void 0) {
+    return {
+      filesystem: []
+    };
+  }
+  let filesystem = makeFilesystem(content, {
+    filename: options?.filename ?? null
+  });
+  const newEntry = options?.filename ? filesystem.find((entry) => entry.filename === options?.filename) : getEntrypoint(filesystem);
+  const listOfReferences = newEntry.references ?? getListOfReferences(content);
+  if (listOfReferences.length === 0) {
+    return {
+      filesystem
+    };
+  }
+  for (const reference of listOfReferences) {
+    const plugin2 = options?.plugins?.find((plugin3) => plugin3.check(reference));
+    if (!plugin2) {
+      continue;
+    }
+    const target = plugin2.check(reference) && plugin2.resolvePath ? plugin2.resolvePath(value, reference) : reference;
+    if (filesystem.find((entry) => entry.filename === reference)) {
+      continue;
+    }
+    const { filesystem: referencedFiles } = await load(target, {
+      ...options,
+      // Make the filename the exact same value as the $ref
+      // TODO: This leads to problems, if there are multiple references with the same file name but in different folders
+      filename: reference
+    });
+    filesystem = [
+      ...filesystem,
+      ...referencedFiles.map((file) => {
+        return {
+          ...file,
+          isEntrypoint: false
+        };
+      })
+    ];
+  }
+  return {
+    filesystem
+  };
+}
+
+export { load };

package/dist/src/utils/load/plugins/fetchUrlsPlugin.js

@@ -0,0 +1,38 @@
+const fetchUrlsPluginDefaultConfiguration = {
+  limit: 20
+};
+const fetchUrlsPlugin = (customConfiguration) => {
+  let numberOfRequests = 0;
+  const configuration = {
+    ...fetchUrlsPluginDefaultConfiguration,
+    ...customConfiguration
+  };
+  return {
+    check(value) {
+      if (typeof value !== "string") {
+        return false;
+      }
+      if (!value.startsWith("http://") && !value.startsWith("https://")) {
+        return false;
+      }
+      return true;
+    },
+    async get(value) {
+      if (configuration?.limit !== false && numberOfRequests >= configuration?.limit) {
+        console.warn(
+          `[fetchUrlsPlugin] Maximum number of requests reeached (${configuration?.limit}), skipping request`
+        );
+        return void 0;
+      }
+      try {
+        numberOfRequests++;
+        const response = await (configuration?.fetch ? configuration.fetch(value) : fetch(value));
+        return await response.text();
+      } catch (error) {
+        console.error("[fetchUrlsPlugin]", error.message, `(${value})`);
+      }
+    }
+  };
+};
+
+export { fetchUrlsPlugin, fetchUrlsPluginDefaultConfiguration };

package/dist/src/utils/load/plugins/readFilesPlugin.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import { ERRORS } from '../../../configuration.js';
+import { dirname, join } from '../../../polyfills/path.js';
+import { isJson } from '../../isJson.js';
+import { isYaml } from '../../isYaml.js';
+
+const readFilesPlugin = () => {
+  return {
+    check(value) {
+      if (typeof value !== "string") {
+        return false;
+      }
+      if (value.startsWith("http://") || value.startsWith("https://")) {
+        return false;
+      }
+      if (value.includes("\n")) {
+        return false;
+      }
+      if (isJson(value)) {
+        return false;
+      }
+      if (isYaml(value)) {
+        return false;
+      }
+      return true;
+    },
+    async get(value) {
+      if (!fs.existsSync(value)) {
+        throw new Error(ERRORS.FILE_DOES_NOT_EXIST.replace("%s", value));
+      }
+      try {
+        return fs.readFileSync(value, "utf-8");
+      } catch (error) {
+        console.error("[readFilesPlugin]", error);
+      }
+    },
+    resolvePath(value, reference) {
+      const dir = dirname(value);
+      return join(dir, reference);
+    },
+    getDir(value) {
+      return dirname(value);
+    },
+    getFilename(value) {
+      return value.split("/").pop();
+    }
+  };
+};
+
+export { readFilesPlugin };

package/dist/src/utils/makeFilesystem.js

@@ -0,0 +1,22 @@
+import { getListOfReferences } from './getListOfReferences.js';
+import { isFilesystem } from './isFilesystem.js';
+import { normalize } from './normalize.js';
+
+function makeFilesystem(value, overwrites = {}) {
+  if (isFilesystem(value)) {
+    return value;
+  }
+  const specification = normalize(value);
+  return [
+    {
+      isEntrypoint: true,
+      specification,
+      filename: null,
+      dir: "./",
+      references: getListOfReferences(specification),
+      ...overwrites
+    }
+  ];
+}
+
+export { makeFilesystem };

package/dist/src/utils/normalize.js

@@ -0,0 +1,20 @@
+import { parse } from 'yaml';
+import { isFilesystem } from './isFilesystem.js';
+
+function normalize(specification) {
+  if (isFilesystem(specification)) {
+    return specification;
+  }
+  if (typeof specification === "string") {
+    try {
+      return JSON.parse(specification);
+    } catch (error) {
+      return parse(specification, {
+        maxAliasCount: 1e4
+      });
+    }
+  }
+  return specification;
+}
+
+export { normalize };

package/dist/src/utils/resolveReferences.js

@@ -0,0 +1,106 @@
+import { ERRORS } from '../configuration.js';
+import { getEntrypoint } from './getEntrypoint.js';
+import { getSegmentsFromPath } from './getSegmentsFromPath.js';
+import { makeFilesystem } from './makeFilesystem.js';
+
+function resolveReferences(input, file, errors) {
+  if (errors === void 0) {
+    errors = [];
+  }
+  const clonedInput = structuredClone(input);
+  const filesystem = makeFilesystem(clonedInput);
+  const entrypoint = getEntrypoint(filesystem);
+  resolve(
+    file?.specification ?? entrypoint.specification,
+    filesystem,
+    file ?? entrypoint
+  );
+  resolve(
+    file?.specification ?? entrypoint.specification,
+    filesystem,
+    file ?? entrypoint
+  );
+  errors = errors.filter(
+    (error, index, self) => index === self.findIndex(
+      (t) => t.message === error.message && t.code === error.code
+    )
+  );
+  return {
+    valid: errors.length === 0,
+    errors,
+    schema: (file ?? getEntrypoint(filesystem)).specification
+  };
+  function resolve(schema, filesystem2, file2) {
+    let result;
+    Object.entries(schema ?? {}).forEach(([_, value]) => {
+      if (schema.$ref !== void 0) {
+        const target = resolveUri(schema.$ref, file2, filesystem2, errors);
+        if (target === void 0) {
+          return void 0;
+        }
+        delete schema.$ref;
+        if (typeof target === "object") {
+          Object.keys(target).forEach((key) => {
+            if (schema[key] === void 0) {
+              schema[key] = target[key];
+            }
+          });
+        }
+      }
+      if (typeof value === "object" && !isCircular(value)) {
+        result = resolve(value, filesystem2, file2);
+      }
+    });
+    return {
+      errors: result?.errors ?? []
+    };
+  }
+}
+function isCircular(schema) {
+  try {
+    JSON.stringify(schema);
+    return false;
+  } catch (error) {
+    return true;
+  }
+}
+function resolveUri(uri, file, filesystem, errors) {
+  if (typeof uri !== "string") {
+    errors.push({
+      code: "INVALID_REFERENCE",
+      message: ERRORS.INVALID_REFERENCE.replace("%s", uri)
+    });
+    return;
+  }
+  const [prefix, path] = uri.split("#", 2);
+  if (prefix) {
+    const externalReference = filesystem.find((entry) => {
+      return entry.filename === prefix;
+    });
+    if (!externalReference) {
+      errors.push({
+        code: "EXTERNAL_REFERENCE_NOT_FOUND",
+        message: ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace("%s", prefix)
+      });
+      return;
+    }
+    const result = resolveReferences(filesystem, externalReference, errors);
+    if (path === void 0) {
+      return result.schema;
+    }
+    return resolveUri(`#${path}`, externalReference, filesystem, errors);
+  }
+  const segments = getSegmentsFromPath(path);
+  try {
+    return segments.reduce((acc, key) => {
+      return acc[key];
+    }, file.specification);
+  } catch (error) {
+    errors.push({
+      code: "INVALID_REFERENCE",
+      message: ERRORS.INVALID_REFERENCE.replace("%s", uri)
+    });
+  }
+}
+
+export { resolveReferences };

package/dist/src/utils/toJson.js

@@ -0,0 +1,3 @@
+const toJson = (value) => JSON.stringify(value, null, 2);
+
+export { toJson };

package/dist/src/utils/toYaml.js

@@ -0,0 +1,5 @@
+import { stringify } from 'yaml';
+
+const toYaml = (value) => stringify(value);
+
+export { toYaml };

package/dist/src/utils/transformErrors.js

@@ -0,0 +1,19 @@
+import { betterAjvErrors } from './betterAjvErrors/index.js';
+
+function transformErrors(specification, errors) {
+  if (typeof errors === "string") {
+    return [
+      {
+        message: errors
+      }
+    ];
+  }
+  return betterAjvErrors(specification, null, errors, {
+    indent: 2
+  }).map((error) => {
+    error.message = error.message.trim();
+    return error;
+  });
+}
+
+export { transformErrors };

package/dist/src/utils/traverse.js

@@ -0,0 +1,20 @@
+function traverse(specification, transform) {
+  const result = {};
+  for (const [key, value] of Object.entries(specification)) {
+    if (Array.isArray(value)) {
+      result[key] = value.map((item) => {
+        if (typeof item === "object" && item !== null) {
+          return traverse(item, transform);
+        }
+        return item;
+      });
+    } else if (typeof value === "object" && value !== null) {
+      result[key] = traverse(value, transform);
+    } else {
+      result[key] = value;
+    }
+  }
+  return transform(result);
+}
+
+export { traverse };

package/dist/src/utils/unescapeJsonPointer.js

@@ -0,0 +1,5 @@
+function unescapeJsonPointer(uri) {
+  return decodeURI(uri.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+export { unescapeJsonPointer };

package/dist/src/utils/upgrade.js

@@ -0,0 +1,19 @@
+import { getEntrypoint } from './getEntrypoint.js';
+import { makeFilesystem } from './makeFilesystem.js';
+import { upgradeFromThreeToThreeOne } from './upgradeFromThreeToThreeOne.js';
+import { upgradeFromTwoToThree } from './upgradeFromTwoToThree.js';
+
+function upgrade(specification, _options) {
+  const upgraders = [upgradeFromTwoToThree, upgradeFromThreeToThreeOne];
+  const result = upgraders.reduce(
+    (specification2, upgrader) => upgrader(specification2),
+    getEntrypoint(makeFilesystem(specification)).specification
+  );
+  return {
+    specification: result,
+    // TODO: Make dynamic
+    version: "3.1"
+  };
+}
+
+export { upgrade };

package/dist/src/utils/upgradeFromThreeToThreeOne.js

@@ -0,0 +1,71 @@
+import { traverse } from './traverse.js';
+
+function upgradeFromThreeToThreeOne(specification) {
+  if (specification.openapi?.startsWith("3.0")) {
+    specification.openapi = "3.1.0";
+  } else {
+    return specification;
+  }
+  specification = traverse(specification, (schema) => {
+    if (schema.type !== "undefined" && schema.nullable === true) {
+      schema.type = ["null", schema.type];
+      delete schema.nullable;
+    }
+    return schema;
+  });
+  specification = traverse(specification, (schema) => {
+    if (schema.exclusiveMinimum === true) {
+      schema.exclusiveMinimum = schema.minimum;
+      delete schema.minimum;
+    } else if (schema.exclusiveMinimum === false) {
+      delete schema.exclusiveMinimum;
+    }
+    if (schema.exclusiveMaximum === true) {
+      schema.exclusiveMaximum = schema.maximum;
+      delete schema.maximum;
+    } else if (schema.exclusiveMaximum === false) {
+      delete schema.exclusiveMaximum;
+    }
+    return schema;
+  });
+  specification = traverse(specification, (schema) => {
+    if (schema.example !== void 0) {
+      schema.examples = {
+        default: schema.example
+      };
+      delete schema.example;
+    }
+    return schema;
+  });
+  specification = traverse(specification, (schema) => {
+    if (schema.type === "object" && schema.properties !== void 0) {
+      for (const [_, value] of Object.entries(schema.properties)) {
+        if (value !== void 0 && // @ts-ignore
+        value.type === "string" && // @ts-ignore
+        value.format === "binary") {
+          value.contentEncoding = "application/octet-stream";
+          delete value.format;
+        }
+      }
+    }
+    return schema;
+  });
+  specification = traverse(specification, (schema) => {
+    if (schema.type === "string" && schema.format === "binary") {
+      return void 0;
+    }
+    return schema;
+  });
+  specification = traverse(specification, (schema) => {
+    if (schema.type === "string" && schema.format === "base64") {
+      return {
+        type: "string",
+        contentEncoding: "base64"
+      };
+    }
+    return schema;
+  });
+  return specification;
+}
+
+export { upgradeFromThreeToThreeOne };

package/dist/src/utils/upgradeFromTwoToThree.js

@@ -0,0 +1,5 @@
+function upgradeFromTwoToThree(specification) {
+  return specification;
+}
+
+export { upgradeFromTwoToThree };

package/dist/src/utils/validate.js

@@ -0,0 +1,15 @@
+import { makeFilesystem } from './makeFilesystem.js';
+import { Validator } from '../lib/Validator/Validator.js';
+
+async function validate(value) {
+  const filesystem = makeFilesystem(value);
+  const validator = new Validator();
+  const result = await validator.validate(filesystem);
+  return {
+    ...result,
+    specification: validator.specification,
+    version: validator.version
+  };
+}
+
+export { validate };

package/dist/src/utils/workThroughQueue.js

@@ -0,0 +1,24 @@
+async function workThroughQueue(queue) {
+  let specification = queue.specification;
+  let result;
+  for (const { action, options } of queue.tasks) {
+    if (typeof action !== "function") {
+      console.warn("[queue] The given action is not a function:", action);
+      continue;
+    }
+    if (action.constructor.name === "AsyncFunction") {
+      result = {
+        ...result,
+        ...await action(result?.filesystem ?? specification, options)
+      };
+    } else {
+      result = {
+        ...result,
+        ...action(result?.filesystem ?? specification, options)
+      };
+    }
+  }
+  return result;
+}
+
+export { workThroughQueue };

package/dist/types/index.d.ts

@@ -0,0 +1,57 @@
+import { OpenApiVersion, ERRORS } from '../configuration.js';
+import { OpenAPI } from './openapi-types.js';
+export { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from './openapi-types.js';
+
+type AnyObject = Record<string, any>;
+type LoadResult = {
+    filesystem: Filesystem;
+};
+type ValidateResult = {
+    valid: boolean;
+    specification?: OpenAPI.Document;
+    version?: string;
+    errors?: ErrorObject[];
+    schema?: OpenAPI.Document;
+};
+type UpgradeResult = {
+    specification: OpenAPI.Document;
+    version: string;
+};
+type FilterResult = {
+    specification: OpenAPI.Document;
+};
+type DetailsResult = {
+    version: OpenApiVersion;
+    specificationType: string;
+    specificationVersion: string;
+};
+type DereferenceResult = {
+    version: string | undefined;
+    specification?: OpenAPI.Document;
+    schema?: OpenAPI.Document;
+    errors?: ErrorObject[];
+};
+type ErrorObject = {
+    message: string;
+    code?: keyof typeof ERRORS | string;
+};
+type AjvOptions = {
+    strict?: boolean | 'log';
+};
+/**
+ * Not literally a filesystem, but a list of files with their content.
+ * This is an abstraction layer to handle multiple files in the browser (without access to the hard disk).
+ */
+type Filesystem = FilesystemEntry[];
+/**
+ * Holds all information about a single file (doesn’t have to be a literal file, see Filesystem).
+ */
+type FilesystemEntry = {
+    dir: string;
+    isEntrypoint: boolean;
+    references: string[];
+    filename: string;
+    specification: AnyObject;
+};
+
+export { type AjvOptions, type AnyObject, type DereferenceResult, type DetailsResult, type ErrorObject, type Filesystem, type FilesystemEntry, type FilterResult, type LoadResult, OpenAPI, type UpgradeResult, type ValidateResult };