Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,52 +1,80 @@
+/**
+ * @typedef {import('hast').Element} HastElement
+ *
+ * @typedef {string|number} ConditionalPrimitive
+ * @typedef {Object.<string, boolean>} ConditionalMap
+ * @typedef {ConditionalPrimitive|ConditionalMap|Array.<ConditionalPrimitive|ConditionalMap|Array.<ConditionalPrimitive|ConditionalMap>>} Conditional
+ *
+ * @typedef {Object.<string, boolean>} ClassMap
+ *
+ */
+
 import {parse} from 'space-separated-tokens'
 
 var own = {}.hasOwnProperty
 
-// A bit inspired by <https://github.com/JedWatson/classnames>, but for hast.
-export function classnames(node) {
+/**
+ * A bit inspired by <https://github.com/JedWatson/classnames>, but for hast.
+ *
+ * @param {HastElement|Conditional} [node]
+ * @param {Array.<Conditional>} [conditionals]
+ */
+export function classnames(node, ...conditionals) {
+  var index = -1
+  /** @type {ClassMap} */
   var map = Object.create(null)
+  /** @type {Array.<string>} */
   var list = []
-  var mutate = node && typeof node === 'object' && 'type' in node
-  var index = -1
+  /** @type {string} */
   var key
 
-  if (mutate) {
+  if (isNode(node)) {
     if (node.type !== 'element') throw new Error('Expected element node')
 
     if (!node.properties) node.properties = {}
 
-    if (node.properties.className) add(map, node.properties.className)
+    if (node.properties.className) {
+      // @ts-ignore Assume `classname` is `Array.<string>`
+      add(map, node.properties.className)
+    }
 
     node.properties.className = list
-
-    index++
+  } else {
+    conditionals.unshift(node)
   }
 
-  while (++index < arguments.length) {
-    add(map, arguments[index])
+  while (++index < conditionals.length) {
+    add(map, conditionals[index])
   }
 
   for (key in map) {
     if (map[key]) list.push(key)
   }
 
-  return mutate ? node : list
+  return isNode(node) ? node : list
 }
 
+/**
+ * @param {ClassMap} result
+ * @param {Conditional} conditional
+ */
 function add(result, conditional) {
   var index = -1
+  /** @type {string} */
   var key
+  /** @type {Array.<string>} */
+  var list
 
   if (typeof conditional === 'number') {
     result[conditional] = true
   } else if (typeof conditional === 'string') {
-    conditional = parse(conditional)
+    list = parse(conditional)
 
-    while (++index < conditional.length) {
-      result[conditional[index]] = true
+    while (++index < list.length) {
+      result[list[index]] = true
     }
   } else if (conditional && typeof conditional === 'object') {
-    if ('length' in conditional) {
+    if (Array.isArray(conditional)) {
       while (++index < conditional.length) {
         add(result, conditional[index])
       }
@@ -59,3 +87,11 @@ function add(result, conditional) {
     }
   }
 }
+
+/**
+ * @param {HastElement|Conditional} [value]
+ * @returns {value is HastElement}
+ */
+function isNode(value) {
+  return value && typeof value === 'object' && 'type' in value
+}

package.json

@@ -27,27 +27,36 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/hast": "^2.0.0",
     "space-separated-tokens": "^2.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "hastscript": "^7.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",
     "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,
@@ -68,5 +77,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

readme.md

@@ -70,8 +70,8 @@ A value that is either:
 
 *   `string` — One or more space-separated tokens (example: `alpha bravo`)
 *   `number` — Single token that is cast to string  (example: `123`)
-*   `Object.<boolean>` — Map where each field is a token, and each value turns
-    it either on or off
+*   `Object.<string, boolean>` — Map where each field is a token, and each value
+    turns it either on or off
 *   `Conditional[]` — List of more conditionals
 *   Other values are ignored
 

test.js

@@ -6,6 +6,7 @@ import {classnames} from './index.js'
 test('hast-util-classnames', function (t) {
   t.throws(
     function () {
+      // @ts-ignore runtime.
       classnames(u('comment', '?'))
     },
     /Expected element node/,
@@ -33,7 +34,7 @@ test('hast-util-classnames', function (t) {
   )
 
   t.deepEqual(
-    classnames(h('a'), {alpha: true, bravo: false, charlie: 1}),
+    classnames(h('a'), {alpha: true, bravo: false, charlie: true}),
     h('a.alpha.charlie'),
     'should support an object'
   )
@@ -73,7 +74,7 @@ test('hast-util-classnames', function (t) {
   )
 
   t.deepEqual(
-    classnames('alpha', ['bravo', 123], {charlie: 1}),
+    classnames('alpha', ['bravo', 123], {charlie: true}),
     ['123', 'alpha', 'bravo', 'charlie'],
     'should return a list if w/o element'
   )

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
+  }
+}