Add types

Closes GH-17.

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>
Reviewed-by: Titus Wormer <tituswormer@gmail.com>

package.json

@@ -20,8 +20,10 @@
   ],
   "files": [
     "lib",
-    "index.js"
+    "index.js",
+    "types/index.d.ts"
   ],
+  "types": "types/index.d.ts",
   "dependencies": {
     "ccount": "^1.0.0",
     "comma-separated-tokens": "^1.0.1",
@@ -30,12 +32,14 @@
     "html-void-elements": "^1.0.0",
     "property-information": "^5.2.0",
     "space-separated-tokens": "^1.0.0",
-    "stringify-entities": "^2.0.0",
+    "stringify-entities": "^3.0.0",
     "unist-util-is": "^3.0.0",
     "xtend": "^4.0.1"
   },
   "devDependencies": {
+    "@types/unist": "^2.0.3",
     "browserify": "^16.0.0",
+    "dtslint": "^2.0.5",
     "hastscript": "^5.0.0",
     "nyc": "^14.0.0",
     "prettier": "^1.0.0",
@@ -47,13 +51,14 @@
     "xo": "^0.25.0"
   },
   "scripts": {
-    "format": "remark . -qfo && prettier --write \"**/*.js\" && xo --fix",
+    "format": "remark . -qfo && prettier --write \"**/*.{js,ts}\" && xo --fix",
     "build-bundle": "browserify . -s hastUtilToHtml > hast-util-to-html.js",
     "build-mangle": "browserify . -s hastUtilToHtml -p tinyify > hast-util-to-html.min.js",
     "build": "npm run build-bundle && npm run build-mangle",
     "test-api": "node test",
     "test-coverage": "nyc --reporter lcov tape test/index.js",
-    "test": "npm run format && npm run build && npm run test-coverage"
+    "test-types": "dtslint types",
+    "test": "npm run format && npm run build && npm run test-coverage && npm run test-types"
   },
   "prettier": {
     "tabWidth": 2,

types/index.d.ts

@@ -0,0 +1,182 @@
+// TypeScript Version: 3.5
+
+import {Node} from 'unist'
+import {StringifyEntitiesOptions} from 'stringify-entities'
+
+declare namespace hastUtilToHtml {
+  interface HastUtilToHtmlOptions {
+    /**
+     * Whether the *root* of the *tree* is in the `'html'` or `'svg'` space.
+     *
+     * If an `svg` element is found in the HTML space, `toHtml` automatically switches to the SVG space when entering the element, and switches back when exiting.
+     *
+     * @defaultValue 'html'
+     */
+    space: 'html' | 'svg'
+
+    /**
+     * Configuration for `stringify-entities`.
+     * Do not use `escapeOnly`, `attribute`, or `subset` (`toHtml` already passes those, so they won’t work).
+     * However, `useNamedReferences`, `useShortestReferences`, and `omitOptionalSemicolons` are all fine.
+     *
+     * @defaultValue {}
+     */
+    entities: Partial<
+      Omit<StringifyEntitiesOptions, 'escapeOnly' | 'attribute' | 'subset'>
+    >
+
+    /**
+     * Tag names of *elements* to stringify without closing tag.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue `require('html-void-elements')`
+     */
+    voids: string[]
+
+    /**
+     * Use an `<!DOCTYPE…` instead of `<!doctype…`.
+     * Useless except for XHTML.
+     *
+     * @defaultValue false
+     */
+    upperDoctype: boolean
+
+    /**
+     * Preferred quote to use.
+     *
+     * @defaultValue '"'
+     */
+    quote: '"' | "'"
+
+    /**
+     * Use the other quote if that results in less bytes.
+     *
+     * @defaultValue false
+     */
+    quoteSmart: boolean
+
+    /**
+     * Leave attributes unquoted if that results in less bytes.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue false
+     */
+    preferUnquoted: boolean
+
+    /**
+     * Omit optional opening and closing tags.
+     * For example, in `<ol><li>one</li><li>two</li></ol>`, both `</li>` closing tags can be omitted.
+     * The first because it’s followed by another `li`, the last because it’s followed by nothing.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue false
+     */
+    omitOptionalTags: boolean
+
+    /**
+     * Collapse empty attributes: `class=""` is stringified as `class` instead.
+     * **Note**: boolean attributes, such as `hidden`, are always collapsed.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue false
+     */
+    collapseEmptyAttributes: boolean
+
+    /**
+     * Close self-closing nodes with an extra slash (`/`): `<img />` instead of `<img>`.
+     * See `tightSelfClosing` to control whether a space is used before the slash.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue false
+     */
+    closeSelfClosing: boolean
+
+    /**
+     * Close SVG elements without any content with slash (`/`) on the opening tag instead of an end tag: `<circle />` instead of `<circle></circle>`.
+     * See `tightSelfClosing` to control whether a space is used before the slash.
+     *
+     * Not used in the HTML space.
+     *
+     * @defaultValue false
+     */
+    closeEmptyElements: boolean
+
+    /**
+     * Do not use an extra space when closing self-closing elements: `<img/>` instead of `<img />`.
+     * **Note**: Only used if `closeSelfClosing: true` or `closeEmptyElements: true`.
+     *
+     * @defaultValue false
+     */
+    tightSelfClosing: boolean
+
+    /**
+     * Join known comma-separated attribute values with just a comma (`,`), instead of padding them on the right as well (`,·`, where `·` represents a space).
+     *
+     * @defaultValue false
+     */
+    tightCommaSeparatedLists: boolean
+
+    /**
+     * Join attributes together, without white-space, if possible: `class="a b" title="c d"` is stringified as `class="a b"title="c d"` instead to save bytes.
+     * **Note**: creates invalid (but working) markup.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue false
+     */
+    tightAttributes: boolean
+
+    /**
+     * Drop unneeded spaces in doctypes: `<!doctypehtml>` instead of `<!doctype html>` to save bytes.
+     * **Note**: creates invalid (but working) markup.
+     *
+     * @defaultValue false
+     */
+    tightDoctype: boolean
+
+    /**
+     * Do not encode characters which cause parse errors (even though they work), to save bytes.
+     * **Note**: creates invalid (but working) markup.
+     *
+     * Not used in the SVG space.
+     *
+     * @defaultValue false
+     */
+    allowParseErrors: boolean
+
+    /**
+     * Do not encode some characters which cause XSS vulnerabilities in older browsers.
+     * **Note**: Only set this if you completely trust the content.
+     *
+     * @defaultValue false
+     */
+    allowDangerousCharacters: boolean
+
+    /**
+     * Allow `raw` nodes and insert them as raw HTML.
+     * When falsey, encodes `raw` nodes.
+     * **Note**: Only set this if you completely trust the content.
+     *
+     * @defaultValue false
+     */
+    allowDangerousHTML: boolean
+  }
+}
+
+/**
+ * Stringify the given **hast** *tree*.
+ *
+ * @param tree given hast tree
+ * @param options configuration for stringifier
+ */
+declare function hastUtilToHtml(
+  tree: Node,
+  options?: Partial<hastUtilToHtml.HastUtilToHtmlOptions>
+): string
+
+export = hastUtilToHtml

types/tests.ts

@@ -0,0 +1,73 @@
+import toHtml = require('hast-util-to-html')
+import {Node} from 'unist'
+
+const node: Node = {
+  type: 'element',
+  tagName: 'div'
+}
+
+const result: string = toHtml(node)
+toHtml(node, {
+  space: 'html'
+})
+toHtml(node, {
+  space: 'svg'
+})
+toHtml(node, {
+  space: 'svg'
+})
+toHtml(node, {entities: {useNamedReferences: true}})
+// $ExpectError
+toHtml(node, {entities: {escapeOnly: true}})
+// $ExpectError
+toHtml(node, {entities: {attribute: true}})
+// $ExpectError
+toHtml(node, {entities: {subset: ['subset']}})
+toHtml(node, {
+  voids: ['hr']
+})
+toHtml(node, {
+  upperDoctype: true
+})
+toHtml(node, {
+  quote: "'"
+})
+toHtml(node, {
+  quoteSmart: true
+})
+toHtml(node, {
+  preferUnquoted: true
+})
+toHtml(node, {
+  omitOptionalTags: true
+})
+toHtml(node, {
+  collapseEmptyAttributes: true
+})
+toHtml(node, {
+  closeSelfClosing: true
+})
+toHtml(node, {
+  closeEmptyElements: true
+})
+toHtml(node, {
+  tightSelfClosing: true
+})
+toHtml(node, {
+  tightCommaSeparatedLists: true
+})
+toHtml(node, {
+  tightAttributes: true
+})
+toHtml(node, {
+  tightDoctype: true
+})
+toHtml(node, {
+  allowParseErrors: true
+})
+toHtml(node, {
+  allowDangerousCharacters: true
+})
+toHtml(node, {
+  allowDangerousHTML: true
+})

types/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "lib": ["es2015"],
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "hast-util-to-html": ["index.d.ts"]
+    }
+  }
+}

types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "semicolon": false,
+    "whitespace": false
+  }
+}