@scalar/openapi-parser 0.8.6 → 0.8.8

package/dist/utils/load/load.js

@@ -1 +1,121 @@
-import{ERRORS as e}from"../../configuration/index.js";import{getEntrypoint as i}from"../getEntrypoint.js";import{getListOfReferences as r}from"../getListOfReferences.js";import{makeFilesystem as s}from"../makeFilesystem.js";import{normalize as t}from"../normalize.js";async function n(o,f){const c=[];if(f?.filesystem?.find((e=>e.filename===o)))return{specification:i(f.filesystem)?.specification,filesystem:f.filesystem,errors:c};const l=f?.plugins?.find((e=>e.check(o)));let a;if(l)try{a=t(await l.get(o))}catch(i){if(f?.throwOnError)throw new Error(e.EXTERNAL_REFERENCE_NOT_FOUND.replace("%s",o));return c.push({code:"EXTERNAL_REFERENCE_NOT_FOUND",message:e.EXTERNAL_REFERENCE_NOT_FOUND.replace("%s",o)}),{specification:null,filesystem:[],errors:c}}else a=t(o);if(void 0===a){if(f?.throwOnError)throw new Error("No content to load");return c.push({code:"NO_CONTENT",message:e.NO_CONTENT}),{specification:null,filesystem:[],errors:c}}let m=s(a,{filename:f?.filename??null});const E=(f?.filename?m.find((e=>e.filename===f?.filename)):i(m)).references??r(a);if(0===E.length)return{specification:i(m)?.specification,filesystem:m,errors:c};for(const e of E){const i=f?.plugins?.find((i=>i.check(e)));if(!i)continue;const r=i.check(e)&&i.resolvePath?i.resolvePath(o,e):e;if(m.find((i=>i.filename===e)))continue;const{filesystem:s,errors:t}=await n(r,{...f,filename:e});c.push(...t),m=[...m,...s.map((e=>({...e,isEntrypoint:!1})))]}return{specification:i(m)?.specification,filesystem:m,errors:c}}export{n as load};
+import { ERRORS } from '../../configuration/index.js';
+import { getEntrypoint } from '../getEntrypoint.js';
+import { getListOfReferences } from '../getListOfReferences.js';
+import { makeFilesystem } from '../makeFilesystem.js';
+import { normalize } from '../normalize.js';
+
+/**
+ * Loads an OpenAPI document, including any external references.
+ *
+ * This function handles loading content from various sources, normalizes the content,
+ * and recursively loads any external references found within the definition.
+ *
+ * It builds a filesystem representation of all loaded content and collects any errors
+ * encountered during the process.
+ */
+async function load(value, options) {
+    const errors = [];
+    // Don’t load a reference twice, check the filesystem before fetching something
+    if (options?.filesystem?.find((entry) => entry.filename === value)) {
+        return {
+            specification: getEntrypoint(options.filesystem)?.specification,
+            filesystem: options.filesystem,
+            errors,
+        };
+    }
+    // Check whether the value is an URL or file path
+    const plugin = options?.plugins?.find((thisPlugin) => thisPlugin.check(value));
+    let content;
+    if (plugin) {
+        try {
+            content = normalize(await plugin.get(value));
+        }
+        catch (error) {
+            if (options?.throwOnError) {
+                throw new Error(ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', value));
+            }
+            errors.push({
+                code: 'EXTERNAL_REFERENCE_NOT_FOUND',
+                message: ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', value),
+            });
+            return {
+                specification: null,
+                filesystem: [],
+                errors,
+            };
+        }
+    }
+    else {
+        content = normalize(value);
+    }
+    // No content
+    if (content === undefined) {
+        if (options?.throwOnError) {
+            throw new Error('No content to load');
+        }
+        errors.push({
+            code: 'NO_CONTENT',
+            message: ERRORS.NO_CONTENT,
+        });
+        return {
+            specification: null,
+            filesystem: [],
+            errors,
+        };
+    }
+    let filesystem = makeFilesystem(content, {
+        filename: options?.filename ?? null,
+    });
+    // Get references from file system entry, or from the content
+    const newEntry = options?.filename
+        ? filesystem.find((entry) => entry.filename === options?.filename)
+        : getEntrypoint(filesystem);
+    const listOfReferences = newEntry.references ?? getListOfReferences(content);
+    // No other references
+    if (listOfReferences.length === 0) {
+        return {
+            specification: getEntrypoint(filesystem)?.specification,
+            filesystem,
+            errors,
+        };
+    }
+    // Load other external references
+    for (const reference of listOfReferences) {
+        // Find a matching plugin
+        const otherPlugin = options?.plugins?.find((thisPlugin) => thisPlugin.check(reference));
+        // Skip if no plugin is found (internal references don’t need a plugin for example)
+        if (!otherPlugin) {
+            continue;
+        }
+        const target = otherPlugin.check(reference) && otherPlugin.resolvePath
+            ? otherPlugin.resolvePath(value, reference)
+            : reference;
+        // Don’t load a reference twice, check the filesystem before fetching something
+        if (filesystem.find((entry) => entry.filename === reference)) {
+            continue;
+        }
+        const { filesystem: referencedFiles, errors: newErrors } = 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,
+        });
+        errors.push(...newErrors);
+        filesystem = [
+            ...filesystem,
+            ...referencedFiles.map((file) => {
+                return {
+                    ...file,
+                    isEntrypoint: false,
+                };
+            }),
+        ];
+    }
+    return {
+        specification: getEntrypoint(filesystem)?.specification,
+        filesystem,
+        errors,
+    };
+}
+
+export { load };

package/dist/utils/makeFilesystem.js

@@ -1 +1,25 @@
-import{getListOfReferences as e}from"./getListOfReferences.js";import{isFilesystem as r}from"./isFilesystem.js";import{normalize as i}from"./normalize.js";function t(t,n={}){if(r(t))return t;const o=i(t);return[{isEntrypoint:!0,specification:o,filename:null,dir:"./",references:e(o),...n}]}export{t as makeFilesystem};
+import { getListOfReferences } from './getListOfReferences.js';
+import { isFilesystem } from './isFilesystem.js';
+import { normalize } from './normalize.js';
+
+function makeFilesystem(value, overwrites = {}) {
+    // Keep as is
+    if (isFilesystem(value)) {
+        return value;
+    }
+    // Make an object
+    const specification = normalize(value);
+    // Create fake filesystem
+    return [
+        {
+            isEntrypoint: true,
+            specification,
+            filename: null,
+            dir: './',
+            references: getListOfReferences(specification),
+            ...overwrites,
+        },
+    ];
+}
+
+export { makeFilesystem };

package/dist/utils/normalize.js

@@ -1 +1,25 @@
-import{parse as r}from"yaml";import{isFilesystem as t}from"./isFilesystem.js";function e(e){if(t(e))return e;if("string"==typeof e)try{return JSON.parse(e)}catch(t){return r(e,{maxAliasCount:1e4})}return e}export{e as normalize};
+import { parse } from 'yaml';
+import { isFilesystem } from './isFilesystem.js';
+
+/**
+ * Normalize the OpenAPI specification to a JavaScript object.
+ * Don’t touch the object if it’s a `Filesystem` (multiple files).
+ */
+function normalize(specification) {
+    if (isFilesystem(specification)) {
+        return specification;
+    }
+    if (typeof specification === 'string') {
+        try {
+            return JSON.parse(specification);
+        }
+        catch (error) {
+            return parse(specification, {
+                maxAliasCount: 10000,
+            });
+        }
+    }
+    return specification;
+}
+
+export { normalize };

package/dist/utils/openapi/actions/details.js

