Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,68 +1 @@
-// Creating xast elements.
-export function x(name, attributes) {
-  var node =
-    name === undefined || name === null
-      ? {type: 'root', children: []}
-      : {type: 'element', name, attributes: {}, children: []}
-  var index = 1
-  var key
-
-  if (name !== undefined && name !== null && typeof name !== 'string') {
-    throw new Error('Expected element name, got `' + name + '`')
-  }
-
-  // Handle props.
-  if (attributes) {
-    if (
-      name === undefined ||
-      name === null ||
-      typeof attributes === 'string' ||
-      typeof attributes === 'number' ||
-      'length' in attributes
-    ) {
-      // Nope, it’s something for `children`.
-      index--
-    } else {
-      for (key in attributes) {
-        // Ignore nullish and NaN values.
-        if (
-          attributes[key] !== undefined &&
-          attributes[key] !== null &&
-          (typeof attributes[key] !== 'number' ||
-            !Number.isNaN(attributes[key]))
-        ) {
-          node.attributes[key] = String(attributes[key])
-        }
-      }
-    }
-  }
-
-  // Handle children.
-  while (++index < arguments.length) {
-    addChild(node.children, arguments[index])
-  }
-
-  return node
-}
-
-function addChild(nodes, value) {
-  var index = -1
-
-  if (value === undefined || value === null) {
-    // Empty.
-  } else if (typeof value === 'string' || typeof value === 'number') {
-    nodes.push({type: 'text', value: String(value)})
-  } else if (typeof value === 'object' && 'length' in value) {
-    while (++index < value.length) {
-      addChild(nodes, value[index])
-    }
-  } else if (typeof value === 'object' && value.type) {
-    if (value.type === 'root') {
-      addChild(nodes, value.children)
-    } else {
-      nodes.push(value)
-    }
-  } else {
-    throw new TypeError('Expected node, nodes, string, got `' + value + '`')
-  }
-}
+export {x} from './lib/index.js'

index.test-d.ts

@@ -0,0 +1,29 @@
+import {expectType, expectError} from 'tsd'
+import {Root, Element} from 'xast'
+import {x} from './index.js'
+
+expectType<Root>(x())
+expectError(x(true))
+expectType<Root>(x(null))
+expectType<Root>(x(undefined))
+expectType<Element>(x(''))
+expectType<Element>(x('', null))
+expectType<Element>(x('', undefined))
+expectType<Element>(x('', 1))
+expectType<Element>(x('', 'a'))
+expectError(x('', true))
+expectType<Element>(x('', [1, 'a', null]))
+expectError(x('', [true]))
+
+expectType<Element>(x('', {}))
+expectType<Element>(x('', {}, [1, 'a', null]))
+expectType<Element>(x('', {p: 1}))
+expectType<Element>(x('', {p: null}))
+expectType<Element>(x('', {p: undefined}))
+expectType<Element>(x('', {p: true}))
+expectType<Element>(x('', {p: false}))
+expectType<Element>(x('', {p: 'a'}))
+expectError(x('', {p: [1]}))
+expectError(x('', {p: [true]}))
+expectError(x('', {p: ['a']}))
+expectError(x('', {p: {x: true}}))

lib/index.js

