feat: improve errors

[fmvilas]

Description

Improves the information provided by errors. It has several improvements:

1. Uses the Problem Details spec: https://tools.ietf.org/html/rfc7807. It makes it easier to differentiate error types.
2. Uses JSON Pointers to refer indicate where's the wrong field.
3. Adds the information about the line, the column, and the offset where the error happens. It's aware of the document format (YAML/JSON) and gives you this information correctly processed for the document format.
4. It makes it easier to differentiate between JSON and YAML documents.
5. Adds more tests.

Examples

Validation error

{
  type: 'https://github.com/asyncapi/parser-js/validation-errors',
  title: 'There were errors validating the AsyncAPI document.',
  validationErrors: [{
    jsonPointer: '/components/schemas/testSchema/properties/test/$ref',
    startLine: 30,
    startColumn: 11,
    startOffset: 615,
    endLine: 30,
    endColumn: 34,
    endOffset: 638,
  }]
}

The document is not valid JSON nor YAML (YAML in this case)

{
  type: 'https://github.com/asyncapi/parser-js/invalid-yaml,
  title: 'The provided YAML is not valid.',
  detail: 'duplicated mapping key at line 2, column -4:\n    bad:\n    ^',
  location: {
    jsonPointer: '/components/schemas/testSchema/properties/test/$ref',
    startLine: 2,
    startColumn: -4,
    startOffset: 5
  }
}

A $ref couldn't be resolved

{
  type: 'https://github.com/asyncapi/parser-js/dereference-error',
  title: 'Error opening file "/Users/fmvilas/refs/refed.yaml" \nENOENT: no such file or directory, open '/Users/fmvilas/refs/refed.yaml'}',
  refs: [{
    jsonPointer: '/components/schemas/testSchema/properties/test/$ref',
    startLine: 30,
    startColumn: 11,
    startOffset: 615,
    endLine: 30,
    endColumn: 34,
    endOffset: 638,
  }]
}

How to migrate

This PR introduces a breaking change. The error classes PaserErrorNoJS and ParserErrorUnsupportedVersion don't exist anymore. Instead, we only have a single ParserError class and you can guess the type of the error by looking at the type field of the it.

ParserErrorNoJS

Before:

ParserErrorNoJS('Could not convert AsyncAPI to JSON.')

Now:

ParserError({
  type: 'impossible-to-convert-to-json',
  title: 'Could not convert AsyncAPI to JSON.',
  detail: 'Most probably the AsyncAPI document contains invalid YAML or YAML features not supported in JSON.'
})

ParserErrorUnsupportedVersion

Before:

ParserErrorUnsupportedVersion('AsyncAPI version is missing or unsupported: x.x.x.')
ParserErrorUnsupportedVersion.parsedJSON = {...}

Now:

ParserError({
  type: 'missing-asyncapi-field',
  title: 'The `asyncapi` field is missing.',
  parsedJSON: {...},
}

and

ParserError({
  type: 'unsupported-version',
  title: `Version x.x.x is not supported.`,
  detail: 'Please update to the latest version.',
  parsedJSON: {...},
  validationErrors: [{...}],
})

ParserError

Before:

ParserError('many different error messages')
ParserError.parsedJSON = {...}
ParserError.errors = [{...}]

Now:

Different ParserError errors with different type fields to make it easier to identify the kind of message. For more information, see README.md.

[derberg]

Awesome stuff, just few remarks

PR description should clearly indicate that new version will no longer support types like ParserErrorNoJS and ParserErrorUnsupportedVersion and what use in exchange. This is a breaking change and it would be explained what is replacement so when people go to this PR from release notes, they do not have to read the code.

[derberg]

I like it a lot ❤️
approved

[fmvilas]

Thanks! 🚀

[asyncapi-bot]

🎉 This PR is included in version 0.17.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