@@ -1 +1,13 @@
-import{details as t}from"../../details.js";import{getEntrypoint as i}from"../../getEntrypoint.js";import{workThroughQueue as o}from"../utils/workThroughQueue.js";async function r(r){const{filesystem:s}=await o(r);return t(i(s).specification)}export{r as details};
+import { details as details$1 } from '../../details.js';
+import { getEntrypoint } from '../../getEntrypoint.js';
+import { workThroughQueue } from '../utils/workThroughQueue.js';
+
+/**
+ * Run the chained tasks and return just some basic information about the OpenAPI document
+ */
+async function details(queue) {
+    const { filesystem } = await workThroughQueue(queue);
+    return details$1(getEntrypoint(filesystem).specification);
+}
+
+export { details };

package/dist/utils/openapi/actions/files.js

@@ -1 +1,11 @@
-import{workThroughQueue as t}from"../utils/workThroughQueue.js";async function o(o){const{filesystem:r}=await t(o);return r}export{o as files};
+import { workThroughQueue } from '../utils/workThroughQueue.js';
+
+/**
+ * Run the chained tasks and return just the filesystem
+ */
+async function files(queue) {
+    const { filesystem } = await workThroughQueue(queue);
+    return filesystem;
+}
+
+export { files };

package/dist/utils/openapi/actions/get.js

@@ -1 +1,13 @@
-import{workThroughQueue as r}from"../utils/workThroughQueue.js";async function t(t){return{filesystem:[],...await r(t)}}export{t as get};
+import { workThroughQueue } from '../utils/workThroughQueue.js';
+
+/**
+ * Run the chained tasks and return the results
+ */
+async function get(queue) {
+    return {
+        filesystem: [],
+        ...(await workThroughQueue(queue)),
+    };
+}
+
+export { get };

package/dist/utils/openapi/actions/toJson.js

@@ -1 +1,13 @@
-import{getEntrypoint as o}from"../../getEntrypoint.js";import{toJson as t}from"../../toJson.js";import{workThroughQueue as r}from"../utils/workThroughQueue.js";async function s(s){const{filesystem:i}=await r(s);return t(o(i).specification)}export{s as toJson};
+import { getEntrypoint } from '../../getEntrypoint.js';
+import { toJson as toJson$1 } from '../../toJson.js';
+import { workThroughQueue } from '../utils/workThroughQueue.js';
+
+/**
+ * Run the chained tasks and return the results
+ */
+async function toJson(queue) {
+    const { filesystem } = await workThroughQueue(queue);
+    return toJson$1(getEntrypoint(filesystem).specification);
+}
+
+export { toJson };

package/dist/utils/openapi/actions/toYaml.js

@@ -1 +1,13 @@
-import{getEntrypoint as t}from"../../getEntrypoint.js";import{toYaml as o}from"../../toYaml.js";import{workThroughQueue as r}from"../utils/workThroughQueue.js";async function i(i){const{filesystem:s}=await r(i);return o(t(s).specification)}export{i as toYaml};
+import { getEntrypoint } from '../../getEntrypoint.js';
+import { toYaml as toYaml$1 } from '../../toYaml.js';
+import { workThroughQueue } from '../utils/workThroughQueue.js';
+
+/**
+ * Run the chained tasks and return the results
+ */
+async function toYaml(queue) {
+    const { filesystem } = await workThroughQueue(queue);
+    return toYaml$1(getEntrypoint(filesystem).specification);
+}
+
+export { toYaml };

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

