https://github.com/asyncapi/diff
Diff is a library that compares two AsyncAPI Documents and provides information about the differences by pointing out explicitly information like breaking changes.
https://github.com/asyncapi/diff
asyncapi cli get-global-node-release-workflows get-global-releaserc javascript nodejs typescript
Last synced: 4 months ago
JSON representation
Diff is a library that compares two AsyncAPI Documents and provides information about the differences by pointing out explicitly information like breaking changes.
- Host: GitHub
- URL: https://github.com/asyncapi/diff
- Owner: asyncapi
- License: apache-2.0
- Created: 2021-05-27T09:25:09.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-06-04T19:16:30.000Z (4 months ago)
- Last Synced: 2025-06-11T13:35:59.437Z (4 months ago)
- Topics: asyncapi, cli, get-global-node-release-workflows, get-global-releaserc, javascript, nodejs, typescript
- Language: TypeScript
- Homepage:
- Size: 994 KB
- Stars: 26
- Watchers: 5
- Forks: 14
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://www.asyncapi.com)
AsyncDiff is a library that compares two AsyncAPI files and provides information about the differences by pointing out explicitly information like breaking changes.
 
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Standard object](#standard-object)
* [Overriding the standard](#overriding-the-standard)
- [Example](#example)
- [Output](#output)
- [API](#api)
- [Develop](#develop)
- [Contributing](#contributing)
- [Contributors](#contributors)
## Features
- Get explicit information about the changes you make to your AsyncAPI files, such as breaking, non-breaking and unclassified changes.
- Different types of output such as JSON, YAML and Markdown.
## Installation
```
npm install @asyncapi/diff
```
## Usage
**NOTE:** The library doesn't have a built-in parser to parse the given AsyncAPI document. Thus, you have to make sure they provide the valid & dereferenced AsyncAPI document as an input. You can use the [AsyncAPI parser](https://github.com/asyncapi/parser-js) to parse and validate the AsyncAPI file first. You can use other tools, but you **must** make sure that the document is valid and dereferenced.
```js
import { diff } from "@asyncapi/diff"; // const { diff } = require('@asyncapi/diff');
const output = diff(firstDocument, secondDocument, {
override: {
// object to override the standard
},
});
```
## Standard object
This library has a pre-configured standard which marks a change as `breaking`, `non-breaking` or `unclassified`. This standard data is stored as an object inside the [`standard.ts`](https://github.com/asyncapi/diff/blob/master/src/standard.ts) file.
The format of this standard object is explained in [this](standard-format.md) document.
### Overriding the standard
To understand the format of overriding object, take a look at [this](standard-format.md) document.
The overrides object must be passed in the following format:
```
{
[jsonPointer]: {
add: 'breaking' | 'non-breaking' | 'unclassified'
remove: 'breaking' | 'non-breaking' | 'unclassified'
edit: 'breaking' | 'non-breaking' | 'unclassified'
}
}
```
## Example
See the [index](./docs/modules/index.md) document to get all the helper methods this library offers.
1. Without any overrides
```js
const output = diff(firstDocument, secondDocument);
output.getOutput(); // the whole output data
output.breaking(); // the breaking changes
output.nonBreaking(); // the non-breaking changes
output.unclassified(); // the unclassified changes
```
2. With overrides
```js
const output = diff(firstDocument, secondDocument, {
override: {
"/servers/*/protocol": {
add: "non-breaking",
remove: "breaking",
edit: "unclassified",
},
},
});
```
## Output
This library supports outputs:
- JSON: `json`
- YAML: `yaml` or `yml`
- Markdown: `markdown` or `md`
```js
const jsonOutput = diff(firstDocument, secondDocument, {
outputType: "json",
});
const yamlOutput = diff(firstDocument, secondDocument, {
outputType: "yaml" | "yml",
});
const markdownOutput = diff(firstDocument, secondDocument, {
outputType: "markdown" | "md",
});
```
With markdown output, you can also choose subtypes of the changes as JSON(`json`) or YAML(`yaml` or `yml`).
```js
const markdownOutput = diff(firstDocument, secondDocument, {
outputType: "markdown" | "md",
markdownSubtype: "json" | "yaml" | "yml",
});
```
## API
Checkout the [index](./docs/modules/index.md) document to see all the APIs this library offers.
## Develop
1. Write code and tests
2. Make sure all tests pass `npm run test`
3. Make sure code is well formatted and secure `npm run lint`
## Contributing
Help us make this library more robust. Read [CONTRIBUTING](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md) guide & start contributing.
## Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Aayush Kumar Sahu
💻 📖 🚧 🤔 👀 ⚠️
Lukasz Gornicki
🤔 👀 🚧
Maciej Urbańczyk
👀
Jonas Lagoni
👀
Vinit Shahdeo
👀
Anubhav Vats
👀
Shiven Sinha
💻 ⚠️
Debajyoti Halder
📖
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!