TypeScript rewrite

.gitignore

@@ -6,3 +6,4 @@ dist
 yarn-error.log
 .vscode
 .nyc_output
+/src/**/*.js

README.md

@@ -194,8 +194,8 @@ For even more customisation of the diffing behavior, you can create a `new Diff.
 * `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).
 * `removeEmpty(array)`: called on the arrays of tokens returned by `tokenize` and can be used to modify them. Defaults to stripping out falsey tokens, such as empty strings. `diffArrays` overrides this to simply return the `array`, which means that falsey values like empty strings can be handled like any other token by `diffArrays`.
 * `equals(left, right, options)`: called to determine if two tokens (one from the old string, one from the new string) should be considered equal. Defaults to comparing them with `===`.
-* `join(tokens)`: gets called with an array of consecutive tokens that have either all been added, all been removed, or are all common. Needs to join them into a single value that can be used as the `value` property of the [change object](#change-objects) for these tokens. Defaults to simply returning `tokens.join('')`.
-* `postProcess(changeObjects)`: gets called at the end of the algorithm with the [change objects](#change-objects) produced, and can do final cleanups on them. Defaults to simply returning `changeObjects` unchanged.
+* `join(tokens)`: gets called with an array of consecutive tokens that have either all been added, all been removed, or are all common. Needs to join them into a single value that can be used as the `value` property of the [change object](#change-objects) for these tokens. Defaults to simply returning `tokens.join('')` (and therefore by default will error out if your tokens are not strings; differs that support non-string tokens like `diffArrays` should override it to be a no-op to fix this).
+* `postProcess(changeObjects, options)`: gets called at the end of the algorithm with the [change objects](#change-objects) produced, and can do final cleanups on them. Defaults to simply returning `changeObjects` unchanged.
 
 ### Change Objects
 Many of the methods above return change objects. These objects consist of the following fields:

eslint.config.mjs

@@ -1,176 +1,157 @@
-import globals from "globals";
-import babelParser from "@babel/eslint-parser";
-
-export default [
-    {
-        languageOptions: {
-            globals: {
-                ...globals.browser,
-            },
-
-            parser: babelParser,
-        },
-
-        rules: {
-            // Possible Errors //
-            //-----------------//
-            "comma-dangle": [2, "never"],
-            "no-cond-assign": [2, "except-parens"],
-            "no-console": 1, // Allow for debugging
-            "no-constant-condition": 2,
-            "no-control-regex": 2,
-            "no-debugger": 1, // Allow for debugging
-            "no-dupe-args": 2,
-            "no-dupe-keys": 2,
-            "no-duplicate-case": 2,
-            "no-empty": 2,
-            "no-empty-character-class": 2,
-            "no-ex-assign": 2,
-            "no-extra-boolean-cast": 2,
-            "no-extra-parens": [2, "functions"],
-            "no-extra-semi": 2,
-            "no-func-assign": 2,
-            "no-invalid-regexp": 2,
-            "no-irregular-whitespace": 2,
-            "no-negated-in-lhs": 2,
-            "no-obj-calls": 2,
-            "no-regex-spaces": 2,
-            "no-unreachable": 1, // Optimizer and coverage will handle/highlight this and can be useful for debugging
-            "use-isnan": 2,
-            "valid-typeof": 2,
-
-            // Best Practices //
-            //----------------//
-            curly: 2,
-            "default-case": 1,
-
-            "dot-notation": [2, {
-                allowKeywords: false,
-            }],
-
-            "guard-for-in": 1,
-            "no-alert": 2,
-            "no-caller": 2,
-            "no-div-regex": 1,
-            "no-eval": 2,
-            "no-extend-native": 2,
-            "no-extra-bind": 2,
-            "no-fallthrough": 2,
-            "no-floating-decimal": 2,
-            "no-implied-eval": 2,
-            "no-iterator": 2,
-            "no-labels": 2,
-            "no-lone-blocks": 2,
-            "no-multi-spaces": 2,
-            "no-multi-str": 1,
-            "no-native-reassign": 2,
-            "no-new": 2,
-            "no-new-func": 2,
-            "no-new-wrappers": 2,
-            "no-octal": 2,
-            "no-octal-escape": 2,
-            "no-process-env": 2,
-            "no-proto": 2,
-            "no-redeclare": 2,
-            "no-return-assign": 2,
-            "no-script-url": 2,
-            "no-self-compare": 2,
-            "no-sequences": 2,
-            "no-throw-literal": 2,
-            "no-unused-expressions": 2,
-            "no-warning-comments": 1,
-            "no-with": 2,
-            radix: 2,
-            "wrap-iife": 2,
-
-            // Variables //
-            //-----------//
-            "no-catch-shadow": 2,
-            "no-delete-var": 2,
-            "no-label-var": 2,
-            "no-undef": 2,
-            "no-undef-init": 2,
-
-            "no-unused-vars": [2, {
-                vars: "all",
-                args: "after-used",
-            }],
-
-            "no-use-before-define": [2, "nofunc"],
-
-            // Node.js //
-            //---------//
-
-            // Stylistic //
-            //-----------//
-            "brace-style": [2, "1tbs", {
-                allowSingleLine: true,
-            }],
+// @ts-check
 
-            camelcase: 2,
-
-            "comma-spacing": [2, {
-                before: false,
-                after: true,
-            }],
-
-            "comma-style": [2, "last"],
-            "consistent-this": [1, "self"],
-            "eol-last": 2,
-            "func-style": [2, "declaration"],
-
-            "key-spacing": [2, {
-                beforeColon: false,
-                afterColon: true,
-            }],
-
-            "new-cap": 2,
-            "new-parens": 2,
-            "no-array-constructor": 2,
-            "no-lonely-if": 2,
-            "no-mixed-spaces-and-tabs": 2,
-            "no-nested-ternary": 1,
-            "no-new-object": 2,
-            "no-spaced-func": 2,
-            "no-trailing-spaces": 2,
-
-            "quote-props": [2, "as-needed", {
-                keywords: true,
-            }],
-
-            quotes: [2, "single", "avoid-escape"],
-            semi: 2,
-
-            "semi-spacing": [2, {
-                before: false,
-                after: true,
-            }],
-
-            "space-before-blocks": [2, "always"],
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from "globals";
 
-            "space-before-function-paren": [2, {
-                anonymous: "never",
-                named: "never",
-            }],
+export default tseslint.config(
+  {
+    ignores: [
+      "**/*", // ignore everything...
+      "!src/**/", "!src/**/*.ts", // ... except our TypeScript source files...
+      "!test/**/", "!test/**/*.js", // ... and our tests
+    ],
+  },
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
 
-            "space-in-parens": [2, "never"],
-            "space-infix-ops": 2,
-            "space-unary-ops": 2,
-            "spaced-comment": [2, "always"],
-            "wrap-regex": 1,
-            "no-var": 2,
-        },
+    rules: {
+      // Possible Errors //
+      //-----------------//
+      "comma-dangle": [2, "never"],
+      "no-console": 1, // Allow for debugging
+      "no-debugger": 1, // Allow for debugging
+      "no-extra-parens": [2, "functions"],
+      "no-extra-semi": 2,
+      "no-negated-in-lhs": 2,
+      "no-unreachable": 1, // Optimizer and coverage will handle/highlight this and can be useful for debugging
+
+      // Best Practices //
+      //----------------//
+      curly: 2,
+      "default-case": 1,
+      "dot-notation": [2, {
+        allowKeywords: false,
+      }],
+      "guard-for-in": 1,
+      "no-alert": 2,
+      "no-caller": 2,
+      "no-div-regex": 1,
+      "no-eval": 2,
+      "no-extend-native": 2,
+      "no-extra-bind": 2,
+      "no-floating-decimal": 2,
+      "no-implied-eval": 2,
+      "no-iterator": 2,
+      "no-labels": 2,
+      "no-lone-blocks": 2,
+      "no-multi-spaces": 2,
+      "no-multi-str": 1,
+      "no-native-reassign": 2,
+      "no-new": 2,
+      "no-new-func": 2,
+      "no-new-wrappers": 2,
+      "no-octal-escape": 2,
+      "no-process-env": 2,
+      "no-proto": 2,
+      "no-return-assign": 2,
+      "no-script-url": 2,
+      "no-self-compare": 2,
+      "no-sequences": 2,
+      "no-throw-literal": 2,
+      "no-unused-expressions": 2,
+      "no-warning-comments": 1,
+      radix: 2,
+      "wrap-iife": 2,
+
+      // Variables //
+      //-----------//
+      "no-catch-shadow": 2,
+      "no-label-var": 2,
+      "no-undef-init": 2,
+
+      // Node.js //
+      //---------//
+
+      // Stylistic //
+      //-----------//
+      "brace-style": [2, "1tbs", {
+        allowSingleLine: true,
+      }],
+      camelcase: 2,
+      "comma-spacing": [2, {
+        before: false,
+        after: true,
+      }],
+      "comma-style": [2, "last"],
+      "consistent-this": [1, "self"],
+      "eol-last": 2,
+      "func-style": [2, "declaration"],
+      "key-spacing": [2, {
+        beforeColon: false,
+        afterColon: true,
+      }],
+      "new-cap": 2,
+      "new-parens": 2,
+      "no-array-constructor": 2,
+      "no-lonely-if": 2,
+      "no-mixed-spaces-and-tabs": 2,
+      "no-nested-ternary": 1,
+      "no-new-object": 2,
+      "no-spaced-func": 2,
+      "no-trailing-spaces": 2,
+      "quote-props": [2, "as-needed", {
+        keywords: true,
+      }],
+      quotes: [2, "single", "avoid-escape"],
+      semi: 2,
+      "semi-spacing": [2, {
+        before: false,
+        after: true,
+      }],
+      "space-before-blocks": [2, "always"],
+      "space-before-function-paren": [2, {
+        anonymous: "never",
+        named: "never",
+      }],
+      "space-in-parens": [2, "never"],
+      "space-infix-ops": 2,
+      "space-unary-ops": 2,
+      "spaced-comment": [2, "always"],
+      "wrap-regex": 1,
+      "no-var": 2,
+
+      // Typescript //
+      //------------//
+      "@typescript-eslint/no-explicit-any": 0, // Very strict rule, incompatible with our code
+
+      // We use these intentionally - e.g.
+      //     export interface DiffCssOptions extends CommonDiffOptions {}
+      // for the options argument to diffCss which currently takes no options beyond the ones
+      // common to all diffFoo functions. Doing this allows consistency (one options interface per
+      // diffFoo function) and future-proofs against the API having to change in future if we add a
+      // non-common option to one of these functions.
+      "@typescript-eslint/no-empty-object-type": [2, {allowInterfaces: 'with-single-extends'}],
+    },
+  },
+  {
+    files: ['test/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.mocha,
+      },
+    },
+    rules: {
+      "no-unused-expressions": 0, // Needs disabling to support Chai `.to.be.undefined` etc syntax
+      "@typescript-eslint/no-unused-expressions": 0, // (as above)
+      "no-use-before-define": [2, "nofunc"], // Useful rule but broken for TypeScript code
     },
-    {
-        files: ['test/**/*.js'],
-        languageOptions: {
-            globals: {
-                ...globals.node,
-                ...globals.mocha,
-            },
-        },
-        rules: {
-            "no-unused-expressions": 0, // Needs disabling to support Chai `.to.be.undefined` etc syntax
-        },
-    }
-];
+  }
+);

package.json

@@ -43,8 +43,8 @@
   },
   "scripts": {
     "clean": "rm -rf lib/ dist/ coverage/ .nyc_output/",
-    "lint": "yarn eslint 'src/**/*.js' 'test/**/*.js'",
-    "build": "yarn lint && yarn run-babel && yarn run-rollup && yarn run-uglify",
+    "lint": "yarn eslint",
+    "build": "yarn tsc src/*.ts src/**/*.ts --module es2015 --moduleResolution bundler --target es2022 && yarn run-babel && yarn run-rollup && yarn run-uglify",
     "test": "nyc yarn _test",
     "_test": "yarn build && cross-env NODE_ENV=test yarn run-mocha",
     "run-babel": "babel --out-dir lib  --source-maps=inline src",
@@ -74,12 +74,16 @@
     "nyc": "^17.1.0",
     "rollup": "^4.34.8",
     "rollup-plugin-babel": "^4.4.0",
+    "typescript": "^5.7.3",
     "uglify-js": "^3.19.3",
     "webpack": "^5.98.0",
     "webpack-dev-server": "^5.2.0"
   },
   "optionalDependencies": {},
-  "dependencies": {},
+  "dependencies": {
+    "@eslint/js": "^9.22.0",
+    "typescript-eslint": "^8.26.1"
+  },
   "nyc": {
     "require": [
       "@babel/register"

src/convert/dmp.js → src/convert/dmp.ts

@@ -1,7 +1,11 @@
+import {ChangeObject} from '../types';
+
+type DmpOperation = 1 | 0 | -1;
+
 // See: http://code.google.com/p/google-diff-match-patch/wiki/API
-export function convertChangesToDMP(changes) {
-  let ret = [],
-      change,
+export function convertChangesToDMP<ValueT>(changes: ChangeObject<ValueT>[]): [DmpOperation, ValueT][] {
+  const ret = [];
+  let change,
       operation;
   for (let i = 0; i < changes.length; i++) {
     change = changes[i];