@@ -1 +1,29 @@
-import{details as o}from"../actions/details.js";import{files as t}from"../actions/files.js";import{get as r}from"../actions/get.js";import{toJson as s}from"../actions/toJson.js";import{toYaml as i}from"../actions/toYaml.js";import{queueTask as n}from"../utils/queueTask.js";function e(e,m){const a={name:"dereference",options:{throwOnError:e.options?.throwOnError,...m??{}}},f=n(e,a);return{details:()=>o(f),files:()=>t(f),get:()=>r(f),toJson:()=>s(f),toYaml:()=>i(f)}}export{e as dereferenceCommand};
+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';
+
+/**
+ * Dereference the given OpenAPI document
+ */
+function dereferenceCommand(previousQueue, options) {
+    const task = {
+        name: 'dereference',
+        options: {
+            throwOnError: previousQueue.options?.throwOnError,
+            ...(options ?? {}),
+        },
+    };
+    const queue = queueTask(previousQueue, task);
+    return {
+        details: () => details(queue),
+        files: () => files(queue),
+        get: () => get(queue),
+        toJson: () => toJson(queue),
+        toYaml: () => toYaml(queue),
+    };
+}
+
+export { dereferenceCommand };

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

@@ -1 +1,28 @@
-import{details as o}from"../actions/details.js";import{files as t}from"../actions/files.js";import{get as e}from"../actions/get.js";import{toJson as r}from"../actions/toJson.js";import{toYaml as s}from"../actions/toYaml.js";import{queueTask as i}from"../utils/queueTask.js";import{dereferenceCommand as m}from"./dereferenceCommand.js";function n(n,f){const a=i(n,{name:"filter",options:f});return{dereference:o=>m(a,o),details:()=>o(a),files:()=>t(a),get:()=>e(a),toJson:()=>r(a),toYaml:()=>s(a)}}export{n as filterCommand};
+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';
+
+/**
+ * Filter the given OpenAPI document
+ */
+function filterCommand(previousQueue, options) {
+    const task = {
+        name: 'filter',
+        options,
+    };
+    const queue = queueTask(previousQueue, task);
+    return {
+        dereference: (dereferenceOptions) => dereferenceCommand(queue, dereferenceOptions),
+        details: () => details(queue),
+        files: () => files(queue),
+        get: () => get(queue),
+        toJson: () => toJson(queue),
+        toYaml: () => toYaml(queue),
+    };
+}
+
+export { filterCommand };

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

@@ -1 +1,44 @@
-import{details as o}from"../actions/details.js";import{files as r}from"../actions/files.js";import{get as t}from"../actions/get.js";import{toJson as m}from"../actions/toJson.js";import{toYaml as i}from"../actions/toYaml.js";import{queueTask as e}from"../utils/queueTask.js";import{dereferenceCommand as s}from"./dereferenceCommand.js";import{filterCommand as n}from"./filterCommand.js";import{upgradeCommand as a}from"./upgradeCommand.js";import{validateCommand as f}from"./validateCommand.js";function p(p,d,l){const j={name:"load",options:{throwOnError:p.options?.throwOnError,...l}},c={...e(p,j),input:d};return{dereference:o=>s(c,o),details:()=>o(c),files:()=>r(c),filter:o=>n(c,o),get:()=>t(c),upgrade:()=>a(c),toJson:()=>m(c),toYaml:()=>i(c),validate:o=>f(c,o)}}export{p as loadCommand};
+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';
+import { validateCommand } from './validateCommand.js';
+
+/**
+ * Pass any OpenAPI document
+ */
+function loadCommand(previousQueue, input, options) {
+    const task = {
+        name: 'load',
+        options: {
+            // global
+            throwOnError: previousQueue.options?.throwOnError,
+            // local
+            ...options,
+        },
+    };
+    const queue = {
+        // Add the load task
+        ...queueTask(previousQueue, task),
+        // Add input to the queue
+        input,
+    };
+    return {
+        dereference: (dereferenceOptions) => dereferenceCommand(queue, dereferenceOptions),
+        details: () => details(queue),
+        files: () => files(queue),
+        filter: (callback) => filterCommand(queue, callback),
+        get: () => get(queue),
+        upgrade: () => upgradeCommand(queue),
+        toJson: () => toJson(queue),
+        toYaml: () => toYaml(queue),
+        validate: (validateOptions) => validateCommand(queue, validateOptions),
+    };
+}
+
+export { loadCommand };

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

