Refactor code-style

Author: wooorm

lib/index.js

@@ -1,57 +1,59 @@
 /**
- * @typedef {import('parse5').DefaultTreeAdapterMap} DefaultTreeAdapterMap
- * @typedef {DefaultTreeAdapterMap['document']} P5Document
- * @typedef {DefaultTreeAdapterMap['documentFragment']} P5Fragment
- * @typedef {DefaultTreeAdapterMap['element']} P5Element
- * @typedef {DefaultTreeAdapterMap['node']} P5Node
- * @typedef {DefaultTreeAdapterMap['documentType']} P5Doctype
- * @typedef {DefaultTreeAdapterMap['commentNode']} P5Comment
- * @typedef {DefaultTreeAdapterMap['textNode']} P5Text
- * @typedef {DefaultTreeAdapterMap['parentNode']} P5Parent
- * @typedef {import('parse5').Token.Attribute} P5Attribute
- * @typedef {Exclude<P5Node, P5Document | P5Fragment>} P5Child
- * @typedef {import('property-information').Schema} Schema
- * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').Comment} Comment
  * @typedef {import('hast').Doctype} Doctype
  * @typedef {import('hast').Element} Element
+ * @typedef {import('hast').Nodes} Nodes
+ * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').RootContent} RootContent
  * @typedef {import('hast').Text} Text
- * @typedef {import('hast').Comment} Comment
- * @typedef {import('hast').Content} Content
+ *
+ * @typedef {import('parse5').DefaultTreeAdapterMap['document']} Parse5Document
+ * @typedef {import('parse5').DefaultTreeAdapterMap['documentFragment']} Parse5Fragment
+ * @typedef {import('parse5').DefaultTreeAdapterMap['element']} Parse5Element
+ * @typedef {import('parse5').DefaultTreeAdapterMap['node']} Parse5Nodes
+ * @typedef {import('parse5').DefaultTreeAdapterMap['documentType']} Parse5Doctype
+ * @typedef {import('parse5').DefaultTreeAdapterMap['commentNode']} Parse5Comment
+ * @typedef {import('parse5').DefaultTreeAdapterMap['textNode']} Parse5Text
+ * @typedef {import('parse5').DefaultTreeAdapterMap['parentNode']} Parse5Parent
+ * @typedef {import('parse5').Token.Attribute} Parse5Attribute
+ *
+ * @typedef {import('property-information').Schema} Schema
  */
 
 /**
- * @typedef {Content | Root} Node
- * @typedef {'html' | 'svg'} Space
- *
  * @typedef Options
  *   Configuration.
  * @property {Space | null | undefined} [space='html']
- *   Which space the document is in.
+ *   Which space the document is in (default: `'html'`).
  *
  *   When an `<svg>` element is found in the HTML space, this package already
  *   automatically switches to and from the SVG space when entering and exiting
  *   it.
+ *
+ * @typedef {Exclude<Parse5Nodes, Parse5Document | Parse5Fragment>} Parse5Content
+ *
+ * @typedef {'html' | 'svg'} Space
  */
 
 import {stringify as commas} from 'comma-separated-tokens'
-import {html, svg, find} from 'property-information'
+import {ok as assert} from 'devlop'
+import {find, html, svg} from 'property-information'
 import {stringify as spaces} from 'space-separated-tokens'
 import {webNamespaces} from 'web-namespaces'
 import {zwitch} from 'zwitch'
 
 const own = {}.hasOwnProperty
 