@@ -0,0 +1,124 @@
+/**
+ * @typedef {import('xast').Root} Root
+ * @typedef {import('xast').Element} Element
+ * @typedef {Root['children'][number]} Child
+ * @typedef {Child|Root} Node
+ * @typedef {Root|Element} XResult
+ * @typedef {string|number|boolean|null|undefined} XValue
+ * @typedef {{[attribute: string]: XValue}} XAttributes Attributes to support JS primitive types
+ *
+ * @typedef {string|number|null|undefined} XPrimitiveChild
+ * @typedef {Array.<Node|XPrimitiveChild>} XArrayChild
+ * @typedef {Node|XPrimitiveChild|XArrayChild} XChild
+ */
+
+/**
+ * Create XML trees in xast.
+ *
+ * @param name Qualified name. Case sensitive and can contain a namespace prefix (such as `rdf:RDF`). Pass `null|undefined` to build a root.
+ * @param attributes Map of attributes. Nullish (null or undefined) or NaN values are ignored, other values (strings, booleans) are cast to strings.
+ * @param children (Lists of) child nodes. When strings are encountered, they are mapped to Text nodes.
+ */
+export const x =
+  /**
+   * @type {{
+   *   (): Root
+   *   (name: null|undefined, ...children: XChild[]): Root
+   *   (name: string, attributes: XAttributes, ...children: XChild[]): Element
+   *   (name: string, ...children: XChild[]): Element
+   * }}
+   */
+  (
+    /**
+     * Hyperscript compatible DSL for creating virtual xast trees.
+     *
+     * @param {string|null} [name]
+     * @param {XAttributes|XChild} [attributes]
+     * @param {XChild[]} children
+     * @returns {XResult}
+     */
+    function (name, attributes, ...children) {
+      var index = -1
+      /** @type {XResult} */
+      var node
+      /** @type {string} */
+      var key
+
+      if (name === undefined || name === null) {
+        node = {type: 'root', children: []}
+        // @ts-ignore Root builder doesn’t accept attributes.
+        children.unshift(attributes)
+      } else if (typeof name === 'string') {
+        node = {type: 'element', name, attributes: {}, children: []}
+
+        if (isAttributes(attributes)) {
+          for (key in attributes) {
+            // Ignore nullish and NaN values.
+            if (
+              attributes[key] !== undefined &&
+              attributes[key] !== null &&
+              (typeof attributes[key] !== 'number' ||
+                !Number.isNaN(attributes[key]))
+            ) {
+              // @ts-ignore Pretty sure we just set it.
+              node.attributes[key] = String(attributes[key])
+            }
+          }
+        } else {
+          children.unshift(attributes)
+        }
+      } else {
+        throw new TypeError('Expected element name, got `' + name + '`')
+      }
+
+      // Handle children.
+      while (++index < children.length) {
+        addChild(node.children, children[index])
+      }
+
+      return node
+    }
+  )
+
+/**
+ * @param {Array.<Child>} nodes
+ * @param {XChild} value
+ */
+function addChild(nodes, value) {
+  var index = -1
+
+  if (value === undefined || value === null) {
+    // Empty.
+  } else if (typeof value === 'string' || typeof value === 'number') {
+    nodes.push({type: 'text', value: String(value)})
+  } else if (Array.isArray(value)) {
+    while (++index < value.length) {
+      addChild(nodes, value[index])
+    }
+  } else if (typeof value === 'object' && 'type' in value) {
+    if (value.type === 'root') {
+      addChild(nodes, value.children)
+    } else {
+      nodes.push(value)
+    }
+  } else {
+    throw new TypeError('Expected node, nodes, string, got `' + value + '`')
+  }
+}
+
+/**
+ * @param {XAttributes|XChild} value
+ * @returns {value is XAttributes}
+ */
+function isAttributes(value) {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value !== 'object' ||
+    Array.isArray(value)
+  ) {
+    return false
+  }
+
+  return true
+}

package.json

@@ -28,9 +28,10 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
-  "types": "types",
+  "types": "index.d.ts",
   "files": [
-    "types/index.d.ts",
+    "lib/",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
@@ -40,23 +41,32 @@
     "@babel/core": "^7.0.0",
     "@babel/plugin-syntax-jsx": "^7.0.0",
     "@babel/plugin-transform-react-jsx": "^7.0.0",
+    "@types/acorn": "^4.0.0",
+    "@types/babel__core": "^7.0.0",
+    "@types/tape": "^4.0.0",
     "astring": "^1.0.0",
     "buble": "^0.20.0",
     "c8": "^7.0.0",
     "estree-util-build-jsx": "^2.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",
+    "tsd": "^0.14.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "unist-builder": "^3.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"{script/**,test/**,lib/**,}*.d.ts\" && tsc && tsd && type-coverage",
     "generate": "node script/generate-jsx",
     "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 generate && npm run format && npm run test-coverage"
+    "test": "npm run generate && npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -80,5 +90,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

readme.md

@@ -241,8 +241,7 @@ For more details on configuring JSX for TypeScript, see the
 TypeScript also lets you configure this in a script:
 
 ```tsx
-/** @jsx x */
-/** @jsxFrag null */
+/** @jsx x @jsxFrag null */
 import {x} from 'xastscript'
 
 console.log(<music />)

script/generate-jsx.js

@@ -15,6 +15,7 @@ fs.writeFileSync(
       // @ts-ignore Acorn nodes are assignable to ESTree nodes.
       Parser.extend(acornJsx()).parse(
         doc.replace(/'name'/, "'jsx (estree-util-build-jsx, classic)'"),
+        // @ts-ignore Hush, `2021` is fine.
         {sourceType: 'module', ecmaVersion: 2021}
       ),
       {pragma: 'x', pragmaFrag: 'null'}

test/core.js

@@ -12,6 +12,7 @@ test('xastscript', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       x(1)
     },
     /Expected element name, got `1`/,
@@ -68,6 +69,7 @@ test('xastscript', function (t) {
   )
 
   t.deepEqual(
+    // @ts-ignore Deeply nested children are not typed.
     x('y', {}, [[[x('a')]], [[[[x('b')]], x('c')]]]),
     {
       type: 'element',
@@ -118,6 +120,7 @@ test('xastscript', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       x('y', {}, {})
     },
     /Expected node, nodes, string, got `\[object Object]`/,

tsconfig.json

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