fix(parser): add throwOnError option to surface validation failures (#878)

[Guciolek]

Summary

Fixes #878 by adding an opt-in throwOnError option to Parser#parse() that surfaces validation failures as a typed AsyncAPIParseError instead of silently returning a result with document: undefined.

Problem

When the parser encounters an invalid AsyncAPI document, it currently returns:

{ document: undefined, diagnostics: [...], extras: { document } }

This silent-failure mode is easy to miss — especially for the legacy .document() accessor which throws a confusing is not a function error if you don't first null-check.

The original report from #878:

The Parser doesn't throw any error when I provide an invalid asyncapi file but instead returns undefined

Fix

Added throwOnError?: boolean to ParseOptions. When true and the input produces at least one error-severity diagnostic, the parser throws a new AsyncAPIParseError that carries:

• name — 'AsyncAPIParseError'
• message — human-readable description
• diagnostics — the full Diagnostic[] from validation
• document — the resolved Spectral Document (when available) for advanced inspection

The default is false, so this is fully backward compatible.

Usage

import { Parser, AsyncAPIParseError } from '@asyncapi/parser';

const parser = new Parser();

try {
  const { document } = await parser.parse(invalidDoc, { throwOnError: true });
  // document is guaranteed to be defined here
} catch (err) {
  if (err instanceof AsyncAPIParseError) {
    console.error(err.message);
    for (const d of err.diagnostics) {
      console.error(`  [${d.code}] ${d.message}`);
    }
  }
}

Tests

• 6 new tests in test/parse.spec.ts covering:
  • default (silent) behavior preserved
  • explicit throwOnError: false preserved
  • throwOnError: true throws AsyncAPIParseError on invalid input
  • thrown error exposes diagnostics
  • valid document still parses without throwing
  • diagnostics with warnings/info only do not throw
• 2472 tests pass (2466 existing + 6 new), zero regressions.

Notes

• This is intentionally a non-breaking change. I'm not changing the default behavior because the existing test suite explicitly asserts document === undefined for invalid inputs and many downstream consumers rely on it.
• Closes the long-standing request in Parser fails to throw an error when i provide an invalid asyncapi file #878 without breaking any existing API contract.

[changeset-bot]

🦋 Changeset detected

Latest commit: 990fa1f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@asyncapi/parser	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud