Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,6 +1,6 @@
 .DS_Store
+*.d.ts
 *.log
-.nyc_output/
 coverage/
 node_modules/
 yarn.lock

.prettierignore

@@ -1,3 +1,2 @@
 coverage/
-*.json
 *.md

index.js

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

lib/all.js

@@ -1,13 +1,28 @@
+/**
+ * @typedef {import('./index.js').Parent} Parent
+ * @typedef {import('./index.js').Context} Context
+ * @typedef {import('./index.js').Child} Child
+ */
+
 import {one} from './one.js'
 
-// Serialize all children of `parent`.
-export function all(parent, config) {
+/**
+ * Serialize all children of `parent`.
+ *
+ * @param {Parent} parent
+ * @param {Context} ctx
+ * @returns {string}
+ *
+ */
+export function all(parent, ctx) {
+  /** @type {Array.<Child>} */
   var children = (parent && parent.children) || []
   var index = -1
+  /** @type {Array.<string>} */
   var results = []
 
   while (++index < children.length) {
-    results[index] = one(children[index], config)
+    results[index] = one(children[index], ctx)
   }
 
   return results.join('')

lib/cdata.js

@@ -1,9 +1,19 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('./index.js').Cdata} Cdata
+ */
+
 import {escape} from './util-escape.js'
 
 var unsafe = /]]>/g
 var subset = ['>']
 
-// Serialize a CDATA section.
+/**
+ * Serialize a CDATA section.
+ *
+ * @type {Handle}
+ * @param {Cdata} node
+ */
 export function cdata(node) {
   return '<![CDATA[' + escape(node.value, subset, unsafe) + ']]>'
 }

lib/comment.js

@@ -1,6 +1,16 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('./index.js').Comment} Comment
+ */
+
 import {escape} from './util-escape.js'
 
-// Serialize a comment.
+/**
+ * Serialize a comment.
+ *
+ * @type {Handle}
+ * @param {Comment} node
+ */
 export function comment(node) {
   return '<!--' + escape(node.value, ['-']) + '-->'
 }

lib/doctype.js

@@ -1,8 +1,18 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('./index.js').Doctype} Doctype
+ */
+
 import {name} from './name.js'
 import {value} from './value.js'
 
