Merge pull request #527 from remarkablemark/refactor/typescript

refactor: migrate to TypeScript

Author: remarkablemark

.github/workflows/build.yml

@@ -21,14 +21,14 @@ jobs:
       - name: Lint JavaScript
         run: npm run lint
 
-      - name: Test TypeScript declaration files
-        run: npm run lint:dts
+      - name: Type check
+        run: npm run lint:tsc
 
       - name: Run server test
         run: npm run test:server
 
       - name: Run module tests
-        run: npm run test:module
+        run: npm run test:esm
 
       - name: Run server test
         run: npm run test:server

.gitignore

@@ -1,5 +1,6 @@
 # Build directory
-dist
+dist/
+lib/
 
 # Logs
 logs
@@ -13,16 +14,16 @@ pids
 *.pid.lock
 
 # Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
+lib-cov/
 
 # Coverage directory used by tools like istanbul
-coverage
+coverage/
 
 # nyc test coverage
-.nyc_output
+.nyc_output/
 
 # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
+.grunt/
 
 # node-waf configuration
 .lock-wscript
@@ -31,11 +32,11 @@ coverage
 build/Release
 
 # Dependency directories
-node_modules
-jspm_packages
+node_modules/
+jspm_packages/
 
 # Optional npm cache directory
-.npm
+.npm/
 
 # Optional eslint cache
 .eslintcache

.prettierrc.json

@@ -1,5 +1,3 @@
 {
-  "arrowParens": "avoid",
-  "trailingComma": "none",
   "singleQuote": true
 }

README.md

@@ -19,7 +19,8 @@ The parser converts an HTML string to a JavaScript object that describes the DOM
 #### Example
 
 ```js
-const parse = require('html-dom-parser');
+import parse from 'html-dom-parser';
+
 parse('<p>Hello, World!</p>');
 ```
 
@@ -83,16 +84,16 @@ yarn add html-dom-parser
 
 ## Usage
 
-Import the module with ES Modules:
+Import with ES Modules:
 
 ```js
 import parse from 'html-dom-parser';
 ```
 
-Or require the module with CommonJS:
+Require with CommonJS:
 
 ```js
-const parse = require('html-dom-parser');
+const parse = require('html-dom-parser').default;
 ```
 
 Parse empty string:
