|
1 | | -# diff |
| 1 | +<h5 align="center"> |
| 2 | + <a href="https://www.asyncapi.org"><img src="https://github.com/asyncapi/parser-nodejs/raw/master/assets/logo.png" alt="AsyncAPI logo" width="200"></a> |
| 3 | + <br> |
| 4 | + Diff |
| 5 | +</h5> |
| 6 | +<p align="center"> |
| 7 | + <em> |
| 8 | + AsyncDiff is a library that compares two AsyncAPI files and provides information about the differences by pointing out explicitly information like breaking changes. |
| 9 | + </em> |
| 10 | +</p> |
2 | 11 |
|
3 | | -AsyncDiff is a library which compares two AsyncAPI Documents and provides information about the differences by pointing out explicitly informations like breaking changes. |
| 12 | +  |
4 | 13 |
|
5 | | -## Note |
| 14 | +<!-- toc is generated with GitHub Actions do not remove toc markers --> |
6 | 15 |
|
7 | | -The library doesn't have a built-in parser to parse the given AsyncAPI document. Thus, users have to make sure they provide the valid & dereferenced AsyncAPI document as the input. |
| 16 | +<!-- toc --> |
8 | 17 |
|
9 | | -Users can use the [AsyncAPI parser](https://github.com/asyncapi/parser-js) to parse the document, or they can use other tools. Though they **must** make sure that the document is valid & dereferenced in case they use other tools to parse the documents. |
| 18 | +- [Installation](#installation) |
| 19 | +- [Usage](#usage) |
| 20 | +- [Standard object](#standard-object) |
| 21 | + - [Overriding the standard](#overriding-the-standard) |
| 22 | +- [Example](#example) |
| 23 | +- [API](#api) |
| 24 | +- [Develop](#develop) |
| 25 | +- [Contributing](#contributing) |
| 26 | + |
| 27 | +<!-- tocstop --> |
| 28 | + |
| 29 | +## Installation |
| 30 | + |
| 31 | +``` |
| 32 | +npm install @asyncapi/diff |
| 33 | +``` |
| 34 | + |
| 35 | +## Usage |
| 36 | + |
| 37 | +**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. |
| 38 | + |
| 39 | +```js |
| 40 | +import { diff } from '@asyncapi/diff'; // const { diff } = require('@asyncapi/diff'); |
| 41 | + |
| 42 | +const output = diff(firstDocument, secondDocument, { |
| 43 | + overrides: { |
| 44 | + // object to override the standard |
| 45 | + }, |
| 46 | +}); |
| 47 | +``` |
| 48 | + |
| 49 | +## Standard object |
| 50 | + |
| 51 | +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. |
| 52 | + |
| 53 | +The format of this standard object is explained in [this](standard-format.md) document. |
| 54 | + |
| 55 | +### Overriding the standard |
| 56 | + |
| 57 | +To understand the format of overriding object, take a look at [this](standard-format.md) document. |
| 58 | + |
| 59 | +The overrides object must be passed in the following format: |
| 60 | + |
| 61 | +``` |
| 62 | +{ |
| 63 | + [jsonPointer]: { |
| 64 | + add: 'breaking' | 'non-breaking' | 'unclassified' |
| 65 | + remove: 'breaking' | 'non-breaking' | 'unclassified' |
| 66 | + edit: 'breaking' | 'non-breaking' | 'unclassified' |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +## Example |
| 72 | + |
| 73 | +See the [API](API.md) document to get all the helper methods this library offers. |
| 74 | + |
| 75 | +1. Without any overrides |
| 76 | + |
| 77 | +```js |
| 78 | +const output = diff(firstDocument, secondDocument); |
| 79 | + |
| 80 | +output.getOutput(); // the whole output data |
| 81 | +output.breaking(); // the breaking changes |
| 82 | +output.nonBreaking(); // the non-breaking changes |
| 83 | +output.unclassified(); // the unclassified changes |
| 84 | +``` |
| 85 | + |
| 86 | +2. With overrides |
| 87 | + |
| 88 | +```js |
| 89 | +const output = diff(firstDocument, secondDocument, { |
| 90 | + overrides: { |
| 91 | + '/servers/*/protocol': { |
| 92 | + add: 'non-breaking', |
| 93 | + remove: 'breaking', |
| 94 | + edit: 'unclassified', |
| 95 | + }, |
| 96 | + }, |
| 97 | +}); |
| 98 | +``` |
| 99 | + |
| 100 | +## API |
| 101 | + |
| 102 | +Checkout the [API](API.md) document to see all the APIs this library offers. |
| 103 | + |
| 104 | +## Develop |
| 105 | + |
| 106 | +1. Write code and tests |
| 107 | +2. Make sure all tests pass `npm run test` |
| 108 | +3. Make sure code is well formatted and secure `npm run lint` |
| 109 | + |
| 110 | +## Contributing |
| 111 | + |
| 112 | +Help us make this library more robust. Read [CONTRIBUTING](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md) guide & start contributing. |
0 commit comments