Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,56 +1,101 @@
+/**
+ * @typedef {import('css-selector-parser').RuleAttr} CssRuleAttr
+ * @typedef {import('css-selector-parser').RulePseudo} CssRulePseudo
+ * @typedef {import('css-selector-parser').Selectors} CssSelectors
+ * @typedef {import('css-selector-parser').RuleSet} CssRuleSet
+ * @typedef {import('css-selector-parser').Rule} CssRule
+ *
+ * @typedef {import('hast').Element} HastElement
+ * @typedef {import('hast').Properties} HastProperties
+ *
+ * @typedef {'html'|'svg'} Space
+ *
+ * @typedef Options
+ * @property {Space} [space]
+ *
+ * @typedef Context
+ * @property {Space} space
+ * @property {boolean} root
+ */
+
 import {h, s} from 'hastscript'
 import {zwitch} from 'zwitch'
 import {CssSelectorParser} from 'css-selector-parser'
 
-var compile = zwitch('type', {
-  handlers: {
-    selectors,
-    ruleSet,
-    rule
-  }
-})
+var compile = zwitch('type', {handlers: {selectors, ruleSet, rule}})
 
 var parser = new CssSelectorParser()
 
 parser.registerNestingOperators('>', '+', '~')
 // Register these so we can throw nicer errors.
 parser.registerAttrEqualityMods('~', '|', '^', '$', '*')
 
+/**
+ * @param {string} [selector='']
+ * @param {Space|Options} [space='html']
+ * @returns {HastElement}
+ */
 export function fromSelector(selector, space) {
-  var config = {space: (space && space.space) || space || 'html', root: true}
+  /** @type {Context} */
+  var config = {
+    space:
+      (space && typeof space === 'object' && space.space) ||
+      (typeof space === 'string' && space) ||
+      'html',
+    root: true
+  }
 
   return (
+    // @ts-ignore Assume one element is returned.
     compile(parser.parse(selector || ''), config) || build(config.space)('')
   )
 }
 
-function selectors() {
+/**
+ * @param {CssSelectors} _
+ */
+function selectors(_) {
   throw new Error('Cannot handle selector list')
 }
 
+/**
+ * @param {CssRuleSet} query
+ * @param {Context} config
+ * @returns {HastElement|Array.<HastElement>}
+ */
 function ruleSet(query, config) {
+  // @ts-ignore Assume one or more elements is returned.
   return compile(query.rule, config)
 }
 
+/**
+ * @param {CssRule} query
+ * @param {Context} config
+ * @returns {HastElement|Array.<HastElement>}
+ */
 function rule(query, config) {
   var parentSpace = config.space
   var name = query.tagName === '*' ? '' : query.tagName || ''
   var space = parentSpace === 'html' && name === 'svg' ? 'svg' : parentSpace
+  /** @type {boolean} */
   var sibling
-  var operator
+  /** @type {HastElement} */
   var node
 
   if (query.rule) {
-    operator = query.rule.nestingOperator
-    sibling = operator === '+' || operator === '~'
+    sibling =
+      query.rule.nestingOperator === '+' || query.rule.nestingOperator === '~'
 
     if (sibling && config.root) {
       throw new Error(
-        'Cannot handle sibling combinator `' + operator + '` at root'
+        'Cannot handle sibling combinator `' +
+          query.rule.nestingOperator +
+          '` at root'
       )
     }
   }
 
+  // @ts-ignore Assume one or more elements is returned.
   node = build(space)(
     name,
     Object.assign(
@@ -61,9 +106,14 @@ function rule(query, config) {
     !query.rule || sibling ? [] : compile(query.rule, {space})
   )
 
+  // @ts-ignore Assume one or more elements is returned.
   return sibling ? [node, compile(query.rule, {space: parentSpace})] : node
 }
 
+/**
+ * @param {Array.<CssRulePseudo>} pseudos
+ * @returns {HastProperties}
+ */
 function pseudosToHast(pseudos) {
   var pseudo = pseudos[0]
 
@@ -78,15 +128,21 @@ function pseudosToHast(pseudos) {
   return {}
 }
 
+/**
+ * @param {Array.<CssRuleAttr>} attrs
+ * @returns {HastProperties}
+ */
 function attrsToHast(attrs) {
-  var props = {}
   var index = -1
+  /** @type {HastProperties} */
+  var props = {}
+  /** @type {CssRuleAttr} */
   var attr
 
   while (++index < attrs.length) {
     attr = attrs[index]
 
-    if (attr.operator) {
+    if ('operator' in attr) {
       if (attr.operator === '=') {
         props[attr.name] = attr.value
       } else {
@@ -102,6 +158,10 @@ function attrsToHast(attrs) {
   return props
 }
 
+/**
+ * @param {Space} space
+ * @returns {typeof h}
+ */
 function build(space) {
   return space === 'html' ? h : s
 }

package.json

@@ -29,24 +29,33 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/hast": "^2.0.0",
     "css-selector-parser": "^1.0.0",
     "hastscript": "^7.0.0",
     "zwitch": "^2.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^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",
@@ -71,5 +80,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -139,15 +139,21 @@ test('fromSelector()', function (t) {
   t.deepEqual(fromSelector('altGlyph', 'svg').tagName, 'altGlyph', 'space (#2)')
 
   t.deepEqual(
-    fromSelector('svg altGlyph').children[0].tagName,
+    fromSelector('altGlyph', {space: 'svg'}).tagName,
     'altGlyph',
     'space (#3)'
   )
 
+  t.deepEqual(
+    fromSelector('svg altGlyph').children[0].tagName,
+    'altGlyph',
+    'space (#4)'
+  )
+
   t.deepEqual(
     fromSelector('div svg + altGlyph').children[1].tagName,
     'altglyph',
-    'space (#4)'
+    'space (#5)'
   )
 
   t.deepEqual(
@@ -159,7 +165,7 @@ test('fromSelector()', function (t) {
         s('circle', {cx: '10', cy: '10', r: '10'}, [s('altGlyph')])
       ])
     ]),
-    'space (#5)'
+    'space (#6)'
   )
 
   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
+  }
+}