Publishing Version 3

[otakustay]

The Goal

From the very begining of this library, more than 5 years have past, I noticed I haven't update it for a long time, community demand on TypeScript increase fast in this period.

To support TypeScript, we once tried #148 to add types without any breaking change, but this is extremely difficult, later I decide to have a big refactor on my codebase and allow myself to introduce a few breaking changes in edge cases.

Version 3 is mostly aimed to add types, I tried my best to NOT add breaking changes, this includes:

1. All component props, util function signatures keeps the same as before.
2. This package is still published as a singled bundled file, allowing you to reference it from CDN via <script> tag.
3. The tokenize dependency refractor is not updated, still uses 2.x version.
4. Dependencies are not changed, even though all of them are not used in runtime (because they are bundled in a single file).

We expect a Upgrade-And-Go experience when you upgrading to 3.0.0.

The Type

I added types to all components and util functions, most of them are strict.

The interesting is our ChangeData type is a union type of 3 interfaces:

export interface InsertChange {
    type: 'insert';
    content: string;
    lineNumber: number;
    isInsert: true;
}

export interface DeleteChange {
    type: 'delete';
    content: string;
    lineNumber: number;
    isDelete: true;
}

export interface NormalChange {
    type: 'normal';
    content: string;
    isNormal: true;
    oldLineNumber: number;
    newLineNumber: number;
}

export type ChangeData = InsertChange | DeleteChange | NormalChange;

From now on you can't destruct a ChangeData object without checking its type, code like this will report a type error:

function getLineNumberOfChange(change: ChangeData) {
    const {isNormal, oldLineNumber, lineNumber} = change;
    return isNormal ? oldLineNumber : lineNumber;
}

I added 3 util functions (isInsert(change), isDelete(change), isNormal(change)) to help discriminstae the type of a ChangeData object, use it like this:

import {isNormal} from 'react-diff-view';

function getLineNumberOfChange(change: ChangeData) {
    return isNormal(change) ? change.oldLineNumber : change.lineNumber;
}

You may encounter many type errors upgrading to 3.0.0, however I expect runtime behavior to stay unchanged, on any type problem, feel free to raise a question on GitHub discussion.

Breaking Changes

Although I struggled to leave all breaking changes out of this version, in some edge cases you may see some behavior changed, expecially in old browsers.

1. Defined types may not be exactly what you expected, I know some types are still not strict enough.
2. Some code introduces modern grammar like optional chain and template string, not sure the are all transformed by babel.

Once you find it crashes in some old browsers, try to include react-diff-view into babel-loader or other transformers.

What's Next

In the near future, I plan to refine some peripherals of this repository:

1. Update our site demo to TypeScript.
2. Create a more friendly document.
3. Add more examples for user cases.
4. Deploy introduction and demos to vercel.

After all these, I'll move to the next big version, there will be a lot of breaking changes there, I'll write a post to demostrate what I expect before I start.

Starting from the next big version, I'll publish this library under @otakustay/react-diff-view.