-// Serialize a document type.
-export function doctype(node, config) {
+/**
+ * Serialize a doctype.
+ *
+ * @type {Handle}
+ * @param {Doctype} node
+ */
+export function doctype(node, ctx) {
   var nodeName = name(node.name)
   var pub = node.public
   var sys = node.system
@@ -13,13 +23,13 @@ export function doctype(node, config) {
   }
 
   if (pub !== null && pub !== undefined && pub !== '') {
-    result += ' PUBLIC ' + value(pub, config)
+    result += ' PUBLIC ' + value(pub, ctx)
   } else if (sys !== null && sys !== undefined && sys !== '') {
     result += ' SYSTEM'
   }
 
   if (sys !== null && sys !== undefined && sys !== '') {
-    result += ' ' + value(sys, config)
+    result += ' ' + value(sys, ctx)
   }
 
   return result + '>'

lib/element.js

@@ -1,25 +1,40 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('./index.js').Element} Element
+ * @typedef {import('./index.js').Attributes} Attributes
+ */
+
 import {all} from './all.js'
 import {name} from './name.js'
 import {value} from './value.js'
 
 var own = {}.hasOwnProperty
 
-// Serialize an element.
-export function element(node, config) {
+/**
+ * Serialize an element.
+ *
+ * @type {Handle}
+ * @param {Element} node
+ */
+export function element(node, ctx) {
   var nodeName = name(node.name)
-  var content = all(node, config)
+  var content = all(node, ctx)
+  /** @type {Attributes} */
   var attributes = node.attributes || {}
-  var close = content ? false : config.close
+  var close = content ? false : ctx.close
+  /** @type {Array.<string>} */
   var attrs = []
+  /** @type {string} */
   var key
+  /** @type {Attributes[keyof Attributes]} */
   var result
 
   for (key in attributes) {
     if (own.call(attributes, key)) {
       result = attributes[key]
 
       if (result !== null && result !== undefined) {
-        attrs.push(name(key) + '=' + value(result, config))
+        attrs.push(name(key) + '=' + value(result, ctx))
       }
     }
   }
@@ -28,7 +43,7 @@ export function element(node, config) {
     '<' +
     nodeName +
     (attrs.length === 0 ? '' : ' ' + attrs.join(' ')) +
-    (close ? (config.tight ? '' : ' ') + '/' : '') +
+    (close ? (ctx.tight ? '' : ' ') + '/' : '') +
     '>' +
     content +
     (close ? '' : '</' + nodeName + '>')

lib/index.js

@@ -1,35 +1,72 @@
-import {one} from './one.js'
+/**
+ * @typedef {import('xast').Root} Root
+ * @typedef {import('xast').Element} Element
+ * @typedef {import('xast').Cdata} Cdata
+ * @typedef {import('xast').Comment} Comment
+ * @typedef {import('xast').Doctype} Doctype
+ * @typedef {import('xast').Instruction} Instruction
+ * @typedef {import('xast').Text} Text
+ * @typedef {import('xast').Literal & {type: 'raw'}} Raw
+ * @typedef {Root|Element} Parent
+ * @typedef {import('xast').Attributes} Attributes
+ * @typedef {Root['children'][number]} Child
+ * @typedef {Child|Root} Node
+ *
+ * @typedef {'"'|"'"} Quote
+ *
+ * @typedef Options
+ * @property {Quote} [quote='"'] Preferred quote to use
+ * @property {boolean} [quoteSmart=false] Use the other quote if that results in
+ *   less bytes
+ * @property {boolean} [closeEmptyElements=false] Close elements without any
+ *   content with slash (/) on the opening tag instead of an end tag:
+ *   `<circle />` instead of `<circle></circle>`.
+ *   See `tightClose` to control whether a space is used before the slash.
+ * @property {boolean} [tightClose=false] Do not use an extra space when closing
+ *    self-closing elements: `<circle/>` instead of `<circle />`.
+ * @property {boolean} [allowDangerousXml=false] Allow `raw` nodes and insert
+ *   them as raw XML. When falsey, encodes `raw` nodes.
+ *   Only set this if you completely trust the content!
+ *
+ * @typedef Context
+ * @property {Quote} quote
+ * @property {Quote} alternative
+ * @property {boolean} close
+ * @property {boolean} tight
+ * @property {boolean} dangerous
+ *
+ * @callback Handle
+ * @param {Node} node
+ * @param {Context} context
+ * @returns {string}
+ */
 
-var quotationMark = '"'
-var apostrophe = "'"
+import {one} from './one.js'
 
-// Serialize the given node.
-export function toXml(node, options) {
-  var settings = options || {}
-  var quote = settings.quote || quotationMark
-  var alternative = quote === quotationMark ? apostrophe : quotationMark
-  var smart = settings.quoteSmart
-  var value =
-    node && typeof node === 'object' && 'length' in node
-      ? {type: 'root', children: node}
-      : node
+/**
+ * Serialize the given xast tree (or list of nodes).
+ *
+ * @param {Node|Array.<Node>} node
+ * @param {Options} [options]
+ * @returns {string}
+ */
+export function toXml(node, options = {}) {
+  var quote = options.quote || '"'
+  /** @type {Quote} */
+  var alternative = quote === '"' ? "'" : '"'
+  var smart = options.quoteSmart
+  /** @type {Node} */
+  // @ts-ignore Assume no `root` in `node`.
+  var value = Array.isArray(node) ? {type: 'root', children: node} : node
 
-  if (quote !== quotationMark && quote !== apostrophe) {
-    throw new Error(
-      'Invalid quote `' +
-        quote +
-        '`, expected `' +
-        apostrophe +
-        '` or `' +
-        quotationMark +
-        '`'
-    )
+  if (quote !== '"' && quote !== "'") {
+    throw new Error('Invalid quote `' + quote + '`, expected `\'` or `"`')
   }
 
   return one(value, {
-    dangerous: settings.allowDangerousXml,
-    close: settings.closeEmptyElements,
-    tight: settings.tightClose,
+    dangerous: options.allowDangerousXml,
+    close: options.closeEmptyElements,
+    tight: options.tightClose,
     quote,
     alternative: smart ? alternative : null
   })

lib/instruction.js

@@ -1,10 +1,20 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('./index.js').Instruction} Instruction
+ */
+
 import {escape} from './util-escape.js'
 import {name} from './name.js'
 
 var unsafe = /\?>/g
 var subset = ['>']
 
-// Serialize a processing instruction.
+/**
+ * Serialize an instruction.
+ *
+ * @type {Handle}
+ * @param {Instruction} node
+ */
 export function instruction(node) {
   var nodeName = name(node.name) || 'x'
   var result = escape(node.value, subset, unsafe)

lib/name.js

@@ -2,6 +2,12 @@ import {escape} from './util-escape.js'
 
 var subset = ['\t', '\n', ' ', '"', '&', "'", '/', '<', '=', '>']
 
+/**
+ * Serialize a node name.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
 export function name(value) {
   return escape(value, subset)
 }

lib/one.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ */
+
 import {all} from './all.js'
 import {element} from './element.js'
 import {text} from './text.js'
@@ -9,19 +13,23 @@ import {raw} from './raw.js'
 
 var own = {}.hasOwnProperty
 
-var handlers = {}
-
-handlers.root = all
-handlers.element = element
-handlers.text = text
-handlers.comment = comment
-handlers.doctype = doctype
-handlers.instruction = instruction
-handlers.cdata = cdata
-handlers.raw = raw
+var handlers = {
+  root: all,
+  element,
+  text,
+  comment,
+  doctype,
+  instruction,
+  cdata,
+  raw
+}
 
-// Serialize one node.
-export function one(node, config) {
+/**
+ * Serialize a node.
+ *
+ * @type {Handle}
+ */
+export function one(node, ctx) {
   var type = node && node.type
 
   if (!type) {
@@ -32,5 +40,6 @@ export function one(node, config) {
     throw new Error('Cannot compile unknown node `' + type + '`')
   }
 
-  return handlers[type](node, config)
+  // @ts-ignore Hush, it works.
+  return handlers[type](node, ctx)
 }

lib/raw.js

@@ -1,6 +1,17 @@
+/**
+ * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('./index.js').Raw} Raw
+ */
+
 import {text} from './text.js'
 
-// Serialize raw.
-export function raw(node, config) {
-  return config.dangerous ? node.value : text(node, config)
+/**
+ * Serialize a (non-standard) raw.
+ *
+ * @type {Handle}
+ * @param {Raw} node
+ */
+export function raw(node, ctx) {
+  // @ts-ignore Looks like a text.
+  return ctx.dangerous ? node.value : text(node)
 }