-/** @type {(from: Node, schema: Schema) => P5Node} */
 const one = zwitch('type', {handlers: {root, element, text, comment, doctype}})
 
 /**
  * Transform a hast tree to Parse5’s AST.
  *
- * @param {Node} tree
+ * @param {Nodes} tree
  *   Tree to transform.
  * @param {Options | Space | null | undefined} [options]
- *   Configuration.
- * @returns {P5Node}
+ *   Configuration (optional).
+ * @returns {Parse5Nodes}
  *   `parse5` node.
  */
 export function toParse5(tree, options) {
@@ -61,12 +63,14 @@ export function toParse5(tree, options) {
 
 /**
  * @param {Root} node
+ *   Node (hast) to transform.
  * @param {Schema} schema
  *   Current schema.
- * @returns {P5Document}
+ * @returns {Parse5Document}
+ *   Parse5 node.
  */
 function root(node, schema) {
-  /** @type {P5Document} */
+  /** @type {Parse5Document} */
   const result = {
     nodeName: '#document',
     // @ts-expect-error: `parse5` uses enums, which are actually strings.
@@ -80,12 +84,14 @@ function root(node, schema) {
 
 /**
  * @param {Root} node
+ *   Node (hast) to transform.
  * @param {Schema} schema
  *   Current schema.
- * @returns {P5Fragment}
+ * @returns {Parse5Fragment}
+ *   Parse5 node.
  */
 function fragment(node, schema) {
-  /** @type {P5Fragment} */
+  /** @type {Parse5Fragment} */
   const result = {nodeName: '#document-fragment', childNodes: []}
   result.childNodes = all(node.children, result, schema)
   patch(node, result)
@@ -94,17 +100,18 @@ function fragment(node, schema) {
 
 /**
  * @param {Doctype} node
- * @returns {P5Doctype}
+ *   Node (hast) to transform.
+ * @returns {Parse5Doctype}
+ *   Parse5 node.
  */
 function doctype(node) {
-  /** @type {P5Doctype} */
+  /** @type {Parse5Doctype} */
   const result = {
     nodeName: '#documentType',
     name: 'html',
     publicId: '',
     systemId: '',
-    // @ts-expect-error: change to `null` in a major?
-    parentNode: undefined
+    parentNode: null
   }
 
   patch(node, result)
@@ -113,31 +120,33 @@ function doctype(node) {
 
 /**
  * @param {Text} node
- * @returns {P5Text}
+ *   Node (hast) to transform.
+ * @returns {Parse5Text}
+ *   Parse5 node.
  */
 function text(node) {
-  /** @type {P5Text} */
+  /** @type {Parse5Text} */
   const result = {
     nodeName: '#text',
     value: node.value,
-    // @ts-expect-error: no `parentNode`
-    parentNode: undefined
+    parentNode: null
   }
   patch(node, result)
   return result
 }
 
 /**
  * @param {Comment} node
- * @returns {P5Comment}
+ *   Node (hast) to transform.
+ * @returns {Parse5Comment}
+ *   Parse5 node.
  */
 function comment(node) {
-  /** @type {P5Comment} */
+  /** @type {Parse5Comment} */
   const result = {
     nodeName: '#comment',
     data: node.value,
-    // @ts-expect-error: no `parentNode`
-    parentNode: undefined
+    parentNode: null
   }
 
   patch(node, result)
@@ -147,10 +156,11 @@ function comment(node) {
 
 /**
  * @param {Element} node
+ *   Node (hast) to transform.
  * @param {Schema} schema
  *   Current schema.
- * @returns {P5Element}
- *   `parse5` node.
+ * @returns {Parse5Element}
+ *   Parse5 node.
  */
 function element(node, schema) {
   const parentSchema = schema
@@ -164,7 +174,7 @@ function element(node, schema) {
     currentSchema = svg
   }
 
-  /** @type {Array<P5Attribute>} */
+  /** @type {Array<Parse5Attribute>} */
   const attrs = []
   /** @type {string} */
   let prop
@@ -185,16 +195,19 @@ function element(node, schema) {
     }
   }
 
-  /** @type {P5Element} */
+  const space = currentSchema.space
+  // `html` and `svg` both have a space.
+  assert(space)
+
+  /** @type {Parse5Element} */
   const result = {
     nodeName: node.tagName,
     tagName: node.tagName,
     attrs,
-    // @ts-expect-error: html and svg both have a space.
-    namespaceURI: webNamespaces[currentSchema.space],
+    // @ts-expect-error: `parse5` types are wrong.
+    namespaceURI: webNamespaces[space],
     childNodes: [],
-    // @ts-expect-error: no `parentNode`
-    parentNode: undefined
+    parentNode: null
   }
   result.childNodes = all(node.children, result, currentSchema)
   patch(node, result)
@@ -214,19 +227,19 @@ function element(node, schema) {
  *   Current schema.
  * @param {string} prop
  *   Key.
- * @param {Array<string | number> | string | number | boolean | null | undefined} value
+ * @param {Array<number | string> | boolean | number | string | null | undefined} value
  *   hast property value.
- * @returns {P5Attribute | void}
+ * @returns {Parse5Attribute | undefined}
  *   Field for runtime, optional.
  */
 function createProperty(schema, prop, value) {
   const info = find(schema, prop)
 
   // Ignore nullish and `NaN` values.
   if (
-    value === undefined ||
-    value === null ||
     value === false ||
+    value === null ||
+    value === undefined ||
     (typeof value === 'number' && Number.isNaN(value)) ||
     (!value && info.boolean)
   ) {
@@ -239,7 +252,7 @@ function createProperty(schema, prop, value) {
     value = info.commaSeparated ? commas(value) : spaces(value)
   }
 
-  /** @type {P5Attribute} */
+  /** @type {Parse5Attribute} */
   const attribute = {
     name: info.attribute,
     value: value === true ? '' : String(value)
@@ -264,24 +277,23 @@ function createProperty(schema, prop, value) {
 /**
  * Transform all hast nodes.
  *
- * @param {Array<Content>} children
+ * @param {Array<RootContent>} children
  *   List of children.
- * @param {P5Parent} parentNode
+ * @param {Parse5Parent} parentNode
  *   `parse5` parent node.
  * @param {Schema} schema
  *   Current schema.
- * @returns {Array<P5Child>}
+ * @returns {Array<Parse5Content>}
  *   Transformed children.
  */
 function all(children, parentNode, schema) {
   let index = -1
-  /** @type {Array<P5Child>} */
+  /** @type {Array<Parse5Content>} */
   const results = []
 
   if (children) {
     while (++index < children.length) {
-      /** @type {P5Child} */
-      // @ts-expect-error assume no document.
+      /** @type {Parse5Content} */
       const child = one(children[index], schema)
 
       child.parentNode = parentNode
@@ -296,25 +308,26 @@ function all(children, parentNode, schema) {
 /**
  * Add position info from `from` to `to`.
  *
- * @param {Node} from
+ * @param {Nodes} from
  *   hast node.
- * @param {P5Node} to
+ * @param {Parse5Nodes} to
  *   `parse5` node.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function patch(from, to) {
   const position = from.position
 
   if (position && position.start && position.end) {
+    assert(typeof position.start.offset === 'number')
+    assert(typeof position.end.offset === 'number')
+
     to.sourceCodeLocation = {
       startLine: position.start.line,
       startCol: position.start.column,
-      // @ts-expect-error assume this is set.
       startOffset: position.start.offset,
       endLine: position.end.line,
       endCol: position.end.column,
-      // @ts-expect-error assume this is set.
       endOffset: position.end.offset
     }
   }

package.json

@@ -36,6 +36,7 @@
   "dependencies": {
     "@types/hast": "^3.0.0",
     "comma-separated-tokens": "^2.0.0",
+    "devlop": "^1.0.0",
     "property-information": "^6.0.0",
     "space-separated-tokens": "^2.0.0",
     "web-namespaces": "^2.0.0",