TypeScript rewrite (#591)

* First steps towards TypeScript conversion

* Convert xml.js->xml.ts

* Add compilation to build step

* Rewrite base.js in TypeScript (maybe shit, need to review own work once I'm done)

* Rewrite json.js -> json.ts and get tests passing (I'm honestly shocked they passed)

* array.js -> array.ts

* character.js -> character.ts

* css.js->css.ts

* sentence.js->sentence.ts

* word.js -> word.ts

* line.js -> line.ts

* index.js->index.ts

* Convert a couple more fiiles

* Convert params.ts

* string.js -> string.ts

* Partly convert patch-related files to TypeScript; more to do

* Type more stuff

* Begin converting line-endings.js. Interesting TypeScript bug along the way.

* Bump TypeScript

* Add link to bug report

* Finish converted line-endings.js to TypeScript

* Add missing overloads to support case where argument type isn't known statically

* reverse.js -> reverse.ts

* add todo

* Rewrite base.ts types (breaks everything for now)

* Per-diff-function options types. Still not compiling but close.

* Fix build

* Run 'yarn add @eslint/js typescript-eslint --save-dev' as suggested at https://typescript-eslint.io/getting-started

* Turn on recommended eslint rules as recommended by Getting Started guide at https://typescript-eslint.io/packages/typescript-eslint/#config

* Get linting of TypeScript working (now with the officially recommended rules)

* yarn lint --fix

* Tweak some indentation that eslint broke

* Fix a couple of linting errors

* Allow explicit 'any'

I'm using it and it's convenient. In some places like diffArrays where we allow arrays of arbitrary type, I don't even know how to NOT use it.

* Eliminate needless explicit respecification of rules that eslint.configs.recommended already enables

* Fix another eslint config bug

* Start using arrow functions and thereby resolve a https://typescript-eslint.io/rules/no-this-alias/ error

I wasn't using them before because I wasn't sure if our build process would turn them into normal functions for compatability with old JS environments; it turns out it does, so we're fine.

* Fix some linting errors about pointless escape sequences

* Fix more linting errors about pointless escape sequences

* Eliminate a util made redundant by Object.keys, and fix a linting error in the process

* Fix a no-prototype-builtins linting error

* Disable no-use-before-define for TypeScript code, where it's broken

* Liberalise more rules

* Fix lint errors in parse.ts

* Fix lint errors in apply.ts

* Fix remaining linting errors

* Add missing newline at EOF

* Remove a couple of unused ts-expect-error directives. (My editor was showing errors but tsc doesn't.)

* create.js->create.ts

* Fix some linting errors

* Lint on build, like before

* Generate type declarations on build

* Migrate to using tsconfig.json instead of CLI args

* Start adding tsd tests... but actually maybe should use dtslint?

* Correctly mark a load of arguments as optional

* convert tests to tsd style

* Fix type test

* Fix some more type test things

* Undo some testing silliness

* aaaaaaaaaaargh

* Get most of the way to fixing type definitions based on #303 (comment). Doesn't compile yet.

* Fix index.ts

* Fix remaining compilation errors

* Restore 'Change' type from DefinitelyTyped

* tsd test syntax fix

* Fix: oldHeader & newHeader are allowed to be explicitly given as undefined

* Fix 'Abortable' types in patch/create

* Fix another typing error

* Fix error-handling-related types in patch/apply

* Analyse errors I'm seeing in tests copied from DT & add TODOs

* Begin adding some docs

* Fix a load of test cases where the DT behaviour was just wrong

* Make diffArrays generic instead of using any

* Make DiffArraysOptions types generic

* Rename ParsedDiff -> StructuredPatch

* Export ApplyPatchOptions, ApplyPatchesOptions

* Make all methods public for backwards compat

* Fix remaining type error

* Fix ignoring of test-d

* Copy latest change from DT (DefinitelyTyped/DefinitelyTyped@2cfdb9f)

* Flesh out docs

* Resolve ignoreWhitespace dilemma

* nah

* Remove obsolete TODOs

* Fix bad .gitignore rule

* Add another type test file

* v0.0.1

* v0.0.2

* .npmignore more stuff

* Move test-d/ out of types/ so yarn clean won't delete it

* Add attw

* durrrr

* failed fix attempt

* Get attw passing (hallelujah!)

* Enable "strict": true

* Fix a strict mode error

* Fix a strict mode error

* Fix more strict mode errors

* Silence a silly strict mode error

* Further placate strict mode

* Further placate strict mode

* Fix a legit type error that strict mode found

* Further placate strict mode

* Get TypeScript happy with create.ts

* Further placate strict mode

* Further placate strict mode

* Placate compiler about apply.ts

* Fix a load more strict mode errors

* Placate strict mode further

* Fix some more compilation errors

* Fix one more compilation error

* Fix remaining base.ts errors

* Fix line.ts

* Type a variable to remove a slew of compilation errors

* Add more types to resolve more errors

* Add even more types to resolve even more errors

* Fix remaining type errors. Huzzah!!!

* Address verbatimModuleSyntax guidance

* Remove obsolete comment

* Get @typescript-eslint/consistent-type-exports enabled

* Un-disable no-duplicate-type-constituents and let it autofix. I guess I was confused.

* Reenable another rule

* Remove no-longer-needed gitignore rule from earlier in this PR

* Remove an obsolete disabling of a rule from early in my eslint tinkering. No longer makes sense.

* Fix deps being wrongly declared as non-dev deps

* Bump new deps to latest

* Re-add support for imports from /lib/, maybe?

* Restore support for subpath imports in Node 12.19 and earlier (see #351 (comment)).

* Restore es5 support

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

* Fix rollup

* Improve docs; restore package.json top-level fields that maybe are useful for compatibility with something, somewhere

* Stop using babel with rollup.

Doesn't seem to really affect anything. Output in dist/diff.js is almost identical; just formatting changes and a handful of other things that look inconsequential.

* Remove unused dependency on Babel CLI

* Remove another unused dep

* Get karma working

* Remove apparently unneeded eslint ignore directives

* Fix misplaced bullet in release notes

* bah

* Begin the tedious work of copying and pasting the README documentation into the function comments, so it can show up in people's editors

* More copying and pasting. I should probably test this before moving on

* More copying and pasting of docs

* Finish pasting docs

* Revert temporary package name change

* Hackily resolve the Intl.Segmenter issue

Author: ExplodingCabbage

.gitignore

@@ -1,6 +1,7 @@
 coverage
 node_modules
-lib
+libesm
+libcjs
 dist
 yarn-error.log
 .vscode

.npmignore

@@ -1,9 +1,10 @@
 .babelrc
-.eslintrc
+.eslint.config.mjs
 .gitignore
 .npmignore
 .vscode
 .nyc_output
+test-d
 components
 coverage
 examples
@@ -15,5 +16,6 @@ runtime.js
 src
 tasks
 test
+tsconfig.json
 yarn-error.log
 yarn.lock

README.md

@@ -1,176 +1,182 @@
-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,
-            }],
-
-            camelcase: 2,
-
-            "comma-spacing": [2, {
-                before: false,
-                after: true,
-            }],
+// @ts-check
 
-            "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",
-            }],
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from "globals";
 
-            "space-in-parens": [2, "never"],
-            "space-infix-ops": 2,
-            "space-unary-ops": 2,
-            "spaced-comment": [2, "always"],
-            "wrap-regex": 1,
-            "no-var": 2,
-        },
+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,
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
     },
