@scalar/openapi-parser 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @scalar/openapi-parser
 
+## 0.15.0
+
+### Minor Changes
+
+- b9dacba: fix(openapi-parser): multi entry build for bundler plugins
+- a73e9be: chore(openapi-parser): bring back pipeline syntax
+- f4332eb: feat: external reference resolution and partial bundle of the openapi document
+
+### Patch Changes
+
+- 17bc0d8: fix: collectionFormat is not migrated to new style and explode keywords
+- 49c04cf: fix(openapi-parser): use dynamic imports inside the plugin
+
+## 0.14.0
+
+### Minor Changes
+
+- ee3eb77: feat(openapi-parser): bundle openapi documents
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -55,6 +55,163 @@ const specification = `{
 const { schema, errors } = await dereference(specification)
 ```
 
+### Bundle external references
+
+The OpenAPI specification allows to point to external files (URLs or files). But sometimes, you just want to combine all files into one.
+
+#### Plugins
+
+##### fetchUrls
+This plugins handles all external urls. It works for both node.js and browser environment
+
+```ts
+import { bundle } from '@scalar/openapi-parser'
+import { fetchUrls } from '@scalar/openapi-parser/utils/bundle/plugins/fetch-urls'
+
+const document = {
+  openapi: '3.1.0',
+  info: { title: 'Bundled API', version: '1.0.0' },
+  paths: {},
+  components: {
+    schemas: {
+      User: { $ref: 'https://example.com/user-schema.json#' }
+    }
+  }
+}
+
+// This will bundle all external documents and turn all references from external into internal
+await bundle(document, {
+  plugins: [fetchUrls()],
+  treeShake: true  // <------  This flag will try to remove any unused part of the external document
+})
+
+console.log(document)
+```
+
+###### Limiting the number of concurrent requests
+
+```ts
+await bundle(document, {
+  plugins: [
+    fetchUrls({
+      limit: 10, // it should run at most 10 requests at the same time
+    }),
+  ],
+  treeShake: false
+})
+
+```
+
+###### Custom headers
+To pass custom headers to requests for specific domains you can configure the fetch plugin like the example
+
+```ts
+await bundle(
+  document,
+  {
+    plugins: [
+      fetchUrls({
+        // Pass custom headers
+        // The header will only be attached to the list of domains
+        headers: [
+          {
+            domains: ['example.com'],
+            headers: {
+              'Authorization': 'Bearer <TOKEN>'
+            }
+          }
+        ]
+      }),
+      readFiles(),
+    ],
+    treeShake: false
+  },
+)
+```
+
+###### Custom fetch function
+For advanced use cases like proxying requests or implementing custom network logic, you can provide your own fetch implementation. This allows you to handle things like CORS restrictions, custom authentication flows, or request/response transformations.
+
+```ts
+await bundle(
+  document,
+  {
+    plugins: [
+      fetchUrls({
+        // Custom fetcher function
+        fetch: async (input, init) => {
+          console.log('Custom fetch logic')
+          return fetch(input, init)
+        },
+      })
+      readFiles(),
+    ],
+    treeShake: false
+  },
+)
+```
+
+###### Bundle from remote url
+
+```ts
+const result = await bundle(
+  'https://example.com/openapi.json',
+  {
+    plugins: [
+      fetchUrls(),
+    ],
+    treeShake: false
+  },
+)
+
+// Bundled document
+console.log(result)
+```
+
+##### readFiles
+This plugins handles local files. Only works on node.js environment
+
+```ts
+import { bundle, readFiles } from '@scalar/openapi-parser'
+
+const document = {
+  openapi: '3.1.0',
+  info: { title: 'Bundled API', version: '1.0.0' },
+  paths: {},
+  components: {
+    schemas: {
+      User: { $ref: './user-schema.json#' }
+    }
+  }
+}
+
+// This will bundle all external documents and turn all references from external into internal
+await bundle(document, {
+  plugins: [readFiles()],
+  treeShake: false
+})
+
+console.log(document)
+```
+
+###### Bundle from local file
+You can pass the file path directly but make sure to have the correct plugins to handle reading from the local files
+
+```ts
+const result = await bundle(
+  './input.json',
+  {
+    plugins: [
+      readFiles(),
+    ],
+    treeShake: false
+  },
+)
+
+// Bundled document
+console.log(result)
+```
+
 ### Track references
 
 The `dereference` function accepts an `onDereference` callback option that gets called whenever a reference is resolved. This can be useful for tracking which schemas are being dereferenced:

