Improve docs; add more exports to obviate need to import stuff from lib/

README.md

@@ -10,9 +10,29 @@ Based on the algorithm proposed in
 npm install diff --save
 ```
 
-## Usage
+## Getting started
 
-Broadly, jsdiff's diff functions all take an old text and a new text and perform three steps:
+### Imports
+
+In an environment where you can use imports, everything you need can be imported directly from `diff`. e.g.
+
+ESM:
+
+```
+import {diffChars, createPatch} from 'diff';
+```
+
+CommonJS
+
+```
+const {diffChars, createPatch} = require('diff');
+```
+
+If you want to serve jsdiff to a web page without using a module system, you can use `dist/diff.js` or `dist/diff.min.js`. These create a global called `Diff` that contains the entire JsDiff API as its properties.
+
+### Usage
+
+jsdiff's diff functions all take an old text and a new text and perform three steps:
 
 1. Split both texts into arrays of "tokens". What constitutes a token varies; in `diffChars`, each character is a token, while in `diffLines`, each line is a token.
 
@@ -22,9 +42,9 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
 
 3. Return an array representing the transformation computed in the previous step as a series of [change objects](#change-objects). The array is ordered from the start of the input to the end, and each change object represents *inserting* one or more tokens, *deleting* one or more tokens, or *keeping* one or more tokens.
 
-### API
+## API
 
-* `Diff.diffChars(oldStr, newStr[, options])` - diffs two blocks of text, treating each character as a token.
+* `diffChars(oldStr, newStr[, options])` - diffs two blocks of text, treating each character as a token.
 
     ("Characters" here means Unicode code points - the elements you get when you loop over a string with a `for ... of ...` loop.)
 
@@ -33,7 +53,7 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
     Options
     * `ignoreCase`: If `true`, the uppercase and lowercase forms of a character are considered equal. Defaults to `false`.
 
-* `Diff.diffWords(oldStr, newStr[, options])` - diffs two blocks of text, treating each word and each punctuation mark as a token. Whitespace is ignored when computing the diff (but preserved as far as possible in the final change objects).
+* `diffWords(oldStr, newStr[, options])` - diffs two blocks of text, treating each word and each punctuation mark as a token. Whitespace is ignored when computing the diff (but preserved as far as possible in the final change objects).
 
     Returns a list of [change objects](#change-objects).
 
@@ -45,47 +65,47 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
 
       Using an `Intl.Segmenter` should allow better word-level diffing of non-English text than the default behaviour. For instance, `Intl.Segmenter`s can generally identify via built-in dictionaries which sequences of adjacent Chinese characters form words, allowing word-level diffing of Chinese. By specifying a language when instantiating the segmenter (e.g. `new Intl.Segmenter('sv', {granularity: 'word'})`) you can also support language-specific rules, like treating Swedish's colon separated contractions (like *k:a* for *kyrka*) as single words; by default this would be seen as two words separated by a colon.
 
-* `Diff.diffWordsWithSpace(oldStr, newStr[, options])` - diffs two blocks of text, treating each word, punctuation mark, newline, or run of (non-newline) whitespace as a token.
+* `diffWordsWithSpace(oldStr, newStr[, options])` - diffs two blocks of text, treating each word, punctuation mark, newline, or run of (non-newline) whitespace as a token.
 
-* `Diff.diffLines(oldStr, newStr[, options])` - diffs two blocks of text, treating each line as a token.
+* `diffLines(oldStr, newStr[, options])` - diffs two blocks of text, treating each line as a token.
 
     Options
     * `ignoreWhitespace`: `true` to ignore leading and trailing whitespace characters when checking if two lines are equal. Defaults to `false`.
     * `ignoreNewlineAtEof`: `true` to ignore a missing newline character at the end of the last line when comparing it to other lines. (By default, the line `'b\n'` in text `'a\nb\nc'` is not considered equal to the line `'b'` in text `'a\nb'`; this option makes them be considered equal.) Ignored if `ignoreWhitespace` or `newlineIsToken` are also true.
-    * `stripTrailingCr`: `true` to remove all trailing CR (`\r`) characters before performing the diff. Defaults to `false`.
+    * `stripTrailingCr`: `true` to remove all trailing CR (`\r`) characters before performing the  Defaults to `false`.
       This helps to get a useful diff when diffing UNIX text files against Windows text files.
     * `newlineIsToken`: `true` to treat the newline character at the end of each line as its own token. This allows for changes to the newline structure to occur independently of the line content and to be treated as such. In general this is the more human friendly form of `diffLines`; the default behavior with this option turned off is better suited for patches and other computer friendly output. Defaults to `false`.
 
     Note that while using `ignoreWhitespace` in combination with `newlineIsToken` is not an error, results may not be as expected. With `ignoreWhitespace: true` and `newlineIsToken: false`, changing a completely empty line to contain some spaces is treated as a non-change, but with `ignoreWhitespace: true` and `newlineIsToken: true`, it is treated as an insertion. This is because the content of a completely blank line is not a token at all in `newlineIsToken` mode.
 
     Returns a list of [change objects](#change-objects).
 
-* `Diff.diffSentences(oldStr, newStr[, options])` - diffs two blocks of text, treating each sentence, and the whitespace between each pair of sentences, as a token. The characters `.`, `!`, and `?`, when followed by whitespace, are treated as marking the end of a sentence; nothing else besides the end of the string is considered to mark a sentence end.
+* `diffSentences(oldStr, newStr[, options])` - diffs two blocks of text, treating each sentence, and the whitespace between each pair of sentences, as a token. The characters `.`, `!`, and `?`, when followed by whitespace, are treated as marking the end of a sentence; nothing else besides the end of the string is considered to mark a sentence end.
 
-  (For more sophisticated detection of sentence breaks, including support for non-English punctuation, consider instead tokenizing with an [`Intl.Segmenter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter) with `granularity: 'sentence'` and passing the result to `Diff.diffArrays`.)
+  (For more sophisticated detection of sentence breaks, including support for non-English punctuation, consider instead tokenizing with an [`Intl.Segmenter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter) with `granularity: 'sentence'` and passing the result to `diffArrays`.)
 
     Returns a list of [change objects](#change-objects).
 
-* `Diff.diffCss(oldStr, newStr[, options])` - diffs two blocks of text, comparing CSS tokens.
+* `diffCss(oldStr, newStr[, options])` - diffs two blocks of text, comparing CSS tokens.
 
     Returns a list of [change objects](#change-objects).
 
-* `Diff.diffJson(oldObj, newObj[, options])` - diffs two JSON-serializable objects by first serializing them to prettily-formatted JSON and then treating each line of the JSON as a token. Object properties are ordered alphabetically in the serialized JSON, so the order of properties in the objects being compared doesn't affect the result.
+* `diffJson(oldObj, newObj[, options])` - diffs two JSON-serializable objects by first serializing them to prettily-formatted JSON and then treating each line of the JSON as a token. Object properties are ordered alphabetically in the serialized JSON, so the order of properties in the objects being compared doesn't affect the result.
 
     Returns a list of [change objects](#change-objects).
 
     Options
     * `stringifyReplacer`: A custom replacer function. Operates similarly to the `replacer` parameter to [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#the_replacer_parameter), but must be a function.
     *  `undefinedReplacement`: A value to replace `undefined` with. Ignored if a `stringifyReplacer` is provided.
 
-* `Diff.diffArrays(oldArr, newArr[, options])` - diffs two arrays of tokens, comparing each item for strict equality (===).
+* `diffArrays(oldArr, newArr[, options])` - diffs two arrays of tokens, comparing each item for strict equality (===).
 
     Options
     * `comparator`: `function(left, right)` for custom equality checks
 
     Returns a list of [change objects](#change-objects).
 
-* `Diff.createTwoFilesPatch(oldFileName, newFileName, oldStr, newStr[, oldHeader[, newHeader[, options]]])` - creates a unified diff patch by first computing a diff with `diffLines` and then serializing it to unified diff format.
+* `createTwoFilesPatch(oldFileName, newFileName, oldStr, newStr[, oldHeader[, newHeader[, options]]])` - creates a unified diff patch by first computing a diff with `diffLines` and then serializing it to unified diff format.
 
     Parameters:
     * `oldFileName` : String to be output in the filename section of the patch for the removals
@@ -99,15 +119,15 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
       - `ignoreWhitespace`: Same as in `diffLines`. Defaults to `false`.
       - `stripTrailingCr`: Same as in `diffLines`. Defaults to `false`.
 
-* `Diff.createPatch(fileName, oldStr, newStr[, oldHeader[, newHeader[, options]]])` - creates a unified diff patch.
+* `createPatch(fileName, oldStr, newStr[, oldHeader[, newHeader[, options]]])` - creates a unified diff patch.
 
-    Just like Diff.createTwoFilesPatch, but with oldFileName being equal to newFileName.
+    Just like createTwoFilesPatch, but with oldFileName being equal to newFileName.
 
-* `Diff.formatPatch(patch)` - creates a unified diff patch.
+* `formatPatch(patch)` - creates a unified diff patch.
 
     `patch` may be either a single structured patch object (as returned by `structuredPatch`) or an array of them (as returned by `parsePatch`).
 
-* `Diff.structuredPatch(oldFileName, newFileName, oldStr, newStr[, oldHeader[, newHeader[, options]]])` - returns an object with an array of hunk objects.
+* `structuredPatch(oldFileName, newFileName, oldStr, newStr[, oldHeader[, newHeader[, options]]])` - returns an object with an array of hunk objects.
 
     This method is similar to createTwoFilesPatch, but returns a data structure
     suitable for further processing. Parameters are the same as createTwoFilesPatch. The data structure returned may look like this:
@@ -123,7 +143,7 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
     }
     ```
 
-* `Diff.applyPatch(source, patch[, options])` - attempts to apply a unified diff patch.
+* `applyPatch(source, patch[, options])` - attempts to apply a unified diff patch.
 
     Hunks are applied first to last. `applyPatch` first tries to apply the first hunk at the line number specified in the hunk header, and with all context lines matching exactly. If that fails, it tries scanning backwards and forwards, one line at a time, to find a place to apply the hunk where the context lines match exactly. If that still fails, and `fuzzFactor` is greater than zero, it increments the maximum number of mismatches (missing, extra, or changed context lines) that there can be between the hunk context and a region where we are trying to apply the patch such that the hunk will still be considered to match. Regardless of `fuzzFactor`, lines to be deleted in the hunk *must* be present for a hunk to match, and the context lines *immediately* before and after an insertion must match exactly.
 
@@ -143,7 +163,7 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
     - `autoConvertLineEndings`: If `true`, and if the file to be patched consistently uses different line endings to the patch (i.e. either the file always uses Unix line endings while the patch uses Windows ones, or vice versa), then `applyPatch` will behave as if the line endings in the patch were the same as those in the source file. (If `false`, the patch will usually fail to apply in such circumstances since lines deleted in the patch won't be considered to match those in the source file.) Defaults to `true`.
     - `compareLine(lineNumber, line, operation, patchContent)`: Callback used to compare to given lines to determine if they should be considered equal when patching. Defaults to strict equality but may be overridden to provide fuzzier comparison. Should return false if the lines should be rejected.
 
-* `Diff.applyPatches(patch, options)` - applies one or more patches.
+* `applyPatches(patch, options)` - applies one or more patches.
 
     `patch` may be either an array of structured patch objects, or a string representing a patch in unified diff format (which may patch one or more files).
 
@@ -154,17 +174,17 @@ Broadly, jsdiff's diff functions all take an old text and a new text and perform
 
     Once all patches have been applied or an error occurs, the `options.complete(err)` callback is made.
 
-* `Diff.parsePatch(diffStr)` - Parses a patch into structured data
+* `parsePatch(diffStr)` - Parses a patch into structured data
 
-    Return a JSON object representation of the a patch, suitable for use with the `applyPatch` method. This parses to the same structure returned by `Diff.structuredPatch`.
+    Return a JSON object representation of the a patch, suitable for use with the `applyPatch` method. This parses to the same structure returned by `structuredPatch`.
 
-* `Diff.reversePatch(patch)` - Returns a new structured patch which when applied will undo the original `patch`.
+* `reversePatch(patch)` - Returns a new structured patch which when applied will undo the original `patch`.
 
     `patch` may be either a single structured patch object (as returned by `structuredPatch`) or an array of them (as returned by `parsePatch`).
 
-* `Diff.convertChangesToXML(changes)` - converts a list of change objects to a serialized XML format
+* `convertChangesToXML(changes)` - converts a list of change objects to a serialized XML format
 
-* `Diff.convertChangesToDMP(changes)` - converts a list of change objects to the format returned by Google's [diff-match-patch](https://github.com/google/diff-match-patch) library
+* `convertChangesToDMP(changes)` - converts a list of change objects to the format returned by Google's [diff-match-patch](https://github.com/google/diff-match-patch) library
 
 #### Universal `options`
 
@@ -188,7 +208,7 @@ The simplest way to customize tokenization behavior is to simply tokenize the te
 
 To customize the notion of token equality used, use the `comparator` option to `diffArrays`.
 
-For even more customisation of the diffing behavior, you can extend the `Diff.Diff()` class, override its `castInput`, `tokenize`, `removeEmpty`, `equals`, and `join` properties with your own functions, then call its `diff(oldString, newString[, options])` method. The methods you can override are used as follows:
+For even more customisation of the diffing behavior, you can extend the `Diff()` class, override its `castInput`, `tokenize`, `removeEmpty`, `equals`, and `join` properties with your own functions, then call its `diff(oldString, newString[, options])` method. The methods you can override are used as follows:
 
 * `castInput(value, options)`: used to transform the `oldString` and `newString` before any other steps in the diffing algorithm happen. For instance, `diffJson` uses `castInput` to serialize the objects being diffed to JSON. Defaults to a no-op.
 * `tokenize(value, options)`: used to convert each of `oldString` and `newString` (after they've gone through `castInput`) to an array of tokens. Defaults to returning `value.split('')` (returning an array of individual characters).
@@ -213,12 +233,12 @@ Many of the methods above return change objects. These objects consist of the fo
 
 ```js
 require('colors');
-const Diff = require('diff');
+const {diffChars} = require('diff');
 
 const one = 'beep boop';
 const other = 'beep boob blah';
 
-const diff = Diff.diffChars(one, other);
+const diff = diffChars(one, other);
 
 diff.forEach((part) => {
   // green for additions, red for deletions
@@ -275,10 +295,10 @@ Open the above .html file in a browser and you should see
 The code below is roughly equivalent to the Unix command `diff -u file1.txt file2.txt > mydiff.patch`:
 
 ```
-const Diff = require('diff');
+const {createTwoFilesPatch} = require('diff');
 const file1Contents = fs.readFileSync("file1.txt").toString();
 const file2Contents = fs.readFileSync("file2.txt").toString();
-const patch = Diff.createTwoFilesPatch("file1.txt", "file2.txt", file1Contents, file2Contents);
+const patch = createTwoFilesPatch("file1.txt", "file2.txt", file1Contents, file2Contents);
 fs.writeFileSync("mydiff.patch", patch);
 ```
 
@@ -289,10 +309,10 @@ fs.writeFileSync("mydiff.patch", patch);
 The code below is roughly equivalent to the Unix command `patch file1.txt mydiff.patch`:
 
 ```
-const Diff = require('diff');
+const {applyPatch} = require('diff');
 const file1Contents = fs.readFileSync("file1.txt").toString();
 const patch = fs.readFileSync("mydiff.patch").toString();
-const patchedFile = Diff.applyPatch(file1Contents, patch);
+const patchedFile = applyPatch(file1Contents, patch);
 fs.writeFileSync("file1.txt", patchedFile);
 ```
 
@@ -301,9 +321,9 @@ fs.writeFileSync("file1.txt", patchedFile);
 The code below is roughly equivalent to the Unix command `patch < mydiff.patch`:
 
 ```
-const Diff = require('diff');
+const {applyPatches} = require('diff');
 const patch = fs.readFileSync("mydiff.patch").toString();
-Diff.applyPatches(patch, {
+applyPatches(patch, {
     loadFile: (patch, callback) => {
         let fileContents;
         try {
@@ -332,7 +352,7 @@ Diff.applyPatches(patch, {
 
 ## Compatibility
 
-jsdiff supports all ES3 environments with some known issues on IE8 and below. Under these browsers some diff algorithms such as word diff and others may fail due to lack of support for capturing groups in the `split` operation.
+jsdiff should support all ES5 environments. If you find one that it doesn't support, please [open an issue](https://github.com/kpdecker/jsdiff/issues).
 
 ## TypeScript
 

examples/node_example.js

@@ -1,12 +1,12 @@
 require('colors');
-let Diff = require('../');
+const {diffChars} = require('diff');
 
-let one = 'beep boop';
-let other = 'beep boob blah';
+const one = 'beep boop';
+const other = 'beep boob blah';
 
-let diff = Diff.diffChars(one, other);
+const diff = diffChars(one, other);
 
-diff.forEach(function(part) {
+diff.forEach((part) => {
   // green for additions, red for deletions
   let text = part.added ? part.value.bgGreen :
              part.removed ? part.value.bgRed :

src/diff/json.ts

@@ -22,7 +22,7 @@ class JsonDiff extends Diff<string, string> {
   }
 }
 
-const jsonDiff = new JsonDiff();
+export const jsonDiff = new JsonDiff();
 
 
 export function diffJson(