@matrixreq/htmldiff 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2012 The Network Inc. and contributors
+Copyright (c) 2022 idesis GmbH, Max-Keith-Straße 66 (E 11), D-45136 Essen, https://www.idesis.de
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# htmldiff.js
+
+Diff and markup HTML with `<ins>` and `<del>` tags.
+
+
+## Origin
+
+Quote from the original source of this fork:
+
+*`htmldiff.js` is a JavaScript port of [https://github.com/myobie/htmldiff](https://github.com/myobie/htmldiff) by
+[Keanu Lee](http://keanulee.com) at [Inkling](https://www.inkling.com/).*
+
+**htmldiff.js** is based on [this fork](https://github.com/inkling/htmldiff.js) and adds a few things:
+
+- Diffing of video, math, widget, iframe, img and svg tags.
+- Ability to set atomic tags via the API.
+- A command line interface.
+- TypeScript support.
+- Better documentation.
+
+See also *Credits* below.
+
+## Description
+
+htmldiff takes two HTML snippets or files and marks the differences between them with
+`<ins>` and `<del>` tags. The diffing understands HTML so it doesn't do a pure text diff,
+instead it will insert the appropriate tags for changed/added/deleted text nodes, single 
+tags or tag hierarchies.
+
+The module can be used as module in Node.js, with RequireJS, or even just as a script tag.
+
+## API
+
+The module exports a single default function:
+
+JavaScript:
+
+````javascript
+diff(before, after, className, dataPrefix, atomicTags);
+````
+
+TypeScript:
+
+````javascript
+function diff(before: string, after: string, className?: string | null, dataPrefix?: string | null, atomicTags?: string | null): string;
+````
+
+### Parameters
+
+- `before` (string) is the original HTML text.
+- `after` (string) is the HTML text after the changes have been applied.
+
+The return value is a string with the diff result, marked by `<ins>` and `del` tags. The 
+function has three optional parameters. If an empty string or `null` is used for any
+of these three parameters it will be ignored:
+
+- `className` (string) className will be added as a class attribute on every inserted 
+  `<ins>` and `<del>` tag.
+- `dataPrefix` (string) The data prefix to use for data attributes. The so called *operation 
+  index data attribute* will be named `data-${dataPrefix-}operation-index`. If not used, 
+  the default attribute name `data-operation-index` will be added on every inserted 
+  `<ins>` and `<del>` tag. The value of this attribute is an auto incremented counter. 
+- `atomicTags` (string) Comma separated list of tag names. The list has to be in the form 
+  `tag1,tag2,...` e. g. `head,script,style`. An atomic tag is one whose child nodes should 
+  not be compared - the entire tag should be treated as one token. This is useful for tags 
+  where it does not make sense to insert `<ins>` and `<del>` tags. If not used, the default 
+  list will be used:
+  `iframe,object,math,svg,script,video,head,style`.
+
+
+### Example
+
+JavaScript:
+
+```javascript
+  diff = require('node-htmldiff');
+
+  console.log(diff('<p>This is some text</p>', '<p>That is some more text</p>', 'myClass'));
+```
+
+TypeScript:
+
+```javascript
+  import diff = require("node-htmldiff");
+
+  console.log(diff("<p>This is some text</p>", "<p>That is some more text</p>", "myClass"));
+```
+
+Please note that `diff` is only an arbitrary name; since the module exports only one default 
+function you can use whatever name you like, e. g., `diffHTML`.
+
+Result:
+
+```html
+<p><del data-operation-index="1" class="myClass">This</del><ins data-operation-index="1" class="myClass">That</ins> is some<ins data-operation-index="3" class="myClass"> more</ins> text.</p>
+```
+
+
+## Command line interface
+
+```bash
+htmldiff beforeFile afterFile diffedFile [-c className] [-p dataPrefix] [-t atomicTags]
+```
+
+Parameters: 
+
+- `beforeFile` An HTML input file in its original form.
+
+- `afterFile` An HTML input file, based on `beforeFile` but with changes.
+
+- `diffedFile` Name of the diffed HTML output file. All differences between
+  `beforeFile` and `afterFile` will be surrounded with `<ins>` and `<del>`
+  tags. If diffedFile is `-` (minus) the result will be written with 
+  `console.log()` to stdout.
+
+Options:
+
+`-c className`, `-p dataPrefix` and `-t atomicTags` are all optional. For a
+description please see API documentation above.
+
+
+## Development
+
+After cloning the repository run `npm i` or `npm install` to install the necessary 
+dependencies. A run of `npm run make` creates the JavaScript output file. 
+`npm run lint` checks the TypeScript sources with TSLint. `npm test` runs all the
+tests from the `test` directory. `npm run testsample` diffs the HTML sample files 
+from the directory `sample` and logs the result to the console.
+
+The command line interface of htmldiff is developed in TypeScript so you have to run
+`npm run make` once to create the JavaScript output file.
+
+
+## Credits
+
+This module wouldn't have been possible without code from the following projects/persons:
+
+- Original project: [The Network Inc.](http://www.tninetwork.com), [Github](https://github.com/tnwinc/htmldiff.js)
+- Massive improvements of the original code: [Inkling](https://www.inkling.com), [Github](https://github.com/inkling/htmldiff.js)
+- Support of more tags: Ian White, [Github](https://github.com/ian97531)
+
+
+## License
+
+MIT © [idesis GmbH](https://www.idesis.de), Max-Keith-Straße 66 (E 11), D-45136 Essen
+
+See the `LICENSE` file for details.

package/htmldiff-cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const htmldiff_1 = __importDefault(require("./js/htmldiff"));
+const argc = process.argv.length;
+const cli = (0, path_1.parse)(__filename).name;
+let className = null;
+let dataPrefix = null;
+let atomicTags = null;
+function printUsage() {
+    const usage = `${cli} v0.9.4
+
+Usage: ${cli} beforeFile afterFile diffedFile [Options]
+
+beforeFile:
+  An HTML input file in its original form.
+
+afterFile:
+  An HTML input file, based on beforeFile but with changes.
+
+diffedFile:
+  Name of the diffed HTML output file. All differences between beforeFile
+  and afterFile will be surrounded with <ins> and <del> tags. If diffedFile
+  is - (minus) the result will be written with console.log() to stdout.
+
+Options:
+
+-c className (optional):
+  className will be added as a class attribute on every <ins> and <del> tag.
+
+-p dataPrefix (optional):
+  The data prefix to use for data attributes. The operation index data
+  attribute will be named "data-$\{dataPrefix-}operation-index". If not
+  used, the default attribute name "data-operation-index" will be added
+  on every <ins> and <del> tag. The value of this attribute is an auto
+  incremented counter.
+
+-t atomicTags (optional):
+  Comma separated list of tag names. The list has to be in the form
+  "tag1,tag2,..." e. g. "head,script,style". An atomic tag is one whose
+  child nodes should not be compared - the entire tag should be treated
+  as one token. This is useful for tags where it does not make sense to
+  insert <ins> and <del> tags. If not used, this default list will be used:
+  "iframe,object,math,svg,script,video,head,style".`;
+    console.log(usage);
+}
+function readFileContent(fileName) {
+    try {
+        const result = (0, fs_1.readFileSync)((0, path_1.resolve)(fileName), "utf-8");
+        if (result === "") {
+            console.error(`File "${fileName}" is empty.`);
+        }
+        return result;
+    }
+    catch (error) {
+        console.error(`Couldn't read file "${fileName}"\n${error}`);
+        return "";
+    }
+}
+function resolveSwitch(name, value) {
+    switch (name) {
+        case "-c":
+            if (className) {
+                return false;
+            }
+            className = value;
+            return true;
+        case "-p":
+            if (dataPrefix) {
+                return false;
+            }
+            dataPrefix = value;
+            return true;
+        case "-t":
+            if (atomicTags) {
+                return false;
+            }
+            atomicTags = value;
+            return true;
+    }
+    return false;
+}
+const validArgc = [5, 7, 9, 11];
+if (validArgc.indexOf(argc) === -1) {
+    printUsage();
+    process.exit(1);
+}
+if (argc > 6) {
+    if (!resolveSwitch(process.argv[5], process.argv[6])) {
+        printUsage();
+        process.exit(1);
+    }
+}
+if (argc > 8) {
+    if (!resolveSwitch(process.argv[7], process.argv[8])) {
+        printUsage();
+        process.exit(1);
+    }
+}
+if (argc > 10) {
+    if (!resolveSwitch(process.argv[9], process.argv[10])) {
+        printUsage();
+        process.exit(1);
+    }
+}
+const beforeFile = readFileContent(process.argv[2]);
+if (!beforeFile) {
+    process.exit(1);
+}
+const afterFile = readFileContent(process.argv[3]);
+if (!afterFile) {
+    process.exit(1);
+}
+const diffedResult = (0, htmldiff_1.default)(beforeFile, afterFile, className, dataPrefix, atomicTags);
+if (process.argv[4] === "-") {
+    console.log(diffedResult);
+}
+else {
+    (0, fs_1.writeFileSync)((0, path_1.resolve)(process.argv[4]), diffedResult);
+}

package/js/htmldiff.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Compares two pieces of HTML content and returns the combined content with differences
+ * wrapped in <ins> and <del> tags.
+ * @param before The HTML content before the changes.
+ * @param after The HTML content after the changes.
+ * @param className (Optional) The class attribute to include in `<ins>` and `<del>` tags.
+ * @param dataPrefix (Optional) The data prefix to use for data attributes. The operation index data
+ * attribute will be named `data-${dataPrefix-}operation-index`.
+ * @param atomicTags (Optional) Comma separated list of tag names. The list has to be in the form
+ * `tag1,tag2,...` e. g. `head,script,style`. An atomic tag is one whose child nodes should not be
+ * compared - the entire tag should be treated as one token. This is useful for tags where it does
+ * not make sense to insert `<ins>` and `<del>` tags. If not used, the default list 
+ * `iframe,object,math,svg,script,video,head,style` will be used.
+ * @return The combined HTML content with differences wrapped in `<ins>` and `<del>` tags.
+ */
+declare function diff(before: string, after: string, className?: string | null, dataPrefix?: string | null, atomicTags?: string | null): string;
+export = diff;