Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

index.js

@@ -1 +1,5 @@
+/**
+ * @typedef {import('./lib/types.js').Options} Options
+ */
+
 export {toHtml} from './lib/index.js'

lib/all.js

@@ -1,7 +1,17 @@
+/**
+ * @typedef {import('./types.js').Handle} Handle
+ * @typedef {import('./types.js').Parent} Parent
+ */
 import {one} from './one.js'
 
-// Serialize all children of `parent`.
+/**
+ * Serialize all children of `parent`.
+ *
+ * @type {Handle}
+ * @param {Parent} parent
+ */
 export function all(ctx, parent) {
+  /** @type {Array.<string>} */
   var results = []
   var children = (parent && parent.children) || []
   var index = -1

lib/comment.js

@@ -1,5 +1,14 @@
+/**
+ * @typedef {import('./types.js').Handle} Handle
+ * @typedef {import('./types.js').Comment} Comment
+ */
+
 import {stringifyEntities} from 'stringify-entities'
 
+/**
+ * @type {Handle}
+ * @param {Comment} node
+ */
 export function comment(ctx, node) {
   // See: <https://html.spec.whatwg.org/multipage/syntax.html#comments>
   return ctx.bogusComments
@@ -11,6 +20,9 @@ export function comment(ctx, node) {
         '>'
     : '<!--' + node.value.replace(/^>|^->|<!--|-->|--!>|<!-$/g, encode) + '-->'
 
+  /**
+   * @param {string} $0
+   */
   function encode($0) {
     return stringifyEntities(
       $0,

lib/doctype.js

@@ -1,3 +1,10 @@
+/**
+ * @typedef {import('./types.js').Handle} Handle
+ */
+
+/**
+ * @type {Handle}
+ */
 export function doctype(ctx) {
   return (
     '<!' +

lib/element.js

@@ -1,3 +1,11 @@
+/**
+ * @typedef {import('./types.js').Handle} Handle
+ * @typedef {import('./types.js').Element} Element
+ * @typedef {import('./types.js').Context} Context
+ * @typedef {import('./types.js').Properties} Properties
+ * @typedef {import('./types.js').PropertyValue} PropertyValue
+ */
+
 import {svg, find} from 'property-information'
 import {stringify as spaces} from 'space-separated-tokens'
 import {stringify as commas} from 'comma-separated-tokens'
@@ -6,17 +14,25 @@ import {ccount} from 'ccount'
 import {all} from './all.js'
 import {constants} from './constants.js'
 
+/**
+ * @type {Handle}
+ * @param {Element} node
+ */
 // eslint-disable-next-line complexity
 export function element(ctx, node, index, parent) {
   var schema = ctx.schema
-  var omit = schema.space === 'svg' ? false : ctx.omit
-  var parts = []
+  var omit = schema.space === 'svg' ? undefined : ctx.omit
   var selfClosing =
     schema.space === 'svg'
       ? ctx.closeEmpty
       : ctx.voids.includes(node.tagName.toLowerCase())
+  /** @type {Array.<string>} */
+  var parts = []
+  /** @type {string} */
   var attrs
+  /** @type {string} */
   var content
+  /** @type {string} */
   var last
 
   if (schema.space === 'html' && node.tagName === 'svg') {
@@ -66,11 +82,20 @@ export function element(ctx, node, index, parent) {
   return parts.join('')
 }
 
+/**
+ * @param {Context} ctx
+ * @param {Properties} props
+ * @returns {string}
+ */
 function serializeAttributes(ctx, props) {
+  /** @type {Array.<string>} */
   var values = []
   var index = -1
+  /** @type {string} */
   var key
+  /** @type {string} */
   var value
+  /** @type {string} */
   var last
 
   for (key in props) {
@@ -92,11 +117,19 @@ function serializeAttributes(ctx, props) {
   return values.join('')
 }
 
+/**
+ * @param {Context} ctx
+ * @param {string} key
+ * @param {PropertyValue} value
+ * @returns {string}
+ */
 // eslint-disable-next-line complexity
 function serializeAttribute(ctx, key, value) {
   var info = find(ctx.schema, key)
   var quote = ctx.quote
+  /** @type {string} */
   var result
+  /** @type {string} */
   var name
 
   if (info.overloadedBoolean && (value === info.attribute || value === '')) {

lib/index.js

@@ -1,42 +1,59 @@
+/**
+ * @typedef {import('./types.js').Node} Node
+ * @typedef {import('./types.js').Options} Options
+ * @typedef {import('./types.js').Context} Context
+ * @typedef {import('./types.js').Quote} Quote
+ */
+
 import {html, svg} from 'property-information'
 import {htmlVoidElements} from 'html-void-elements'
 import {omission} from './omission/index.js'
 import {one} from './one.js'
 
-export function toHtml(node, options) {
-  var settings = options || {}
-  var quote = settings.quote || '"'
+/**
+ * @param {Node|Array.<Node>} node
+ * @param {Options} [options]
+ * @returns {string}
+ */
+export function toHtml(node, options = {}) {
+  var quote = options.quote || '"'
+  /** @type {Quote} */
   var alternative = quote === '"' ? "'" : '"'
 
   if (quote !== '"' && quote !== "'") {
     throw new Error('Invalid quote `' + quote + '`, expected `\'` or `"`')
   }
 
+  /** @type {Context} */
+  var context = {
+    valid: options.allowParseErrors ? 0 : 1,
+    safe: options.allowDangerousCharacters ? 0 : 1,
+    schema: options.space === 'svg' ? svg : html,
+    omit: options.omitOptionalTags ? omission : undefined,
+    quote,
+    alternative,
+    smart: options.quoteSmart,
+    unquoted: options.preferUnquoted,
+    tight: options.tightAttributes,
+    upperDoctype: options.upperDoctype,
+    tightDoctype: options.tightDoctype,
+    bogusComments: options.bogusComments,
+    tightLists: options.tightCommaSeparatedLists,
+    tightClose: options.tightSelfClosing,
+    collapseEmpty: options.collapseEmptyAttributes,
+    // @ts-ignore `allowDangerousHTML` is deprecated.
+    dangerous: options.allowDangerousHtml || options.allowDangerousHTML,
+    voids: options.voids || htmlVoidElements.concat(),
+    entities: options.entities || {},
+    close: options.closeSelfClosing,
+    closeEmpty: options.closeEmptyElements
+  }
+
   return one(
-    {
-      valid: settings.allowParseErrors ? 0 : 1,
-      safe: settings.allowDangerousCharacters ? 0 : 1,
-      schema: settings.space === 'svg' ? svg : html,
-      omit: settings.omitOptionalTags && omission,
-      quote,
-      alternative,
-      smart: settings.quoteSmart,
-      unquoted: settings.preferUnquoted,
-      tight: settings.tightAttributes,
-      upperDoctype: settings.upperDoctype,
-      tightDoctype: settings.tightDoctype,
-      bogusComments: settings.bogusComments,
-      tightLists: settings.tightCommaSeparatedLists,
-      tightClose: settings.tightSelfClosing,
-      collapseEmpty: settings.collapseEmptyAttributes,
-      dangerous: settings.allowDangerousHtml || settings.allowDangerousHTML,
-      voids: settings.voids || htmlVoidElements.concat(),
-      entities: settings.entities || {},
-      close: settings.closeSelfClosing,
-      closeEmpty: settings.closeEmptyElements
-    },
-    node && typeof node === 'object' && 'length' in node
-      ? {type: 'root', children: node}
-      : node
+    context,
+    // @ts-ignore Assume `node` does not contain a root.
+    Array.isArray(node) ? {type: 'root', children: node} : node,
+    null,
+    null
   )
 }