Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,3 +1,35 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('hast').DocType} HastDoctype
+ * @typedef {import('hast').Element} HastElement
+ * @typedef {import('hast').Comment} HastComment
+ * @typedef {import('hast').Text} HastText
+ * @typedef {import('hast').Properties[string]} HastPropertyValue
+ * @typedef {import('property-information').html['property'][string]} Info
+ * @typedef {import('xast').Root} BaseXastRoot
+ * @typedef {import('xast').Element} XastElement
+ * @typedef {import('xast').Text} XastText
+ * @typedef {import('xast').Comment} XastComment
+ * @typedef {import('xast').Doctype} XastDoctype
+ * @typedef {import('xast').Attributes} XastAttributes
+ * @typedef {import('xast').RootChildMap} RootChildMap
+ * @typedef {HastRoot|HastDoctype|HastElement|HastComment|HastText} HastNode
+ * @typedef {BaseXastRoot & {children: Array<XastElement|XastText|XastComment|XastDoctype>}} XastRoot
+ * @typedef {XastRoot|XastElement|XastText|XastComment|XastDoctype} XastNode
+ *
+ * @typedef {'html'|'svg'} Space
+ * @typedef Options
+ * @property {Space} [space]
+ *
+ * @typedef {html|svg} Schema
+ * @typedef {webNamespaces[Space]} Namespace
+ *
+ * @typedef Context
+ * @property {Schema} schema
+ * @property {Namespace} ns
+ */
+
 import {stringify as commas} from 'comma-separated-tokens'
 import {stringify as spaces} from 'space-separated-tokens'
 import {html, svg, find} from 'property-information'
@@ -13,52 +45,86 @@ var one = zwitch('type', {
   unknown
 })
 
+/**
+ * @param {unknown} value
+ */
 function invalid(value) {
   throw new Error('Expected node, not `' + value + '`')
 }
 
+/**
+ * @param {Node} value
+ */
 function unknown(value) {
   throw new Error('Cannot transform node of type `' + value.type + '`')
 }
 
+/**
+ * @param {HastNode} tree
+ * @param {Space|Options} [options]
+ */
 export function toXast(tree, options) {
   var space = typeof options === 'string' ? options : (options || {}).space
+  // @ts-ignore types are wrong.
   return one(tree, {schema: space === 'svg' ? svg : html, ns: null})
 }
 
+/**
+ * @param {HastRoot} node
+ * @param {Context} config
+ * @returns {XastRoot}
+ */
 function root(node, config) {
-  return patch(node, {type: 'root'}, config)
+  return patch(node, {type: 'root', children: all(node, config)})
 }
 
