@scalar/openapi-parser 0.25.3 → 0.25.5

package/dist/utils/openapi/commands/upgradeCommand.js

@@ -1,29 +1,28 @@
-import { details } from "../actions/details.js";
-import { files } from "../actions/files.js";
-import { get } from "../actions/get.js";
-import { toJson } from "../actions/toJson.js";
-import { toYaml } from "../actions/toYaml.js";
-import { queueTask } from "../utils/queueTask.js";
-import { dereferenceCommand } from "./dereferenceCommand.js";
-import { filterCommand } from "./filterCommand.js";
-import { validateCommand } from "./validateCommand.js";
-function upgradeCommand(previousQueue) {
-  const task = {
-    name: "upgrade"
-  };
-  const queue = queueTask(previousQueue, task);
-  return {
-    dereference: (dereferenceOptions) => dereferenceCommand(queue, dereferenceOptions),
-    details: () => details(queue),
-    files: () => files(queue),
-    filter: (callback) => filterCommand(queue, callback),
-    get: () => get(queue),
-    toJson: () => toJson(queue),
-    toYaml: () => toYaml(queue),
-    validate: (validateOptions) => validateCommand(queue, validateOptions)
-  };
+import { details } from '../actions/details.js';
+import { files } from '../actions/files.js';
+import { get } from '../actions/get.js';
+import { toJson } from '../actions/toJson.js';
+import { toYaml } from '../actions/toYaml.js';
+import { queueTask } from '../utils/queueTask.js';
+import { dereferenceCommand } from './dereferenceCommand.js';
+import { filterCommand } from './filterCommand.js';
+import { validateCommand } from './validateCommand.js';
+/**
+ * Upgrade the given OpenAPI document
+ */
+export function upgradeCommand(previousQueue) {
+    const task = {
+        name: 'upgrade',
+    };
+    const queue = queueTask(previousQueue, task);
+    return {
+        dereference: (dereferenceOptions) => dereferenceCommand(queue, dereferenceOptions),
+        details: () => details(queue),
+        files: () => files(queue),
+        filter: (callback) => filterCommand(queue, callback),
+        get: () => get(queue),
+        toJson: () => toJson(queue),
+        toYaml: () => toYaml(queue),
+        validate: (validateOptions) => validateCommand(queue, validateOptions),
+    };
 }
-export {
-  upgradeCommand
-};
-//# sourceMappingURL=upgradeCommand.js.map

package/dist/utils/openapi/commands/validateCommand.js

@@ -1,33 +1,32 @@
-import { details } from "../actions/details.js";
-import { files } from "../actions/files.js";
-import { get } from "../actions/get.js";
-import { toJson } from "../actions/toJson.js";
-import { toYaml } from "../actions/toYaml.js";
-import { queueTask } from "../utils/queueTask.js";
-import { dereferenceCommand } from "./dereferenceCommand.js";
-import { filterCommand } from "./filterCommand.js";
-import { upgradeCommand } from "./upgradeCommand.js";
-function validateCommand(previousQueue, options) {
-  const task = {
-    name: "validate",
-    options: {
-      throwOnError: previousQueue.options?.throwOnError,
-      ...options ?? {}
-    }
-  };
-  const queue = queueTask(previousQueue, task);
-  return {
-    dereference: (dereferenceOptions) => dereferenceCommand(queue, dereferenceOptions),
-    details: () => details(queue),
-    files: () => files(queue),
-    filter: (callback) => filterCommand(queue, callback),
-    get: () => get(queue),
-    toJson: () => toJson(queue),
-    toYaml: () => toYaml(queue),
-    upgrade: () => upgradeCommand(queue)
-  };
+import { details } from '../actions/details.js';
+import { files } from '../actions/files.js';
+import { get } from '../actions/get.js';
+import { toJson } from '../actions/toJson.js';
+import { toYaml } from '../actions/toYaml.js';
+import { queueTask } from '../utils/queueTask.js';
+import { dereferenceCommand } from './dereferenceCommand.js';
+import { filterCommand } from './filterCommand.js';
+import { upgradeCommand } from './upgradeCommand.js';
+/**
+ * Validate the given OpenAPI document
+ */
+export function validateCommand(previousQueue, options) {
+    const task = {
+        name: 'validate',
+        options: {
+            throwOnError: previousQueue.options?.throwOnError,
+            ...(options ?? {}),
+        },
+    };
+    const queue = queueTask(previousQueue, task);
+    return {
+        dereference: (dereferenceOptions) => dereferenceCommand(queue, dereferenceOptions),
+        details: () => details(queue),
+        files: () => files(queue),
+        filter: (callback) => filterCommand(queue, callback),
+        get: () => get(queue),
+        toJson: () => toJson(queue),
+        toYaml: () => toYaml(queue),
+        upgrade: () => upgradeCommand(queue),
+    };
 }
-export {
-  validateCommand
-};
-//# sourceMappingURL=validateCommand.js.map

package/dist/utils/openapi/openapi.js

@@ -1,15 +1,17 @@
-import { loadCommand } from "./commands/loadCommand.js";
-function openapi(globalOptions) {
-  const queue = {
-    input: null,
-    options: globalOptions,
-    tasks: []
-  };
-  return {
-    load: (input, options) => loadCommand(queue, input, options)
-  };
+import { loadCommand } from './commands/loadCommand.js';
+/**
+ * Creates a fluent OpenAPI pipeline
+ *
+ * @deprecated We are about to drop the pipeline syntax. Use the individual utilities instead.
+ */
+export function openapi(globalOptions) {
+    // Create a new queue
+    const queue = {
+        input: null,
+        options: globalOptions,
+        tasks: [],
+    };
+    return {
+        load: (input, options) => loadCommand(queue, input, options),
+    };
 }
-export {
-  openapi
-};
-//# sourceMappingURL=openapi.js.map

package/dist/utils/openapi/openapi.test-d.js

@@ -1,14 +1,14 @@
-import { describe, expectTypeOf, it } from "vitest";
-import { openapi } from "./openapi.js";
-describe("openapi", () => {
-  it("returns the correct type for load()", async () => {
-    const result = await openapi().load({}).get();
-    expectTypeOf(result.filesystem).toMatchTypeOf();
-    expectTypeOf(result.valid).toMatchTypeOf();
-  });
-  it("returns the correct type for validate()", async () => {
-    const result = await openapi().load({}).validate().get();
-    expectTypeOf(result.valid).toMatchTypeOf();
-  });
+import { describe, expectTypeOf, it } from 'vitest';
+import { openapi } from './openapi.js';
+describe('openapi', () => {
+    it('returns the correct type for load()', async () => {
+        const result = await openapi().load({}).get();
+        expectTypeOf(result.filesystem).toMatchTypeOf();
+        // @ts-expect-error `valid` should be undefined
+        expectTypeOf(result.valid).toMatchTypeOf();
+    });
+    it('returns the correct type for validate()', async () => {
+        const result = await openapi().load({}).validate().get();
+        expectTypeOf(result.valid).toMatchTypeOf();
+    });
 });
-//# sourceMappingURL=openapi.test-d.js.map

package/dist/utils/openapi/utils/queueTask.js

@@ -1,10 +1,9 @@
-function queueTask(queue, task) {
-  return {
-    ...queue,
-    tasks: [...queue.tasks, task]
-  };
+/**
+ * Add a new task to the existing queue
+ */
+export function queueTask(queue, task) {
+    return {
+        ...queue,
+        tasks: [...queue.tasks, task],
+    };
 }
-export {
-  queueTask
-};
-//# sourceMappingURL=queueTask.js.map

package/dist/utils/openapi/utils/workThroughQueue.js

@@ -1,52 +1,66 @@
-import { dereference } from "../../../utils/dereference.js";
-import { filter } from "../../../utils/filter.js";
-import { load } from "../../../utils/load/load.js";
-import { upgrade } from "../../../utils/upgrade.js";
-import { validate } from "../../../utils/validate.js";
-async function workThroughQueue(queue) {
-  const { input } = {
-    ...queue
-  };
-  let result = {};
-  for (const task of queue.tasks) {
-    const name = task.name;
-    const options = "options" in task ? task.options : void 0;
-    const currentSpecification = result.specification ? result.specification : typeof input === "object" ? (
-      // Detach from the original object
-      structuredClone(input)
-    ) : input;
-    if (name === "load") {
-      result = {
-        ...result,
-        ...await load(input, options)
-      };
-    } else if (name === "filter") {
-      result = {
-        ...result,
-        ...filter(currentSpecification, options)
-      };
-    } else if (name === "dereference") {
-      result = {
-        ...result,
-        ...dereference(currentSpecification, options)
-      };
-    } else if (name === "upgrade") {
-      result = {
-        ...result,
-        ...upgrade(currentSpecification)
-      };
-    } else if (name === "validate") {
-      result = {
-        ...result,
-        ...await validate(currentSpecification, options)
-      };
-    } else {
-      name;
+import { dereference } from '../../../utils/dereference.js';
+import { filter } from '../../../utils/filter.js';
+import { load } from '../../../utils/load/load.js';
+import { upgrade } from '../../../utils/upgrade.js';
+import { validate } from '../../../utils/validate.js';
+/**
+ * Takes a queue of tasks and works through them
+ */
+export async function workThroughQueue(queue) {
+    const { input } = {
+        ...queue,
+    };
+    let result = {};
+    // Work through the whole queue
+    for (const task of queue.tasks) {
+        const name = task.name;
+        const options = 'options' in task ? task.options : undefined;
+        // Use the result of the previous task, or fall back to the original input
+        const currentSpecification = result.specification
+            ? result.specification
+            : typeof input === 'object'
+                ? // Detach from the original object
+                    structuredClone(input)
+                : input;
+        // load
+        if (name === 'load') {
+            result = {
+                ...result,
+                ...(await load(input, options)),
+            };
+        }
+        // validate
+        else if (name === 'filter') {
+            result = {
+                ...result,
+                ...filter(currentSpecification, options),
+            };
+        }
+        // dereference
+        else if (name === 'dereference') {
+            result = {
+                ...result,
+                ...dereference(currentSpecification, options),
+            };
+        }
+        // upgrade
+        else if (name === 'upgrade') {
+            result = {
+                ...result,
+                ...upgrade(currentSpecification),
+            };
+        }
+        // validate
+        else if (name === 'validate') {
+            result = {
+                ...result,
+                ...(await validate(currentSpecification, options)),
+            };
+        }
+        // Make TS complain when we forgot to handle a command.
+        else {
+            name;
+        }
     }
-  }
-  return result;
+    return result;
 }
-export {
-  workThroughQueue
-};
-//# sourceMappingURL=workThroughQueue.js.map

package/dist/utils/resolve-references.js

@@ -1,124 +1,182 @@
-import { isObject } from "@scalar/helpers/object/is-object";
-import { ERRORS } from "../configuration/index.js";
-import { getEntrypoint } from "./get-entrypoint.js";
-import { getSegmentsFromPath } from "./get-segments-from-path.js";
-import { makeFilesystem } from "./make-filesystem.js";
-function resolveReferences(input, options, file, errors = []) {
-  const clonedInput = structuredClone(input);
-  const filesystem = makeFilesystem(clonedInput);
-  const entrypoint = getEntrypoint(filesystem);
-  const finalInput = file?.specification ?? entrypoint.specification;
-  if (!isObject(finalInput)) {
-    if (options?.throwOnError) {
-      throw new Error(ERRORS.NO_CONTENT);
+import { isObject } from '@scalar/helpers/object/is-object';
+import { ERRORS } from '../configuration/index.js';
+import { getEntrypoint } from './get-entrypoint.js';
+import { getSegmentsFromPath } from './get-segments-from-path.js';
+import { makeFilesystem } from './make-filesystem.js';
+/**
+ * Takes a specification and resolves all references.
+ */
+export function resolveReferences(
+// Just a specification, or a set of files.
+input, 
+// Additional options to control the behaviour
+options, 
+// Fallback to the entrypoint
+file, 
+// Errors that occurred during the process
+errors = []) {
+    // Detach from input
+    const clonedInput = structuredClone(input);
+    // Make it a filesystem, even if it's just one file
+    const filesystem = makeFilesystem(clonedInput);
+    // Get the main file
+    const entrypoint = getEntrypoint(filesystem);
+    const finalInput = file?.specification ?? entrypoint.specification;
+    // Does it look like an OpenAPI document?
+    if (!isObject(finalInput)) {
+        if (options?.throwOnError) {
+            throw new Error(ERRORS.NO_CONTENT);
+        }
+        return {
+            valid: false,
+            errors,
+            schema: finalInput,
+        };
     }
+    // Recursively resolve all references
+    dereference(finalInput, filesystem, file ?? entrypoint, new WeakSet(), errors, options);
+    // Remove duplicates (according to message) from errors
+    errors = errors.filter((error, index, self) => index === self.findIndex((t) => t.message === error.message && t.code === error.code));
+    // Return the resolved specification
     return {
-      valid: false,
-      errors,
-      schema: finalInput
+        valid: errors.length === 0,
+        errors,
+        schema: finalInput,
     };
-  }
-  dereference(finalInput, filesystem, file ?? entrypoint, /* @__PURE__ */ new WeakSet(), errors, options);
-  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: finalInput
-  };
 }
-function dereference(schema, filesystem, entrypoint, resolvedSchemas, errors, options) {
-  if (schema === null || resolvedSchemas.has(schema)) {
-    return;
-  }
-  resolvedSchemas.add(schema);
-  function resolveExternal(externalFile) {
-    dereference(externalFile.specification, filesystem, externalFile, resolvedSchemas, errors, options);
-    return externalFile;
-  }
-  const processedRefs = /* @__PURE__ */ new Set();
-  while (schema.$ref !== void 0) {
-    const selfReferenceDetected = processedRefs.has(schema.$ref);
-    if (selfReferenceDetected) {
-      errors.push({
-        code: "SELF_REFERENCE",
-        message: ERRORS.SELF_REFERENCE.replace("%s", schema.$ref)
-      });
-      delete schema.$ref;
-      break;
+/**
+ * Resolves the circular reference to an object and deletes the $ref properties (in-place).
+ */
+function dereference(schema, filesystem, entrypoint, 
+// references to resolved object
+resolvedSchemas, 
+// error output
+errors, options) {
+    if (schema === null || resolvedSchemas.has(schema)) {
+        return;
     }
-    processedRefs.add(schema.$ref);
-    const resolved = resolveUri(schema.$ref, options, entrypoint, filesystem, resolveExternal, errors);
-    if (typeof resolved !== "object" || resolved === null) {
-      break;
+    resolvedSchemas.add(schema);
+    function resolveExternal(externalFile) {
+        dereference(externalFile.specification, filesystem, externalFile, resolvedSchemas, errors, options);
+        return externalFile;
     }
-    const dereferencedRef = schema.$ref;
-    delete schema.$ref;
-    for (const key of Object.keys(resolved)) {
-      if (schema[key] === void 0) {
-        schema[key] = resolved[key];
-      }
+    /**
+     * Track seen $ref paths to detect self-referencing schemas.
+     *
+     * This only tracks $refs within the current while loop (one resolution chain).
+     * Each schema object gets its own fresh processedRefs when dereference() is called.
+     *
+     * This catches invalid cases like:
+     *   Test: { $ref: '#/components/schemas/Test' }
+     *
+     * But allows valid recursive schemas where the $ref is nested:
+     *   Person: { type: 'object', properties: { friend: { $ref: '#/components/schemas/Person' } } }
+     */
+    const processedRefs = new Set();
+    while (schema.$ref !== undefined) {
+        const selfReferenceDetected = processedRefs.has(schema.$ref);
+        if (selfReferenceDetected) {
+            errors.push({
+                code: 'SELF_REFERENCE',
+                message: ERRORS.SELF_REFERENCE.replace('%s', schema.$ref),
+            });
+            delete schema.$ref;
+            break;
+        }
+        processedRefs.add(schema.$ref);
+        // Find the referenced content
+        const resolved = resolveUri(schema.$ref, options, entrypoint, filesystem, resolveExternal, errors);
+        // invalid
+        if (typeof resolved !== 'object' || resolved === null) {
+            break;
+        }
+        const dereferencedRef = schema.$ref;
+        // Get rid of the reference
+        delete schema.$ref;
+        for (const key of Object.keys(resolved)) {
+            if (schema[key] === undefined) {
+                schema[key] = resolved[key];
+            }
+        }
+        if (dereferencedRef) {
+            options?.onDereference?.({ schema, ref: dereferencedRef });
+        }
     }
-    if (dereferencedRef) {
-      options?.onDereference?.({ schema, ref: dereferencedRef });
+    // Iterate over the whole object
+    for (const value of Object.values(schema)) {
+        if (typeof value === 'object' && value !== null) {
+            dereference(value, filesystem, entrypoint, resolvedSchemas, errors, options);
+        }
     }
-  }
-  for (const value of Object.values(schema)) {
-    if (typeof value === "object" && value !== null) {
-      dereference(value, filesystem, entrypoint, resolvedSchemas, errors, options);
-    }
-  }
 }
-function resolveUri(uri, options, file, filesystem, resolve, errors) {
-  if (typeof uri !== "string") {
-    if (options?.throwOnError) {
-      throw new Error(ERRORS.INVALID_REFERENCE.replace("%s", uri));
+/**
+ * Resolves a URI to a part of the specification
+ *
+ * The output is not necessarily dereferenced
+ */
+function resolveUri(
+// 'foobar.json#/foo/bar'
+uri, options, 
+// { filename: './foobar.json '}
+file, 
+// [ { filename: './foobar.json '} ]
+filesystem, 
+// a function to resolve references in external file
+resolve, errors) {
+    // Ignore invalid URIs
+    if (typeof uri !== 'string') {
+        if (options?.throwOnError) {
+            throw new Error(ERRORS.INVALID_REFERENCE.replace('%s', uri));
+        }
+        errors.push({
+            code: 'INVALID_REFERENCE',
+            message: ERRORS.INVALID_REFERENCE.replace('%s', uri),
+        });
+        return undefined;
     }
-    errors.push({
-      code: "INVALID_REFERENCE",
-      message: ERRORS.INVALID_REFERENCE.replace("%s", uri)
-    });
-    return void 0;
-  }
-  const [prefix, path] = uri.split("#", 2);
-  const isDifferentFile = prefix !== file.filename;
-  if (prefix && isDifferentFile) {
-    const externalReference = filesystem.find((entry) => {
-      return entry.filename === prefix;
-    });
-    if (!externalReference) {
-      if (options?.throwOnError) {
-        throw new Error(ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace("%s", prefix));
-      }
-      errors.push({
-        code: "EXTERNAL_REFERENCE_NOT_FOUND",
-        message: ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace("%s", prefix)
-      });
-      return void 0;
+    // Understand the URI
+    const [prefix, path] = uri.split('#', 2);
+    /** Check whether the file is pointing to itself */
+    const isDifferentFile = prefix !== file.filename;
+    // External references
+    if (prefix && isDifferentFile) {
+        const externalReference = filesystem.find((entry) => {
+            return entry.filename === prefix;
+        });
+        if (!externalReference) {
+            if (options?.throwOnError) {
+                throw new Error(ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', prefix));
+            }
+            errors.push({
+                code: 'EXTERNAL_REFERENCE_NOT_FOUND',
+                message: ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', prefix),
+            });
+            return undefined;
+        }
+        // $ref: 'other-file.yaml'
+        if (path === undefined) {
+            return externalReference.specification;
+        }
+        // $ref: 'other-file.yaml#/foo/bar'
+        // resolve refs first before accessing properties directly
+        return resolveUri(`#${path}`, options, resolve(externalReference), filesystem, resolve, errors);
     }
-    if (path === void 0) {
-      return externalReference.specification;
+    // Pointers
+    const segments = getSegmentsFromPath(path);
+    // Try to find the URI
+    try {
+        return segments.reduce((acc, key) => {
+            return acc[key];
+        }, file.specification);
     }
-    return resolveUri(`#${path}`, options, resolve(externalReference), filesystem, resolve, errors);
-  }
-  const segments = getSegmentsFromPath(path);
-  try {
-    return segments.reduce((acc, key) => {
-      return acc[key];
-    }, file.specification);
-  } catch (_error) {
-    if (options?.throwOnError) {
-      throw new Error(ERRORS.INVALID_REFERENCE.replace("%s", uri));
+    catch (_error) {
+        if (options?.throwOnError) {
+            throw new Error(ERRORS.INVALID_REFERENCE.replace('%s', uri));
+        }
+        errors.push({
+            code: 'INVALID_REFERENCE',
+            message: ERRORS.INVALID_REFERENCE.replace('%s', uri),
+        });
     }
-    errors.push({
-      code: "INVALID_REFERENCE",
-      message: ERRORS.INVALID_REFERENCE.replace("%s", uri)
-    });
-  }
-  return void 0;
+    return undefined;
 }
-export {
-  resolveReferences
-};
-//# sourceMappingURL=resolve-references.js.map

package/dist/utils/to-json.js

@@ -1,5 +1 @@
-const toJson = (value) => JSON.stringify(value, null, 2);
-export {
-  toJson
-};
-//# sourceMappingURL=to-json.js.map
+export const toJson = (value) => JSON.stringify(value, null, 2);

package/dist/utils/to-yaml.js

@@ -1,6 +1,2 @@
-import { stringify } from "yaml";
-const toYaml = (value) => stringify(value);
-export {
-  toYaml
-};
-//# sourceMappingURL=to-yaml.js.map
+import { stringify } from 'yaml';
+export const toYaml = (value) => stringify(value);