@scalar/openapi-parser 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/openapi-parser
 
+## 0.14.0
+
+### Minor Changes
+
+- ee3eb77: feat(openapi-parser): bundle openapi documents
+
+## 0.13.0
+
+### Minor Changes
+
+- 1e87feb: fix: normalize doesn’t handle empty documents well
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -55,6 +55,140 @@ 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, fetchUrls } from '@scalar/openapi-parser'
+
+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
+  },
+)
+```
+
+###### 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/configuration/index.d.ts

@@ -3897,8 +3897,8 @@ export declare const OpenApiVersions: OpenApiVersion[];
  * List of error messages used in the Validator
  */
 export declare const ERRORS: {
-    readonly EMPTY_OR_INVALID: "Can’t find JSON, YAML or filename in data";
-    readonly OPENAPI_VERSION_NOT_SUPPORTED: "Can’t find supported Swagger/OpenAPI version in specification, version must be a string.";
+    readonly EMPTY_OR_INVALID: "Can’t find JSON, YAML or filename in data.";
+    readonly OPENAPI_VERSION_NOT_SUPPORTED: "Can’t find supported Swagger/OpenAPI version in the provided document, version must be a string.";
     readonly INVALID_REFERENCE: "Can’t resolve reference: %s";
     readonly EXTERNAL_REFERENCE_NOT_FOUND: "Can’t resolve external reference: %s";
     readonly FILE_DOES_NOT_EXIST: "File does not exist: %s";

package/dist/configuration/index.js

@@ -8,9 +8,9 @@ const OpenApiSpecifications = {
 };
 const OpenApiVersions = Object.keys(OpenApiSpecifications);
 const ERRORS = {
-  EMPTY_OR_INVALID: "Can\u2019t find JSON, YAML or filename in data",
+  EMPTY_OR_INVALID: "Can\u2019t find JSON, YAML or filename in data.",
   // URI_MUST_BE_STRING: 'uri parameter or $id attribute must be a string',
-  OPENAPI_VERSION_NOT_SUPPORTED: "Can\u2019t find supported Swagger/OpenAPI version in specification, version must be a string.",
+  OPENAPI_VERSION_NOT_SUPPORTED: "Can\u2019t find supported Swagger/OpenAPI version in the provided document, version must be a string.",
   INVALID_REFERENCE: "Can\u2019t resolve reference: %s",
   EXTERNAL_REFERENCE_NOT_FOUND: "Can\u2019t resolve external reference: %s",
   FILE_DOES_NOT_EXIST: "File does not exist: %s",

package/dist/configuration/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/configuration/index.ts"],
-  "sourcesContent": ["import Swagger20 from '@/schemas/v2.0/schema'\nimport OpenApi30 from '@/schemas/v3.0/schema'\nimport OpenApi31 from '@/schemas/v3.1/schema'\n\n/**\n * A list of the supported OpenAPI specifications\n */\nexport const OpenApiSpecifications = {\n  '2.0': Swagger20,\n  '3.0': OpenApi30,\n  '3.1': OpenApi31,\n}\n\nexport type OpenApiVersion = keyof typeof OpenApiSpecifications\n\nexport const OpenApiVersions = Object.keys(OpenApiSpecifications) as OpenApiVersion[]\n\n/**\n * List of error messages used in the Validator\n */\nexport const ERRORS = {\n  EMPTY_OR_INVALID: 'Can\u2019t find JSON, YAML or filename in data',\n  // URI_MUST_BE_STRING: 'uri parameter or $id attribute must be a string',\n  OPENAPI_VERSION_NOT_SUPPORTED:\n    'Can\u2019t find supported Swagger/OpenAPI version in specification, version must be a string.',\n  INVALID_REFERENCE: 'Can\u2019t resolve reference: %s',\n  EXTERNAL_REFERENCE_NOT_FOUND: 'Can\u2019t resolve external reference: %s',\n  FILE_DOES_NOT_EXIST: 'File does not exist: %s',\n  NO_CONTENT: 'No content found',\n} as const\n\nexport type ValidationError = keyof typeof ERRORS\n"],
+  "sourcesContent": ["import Swagger20 from '@/schemas/v2.0/schema'\nimport OpenApi30 from '@/schemas/v3.0/schema'\nimport OpenApi31 from '@/schemas/v3.1/schema'\n\n/**\n * A list of the supported OpenAPI specifications\n */\nexport const OpenApiSpecifications = {\n  '2.0': Swagger20,\n  '3.0': OpenApi30,\n  '3.1': OpenApi31,\n}\n\nexport type OpenApiVersion = keyof typeof OpenApiSpecifications\n\nexport const OpenApiVersions = Object.keys(OpenApiSpecifications) as OpenApiVersion[]\n\n/**\n * List of error messages used in the Validator\n */\nexport const ERRORS = {\n  EMPTY_OR_INVALID: 'Can\u2019t find JSON, YAML or filename in data.',\n  // URI_MUST_BE_STRING: 'uri parameter or $id attribute must be a string',\n  OPENAPI_VERSION_NOT_SUPPORTED:\n    'Can\u2019t find supported Swagger/OpenAPI version in the provided document, version must be a string.',\n  INVALID_REFERENCE: 'Can\u2019t resolve reference: %s',\n  EXTERNAL_REFERENCE_NOT_FOUND: 'Can\u2019t resolve external reference: %s',\n  FILE_DOES_NOT_EXIST: 'File does not exist: %s',\n  NO_CONTENT: 'No content found',\n} as const\n\nexport type ValidationError = keyof typeof ERRORS\n"],
   "mappings": "AAAA,OAAO,eAAe;AACtB,OAAO,eAAe;AACtB,OAAO,eAAe;AAKf,MAAM,wBAAwB;AAAA,EACnC,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AACT;AAIO,MAAM,kBAAkB,OAAO,KAAK,qBAAqB;AAKzD,MAAM,SAAS;AAAA,EACpB,kBAAkB;AAAA;AAAA,EAElB,+BACE;AAAA,EACF,mBAAmB;AAAA,EACnB,8BAA8B;AAAA,EAC9B,qBAAqB;AAAA,EACrB,YAAY;AACd;",
   "names": []
 }

package/dist/index.d.ts

@@ -14,5 +14,6 @@ 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, fetchUrls, readFiles } from './utils/bundle/index.js';
 export type { LoadResult, Filesystem, AnyObject, ErrorObject } from './types/index.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,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -14,14 +14,18 @@ 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, fetchUrls, readFiles } from "./utils/bundle/index.js";
 export {
+  bundle,
   dereference,
   escapeJsonPointer,
+  fetchUrls,
   filter,
   isJson,
   isYaml,
   load,
   normalize,
+  readFiles,
   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, fetchUrls, readFiles } from './utils/bundle'\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;AACzB,SAAS,QAAQ,WAAW,iBAAiB;",
   "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,193 @@
+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.
+ *
+ * @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'
+ * //   }
+ * // }
+ */
+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.
+ *
+ * @param value - The string to hash
+ * @returns A 7-character hexadecimal hash
+ * @example
+ * // Returns "a1b2c3d"
+ * 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>;
+};
+type Config = {
+    plugins: Plugin[];
+    root?: UnknownObject;
+    cache?: Map<string, Promise<ResolveResult>>;
+    treeShake: boolean;
+    urlMap?: boolean;
+};
+/**
+ * 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 for resolving references
+ * @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()] })
+ * // Result:
+ * // {
+ * //   paths: {
+ * //     '/users': {
+ * //       $ref: '#/x-ext/https~1~1example.com~1schemas~1users.yaml'
+ * //     }
+ * //   },
+ * //   'x-ext': {
+ * //     'https~1~1example.com~1schemas~1users.yaml': {
+ * //       // Resolved content from users.yaml
+ * //     }
+ * //   }
+ * // }
+ *
+ * // Example with URL input
+ * const bundledFromUrl = await bundle('https://example.com/openapi.yaml', { plugins: [fetchUrls()] })
+ * // 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,mBAa1C;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,KAAK,MAAM,GAAG;IAEZ,OAAO,EAAE,MAAM,EAAE,CAAA;IAGjB,IAAI,CAAC,EAAE,aAAa,CAAA;IAEpB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAE3C,SAAS,EAAE,OAAO,CAAA;IAElB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,oBA2IzE"}

package/dist/utils/bundle/bundle.js

@@ -0,0 +1,197 @@
+import { escapeJsonPointer } from "../../utils/escape-json-pointer.js";
+import path from "../../polyfills/path.js";
+import { getSegmentsFromPath } from "../../utils/get-segments-from-path.js";
+import { isObject } from "../../utils/is-object.js";
+function isRemoteUrl(value) {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+function isLocalRef(value) {
+  return value.startsWith("#");
+}
+async function resolveContents(value, plugins) {
+  const plugin = plugins.find((p) => p.validate(value));
+  if (plugin) {
+    return plugin.exec(value);
+  }
+  return {
+    ok: false
+  };
+}
+function getNestedValue(target, segments) {
+  return segments.reduce((acc, key) => {
+    if (acc === void 0) {
+      return void 0;
+    }
+    return acc[key];
+  }, target);
+}
+function setValueAtPath(obj, path2, value) {
+  if (path2 === "") {
+    throw new Error("Cannot set value at root ('') pointer");
+  }
+  const parts = getSegmentsFromPath(path2);
+  let current = obj;
+  for (let i = 0; i < parts.length; i++) {
+    const key = parts[i];
+    const isLast = i === parts.length - 1;
+    const nextKey = parts[i + 1];
+    const shouldBeArray = /^\d+$/.test(nextKey ?? "");
+    if (isLast) {
+      current[key] = value;
+    } else {
+      if (!(key in current) || typeof current[key] !== "object") {
+        current[key] = shouldBeArray ? [] : {};
+      }
+      current = current[key];
+    }
+  }
+}
+function resolveReferencePath(base, relativePath) {
+  if (isRemoteUrl(relativePath)) {
+    return relativePath;
+  }
+  if (isRemoteUrl(base)) {
+    const url = new URL(base);
+    const mergedPath = path.join(path.dirname(url.pathname), relativePath);
+    return new URL(mergedPath, base).toString();
+  }
+  return path.join(path.dirname(base), relativePath);
+}
+function prefixInternalRef(input, prefix) {
+  if (!isLocalRef(input)) {
+    throw "Please provide an internal ref";
+  }
+  return `#/${prefix.map(escapeJsonPointer).join("/")}${input.substring(1)}`;
+}
+function prefixInternalRefRecursive(input, prefix) {
+  if (!isObject(input)) {
+    return;
+  }
+  Object.values(input).forEach((el) => prefixInternalRefRecursive(el, prefix));
+  if (typeof input === "object" && "$ref" in input && typeof input["$ref"] === "string") {
+    const ref = input["$ref"];
+    if (!isLocalRef(ref)) {
+      return;
+    }
+    return input["$ref"] = prefixInternalRef(ref, prefix);
+  }
+}
+const resolveAndCopyReferences = (targetDocument, sourceDocument, referencePath, externalRefsKey, documentKey, processedNodes = /* @__PURE__ */ new Set()) => {
+  const referencedValue = getNestedValue(sourceDocument, getSegmentsFromPath(referencePath));
+  if (processedNodes.has(referencedValue)) {
+    return;
+  }
+  processedNodes.add(referencedValue);
+  setValueAtPath(targetDocument, referencePath, referencedValue);
+  const traverse = (node) => {
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    if ("$ref" in node && typeof node["$ref"] === "string") {
+      if (node["$ref"].startsWith(`#/${externalRefsKey}/${escapeJsonPointer(documentKey)}`)) {
+        resolveAndCopyReferences(
+          targetDocument,
+          sourceDocument,
+          node["$ref"].substring(1),
+          documentKey,
+          externalRefsKey,
+          processedNodes
+        );
+      }
+    }
+    for (const value of Object.values(node)) {
+      traverse(value);
+    }
+  };
+  traverse(referencedValue);
+};
+async function getHash(value) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(value);
+  const hashBuffer = await crypto.subtle.digest("SHA-1", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex.slice(0, 7);
+}
+async function bundle(input, config) {
+  const cache = config.cache ?? /* @__PURE__ */ new Map();
+  const resolveInput = async () => {
+    if (typeof input !== "string") {
+      return input;
+    }
+    const result = await resolveContents(input, config.plugins);
+    if (result.ok) {
+      return result.data;
+    }
+    throw "Please provide a valid string value or pass a loader to process the input";
+  };
+  const rawSpecification = await resolveInput();
+  const documentRoot = config.root ?? rawSpecification;
+  const EXTERNAL_KEY = "x-ext";
+  const EXTERNAL_URL_MAPPING = "x-ext-urls";
+  const bundler = async (root, origin = typeof input === "string" ? input : "") => {
+    if (!isObject(root) && !Array.isArray(root)) {
+      return;
+    }
+    if (typeof root === "object" && "$ref" in root && typeof root["$ref"] === "string") {
+      const ref = root["$ref"];
+      if (isLocalRef(ref)) {
+        return;
+      }
+      const [prefix, path2 = ""] = ref.split("#", 2);
+      const resolvedPath = resolveReferencePath(origin, prefix);
+      const hashPath = await getHash(resolvedPath);
+      const seen = cache.has(resolvedPath);
+      if (!seen) {
+        cache.set(resolvedPath, resolveContents(resolvedPath, config.plugins));
+      }
+      const result = await cache.get(resolvedPath);
+      if (result.ok) {
+        if (!seen) {
+          prefixInternalRefRecursive(result.data, [EXTERNAL_KEY, hashPath]);
+          await bundler(result.data, resolvedPath);
+          if (config.urlMap) {
+            setValueAtPath(documentRoot, `/${EXTERNAL_URL_MAPPING}/${escapeJsonPointer(resolvedPath)}`, hashPath);
+          }
+        }
+        if (config.treeShake === true) {
+          resolveAndCopyReferences(
+            documentRoot,
+            { [EXTERNAL_KEY]: { [hashPath]: result.data } },
+            prefixInternalRef(`#${path2}`, [EXTERNAL_KEY, hashPath]).substring(1),
+            EXTERNAL_KEY,
+            hashPath
+          );
+        } else if (!seen) {
+          setValueAtPath(documentRoot, `/${EXTERNAL_KEY}/${hashPath}`, result.data);
+        }
+        root.$ref = prefixInternalRef(`#${path2}`, [EXTERNAL_KEY, hashPath]);
+        return;
+      }
+      return console.warn(
+        `Failed to resolve external reference "${prefix}". The reference may be invalid, inaccessible, or missing a loader for this type of reference.`
+      );
+    }
+    await Promise.all(
+      Object.entries(root).map(async ([key, value]) => {
+        if (key === EXTERNAL_KEY) {
+          return;
+        }
+        await bundler(value, origin);
+      })
+    );
+  };
+  await bundler(rawSpecification);
+  return rawSpecification;
+}
+export {
+  bundle,
+  getHash,
+  getNestedValue,
+  isLocalRef,
+  isRemoteUrl,
+  prefixInternalRef,
+  prefixInternalRefRecursive,
+  setValueAtPath
+};
+//# sourceMappingURL=bundle.js.map