-    {
-        files: ['test/**/*.js'],
-        languageOptions: {
-            globals: {
-                ...globals.node,
-                ...globals.mocha,
-            },
-        },
-        rules: {
-            "no-unused-expressions": 0, // Needs disabling to support Chai `.to.be.undefined` etc syntax
-        },
+    extends: [tseslint.configs.recommendedTypeChecked],
+    rules: {
+      // Not sure if these actually serve a purpose, but they provide a way to enforce SOME of what
+      // would be imposed by having "verbatimModuleSyntax": true in our tsconfig.json without
+      // actually doing that.
+      "@typescript-eslint/consistent-type-imports": 2,
+      "@typescript-eslint/consistent-type-exports": 2,
+
+      // Things from the recommendedTypeChecked shared config that are disabled simply because they
+      // caused lots of errors in our existing code when tried. Plausibly useful to turn on if
+      // possible and somebody fancies doing the work:
+      "@typescript-eslint/no-unsafe-argument": 0,
+      "@typescript-eslint/no-unsafe-assignment": 0,
+      "@typescript-eslint/no-unsafe-call": 0,
+      "@typescript-eslint/no-unsafe-member-access": 0,
+      "@typescript-eslint/no-unsafe-return": 0,
     }
-];
+  },
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+
+    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)
+    },
+  }
+);