-function text(node, config) {
-  return patch(node, {type: 'text', value: node.value || ''}, config)
+/**
+ * @param {HastText} node
+ * @returns {XastText}
+ */
+function text(node) {
+  return patch(node, {type: 'text', value: node.value || ''})
 }
 
-function comment(node, config) {
-  return patch(node, {type: 'comment', value: node.value || ''}, config)
+/**
+ * @param {HastComment} node
+ * @returns {XastComment}
+ */
+function comment(node) {
+  return patch(node, {type: 'comment', value: node.value || ''})
 }
 
-function doctype(node, config) {
-  return patch(
-    node,
-    {
-      type: 'doctype',
-      name: node.name || '',
-      public: node.public,
-      system: node.system
-    },
-    config
-  )
+/**
+ * @param {HastDoctype} node
+ * @returns {XastDoctype}
+ */
+function doctype(node) {
+  return patch(node, {
+    type: 'doctype',
+    name: 'html',
+    public: undefined,
+    system: undefined
+  })
 }
 
+/**
+ * @param {HastElement} node
+ * @param {Context} parentConfig
+ * @returns {XastElement}
+ */
 // eslint-disable-next-line complexity
 function element(node, parentConfig) {
   var props = node.properties || {}
   var schema = parentConfig.schema
+  /** @type {XastAttributes} */
   var attributes = {}
+  /** @type {Context} */
   var config
+  /** @type {HastPropertyValue} */
   var value
+  /** @type {string} */
   var key
+  /** @type {Info} */
   var info
 
   if (props.xmlns === webNamespaces.html) {
@@ -81,6 +147,7 @@ function element(node, parentConfig) {
   }
 
   for (key in props) {
+    /* c8 ignore next 3 */
     if (!own.call(props, key)) {
       continue
     }
@@ -105,7 +172,7 @@ function element(node, parentConfig) {
     }
     // Accept `array`.
     // Most props are space-separated.
-    else if (typeof value === 'object' && 'length' in value) {
+    else if (Array.isArray(value)) {
       value = info.commaSeparated ? commas(value) : spaces(value)
     }
     // Cast everything else to string.
@@ -116,33 +183,50 @@ function element(node, parentConfig) {
     attributes[info.attribute] = value
   }
 
-  return patch(node, {type: 'element', name: node.tagName, attributes}, config)
+  // @ts-ignore Assume no `doctypes` in `element.`
+  return patch(node, {
+    type: 'element',
+    name: node.tagName,
+    attributes,
+    children: all(node, config)
+  })
 }
 
-function patch(origin, node, config) {
-  var index
+/**
+ * @param {HastRoot|HastElement} origin
+ * @param {Context} config
+ * @returns {Array.<XastElement|XastText|XastComment|XastDoctype>}
+ */
+function all(origin, config) {
+  /** @type {Array.<XastElement|XastText|XastComment|XastDoctype>} */
+  var result = []
+  var index = -1
 
   if (
     config.schema === html &&
     origin.type === 'element' &&
-    origin.tagName === 'template'
+    origin.tagName === 'template' &&
+    origin.content
   ) {
-    node.children = root(origin.content, config).children
-  } else if (
-    origin.children &&
-    (origin.type === 'element' || origin.type === 'root')
-  ) {
-    node.children = []
-    index = -1
-
-    while (++index < origin.children.length) {
-      node.children[index] = one(origin.children[index], config)
-    }
+    return root(origin.content, config).children
   }
 
-  if (origin.position) {
-    node.position = position(origin)
+  while (++index < origin.children.length) {
+    // @ts-ignore `zwitch` types are wrong.
+    result[index] = one(origin.children[index], config)
   }
 
+  return result
+}
+
+/**
+ * @template {XastNode} X
+ * @param {HastNode} origin
+ * @param {X} node
+ * @returns {X}
+ */
+function patch(origin, node) {
+  if (origin.position) node.position = position(origin)
+
   return node
 }

package.json

@@ -28,10 +28,15 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/hast": "^2.0.0",
+    "@types/unist": "^2.0.0",
+    "@types/xast": "^1.0.0",
     "comma-separated-tokens": "^2.0.0",
     "property-information": "^6.0.0",
     "space-separated-tokens": "^2.0.0",
@@ -40,21 +45,27 @@
     "zwitch": "^2.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "hastscript": "^6.0.0",
     "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",
     "unist-builder": "^3.0.0",
     "xastscript": "^2.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -75,5 +86,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -12,6 +12,7 @@ test('toXast', function (t) {
 
     t.throws(
       function () {
+        // @ts-ignore runtime.
         toXast()
       },
       /Error: Expected node, not `undefined`/,
@@ -20,6 +21,7 @@ test('toXast', function (t) {
 
     t.throws(
       function () {
+        // @ts-ignore well-known.
         toXast({type: 'raw', value: '<script>alert(1)</script>'})
       },
       /Error: Cannot transform node of type `raw`/,
@@ -85,6 +87,7 @@ test('toXast', function (t) {
     )
 
     t.deepEqual(
+      // @ts-ignore runtime.
       toXast(u('text')),
       u('text', ''),
       'should support a void text node'
@@ -101,6 +104,7 @@ test('toXast', function (t) {
     )
 
     t.deepEqual(
+      // @ts-ignore runtime.
       toXast(u('comment')),
       u('comment', ''),
       'should support a void comment node'
@@ -111,15 +115,10 @@ test('toXast', function (t) {
 
   t.test('doctype', function (t) {
     t.deepEqual(
-      toXast(u('doctype', {name: 'a'})),
-      u('doctype', {name: 'a', public: undefined, system: undefined}),
-      'should support a doctype node'
-    )
-
-    t.deepEqual(
+      // @ts-ignore hast@next.
       toXast(u('doctype')),
-      u('doctype', {name: '', public: undefined, system: undefined}),
-      'should support a doctype without a name'
+      u('doctype', {name: 'html', public: undefined, system: undefined}),
+      'should support a doctype node'
     )
 
     t.end()

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": ["*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}