@@ -1 +1,31 @@
-import{details as o}from"../actions/details.js";import{files as t}from"../actions/files.js";import{get as r}from"../actions/get.js";import{toJson as m}from"../actions/toJson.js";import{toYaml as e}from"../actions/toYaml.js";import{queueTask as i}from"../utils/queueTask.js";import{dereferenceCommand as s}from"./dereferenceCommand.js";import{filterCommand as a}from"./filterCommand.js";import{validateCommand as n}from"./validateCommand.js";function f(f){const l=i(f,{name:"upgrade"});return{dereference:o=>s(l,o),details:()=>o(l),files:()=>t(l),filter:o=>a(l,o),get:()=>r(l),toJson:()=>m(l),toYaml:()=>e(l),validate:o=>n(l,o)}}export{f as upgradeCommand};
+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
+ */
+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 };

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

@@ -1 +1,35 @@
-import{details as o}from"../actions/details.js";import{files as r}from"../actions/files.js";import{get as t}from"../actions/get.js";import{toJson as m}from"../actions/toJson.js";import{toYaml as e}from"../actions/toYaml.js";import{queueTask as i}from"../utils/queueTask.js";import{dereferenceCommand as s}from"./dereferenceCommand.js";import{filterCommand as n}from"./filterCommand.js";import{upgradeCommand as a}from"./upgradeCommand.js";function f(f,p){const d={name:"validate",options:{throwOnError:f.options?.throwOnError,...p??{}}},l=i(f,d);return{dereference:o=>s(l,o),details:()=>o(l),files:()=>r(l),filter:o=>n(l,o),get:()=>t(l),toJson:()=>m(l),toYaml:()=>e(l),upgrade:()=>a(l)}}export{f as validateCommand};
+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
+ */
+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 };

package/dist/utils/openapi/openapi.js

@@ -1 +1,18 @@
-import{loadCommand as o}from"./commands/loadCommand.js";function n(n){const t={input:null,options:n,tasks:[]};return{load:(n,m)=>o(t,n,m)}}export{n as openapi};
+import { loadCommand } from './commands/loadCommand.js';
+
+/**
+ * Creates a fluent OpenAPI pipeline
+ */
+function openapi(globalOptions) {
+    // Create a new queue
+    const queue = {
+        input: null,
+        options: globalOptions,
+        tasks: [],
+    };
+    return {
+        load: (input, options) => loadCommand(queue, input, options),
+    };
+}
+
+export { openapi };

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

@@ -1 +1,11 @@
-function t(t,s){return{...t,tasks:[...t.tasks,s]}}export{t as queueTask};
+/**
+ * Add a new task to the existing queue
+ */
+function queueTask(queue, task) {
+    return {
+        ...queue,
+        tasks: [...queue.tasks, task],
+    };
+}
+
+export { queueTask };

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

@@ -1 +1,67 @@
-import{dereference as o}from"../../dereference.js";import{filter as t}from"../../filter.js";import{load as e}from"../../load/load.js";import{upgrade as i}from"../../upgrade.js";import{validate as r}from"../../validate.js";async function a(a){const{input:n}={...a};let s={};for(const f of a.tasks){const a=f.name,p="options"in f?f.options:void 0,c=s.specification?s.specification:"object"==typeof n?structuredClone(n):n;"load"===a?s={...s,...await e(n,p)}:"filter"===a?s={...s,...t(c,p)}:"dereference"===a?s={...s,...await o(c,p)}:"upgrade"===a?s={...s,...i(c)}:"validate"===a&&(s={...s,...await r(c,p)})}return s}export{a as workThroughQueue};
+import { dereference } from '../../dereference.js';
+import { filter } from '../../filter.js';
+import { upgrade } from '../../upgrade.js';
+import { validate } from '../../validate.js';
+import { load } from '../../load/load.js';
+
+/**
+ * Takes a queue of tasks and works through them
+ */
+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,
+                ...(await 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 ;
+    }
+    return result;
+}
+
+export { workThroughQueue };