feat(types): add TypeScript decelerations

.travis.yml

@@ -8,6 +8,7 @@ install:
     - npm install
 script:
     - npm run lint
+    - npm run dtslint
     - npm run cover
 after_script:
     - npm run coveralls

package.json

@@ -4,6 +4,7 @@
   "description": "An HTML to DOM parser that works on the server and client.",
   "author": "Mark <mark@remarkablemark.org>",
   "main": "index.js",
+  "types": "types",
   "scripts": {
     "prepublish": "npm run clean && npm run build",
     "clean": "rm -rf dist",
@@ -12,6 +13,7 @@
     "build:unmin": "webpack index.js dist/html-dom-parser.js --output-library HTMLDOMParser --output-library-target umd",
     "test": "mocha",
     "lint": "eslint . --ignore-path .gitignore",
+    "dtslint": "dtslint types",
     "cover": "istanbul cover _mocha -- -R spec",
     "coveralls": "cat coverage/lcov.info | coveralls"
   },
@@ -33,8 +35,10 @@
     "htmlparser2": "3.9.1"
   },
   "devDependencies": {
+    "@types/domhandler": "^2.4.1",
     "chai": "^3.5.0",
     "coveralls": "^2.11.14",
+    "dtslint": "^0.5.9",
     "eslint": "^3.4.0",
     "html-minifier": "^3.1.0",
     "istanbul": "^0.4.5",

types/index.d.ts

@@ -0,0 +1,4 @@
+// TypeScript Version: 3.3
+
+import htmlToDomServer from './lib/html-to-dom-server';
+export default htmlToDomServer;

types/index.test.ts

@@ -0,0 +1,19 @@
+import parseDOM from 'html-dom-parser';
+
+// $ExpectType DomElement[]
+parseDOM('<div>text</div>');
+
+// $ExpectType DomElement[]
+parseDOM('<div>text</div>', { normalizeWhitespace: true });
+
+// $ExpectType DomElement[]
+parseDOM('<div>text</div>', { withDomLvl1: true });
+
+// $ExpectType DomElement[]
+parseDOM('<div>text</div>', { withStartIndices: true });
+
+// $ExpectType DomElement[]
+parseDOM('<div>text</div>', { withEndIndices: true });
+
+// $ExpectType DomElement[]
+parseDOM('');

types/lib/domparser.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parses HTML string to DOM nodes.
+ *
+ * @param - Raw string of HTML to parse.
+ * @returns NodeList or empty array.
+ */
+export default function parseDOM(html: string): NodeList | [];

types/lib/html-to-dom-client.d.ts

@@ -0,0 +1,9 @@
+import { DomElement } from 'domhandler';
+
+/**
+ * Parses HTML and reformats DOM nodes output.
+ *
+ * @param - Raw string of HTML to parse.
+ * @returns Parsed DomElements.
+ */
+export default function parseDOM(html: string): DomElement[];

types/lib/html-to-dom-server.d.ts

@@ -0,0 +1,14 @@
+import { DomHandlerOptions, DomElement } from 'domhandler';
+
+/**
+ * Parses HTML string to DOM nodes (server).
+ *
+ * @remarks
+ * This is the same method as `require('htmlparser2').parseDOM`
+ * https://github.com/fb55/htmlparser2/blob/v3.9.1/lib/index.js#L39-L43
+ *
+ * @param - Raw string of HTML to parse.
+ * @param - Options to pass to domhandler (See https://github.com/fb55/DomHandler#readme).
+ * @returns Parsed DomElements.
+ */
+export default function parseDOM(html: string, options?: DomHandlerOptions): DomElement[];

types/lib/utilities.d.ts

@@ -0,0 +1,26 @@
+import { DomElement } from 'domhandler';
+
+/**
+ * Format DOM attributes to an associative array.
+ *
+ * @param attributes - The list of attributes to format.
+ * @returns An object mapping attributes names to values.
+ */
+export function formatAttributes(attributes: NamedNodeMap): {[name: string]: string};
+
+/**
+ * Format the browser DOM nodes to mimic the output of `htmlparser2.parseDOM()`.
+ *
+ * @param nodes - The DOM nodes to format.
+ * @param parentObj - The formatted parent node of the given DOM nodes.
+ * @param directive - The directive.
+ */
+export function formatDOM(nodes: NodeList, parentObj?: DomElement, directive?: string): DomElement[];
+
+/**
+ * Detect IE with or without version.
+ *
+ * @param version The IE version to detect.
+ * @returns Whether IE or the version has been detected.
+ */
+export function isIE(version: number): boolean;

types/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["es6", "dom"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": { "html-dom-parser": ["."], "html-dom-parser/*": ["./*"] }
+  }
+}

types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "semicolon": false,
+    "indent": [true, "tabs"]
+  }
+}