@ebarahona/loopback-openapi-v3 1.0.0 → 1.1.1

package/README.md

@@ -1,8 +1,32 @@
 # @ebarahona/loopback-openapi-v3
 
-OpenAPI version compatibility enhancer for LoopBack 4. Supports emitting OpenAPI Specification (OAS) 3.0.x, 3.1.x, and 3.2.x specs from LoopBack-generated OpenAPI output, with nullable conversion and lossy downgrade diagnostics.
+OpenAPI version compatibility enhancer for LoopBack 4. Transforms LoopBack-generated OpenAPI 3.0 specs into OAS 3.1 or 3.2 at boot, handles nullable conversion both ways, and emits structured warnings for lossy downgrades.
 
-LoopBack 4 generates OpenAPI 3.0 specs by default. This component transforms the output to OpenAPI 3.1 or 3.2, enabling JSON Schema compatibility (3.1) and SSE streaming support (3.2). It also handles downgrading from higher versions to lower ones for backward compatibility.
+```bash
+npm install @ebarahona/loopback-openapi-v3
+```
+
+> Part of the [`@ebarahona/loopback-*` plugin portfolio](https://github.com/ebarahona/loopback-plugins). See the [portfolio roadmap](https://github.com/ebarahona/loopback-plugins/blob/main/ROADMAP.md) for sibling plugins (`loopback-connector-mongodb`, `loopback-transport-core`, planned `loopback-graphql`) and the shared infrastructure they use.
+
+LoopBack 4 emits OpenAPI 3.0 by default. This component registers an OAS Enhancer that runs during spec generation and rewrites the document to the target version. Upgrades convert `{type, nullable}` to `{type: [type, 'null']}` and emit 3.1+ idioms. Downgrades strip fields that have no 3.0 equivalent and emit a `TransformWarning` for each one. The enhancer is pure and deterministic, so LoopBack's spec cache reuses the result on subsequent requests.
+
+## What This Provides
+
+| Export                                | Purpose                                                                |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `OpenApiVersionComponent`             | LoopBack 4 component that registers the enhancer                       |
+| `OpenApiVersionEnhancer`              | OAS Enhancer wired into `@loopback/openapi-v3` spec generation         |
+| `OpenApiVersionBindings`              | Typed `BindingKey` namespace (`CONFIG`)                                |
+| `OpenApiVersion`                      | Version literal type (`'3.0.0' \| '3.1.0' \| '3.2.0'`)                 |
+| `OpenApiVersionConfig`                | Component config type (target version, nullable transform flag)        |
+| `transformOpenApiSpec(spec, config?)` | Pure transform function, usable outside LoopBack                       |
+| `parseVersion(version)`               | Parses `'3.1.0'` into `{major, minor, patch}`                          |
+| `TransformResult`                     | `{spec, warnings}` returned by `transformOpenApiSpec`                  |
+| `TransformWarning`                    | Structured warning describing a stripped or rewritten field            |
+| `OpenApiVersionError`                 | Base class for every error thrown by this package                      |
+| `OpenApiVersionConfigError`           | Thrown when component config is invalid                                |
+| `OpenApiTransformError`               | Thrown when the input spec cannot be transformed                       |
+| `OpenApiDowngradeError`               | Thrown when a downgrade target cannot represent required source fields |
 
 ## Install
 
@@ -12,111 +36,121 @@ npm install @ebarahona/loopback-openapi-v3
 
 ## Usage
 
+### Component path (recommended)
+
 ```typescript
-import {OpenApiVersionComponent, OpenApiVersionBindings} from '@ebarahona/loopback-openapi-v3';
+import {RestApplication} from '@loopback/rest';
+import {
+  OpenApiVersionComponent,
+  OpenApiVersionBindings,
+} from '@ebarahona/loopback-openapi-v3';
 
 const app = new RestApplication();
 app.component(OpenApiVersionComponent);
-app.bind(OpenApiVersionBindings.CONFIG).to({version: '3.1.0'});
+app.bind(OpenApiVersionBindings.CONFIG).to({
+  version: '3.1.0',
+  transformNullable: true,
+});
 ```
 
-The spec served at `/openapi.json` will output `"openapi": "3.1.0"`.
+The spec served at `/openapi.json` is rewritten to `"openapi": "3.1.0"`, with nullable fields converted to type arrays. LoopBack caches the transformed spec; the enhancer does not re-run per request.
 
-## Configuration
+### Pure-function path (standalone)
+
+`transformOpenApiSpec` is exported for use outside a LoopBack application (build-time tooling, tests, fixture generation):
 
 ```typescript
-app.bind(OpenApiVersionBindings.CONFIG).to({
-  // Target version: '3.0.0' (default, no-op), '3.1.0', or '3.2.0'
-  version: '3.1.0',
+import {transformOpenApiSpec} from '@ebarahona/loopback-openapi-v3';
 
-  // Transform nullable fields from 3.0 format to 3.1+ format
-  // { type: 'string', nullable: true } -> { type: ['string', 'null'] }
-  // Defaults to true for 3.1+
-  transformNullable: true,
+const {spec, warnings} = transformOpenApiSpec(inputSpec, {
+  version: '3.1.0',
 });
+
+for (const w of warnings) {
+  console.warn(`[${w.field}] ${w.message}`);
+}
 ```
 
-## Supported Versions
+The input spec is deep-cloned with `structuredClone`; the original is never mutated.
+
+## Configuration
+
+`OpenApiVersionBindings.CONFIG` accepts an `OpenApiVersionConfig`:
+
+| Field               | Type                            | Default   | Purpose                                                                                                |
+| ------------------- | ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
+| `version`           | `'3.0.0' \| '3.1.0' \| '3.2.0'` | `'3.0.0'` | Target OAS version. `'3.0.0'` is a no-op pass-through.                                                 |
+| `transformNullable` | `boolean`                       | `true`    | Rewrite `{type, nullable: true}` to `{type: [type, 'null']}` on upgrade, and the reverse on downgrade. |
 
-| Version | Status | Spec |
-|---|---|---|
-| 3.0.0 | Default (no-op) | [spec.openapis.org/oas/v3.0.3](https://spec.openapis.org/oas/v3.0.3.html) |
-| 3.1.0 | Supported | [spec.openapis.org/oas/v3.1.0](https://spec.openapis.org/oas/v3.1.0.html) |
-| 3.2.0 | Supported | [spec.openapis.org/oas/v3.2.0](https://spec.openapis.org/oas/v3.2.0.html) |
+Invalid configurations (unrecognized version, non-boolean flag) throw `OpenApiVersionConfigError` synchronously when the component binds.
 
-## How It Works
+## Supported versions
 
-The component registers an OAS Enhancer that runs once at boot after LoopBack assembles the spec. The original spec is deep-cloned to prevent mutation. The transformed spec is cached by LoopBack and served on subsequent requests without re-processing.
+| Version | Status        | Spec                                                                      |
+| ------- | ------------- | ------------------------------------------------------------------------- |
+| 3.0.0   | Default no-op | [spec.openapis.org/oas/v3.0.3](https://spec.openapis.org/oas/v3.0.3.html) |
+| 3.1.0   | Supported     | [spec.openapis.org/oas/v3.1.0](https://spec.openapis.org/oas/v3.1.0.html) |
+| 3.2.0   | Supported     | [spec.openapis.org/oas/v3.2.0](https://spec.openapis.org/oas/v3.2.0.html) |
 
-### Upgrades (3.0 -> 3.1/3.2)
+### Upgrades (3.0 -> 3.1 / 3.2)
 
-- `nullable: true` transformed to type arrays (`{ type: ['string', 'null'] }`)
-- Handles nullable with `oneOf`, `anyOf`, `allOf`, and no type
+- `nullable: true` rewritten to type arrays (`{type: ['string', 'null']}`).
+- Handles nullable combined with `oneOf`, `anyOf`, `allOf`, and schemas without an explicit `type`.
 
-### Downgrades (3.2 -> 3.0/3.1)
+### Downgrades (3.2 -> 3.0 / 3.1)
 
-Downgrades are lossy. Features that have no equivalent in lower versions are stripped with diagnostic warnings.
+Downgrades are lossy. Features that have no equivalent in lower versions are stripped, and a `TransformWarning` is emitted for each one.
 
 **3.1 features stripped when targeting 3.0:**
 
-| Feature | Field |
-|---|---|
-| JSON Schema dialect | `jsonSchemaDialect` |
-| Webhooks | `webhooks` |
-| Reusable path items | `components.pathItems` |
-| SPDX license identifier | `info.license.identifier` |
-| Type arrays | `type: ['string', 'null']` reverted to `nullable: true` |
+| Feature                 | Field                                          |
+| ----------------------- | ---------------------------------------------- |
+| JSON Schema dialect     | `jsonSchemaDialect`                            |
+| Webhooks                | `webhooks`                                     |
+| Reusable path items     | `components.pathItems`                         |
+| SPDX license identifier | `info.license.identifier`                      |
+| Type arrays             | `type: ['string', 'null']` -> `nullable: true` |
 
 **3.2 features stripped when targeting 3.0 or 3.1:**
 
-| Feature | Field |
-|---|---|
-| Document identity | `$self` |
-| Server name | `servers[].name` |
-| QUERY HTTP method | `paths.*. query` |
-| Additional HTTP methods | `paths.*.additionalOperations` |
-| Tag nesting | `tags[].summary`, `.parent`, `.kind` |
-| Querystring parameter | `parameters[].in: 'querystring'` converted to `'query'` |
-| OAuth2 device flow | `securitySchemes.*.flows.device` |
-| SSE streaming schema | `content.*.itemSchema` |
-| SSE streaming encoding | `content.*.itemEncoding`, `.prefixEncoding` |
-| Example formats | `examples.*.dataValue`, `.serializedValue` |
-| Reusable media types | `components.mediaTypes` |
-| XML text nodes | `xml.text` |
-
-### Diagnostics
-
-The transformer emits warnings for every stripped feature:
+| Feature                 | Field                                         |
+| ----------------------- | --------------------------------------------- |
+| Document identity       | `$self`                                       |
+| Server name             | `servers[].name`                              |
+| QUERY HTTP method       | `paths.*.query`                               |
+| Additional HTTP methods | `paths.*.additionalOperations`                |
+| Tag nesting             | `tags[].summary`, `.parent`, `.kind`          |
+| Querystring parameter   | `parameters[].in: 'querystring'` -> `'query'` |
+| OAuth2 device flow      | `securitySchemes.*.flows.device`              |
+| SSE streaming schema    | `content.*.itemSchema`                        |
+| SSE streaming encoding  | `content.*.itemEncoding`, `.prefixEncoding`   |
+| Example formats         | `examples.*.dataValue`, `.serializedValue`    |
+| Reusable media types    | `components.mediaTypes`                       |
+| XML text nodes          | `xml.text`                                    |
 
-```typescript
-import {transformOpenApiSpec} from '@ebarahona/loopback-openapi-v3';
+When a required source field cannot be expressed in the target version (for example a 3.2 spec that depends on `$self` referenced elsewhere in the document), the transform raises `OpenApiDowngradeError` instead of silently dropping the reference.
 
-const {spec, warnings} = transformOpenApiSpec(inputSpec, {version: '3.0.0'});
-for (const w of warnings) {
-  console.log(`[${w.field}] ${w.message}`);
-}
-// [webhooks] Removed webhooks because target version is 3.0.x (webhooks require 3.1+)
-// [$self] Removed $self because target version is 3.0.x
-```
+## Typed errors
 
-### Pure Function API
+This package throws four typed error classes, all derived from `OpenApiVersionError`. Catch the base class for a category check, or the specific subclass for fine-grained handling.
 
-The transformer is available as a standalone pure function for use outside LoopBack:
+- `OpenApiVersionError`: abstract base. Every error thrown by this package extends it.
+- `OpenApiVersionConfigError`: invalid component configuration. Thrown synchronously when the component binds or when `transformOpenApiSpec` is called with an unsupported target version.
+- `OpenApiTransformError`: input spec is structurally invalid (missing `openapi` field, unparsable version string, cyclic schema references).
+- `OpenApiDowngradeError`: a downgrade target cannot represent a load-bearing source field. The error includes the offending field path and the source/target version pair.
 
-```typescript
-import {transformOpenApiSpec, parseVersion} from '@ebarahona/loopback-openapi-v3';
+## Stability
 
-const {spec, warnings} = transformOpenApiSpec(inputSpec, {version: '3.1.0'});
-```
+Every export listed in [What This Provides](#what-this-provides) is tagged `@public` from v1.0 onward. The public-API surface is audited by the `/lb4-public-api-audit` skill before every release; experimental additions are tagged `@experimental` until at least one real consumer has exercised the surface.
 
 ## Requirements
 
-- Node.js >= 18 (for `structuredClone`)
-- LoopBack 4 (`@loopback/core` >= 7.0.0)
-- `@loopback/openapi-v3` >= 11.0.0
-- `@loopback/rest` >= 15.0.0
+- Node.js >= 20.19.0 (for `structuredClone` and the package's engines field)
+- LoopBack 4 application
+
+Peer dependencies: `@loopback/core` (>=7.0.0 <8.0.0), `@loopback/openapi-v3` (>=11.0.0 <12.0.0), `@loopback/rest` (>=15.0.0 <16.0.0).
 
-## Spec References
+## Spec references
 
 - [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3.html)
 - [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0.html)
@@ -125,7 +159,7 @@ const {spec, warnings} = transformOpenApiSpec(inputSpec, {version: '3.1.0'});
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md). Help-wanted topics with measurable acceptance criteria are listed in [HELP_WANTED.md](HELP_WANTED.md).
 
 ## License
 

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export interface OpenApiErrorOptions {
+    cause?: unknown;
+}
+export declare class OpenApiVersionError extends Error {
+    readonly name: string;
+    readonly cause?: unknown;
+    constructor(message: string, options?: OpenApiErrorOptions);
+}
+export declare class OpenApiVersionConfigError extends OpenApiVersionError {
+    readonly name = "OpenApiVersionConfigError";
+}
+export declare class OpenApiTransformError extends OpenApiVersionError {
+    readonly name = "OpenApiTransformError";
+}
+export declare class OpenApiDowngradeError extends OpenApiVersionError {
+    readonly unsupportedFeatures: readonly string[];
+    readonly name = "OpenApiDowngradeError";
+    constructor(message: string, unsupportedFeatures: readonly string[], options?: OpenApiErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiDowngradeError = exports.OpenApiTransformError = exports.OpenApiVersionConfigError = exports.OpenApiVersionError = void 0;
+class OpenApiVersionError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'OpenApiVersionError';
+        if (options && 'cause' in options) {
+            this.cause = options.cause;
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.OpenApiVersionError = OpenApiVersionError;
+class OpenApiVersionConfigError extends OpenApiVersionError {
+    constructor() {
+        super(...arguments);
+        this.name = 'OpenApiVersionConfigError';
+    }
+}
+exports.OpenApiVersionConfigError = OpenApiVersionConfigError;
+class OpenApiTransformError extends OpenApiVersionError {
+    constructor() {
+        super(...arguments);
+        this.name = 'OpenApiTransformError';
+    }
+}
+exports.OpenApiTransformError = OpenApiTransformError;
+class OpenApiDowngradeError extends OpenApiVersionError {
+    constructor(message, unsupportedFeatures, options) {
+        super(message, options);
+        this.unsupportedFeatures = unsupportedFeatures;
+        this.name = 'OpenApiDowngradeError';
+    }
+}
+exports.OpenApiDowngradeError = OpenApiDowngradeError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AA8BA,MAAa,mBAAoB,SAAQ,KAAK;IAG5C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAW,qBAAqB,CAAC;QAOrD,IAAI,OAAO,IAAI,OAAO,IAAI,OAAO,EAAE;YACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;SAC5B;QACD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAbD,kDAaC;AAQD,MAAa,yBAA0B,SAAQ,mBAAmB;IAAlE;;QACoB,SAAI,GAAG,2BAA2B,CAAC;IACvD,CAAC;CAAA;AAFD,8DAEC;AAQD,MAAa,qBAAsB,SAAQ,mBAAmB;IAA9D;;QACoB,SAAI,GAAG,uBAAuB,CAAC;IACnD,CAAC;CAAA;AAFD,sDAEC;AAUD,MAAa,qBAAsB,SAAQ,mBAAmB;IAE5D,YACE,OAAe,EACC,mBAAsC,EACtD,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAHR,wBAAmB,GAAnB,mBAAmB,CAAmB;QAHtC,SAAI,GAAG,uBAAuB,CAAC;IAOjD,CAAC;CACF;AATD,sDASC"}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { OpenApiVersionComponent } from './openapi-version.component';
 export { OpenApiVersionEnhancer } from './openapi-version.enhancer';
 export { OpenApiVersionBindings } from './keys';
-export { OpenApiVersion, OpenApiVersionConfig } from './types';
-export { transformOpenApiSpec, parseVersion, TransformResult, TransformWarning, } from './transform';
+export type { OpenApiVersion, OpenApiVersionConfig } from './types';
+export { transformOpenApiSpec, parseVersion } from './transform';
+export type { TransformResult, TransformWarning } from './transform';
+export { OpenApiVersionError, OpenApiVersionConfigError, OpenApiTransformError, OpenApiDowngradeError, } from './errors';
+export type { OpenApiErrorOptions } from './errors';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseVersion = exports.transformOpenApiSpec = exports.OpenApiVersionBindings = exports.OpenApiVersionEnhancer = exports.OpenApiVersionComponent = void 0;
+exports.OpenApiDowngradeError = exports.OpenApiTransformError = exports.OpenApiVersionConfigError = exports.OpenApiVersionError = exports.parseVersion = exports.transformOpenApiSpec = exports.OpenApiVersionBindings = exports.OpenApiVersionEnhancer = exports.OpenApiVersionComponent = void 0;
 var openapi_version_component_1 = require("./openapi-version.component");
 Object.defineProperty(exports, "OpenApiVersionComponent", { enumerable: true, get: function () { return openapi_version_component_1.OpenApiVersionComponent; } });
 var openapi_version_enhancer_1 = require("./openapi-version.enhancer");
@@ -10,4 +10,9 @@ Object.defineProperty(exports, "OpenApiVersionBindings", { enumerable: true, get
 var transform_1 = require("./transform");
 Object.defineProperty(exports, "transformOpenApiSpec", { enumerable: true, get: function () { return transform_1.transformOpenApiSpec; } });
 Object.defineProperty(exports, "parseVersion", { enumerable: true, get: function () { return transform_1.parseVersion; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "OpenApiVersionError", { enumerable: true, get: function () { return errors_1.OpenApiVersionError; } });
+Object.defineProperty(exports, "OpenApiVersionConfigError", { enumerable: true, get: function () { return errors_1.OpenApiVersionConfigError; } });
+Object.defineProperty(exports, "OpenApiTransformError", { enumerable: true, get: function () { return errors_1.OpenApiTransformError; } });
+Object.defineProperty(exports, "OpenApiDowngradeError", { enumerable: true, get: function () { return errors_1.OpenApiDowngradeError; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yEAAoE;AAA5D,oIAAA,uBAAuB,OAAA;AAC/B,uEAAkE;AAA1D,kIAAA,sBAAsB,OAAA;AAC9B,+BAA8C;AAAtC,8GAAA,sBAAsB,OAAA;AAE9B,yCAKqB;AAJnB,iHAAA,oBAAoB,OAAA;AACpB,yGAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAUA,yEAAoE;AAA5D,oIAAA,uBAAuB,OAAA;AAE/B,uEAAkE;AAA1D,kIAAA,sBAAsB,OAAA;AAE9B,+BAA8C;AAAtC,8GAAA,sBAAsB,OAAA;AAI9B,yCAA+D;AAAvD,iHAAA,oBAAoB,OAAA;AAAE,yGAAA,YAAY,OAAA;AAI1C,mCAKkB;AAJhB,6GAAA,mBAAmB,OAAA;AACnB,mHAAA,yBAAyB,OAAA;AACzB,+GAAA,qBAAqB,OAAA;AACrB,+GAAA,qBAAqB,OAAA"}

package/dist/keys.d.ts

@@ -1,5 +1,5 @@
 import { BindingKey } from '@loopback/core';
-import { OpenApiVersionConfig } from './types';
+import type { OpenApiVersionConfig } from './types';
 export declare namespace OpenApiVersionBindings {
     const CONFIG: BindingKey<OpenApiVersionConfig>;
     const COMPONENT = "openapi-version.component";

package/dist/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";;;AAAA,yCAA0C;AAG1C,IAAiB,sBAAsB,CAKtC;AALD,WAAiB,sBAAsB;IACxB,6BAAM,GAAG,iBAAU,CAAC,MAAM,CACrC,wBAAwB,CACzB,CAAC;IACW,gCAAS,GAAG,2BAA2B,CAAC;AACvD,CAAC,EALgB,sBAAsB,sCAAtB,sBAAsB,QAKtC"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";;;AAAA,yCAA0C;AAQ1C,IAAiB,sBAAsB,CAgBtC;AAhBD,WAAiB,sBAAsB;IAMxB,6BAAM,GAAG,iBAAU,CAAC,MAAM,CACrC,wBAAwB,CACzB,CAAC;IAOW,gCAAS,GAAG,2BAA2B,CAAC;AACvD,CAAC,EAhBgB,sBAAsB,sCAAtB,sBAAsB,QAgBtC"}

package/dist/openapi-version.component.d.ts

@@ -1,4 +1,5 @@
-import { Binding, Component } from '@loopback/core';
+import { Binding } from '@loopback/core';
+import type { Component } from '@loopback/core';
 export declare class OpenApiVersionComponent implements Component {
     bindings: Binding[];
 }

package/dist/openapi-version.component.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-version.component.js","sourceRoot":"","sources":["../src/openapi-version.component.ts"],"names":[],"mappings":";;;AAAA,yCAIwB;AACxB,qDAAoD;AACpD,iCAA8C;AAC9C,yEAAkE;AAClE,mCAAuC;AAavC,MAAa,uBAAuB;IAApC;QACE,aAAQ,GAAc;YACpB,cAAO,CAAC,IAAI,CAAC,6BAAsB,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,sBAAc,CAAC;YAC9D,IAAA,6BAAsB,EAAC,iDAAsB,CAAC,CAAC,KAAK,CAAC,2BAAc,CAAC;SACrE,CAAC;IACJ,CAAC;CAAA;AALD,0DAKC"}
+{"version":3,"file":"openapi-version.component.js","sourceRoot":"","sources":["../src/openapi-version.component.ts"],"names":[],"mappings":";;;AAAA,yCAA+D;AAE/D,qDAAoD;AACpD,iCAA8C;AAC9C,yEAAkE;AAClE,mCAAuC;AAevC,MAAa,uBAAuB;IAApC;QACE,aAAQ,GAAc;YACpB,cAAO,CAAC,IAAI,CAAC,6BAAsB,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,sBAAc,CAAC;YAC9D,IAAA,6BAAsB,EAAC,iDAAsB,CAAC,CAAC,KAAK,CAAC,2BAAc,CAAC;SACrE,CAAC;IACJ,CAAC;CAAA;AALD,0DAKC"}

package/dist/openapi-version.enhancer.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-version.enhancer.js","sourceRoot":"","sources":["../src/openapi-version.enhancer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,yCAAkD;AAKlD,iCAAiC;AACjC,iCAA8C;AAC9C,2CAAiD;AACjD,mCAA6D;AAE7D,MAAM,KAAK,GAAG,IAAA,eAAY,EAAC,0BAA0B,CAAC,CAAC;AAqBhD,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAGjC,YAEE,UAAwC,sBAAc;QAA9C,YAAO,GAAP,OAAO,CAAuC;QAJxD,SAAI,GAAG,iBAAiB,CAAC;IAKtB,CAAC;IAEJ,UAAU,CAAC,IAAiB;QAC1B,MAAM,IAAI,GAAG,EAAC,GAAG,sBAAc,EAAE,GAAG,IAAI,CAAC,OAAO,EAAC,CAAC;QAClD,KAAK,CACH,8DAA8D,EAC9D,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,iBAAiB,KAAK,KAAK,CACjC,CAAC;QACF,MAAM,MAAM,GAAG,IAAA,gCAAoB,EACjC,IAA+B,EAC/B,IAAI,CACL,CAAC;QAEF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;YAC9B,KAAK,CAAC,2CAA2C,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC3E,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE;gBAC/B,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;aAC/C;SACF;QAED,OAAO,MAAM,CAAC,IAAmB,CAAC;IACpC,CAAC;CACF,CAAA;AA7BY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,iBAAU,GAAE;IAKR,WAAA,IAAA,aAAM,EAAC,EAAC,WAAW,EAAE,6BAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAC,CAAC,CAAA;;GAJ5D,sBAAsB,CA6BlC"}
+{"version":3,"file":"openapi-version.enhancer.js","sourceRoot":"","sources":["../src/openapi-version.enhancer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,yCAAkD;AAElD,iCAAiC;AACjC,iCAA8C;AAC9C,2CAAiD;AACjD,mCAA6D;AAE7D,MAAM,KAAK,GAAG,IAAA,eAAY,EAAC,0BAA0B,CAAC,CAAC;AAuBhD,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAGjC,YAEE,UAAwC,sBAAc;QAA9C,YAAO,GAAP,OAAO,CAAuC;QAJxD,SAAI,GAAG,iBAAiB,CAAC;IAKtB,CAAC;IAEJ,UAAU,CAAC,IAAiB;QAC1B,MAAM,IAAI,GAAG,EAAC,GAAG,sBAAc,EAAE,GAAG,IAAI,CAAC,OAAO,EAAC,CAAC;QAClD,KAAK,CACH,8DAA8D,EAC9D,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,iBAAiB,KAAK,KAAK,CACjC,CAAC;QACF,MAAM,MAAM,GAAG,IAAA,gCAAoB,EAAC,IAA+B,EAAE,IAAI,CAAC,CAAC;QAE3E,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;YAC9B,KAAK,CACH,2CAA2C,EAC3C,MAAM,CAAC,QAAQ,CAAC,MAAM,CACvB,CAAC;YACF,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE;gBAC/B,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;aAC/C;SACF;QAED,OAAO,MAAM,CAAC,IAAmB,CAAC;IACpC,CAAC;CACF,CAAA;AA7BY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,iBAAU,GAAE;IAKR,WAAA,IAAA,aAAM,EAAC,EAAC,WAAW,EAAE,6BAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAC,CAAC,CAAA;;GAJ5D,sBAAsB,CA6BlC"}

package/dist/transform.d.ts

@@ -1,4 +1,4 @@
-import { OpenApiVersionConfig } from './types';
+import type { OpenApiVersionConfig } from './types';
 interface Obj {
     [key: string]: unknown;
 }

package/dist/transform.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformOpenApiSpec = exports.parseVersion = void 0;
+const errors_1 = require("./errors");
 const types_1 = require("./types");
 const SUPPORTED_MINORS = [0, 1, 2];
 function isSupportedMinor(minor) {
@@ -16,23 +17,23 @@ function warnOnce(warnings, seen, field, message) {
 function parseVersion(version) {
     const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
     if (!match) {
-        throw new Error(`Invalid OpenAPI version: "${version}". Expected format: "3.x.x"`);
+        throw new errors_1.OpenApiVersionConfigError(`Invalid OpenAPI version: "${version}". Expected format: "3.x.x"`);
     }
     const major = Number(match[1]);
     const minor = Number(match[2]);
     const patch = Number(match[3]);
     if (major !== 3) {
-        throw new Error(`Unsupported OpenAPI major version: ${major}. Only version 3.x is supported.`);
+        throw new errors_1.OpenApiVersionConfigError(`Unsupported OpenAPI major version: ${major}. Only version 3.x is supported.`);
     }
     if (!isSupportedMinor(minor)) {
-        throw new Error(`Unsupported OpenAPI minor version: 3.${minor}. Supported: 3.0.x, 3.1.x, 3.2.x`);
+        throw new errors_1.OpenApiVersionConfigError(`Unsupported OpenAPI minor version: 3.${minor}. Supported: 3.0.x, 3.1.x, 3.2.x`);
     }
     return { major, minor, patch };
 }
 exports.parseVersion = parseVersion;
 function transformOpenApiSpec(spec, config = types_1.DEFAULT_CONFIG) {
     if (typeof spec.openapi !== 'string') {
-        throw new Error('Invalid OpenAPI spec: missing required string field "openapi".');
+        throw new errors_1.OpenApiTransformError('Invalid OpenAPI spec: missing required string field "openapi".');
     }
     const sourceVersion = parseVersion(spec.openapi);
     const targetVersion = parseVersion(config.version);
@@ -45,7 +46,9 @@ function transformOpenApiSpec(spec, config = types_1.DEFAULT_CONFIG) {
     if (sourceMinor === targetMinor) {
         return { spec: out, warnings };
     }
-    if (config.transformNullable !== false && targetMinor >= 1 && sourceMinor < 1) {
+    if (config.transformNullable !== false &&
+        targetMinor >= 1 &&
+        sourceMinor < 1) {
         upgradeNullable(out);
     }
     if (targetMinor < 2 && sourceMinor >= 2) {
@@ -98,8 +101,10 @@ function downgradeNullable(spec, warnings, seen) {
             if (!Array.isArray(s[key]))
                 continue;
             const arr = s[key];
-            const nullIdx = arr.findIndex(item => typeof item === 'object' && item !== null &&
-                Object.keys(item).length === 1 && item.type === 'null');
+            const nullIdx = arr.findIndex(item => typeof item === 'object' &&
+                item !== null &&
+                Object.keys(item).length === 1 &&
+                item.type === 'null');
             if (nullIdx !== -1) {
                 arr.splice(nullIdx, 1);
                 s.nullable = true;
@@ -189,7 +194,9 @@ function strip32Features(spec, targetMinor, warnings, seen) {
         for (const tag of spec.tags) {
             if (tag && typeof tag === 'object') {
                 const t = tag;
-                if (t.summary !== undefined || t.parent !== undefined || t.kind !== undefined) {
+                if (t.summary !== undefined ||
+                    t.parent !== undefined ||
+                    t.kind !== undefined) {
                     delete t.summary;
                     delete t.parent;
                     delete t.kind;
@@ -307,7 +314,9 @@ function walkAllSchemas(spec, visitor) {
                     visit(p);
             }
         }
-        if (schema.items && typeof schema.items === 'object' && !('$ref' in schema.items)) {
+        if (schema.items &&
+            typeof schema.items === 'object' &&
+            !('$ref' in schema.items)) {
             visit(schema.items);
         }
         for (const key of ['allOf', 'oneOf', 'anyOf', 'prefixItems']) {
@@ -318,7 +327,9 @@ function walkAllSchemas(spec, visitor) {
                 }
             }
         }
-        if (schema.not && typeof schema.not === 'object' && !('$ref' in schema.not)) {
+        if (schema.not &&
+            typeof schema.not === 'object' &&
+            !('$ref' in schema.not)) {
             visit(schema.not);
         }
         if (schema.additionalProperties &&
@@ -332,10 +343,14 @@ function walkAllSchemas(spec, visitor) {
             const media = content[mt];
             if (!media || typeof media !== 'object')
                 continue;
-            if (media.schema && typeof media.schema === 'object' && !('$ref' in media.schema)) {
+            if (media.schema &&
+                typeof media.schema === 'object' &&
+                !('$ref' in media.schema)) {
                 visit(media.schema);
             }
-            if (media.itemSchema && typeof media.itemSchema === 'object' && !('$ref' in media.itemSchema)) {
+            if (media.itemSchema &&
+                typeof media.itemSchema === 'object' &&
+                !('$ref' in media.itemSchema)) {
                 visit(media.itemSchema);
             }
         }
@@ -345,7 +360,9 @@ function walkAllSchemas(spec, visitor) {
             if (!p || typeof p !== 'object' || '$ref' in p)
                 continue;
             const param = p;
-            if (param.schema && typeof param.schema === 'object' && !('$ref' in param.schema)) {
+            if (param.schema &&
+                typeof param.schema === 'object' &&
+                !('$ref' in param.schema)) {
                 visit(param.schema);
             }
             if (param.content && typeof param.content === 'object') {
@@ -369,7 +386,9 @@ function walkAllSchemas(spec, visitor) {
                 const p = params[name];
                 if (p && typeof p === 'object' && !('$ref' in p)) {
                     const param = p;
-                    if (param.schema && typeof param.schema === 'object' && !('$ref' in param.schema)) {
+                    if (param.schema &&
+                        typeof param.schema === 'object' &&
+                        !('$ref' in param.schema)) {
                         visit(param.schema);
                     }
                 }
@@ -404,7 +423,9 @@ function walkAllSchemas(spec, visitor) {
                 if (!h || typeof h !== 'object' || '$ref' in h)
                     continue;
                 const header = h;
-                if (header.schema && typeof header.schema === 'object' && !('$ref' in header.schema)) {
+                if (header.schema &&
+                    typeof header.schema === 'object' &&
+                    !('$ref' in header.schema)) {
                     visit(header.schema);
                 }
             }
@@ -419,7 +440,17 @@ function walkAllSchemas(spec, visitor) {
             if (Array.isArray(pi.parameters)) {
                 visitParams(pi.parameters);
             }
-            const verbs = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace', 'query'];
+            const verbs = [
+                'get',
+                'post',
+                'put',
+                'patch',
+                'delete',
+                'options',
+                'head',
+                'trace',
+                'query',
+            ];
             for (const verb of verbs) {
                 const op = pi[verb];
                 if (!op || typeof op !== 'object')
@@ -465,7 +496,17 @@ function walkAllSchemas(spec, visitor) {
     }
 }
 function forEachOperation(spec, visitor) {
-    const verbs = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace', 'query'];
+    const verbs = [
+        'get',
+        'post',
+        'put',
+        'patch',
+        'delete',
+        'options',
+        'head',
+        'trace',
+        'query',
+    ];
     function visitPathItems(pathsObj, prefix) {
         for (const path in pathsObj) {
             const item = pathsObj[path];