From 995230ed1d247a2855831434f5efc1bc130c772f Mon Sep 17 00:00:00 2001 From: Junyoung Choi Date: Tue, 14 Jan 2020 11:27:13 -0500 Subject: [PATCH 1/3] Add types --- package.json | 13 ++-- types/index.d.ts | 141 ++++++++++++++++++++++++++++++++++++++++++++ types/tests.ts | 71 ++++++++++++++++++++++ types/tsconfig.json | 10 ++++ types/tslint.json | 7 +++ 5 files changed, 238 insertions(+), 4 deletions(-) create mode 100644 types/index.d.ts create mode 100644 types/tests.ts create mode 100644 types/tsconfig.json create mode 100644 types/tslint.json diff --git a/package.json b/package.json index e806561..e658c2d 100644 --- a/package.json +++ b/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, diff --git a/types/index.d.ts b/types/index.d.ts new file mode 100644 index 0000000..adc0dd2 --- /dev/null +++ b/types/index.d.ts @@ -0,0 +1,141 @@ +// TypeScript Version: 3.0 + +import {Node} from 'unist' +import stringifyEntities = require('stringify-entities') + +declare namespace hastUtilToHtml { + interface HastUtilToHtmlOptions { + /** + * Whether the *root* of the *tree* is in the `'html'` or `'svg'` space (enum, `'svg'` or `'html'`, default: `'html'`). + * + * 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. + */ + space: 'html' | 'svg' + + /** + * Configuration for `stringify-entities` (`Object`, default: `{}`). + * Do not use `escapeOnly`, `attribute`, or `subset` (`toHtml` already passes those, so they won’t work). + * However, `useNamedReferences`, `useShortestReferences`, and `omitOptionalSemicolons` are all fine. + */ + entities: Partial + + /** + * Tag names of *elements* to stringify without closing tag(`Array.`, default: `html-void-elements`). + * + * Not used in the SVG space. + */ + voids: string[] + + /** + * Use an `
  • one
  • two
    • `, both `` 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. + */ + omitOptionalTags: boolean + + /** + * Collapse empty attributes: `class=""` is stringified as `class` instead (`boolean`, default: `false`). + * **Note**: boolean attributes, such as `hidden`, are always collapsed. + * + * Not used in the SVG space. + */ + collapseEmptyAttributes: boolean + + /** + * Close self-closing nodes with an extra slash (`/`): `` instead of `` (`boolean`, default: `false`). + * See `tightSelfClosing` to control whether a space is used before the slash. + * + * Not used in the SVG space. + */ + closeSelfClosing: boolean + + /** + * Close SVG elements without any content with slash (`/`) on the opening tag instead of an end tag: `` instead of `` (`boolean`, default: `false`). + * See `tightSelfClosing` to control whether a space is used before the slash. + * + * Not used in the HTML space. + */ + closeEmptyElements: boolean + + /** + * Do not use an extra space when closing self-closing elements: `` instead of `` (`boolean`, default: `false`). + * **Note**: Only used if `closeSelfClosing: true` or `closeEmptyElements: true`. + */ + 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) (`boolean`, default: `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 (`boolean`, default: `false`). + * **Note**: creates invalid (but working) markup. + * + * Not used in the SVG space. + */ + tightAttributes: boolean + + /** + * Drop unneeded spaces in doctypes: `` instead of `` to save bytes (`boolean`, default: `false`). + * **Note**: creates invalid (but working) markup. + */ + tightDoctype: boolean + + /** + * Do not encode characters which cause parse errors (even though they work), to save bytes (`boolean`, default: `false`). + * **Note**: creates invalid (but working) markup. + * + * Not used in the SVG space. + */ + allowParseErrors: boolean + + /** + * Do not encode some characters which cause XSS vulnerabilities in older browsers (`boolean`, default: `false`). + * **Note**: Only set this if you completely trust the content. + */ + allowDangerousCharacters: boolean + + /** + * Allow `raw` nodes and insert them as raw HTML. + * When falsey, encodes `raw` nodes (`boolean`, default: `false`). + * **Note**: Only set this if you completely trust the content. + */ + allowDangerousHTML: boolean + } +} + +/** + * Stringify the given **hast** *tree*. + */ +declare function hastUtilToHtml( + tree: Node, + options?: Partial +): string + +export = hastUtilToHtml diff --git a/types/tests.ts b/types/tests.ts new file mode 100644 index 0000000..b12f463 --- /dev/null +++ b/types/tests.ts @@ -0,0 +1,71 @@ +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: { + escapeOnly: true + } +}) +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 +}) diff --git a/types/tsconfig.json b/types/tsconfig.json new file mode 100644 index 0000000..633d2fe --- /dev/null +++ b/types/tsconfig.json @@ -0,0 +1,10 @@ +{ + "compilerOptions": { + "lib": ["es2015"], + "strict": true, + "baseUrl": ".", + "paths": { + "hast-util-to-html": ["index.d.ts"] + } + } +} diff --git a/types/tslint.json b/types/tslint.json new file mode 100644 index 0000000..70c4494 --- /dev/null +++ b/types/tslint.json @@ -0,0 +1,7 @@ +{ + "extends": "dtslint/dtslint.json", + "rules": { + "semicolon": false, + "whitespace": false + } +} From 5280265385e4c1d4501358a2f3ddaa0633474ae5 Mon Sep 17 00:00:00 2001 From: Junyoung Choi Date: Wed, 15 Jan 2020 11:38:07 -0500 Subject: [PATCH 2/3] Resolve change requests --- types/index.d.ts | 10 ++++++---- types/tests.ts | 12 +++++++----- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index adc0dd2..0d2f71a 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -1,7 +1,7 @@ -// TypeScript Version: 3.0 +// TypeScript Version: 3.5 import {Node} from 'unist' -import stringifyEntities = require('stringify-entities') +import {StringifyEntitiesOptions} from 'stringify-entities' declare namespace hastUtilToHtml { interface HastUtilToHtmlOptions { @@ -17,7 +17,9 @@ declare namespace hastUtilToHtml { * Do not use `escapeOnly`, `attribute`, or `subset` (`toHtml` already passes those, so they won’t work). * However, `useNamedReferences`, `useShortestReferences`, and `omitOptionalSemicolons` are all fine. */ - entities: Partial + entities: Partial< + Omit + > /** * Tag names of *elements* to stringify without closing tag(`Array.`, default: `html-void-elements`). @@ -35,7 +37,7 @@ declare namespace hastUtilToHtml { /** * Preferred quote to use (`'"'` or `'\''`, default: `'"'`). */ - quote: string + quote: '"' | "'" /** * Use the other quote if that results in less bytes (`boolean`, default: `false`). diff --git a/types/tests.ts b/types/tests.ts index b12f463..d998c61 100644 --- a/types/tests.ts +++ b/types/tests.ts @@ -16,11 +16,13 @@ toHtml(node, { toHtml(node, { space: 'svg' }) -toHtml(node, { - entities: { - escapeOnly: true - } -}) +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'] }) From 318112f2c59275c59d8b687f75f4c21b12486f44 Mon Sep 17 00:00:00 2001 From: Christian Murphy Date: Wed, 15 Jan 2020 11:45:18 -0700 Subject: [PATCH 3/3] docs: add typedoc annotations --- types/index.d.ts | 75 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 18 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index 0d2f71a..3e58d65 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -6,127 +6,163 @@ import {StringifyEntitiesOptions} from 'stringify-entities' declare namespace hastUtilToHtml { interface HastUtilToHtmlOptions { /** - * Whether the *root* of the *tree* is in the `'html'` or `'svg'` space (enum, `'svg'` or `'html'`, default: `'html'`). + * 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` (`Object`, default: `{}`). + * 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 > /** - * Tag names of *elements* to stringify without closing tag(`Array.`, default: `html-void-elements`). + * Tag names of *elements* to stringify without closing tag. * * Not used in the SVG space. + * + * @defaultValue `require('html-void-elements')` */ voids: string[] /** * Use an `
  • one
  • two
    • `, both `` 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 (`boolean`, default: `false`). + * 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 (`/`): `` instead of `` (`boolean`, default: `false`). + * Close self-closing nodes with an extra slash (`/`): `` instead of ``. * 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: `` instead of `` (`boolean`, default: `false`). + * Close SVG elements without any content with slash (`/`) on the opening tag instead of an end tag: `` instead of ``. * 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: `` instead of `` (`boolean`, default: `false`). + * Do not use an extra space when closing self-closing elements: `` instead of ``. * **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) (`boolean`, default: `false`). + * 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 (`boolean`, default: `false`). + * 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: `` instead of `` to save bytes (`boolean`, default: `false`). + * Drop unneeded spaces in doctypes: `` instead of `` 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 (`boolean`, default: `false`). + * 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 (`boolean`, default: `false`). + * 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 (`boolean`, default: `false`). + * When falsey, encodes `raw` nodes. * **Note**: Only set this if you completely trust the content. + * + * @defaultValue false */ allowDangerousHTML: boolean } @@ -134,6 +170,9 @@ declare namespace hastUtilToHtml { /** * Stringify the given **hast** *tree*. + * + * @param tree given hast tree + * @param options configuration for stringifier */ declare function hastUtilToHtml( tree: Node,