Add JSDoc based types

Author: wooorm

index.js

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

lib/index.js

@@ -1,49 +1,84 @@
+/**
+ * @typedef {import('hast').Parent} HastParent
+ * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('hast').DocType} HastDoctype
+ * @typedef {import('hast').Element} HastElement
+ * @typedef {import('hast').Text} HastText
+ * @typedef {import('hast').Comment} HastComment
+ * @typedef {HastParent['children'][number]} HastChild
+ * @typedef {HastChild|HastRoot} HastNode
+ *
+ * @typedef Options
+ * @property {boolean} [fragment=false] Whether a DOM fragment should be returned
+ * @property {Document} [document] Document interface to use (default: `globalThis.document`)
+ * @property {string} [namespace] `namespace` to use to create elements
+ *
+ * @typedef Context
+ * @property {Document} doc
+ * @property {boolean} [fragment=false]
+ * @property {string} [namespace]
+ * @property {string} [impliedNamespace]
+ */
+
 import {webNamespaces} from 'web-namespaces'
 import {find, html, svg} from 'property-information'
 
 /* eslint-env browser */
 
-function transform(node, options) {
+/**
+ * @param {HastNode} node
+ * @param {Context} [ctx]
+ */
+function transform(node, ctx) {
   switch (node.type) {
     case 'root':
-      return root(node, options)
+      return root(node, ctx)
     case 'text':
-      return text(node, options)
+      return text(node, ctx)
     case 'element':
-      return element(node, options)
+      return element(node, ctx)
     case 'doctype':
-      return doctype(node, options)
+      return doctype(node, ctx)
     case 'comment':
-      return comment(node, options)
+      return comment(node, ctx)
     default:
-      return element(node, options)
+      return element(node, ctx)
   }
 }
 
-// Create a document.
-function root(node, options) {
-  const {doc, fragment, namespace: optionsNamespace} = options
+/**
+ * Create a document.
+ *
+ * @param {HastRoot} node
+ * @param {Context} ctx
+ * @returns {XMLDocument|DocumentFragment|HTMLHtmlElement}
+ */
+function root(node, ctx) {
+  const {doc, fragment, namespace: ctxNamespace} = ctx
   const {children = []} = node
   const {length: childrenLength} = children
 
-  let namespace = optionsNamespace
+  let namespace = ctxNamespace
   let rootIsDocument = childrenLength === 0
 
   for (let i = 0; i < childrenLength; i += 1) {
-    const {tagName, properties = {}} = children[i]
+    const child = children[i]
+
+    if (child.type === 'element' && child.tagName === 'html') {
+      const {properties = {}} = child
 
-    if (tagName === 'html') {
       // If we have a root HTML node, we don’t need to render as a fragment.
       rootIsDocument = true
 
       // Take namespace of the first child.
-      if (typeof optionsNamespace === 'undefined') {
-        namespace = properties.xmlns || webNamespaces.html
+      if (typeof ctxNamespace === 'undefined') {
+        namespace = String(properties.xmlns || '') || webNamespaces.html
       }
     }
   }
 
   // The root node will be a Document, DocumentFragment, or HTMLElement.
+  /** @type {XMLDocument|DocumentFragment|HTMLHtmlElement} */
   let result
 
   if (rootIsDocument) {
@@ -55,14 +90,20 @@ function root(node, options) {
   }
 
   return appendAll(result, children, {
-    ...options,
+    ...ctx,
     fragment,
     namespace,
     impliedNamespace: namespace
   })
 }
 
-// Create a `doctype`.
+/**
+ * Create a `doctype`.
+ *
+ * @param {HastDoctype} node
+ * @param {Context} ctx
+ * @returns {DocumentType}
+ */
 function doctype(node, {doc}) {
   return doc.implementation.createDocumentType(
     node.name || 'html',
@@ -71,21 +112,39 @@ function doctype(node, {doc}) {
   )
 }
 
-// Create a `text`.
+/**
+ * Create a `text`.
+ *
+ * @param {HastText} node
+ * @param {Context} ctx
+ * @returns {Text}
+ */
 function text(node, {doc}) {
   return doc.createTextNode(node.value)
 }
 
-// Create a `comment`.
+/**
+ * Create a `comment`.
+ *
+ * @param {HastComment} node
+ * @param {Context} ctx
+ * @returns {Comment}
+ */
 function comment(node, {doc}) {
   return doc.createComment(node.value)
 }
 
-// Create an `element`.
+/**
+ * Create an `element`.
+ *
+ * @param {HastElement} node
+ * @param {Context} ctx
+ * @returns {Element}
+ */
 // eslint-disable-next-line complexity
-function element(node, options) {
-  const {namespace, doc} = options
-  let impliedNamespace = options.impliedNamespace || namespace
+function element(node, ctx) {
+  const {namespace, doc} = ctx
+  let impliedNamespace = ctx.impliedNamespace || namespace
   const {
     tagName = impliedNamespace === webNamespaces.svg ? 'g' : 'div',
     properties = {},
@@ -147,29 +206,45 @@ function element(node, options) {
         result.removeAttribute(attribute)
       }
     } else if (booleanish) {
-      result.setAttribute(attribute, value)
+      result.setAttribute(attribute, String(value))
     } else if (value === true) {
       result.setAttribute(attribute, '')
     } else if (value || value === 0 || value === '') {
-      result.setAttribute(attribute, value)
+      result.setAttribute(attribute, String(value))
     }
   }
 
-  return appendAll(result, children, {...options, impliedNamespace})
+  return appendAll(result, children, {...ctx, impliedNamespace})
 }
 
-// Add all children.
-function appendAll(node, children, options) {
-  const childrenLength = children.length
-
-  for (let i = 0; i < childrenLength; i += 1) {
+/**
+ * Add all children.
+ *
+ * @template {Node} N
+ * @param {N} node
+ * @param {Array.<HastChild>} children
+ * @param {Context} ctx
+ * @returns {N}
+ */
+function appendAll(node, children, ctx) {
+  let index = -1
+
+  while (++index < children.length) {
     // eslint-disable-next-line unicorn/prefer-dom-node-append
-    node.appendChild(transform(children[i], options))
+    node.appendChild(transform(children[index], ctx))
   }
 
   return node
 }
 
-export function toDom(hast, options = {}) {
-  return transform(hast, {...options, doc: options.document || document})
+/**
+ * Transform a hast tree to a DOM tree
+ *
+ * @param {HastNode} node
+ * @param {Options} [options]
+ * @returns {Node}
+ */
+export function toDom(node, options = {}) {
+  const {document: doc = document, ...rest} = options
+  return transform(node, {doc, ...rest})
 }

package.json

@@ -27,31 +27,41 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "lib/",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "property-information": "^6.0.0",
     "web-namespaces": "^2.0.0"
   },
   "devDependencies": {
+    "@types/jsdom": "^16.0.0",
+    "@types/tape": "^4.0.0",
+    "@types/w3c-xmlserializer": "^2.0.0",
     "c8": "^7.0.0",
     "glob": "^7.0.0",
     "hastscript": "^7.0.0",
     "jsdom": "^16.5.3",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "w3c-xmlserializer": "^2.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"{lib/**,test/**,}*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test/index.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test/index.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -68,5 +78,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

readme.md

@@ -82,7 +82,7 @@ Whether a DOM fragment should be returned (default: `false`).
 
 ###### `options.document`
 
-Document interface to use (default: `global.document`).
+Document interface to use (default: `globalThis.document`).
 
 ###### `options.namespace`