package/dist/index.d.ts

@@ -14,5 +14,7 @@ export { upgrade } from './utils/upgrade.js';
 export { upgradeFromThreeToThreeOne } from './utils/upgrade-from-three-to-three-one.js';
 export { upgradeFromTwoToThree } from './utils/upgrade-from-two-to-three.js';
 export { validate } from './utils/validate.js';
+export { bundle } from './utils/bundle/index.js';
 export type { LoadResult, Filesystem, AnyObject, ErrorObject } from './types/index.js';
+export { openapi } from './utils/openapi/openapi.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -14,7 +14,10 @@ import { upgrade } from "./utils/upgrade.js";
 import { upgradeFromThreeToThreeOne } from "./utils/upgrade-from-three-to-three-one.js";
 import { upgradeFromTwoToThree } from "./utils/upgrade-from-two-to-three.js";
 import { validate } from "./utils/validate.js";
+import { bundle } from "./utils/bundle/index.js";
+import { openapi } from "./utils/openapi/openapi.js";
 export {
+  bundle,
   dereference,
   escapeJsonPointer,
   filter,
@@ -22,6 +25,7 @@ export {
   isYaml,
   load,
   normalize,
+  openapi,
   sanitize,
   toJson,
   toYaml,

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["export { dereference } from './utils/dereference'\nexport { escapeJsonPointer } from './utils/escape-json-pointer'\nexport { filter } from './utils/filter'\nexport { isJson } from './utils/is-json'\nexport { isYaml } from './utils/is-yaml'\nexport { load } from './utils/load'\nexport { normalize } from './utils/normalize'\nexport { sanitize } from './utils/transform/sanitize'\nexport { toJson } from './utils/to-json'\nexport { toYaml } from './utils/to-yaml'\nexport { traverse } from './utils/traverse'\nexport { unescapeJsonPointer } from './utils/unescape-json-pointer'\nexport { upgrade } from './utils/upgrade'\nexport { upgradeFromThreeToThreeOne } from './utils/upgrade-from-three-to-three-one'\nexport { upgradeFromTwoToThree } from './utils/upgrade-from-two-to-three'\nexport { validate } from './utils/validate'\nexport type { LoadResult, Filesystem, AnyObject, ErrorObject } from './types'\n"],
-  "mappings": "AAAA,SAAS,mBAAmB;AAC5B,SAAS,yBAAyB;AAClC,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,YAAY;AACrB,SAAS,iBAAiB;AAC1B,SAAS,gBAAgB;AACzB,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,gBAAgB;AACzB,SAAS,2BAA2B;AACpC,SAAS,eAAe;AACxB,SAAS,kCAAkC;AAC3C,SAAS,6BAA6B;AACtC,SAAS,gBAAgB;",
+  "sourcesContent": ["export { dereference } from './utils/dereference'\nexport { escapeJsonPointer } from './utils/escape-json-pointer'\nexport { filter } from './utils/filter'\nexport { isJson } from './utils/is-json'\nexport { isYaml } from './utils/is-yaml'\nexport { load } from './utils/load'\nexport { normalize } from './utils/normalize'\nexport { sanitize } from './utils/transform/sanitize'\nexport { toJson } from './utils/to-json'\nexport { toYaml } from './utils/to-yaml'\nexport { traverse } from './utils/traverse'\nexport { unescapeJsonPointer } from './utils/unescape-json-pointer'\nexport { upgrade } from './utils/upgrade'\nexport { upgradeFromThreeToThreeOne } from './utils/upgrade-from-three-to-three-one'\nexport { upgradeFromTwoToThree } from './utils/upgrade-from-two-to-three'\nexport { validate } from './utils/validate'\nexport { bundle } from './utils/bundle'\nexport type { LoadResult, Filesystem, AnyObject, ErrorObject } from './types'\nexport { openapi } from './utils/openapi/openapi'\n"],
+  "mappings": "AAAA,SAAS,mBAAmB;AAC5B,SAAS,yBAAyB;AAClC,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,YAAY;AACrB,SAAS,iBAAiB;AAC1B,SAAS,gBAAgB;AACzB,SAAS,cAAc;AACvB,SAAS,cAAc;AACvB,SAAS,gBAAgB;AACzB,SAAS,2BAA2B;AACpC,SAAS,eAAe;AACxB,SAAS,kCAAkC;AAC3C,SAAS,6BAA6B;AACtC,SAAS,gBAAgB;AACzB,SAAS,cAAc;AAEvB,SAAS,eAAe;",
   "names": []
 }

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ import type { ERRORS, OpenApiVersion } from '../configuration/index.js';
  */
 export type Merge<A, B> = A & Omit<B, keyof A>;
 export type AnyObject = Record<string, any>;
+export type UnknownObject = Record<string, unknown>;
 /**
  * JSON, YAML or object representation of an OpenAPI API definition
  */

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/bundle/bundle.d.ts

@@ -0,0 +1,279 @@
+import type { UnknownObject } from '../../types/index.js';
+/**
+ * Checks if a string is a remote URL (starts with http:// or https://)
+ * @param value - The URL string to check
+ * @returns true if the string is a remote URL, false otherwise
+ * @example
+ * ```ts
+ * isRemoteUrl('https://example.com/schema.json') // true
+ * isRemoteUrl('http://api.example.com/schemas/user.json') // true
+ * isRemoteUrl('#/components/schemas/User') // false
+ * isRemoteUrl('./local-schema.json') // false
+ * ```
+ */
+export declare function isRemoteUrl(value: string): boolean;
+/**
+ * Checks if a string is a local reference (starts with #)
+ * @param value - The reference string to check
+ * @returns true if the string is a local reference, false otherwise
+ * @example
+ * ```ts
+ * isLocalRef('#/components/schemas/User') // true
+ * isLocalRef('https://example.com/schema.json') // false
+ * isLocalRef('./local-schema.json') // false
+ * ```
+ */
+export declare function isLocalRef(value: string): boolean;
+export type ResolveResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+};
+/**
+ * Retrieves a nested value from an object using an array of property segments.
+ * @param target - The target object to traverse
+ * @param segments - Array of property names representing the path to the desired value
+ * @returns The value at the specified path, or undefined if the path doesn't exist
+ * @example
+ * const obj = { foo: { bar: { baz: 42 } } };
+ * getNestedValue(obj, ['foo', 'bar', 'baz']); // returns 42
+ */
+export declare function getNestedValue(target: Record<string, any>, segments: string[]): any;
+/**
+ * Sets a value at a specified path in an object, creating intermediate objects/arrays as needed.
+ * This function traverses the object structure and creates any missing intermediate objects
+ * or arrays based on the path segments. If the next segment is a numeric string, it creates
+ * an array instead of an object.
+ *
+ * ⚠️ Warning: Be careful with object keys that look like numbers (e.g. "123") as this function
+ * will interpret them as array indices and create arrays instead of objects. If you need to
+ * use numeric-looking keys, consider prefixing them with a non-numeric character.
+ *
+ * @param obj - The target object to set the value in
+ * @param path - The JSON pointer path where the value should be set
+ * @param value - The value to set at the specified path
+ * @throws {Error} If attempting to set a value at the root path ('')
+ *
+ * @example
+ * const obj = {}
+ * setValueAtPath(obj, '/foo/bar/0', 'value')
+ * // Result:
+ * // {
+ * //   foo: {
+ * //     bar: ['value']
+ * //   }
+ * // }
+ *
+ * @example
+ * const obj = { existing: { path: 'old' } }
+ * setValueAtPath(obj, '/existing/path', 'new')
+ * // Result:
+ * // {
+ * //   existing: {
+ * //     path: 'new'
+ * //   }
+ * // }
+ *
+ * @example
+ * // ⚠️ Warning: This will create an array instead of an object with key "123"
+ * setValueAtPath(obj, '/foo/123/bar', 'value')
+ * // Result:
+ * // {
+ * //   foo: [
+ * //     undefined,
+ * //     undefined,
+ * //     undefined,
+ * //     { bar: 'value' }
+ * //   ]
+ * // }
+ */
+export declare function setValueAtPath(obj: any, path: string, value: any): void;
+/**
+ * Prefixes an internal JSON reference with a given path prefix.
+ * Takes a local reference (starting with #) and prepends the provided prefix segments.
+ *
+ * @param input - The internal reference string to prefix (must start with #)
+ * @param prefix - Array of path segments to prepend to the reference
+ * @returns The prefixed reference string
+ * @throws Error if input is not a local reference
+ * @example
+ * prefixInternalRef('#/components/schemas/User', ['definitions'])
+ * // Returns: '#/definitions/components/schemas/User'
+ */
+export declare function prefixInternalRef(input: string, prefix: string[]): string;
+/**
+ * Updates internal references in an object by adding a prefix to their paths.
+ * Recursively traverses the input object and modifies any local $ref references
+ * by prepending the given prefix to their paths. This is used when embedding external
+ * documents to maintain correct reference paths relative to the main document.
+ *
+ * @param input - The object to update references in
+ * @param prefix - Array of path segments to prepend to internal reference paths
+ * @returns void
+ * @example
+ * ```ts
+ * const input = {
+ *   foo: {
+ *     $ref: '#/components/schemas/User'
+ *   }
+ * }
+ * prefixInternalRefRecursive(input, ['definitions'])
+ * // Result:
+ * // {
+ * //   foo: {
+ * //     $ref: '#/definitions/components/schemas/User'
+ * //   }
+ * // }
+ * ```
+ */
+export declare function prefixInternalRefRecursive(input: unknown, prefix: string[]): string;
+/**
+ * Generates a short SHA-1 hash from a string value.
+ * This function is used to create unique identifiers for external references
+ * while keeping the hash length manageable. It uses the Web Crypto API to
+ * generate a SHA-1 hash and returns the first 7 characters of the hex string.
+ * If the hash would be all numbers, it ensures at least one letter is included.
+ *
+ * @param value - The string to hash
+ * @returns A 7-character hexadecimal hash with at least one letter
+ * @example
+ * // Returns "2ae91d7"
+ * await getHash("https://example.com/schema.json")
+ */
+export declare function getHash(value: string): Promise<string>;
+/**
+ * Represents a plugin that handles resolving references from external sources.
+ * Plugins are responsible for fetching and processing data from different sources
+ * like URLs or the filesystem. Each plugin must implement validation to determine
+ * if it can handle a specific reference, and an execution function to perform
+ * the actual resolution.
+ *
+ * @property validate - Determines if this plugin can handle the given reference
+ * @property exec - Fetches and processes the reference, returning the resolved data
+ */
+export type Plugin = {
+    validate: (value: string) => boolean;
+    exec: (value: string) => Promise<ResolveResult>;
+};
+/**
+ * Configuration options for the bundler.
+ * Controls how external references are resolved and processed during bundling.
+ */
+type Config = {
+    /**
+     * Array of plugins that handle resolving references from different sources.
+     * Each plugin is responsible for fetching and processing data from specific sources
+     * like URLs or the filesystem.
+     */
+    plugins: Plugin[];
+    /**
+     * Optional root object that serves as the base document when bundling a subpart.
+     * This allows resolving references relative to the root document's location,
+     * ensuring proper path resolution for nested references.
+     */
+    root?: UnknownObject;
+    /**
+     * Optional cache to store promises of resolved references.
+     * Helps avoid duplicate fetches/reads of the same resource by storing
+     * the resolution promises for reuse.
+     */
+    cache?: Map<string, Promise<ResolveResult>>;
+    /**
+     * Cache of visited nodes during partial bundling.
+     * Used to prevent re-bundling the same tree multiple times when doing partial bundling,
+     * improving performance by avoiding redundant processing of already bundled sections.
+     */
+    visitedNodes?: Set<unknown>;
+    /**
+     * Enable tree shaking to optimize the bundle size.
+     * When enabled, only the parts of external documents that are actually referenced
+     * will be included in the final bundle.
+     */
+    treeShake: boolean;
+    /**
+     * Optional flag to generate a URL map.
+     * When enabled, tracks the original source URLs of bundled references
+     * in an x-ext-urls section for reference mapping.
+     */
+    urlMap?: boolean;
+    /**
+     * Optional hooks to monitor the bundler's lifecycle.
+     * Allows tracking the progress and status of reference resolution.
+     */
+    hooks?: Partial<{
+        /** Called when starting to resolve a reference */
+        onResolveStart: (node: Record<string, unknown> & Record<'$ref', unknown>) => void;
+        /** Called when a reference resolution fails */
+        onResolveError: (node: Record<string, unknown> & Record<'$ref', unknown>) => void;
+        /** Called when a reference is successfully resolved */
+        onResolveSuccess: (node: Record<string, unknown> & Record<'$ref', unknown>) => void;
+    }>;
+};
+/**
+ * Bundles an OpenAPI specification by resolving all external references.
+ * This function traverses the input object recursively and embeds external $ref
+ * references into an x-ext section. External references can be URLs or local files.
+ * The original $refs are updated to point to their embedded content in the x-ext section.
+ * If the input is an object, it will be modified in place by adding an x-ext
+ * property to store resolved external references.
+ *
+ * @param input - The OpenAPI specification object or string to bundle. If a string is provided,
+ *                it should be a URL or file path that points to an OpenAPI specification.
+ *                The string will be resolved using the provided plugins before bundling.
+ * @param config - Configuration object containing plugins and options for bundling OpenAPI specifications
+ * @returns A promise that resolves to the bundled specification with all references embedded
+ * @example
+ * // Example with object input
+ * const spec = {
+ *   paths: {
+ *     '/users': {
+ *       $ref: 'https://example.com/schemas/users.yaml'
+ *     }
+ *   }
+ * }
+ *
+ * const bundled = await bundle(spec, {
+ *   plugins: [fetchUrls()],
+ *   treeShake: true,
+ *   urlMap: true,
+ *   hooks: {
+ *     onResolveStart: (ref) => console.log('Resolving:', ref.$ref),
+ *     onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),
+ *     onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)
+ *   }
+ * })
+ * // Result:
+ * // {
+ * //   paths: {
+ * //     '/users': {
+ * //       $ref: '#/x-ext/abc123'
+ * //     }
+ * //   },
+ * //   'x-ext': {
+ * //     'abc123': {
+ * //       // Resolved content from users.yaml
+ * //     }
+ * //   },
+ * //   'x-ext-urls': {
+ * //     'https://example.com/schemas/users.yaml': 'abc123'
+ * //   }
+ * // }
+ *
+ * // Example with URL input
+ * const bundledFromUrl = await bundle('https://example.com/openapi.yaml', {
+ *   plugins: [fetchUrls()],
+ *   treeShake: true,
+ *   urlMap: true,
+ *   hooks: {
+ *     onResolveStart: (ref) => console.log('Resolving:', ref.$ref),
+ *     onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),
+ *     onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)
+ *   }
+ * })
+ * // The function will first fetch the OpenAPI spec from the URL,
+ * // then bundle all its external references into the x-ext section
+ */
+export declare function bundle(input: UnknownObject | string, config: Config): Promise<unknown>;
+export {};
+//# sourceMappingURL=bundle.d.ts.map

package/dist/utils/bundle/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/utils/bundle/bundle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAM5C;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAA;AA2BvE;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAO7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAyBvE;AAiCD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAMhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAgB1E;AAqFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,mBAe1C;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG;IAEnB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;IAEpC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;CAChD,CAAA;AAED;;;GAGG;AACH,KAAK,MAAM,GAAG;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,EAAE,CAAA;IAEjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAA;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAE3C;;;;OAIG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;IAE3B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;QACd,kDAAkD;QAClD,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;QACjF,+CAA+C;QAC/C,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;QACjF,uDAAuD;QACvD,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;KACpF,CAAC,CAAA;CACH,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,oBAmLzE"}