@@ -179,60 +180,41 @@ Because the server parser is a wrapper of [htmlparser2](https://github.com/fb55/
  * should be combined into a single object like so:
  */
 const options = {
-    /**
-     * Options for the domhandler class.
-     * https://github.com/fb55/domhandler/blob/master/src/index.ts#L16
-     */
-    withStartIndices: false,
-    withEndIndices: false,
-    xmlMode: false,
-    /**
-     * Options for the htmlparser2 class.
-     * https://github.com/fb55/htmlparser2/blob/master/src/Parser.ts#L104
-     */ 
-    xmlMode: false, // Will overwrite what is used for the domhandler, otherwise inherited.
-    decodeEntities: true,
-    lowerCaseTags: true, // !xmlMode by default
-    lowerCaseAttributeNames: true, // !xmlMode by default
-    recognizeCDATA: false, // xmlMode by default
-    recognizeSelfClosing: false, // xmlMode by default
-    Tokenizer: Tokenizer
+  /**
+   * Options for the domhandler class.
+   * https://github.com/fb55/domhandler/blob/master/src/index.ts#L16
+   */
+  withStartIndices: false,
+  withEndIndices: false,
+  xmlMode: false,
+  /**
+   * Options for the htmlparser2 class.
+   * https://github.com/fb55/htmlparser2/blob/master/src/Parser.ts#L104
+   */
+  xmlMode: false, // Will overwrite what is used for the domhandler, otherwise inherited.
+  decodeEntities: true,
+  lowerCaseTags: true, // !xmlMode by default
+  lowerCaseAttributeNames: true, // !xmlMode by default
+  recognizeCDATA: false, // xmlMode by default
+  recognizeSelfClosing: false, // xmlMode by default
+  Tokenizer: Tokenizer,
 };
 ```
 
 If you are parsing HTML with SVG code you can set `lowerCaseTags` to `true` without having to enable `xmlMode`. Keep in mind this will return all tag names in camel-case and not the HTML standard of lowercase.
 
 > **Note**: If you are parsing code client-side (in-browser), you can not control the parsing options. Client-side parsing automatically handles returning some HTML tags in camel-case, such as specific SVG elements, but returns all other tags lowercased according to the HTML standard.
 
-## Testing
-
-Run server and client tests:
-
-```sh
-npm test
-```
-
-Generate HTML coverage report for server tests:
-
-```sh
-npx nyc report --reporter=html
-```
-
-Lint files:
+## Migration
 
-```sh
-npm run lint
-npm run lint:fix
-```
+### v5
 
-Test TypeScript declaration file for style and correctness:
+Migrated to TypeScript. CommonJS imports require the `.default` key:
 
-```sh
-npm run lint:dts
+```js
+const parse = require('html-dom-parser').default;
 ```
 
-## Migration
-
 ### v4
 
 Upgraded [htmlparser2](https://github.com/fb55/htmlparser2) to v9.

esm/client/html-to-dom.mjs

@@ -0,0 +1,3 @@
+import ClientParser from '../../lib/client/html-to-dom.js';
+
+export default ClientParser.default;

esm/index.mjs

@@ -0,0 +1,3 @@
+import HTMLDOMParser from '../lib/index.js';
+
+export default HTMLDOMParser.default;

esm/server/html-to-dom.mjs

@@ -0,0 +1,3 @@
+import ServerParser from '../../lib/server/html-to-dom.js';
+
+export default ServerParser.default;

index.d.ts

@@ -1,6 +1,7 @@
-// Karma configuration
-// https://karma-runner.github.io/5.2/config/configuration-file.html
-module.exports = config => {
+/**
+ * @see https://karma-runner.github.io/6.4/config/configuration-file.html
+ */
+module.exports = (config) => {
   config.set({
     // base path that will be used to resolve all patterns (eg. files, exclude)
     basePath: '',
@@ -16,7 +17,7 @@ module.exports = config => {
       'lib/server/utilities.js',
       'test/cases/html.js',
       'test/client/*.js',
-      'test/helpers/*.js'
+      'test/helpers/*.js',
     ],
 
     // list of files / patterns to exclude
@@ -27,7 +28,7 @@ module.exports = config => {
     preprocessors: {
       'dist/*.js': ['commonjs'],
       'lib/**/*.js': ['commonjs'],
-      'test/**/*.js': ['commonjs']
+      'test/**/*.js': ['commonjs'],
     },
 
     // test results reporter to use
@@ -74,14 +75,14 @@ module.exports = config => {
     client: {
       mocha: {
         // change Karma's `debug.html` to the Mocha web reporter
-        reporter: 'html'
-      }
+        reporter: 'html',
+      },
     },
 
     // Mocha reporter options
     // https://www.npmjs.com/package/karma-mocha-reporter
     mochaReporter: {
-      showDiff: true
-    }
+      showDiff: true,
+    },
   });
 };

index.mjs

@@ -1,6 +1,8 @@
 /**
- * SVG elements, unlike HTML elements, are case-sensitive.
+ * SVG elements are case-sensitive.
  *
- * {@link https://developer.mozilla.org/docs/Web/SVG/Element#SVG_elements_A_to_Z}
+ * @see https://developer.mozilla.org/docs/Web/SVG/Element#svg_elements_a_to_z
  */
-export const CASE_SENSITIVE_TAG_NAMES: string[];
+export declare const CASE_SENSITIVE_TAG_NAMES: readonly ["animateMotion", "animateTransform", "clipPath", "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite", "feConvolveMatrix", "feDiffuseLighting", "feDisplacementMap", "feDropShadow", "feFlood", "feFuncA", "feFuncB", "feFuncG", "feFuncR", "feGaussianBlur", "feImage", "feMerge", "feMergeNode", "feMorphology", "feOffset", "fePointLight", "feSpecularLighting", "feSpotLight", "feTile", "feTurbulence", "foreignObject", "linearGradient", "radialGradient", "textPath"];
+export declare const CASE_SENSITIVE_TAG_NAMES_MAP: Record<string, string>;
+//# sourceMappingURL=constants.d.ts.map

karma.conf.js

@@ -2,6 +2,7 @@
  * Parses HTML string to DOM nodes.
  *
  * @param html - HTML markup.
- * @returns - NodeList.
+ * @returns - DOM nodes.
  */
 export default function domparser(html: string): NodeList;
+//# sourceMappingURL=domparser.d.ts.map