Add JSDoc based types

syntax-tree · Apr 25, 2021 · 2c6a29c · 2c6a29c
1 parent efad048
commit 2c6a29c
Show file tree

Hide file tree

Showing 5 changed files with 141 additions and 19 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

diff --git a/index.js b/index.js
@@ -1,14 +1,48 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ * @typedef {import('unist').Point} Point
+ * @typedef {import('mdast').Content} Content
+ * @typedef {import('vfile').VFile} VFile
+ * @typedef {import('vfile-location').Location} LocationInterface
+ * @typedef {{
+ *   parse(nodes: Node[]): Node
+ *   tokenizeSource(value: string): Node
+ *   tokenizeWhiteSpace(value: string): Node
+ *   tokenize(value: string): Node[]
+ * }} ParserInstance
+ * @typedef {new () => ParserInstance} ParserConstructor
+ *
+ * @typedef Options
+ * @property {Array.<string>} [ignore]
+ * @property {Array.<string>} [source]
+ *
+ * @typedef Context
+ * @property {string} doc
+ * @property {LocationInterface} location
+ * @property {ParserInstance} parser
+ * @property {Array.<string>} ignore
+ * @property {Array.<string>} source
+ */
+
 import repeat from 'repeat-string'
 import {toString} from 'nlcst-to-string'
 import {pointStart, pointEnd} from 'unist-util-position'
 import vfileLocation from 'vfile-location'
 
-// Transform a `tree` in mdast to nlcst.
-export function toNlcst(tree, file, Parser, options) {
-  var settings = options || {}
+/**
+ * Transform a `tree` in mdast to nlcst.
+ *
+ * @param {Node} tree
+ * @param {VFile} file
+ * @param {ParserInstance|ParserConstructor} Parser
+ * @param {Options} [options]
+ */
+export function toNlcst(tree, file, Parser, options = {}) {
+  /** @type {ParserInstance} */
   var parser
 
-  // Warn for invalid parameters.
+  // Crash on invalid parameters.
   if (!tree || !tree.type) {
     throw new Error('mdast-util-to-nlcst expected node')
   }
@@ -45,18 +79,26 @@ export function toNlcst(tree, file, Parser, options) {
           'table',
           'tableRow',
           'tableCell',
-          settings.ignore || []
+          options.ignore || []
         ),
-        source: [].concat('inlineCode', settings.source || [])
+        source: [].concat('inlineCode', options.source || [])
       },
+      // @ts-ignore assume mdast node.
       tree
     )
   )
 }
 
-// Transform a single node.
+/**
+ * Transform a single node.
+ * @param {Context} config
+ * @param {Content} node
+ * @returns {Array.<Node>|undefined}
+ */
 function one(config, node) {
+  /** @type {number} */
   var start
+  /** @type {number} */
   var end
 
   if (!config.ignore.includes(node.type)) {
@@ -73,7 +115,8 @@ function one(config, node) {
       )
     }
 
-    if (node.children) {
+    if ('children' in node) {
+      // @ts-ignore looks like a parent.
       return all(config, node)
     }
 
@@ -86,22 +129,37 @@ function one(config, node) {
     }
 
     // To do: next major — remove `escape`.
-    if (node.type === 'text' || node.type === 'escape') {
+    if (
+      node.type === 'text' ||
+      // @ts-ignore legacy.
+      node.type === 'escape'
+    ) {
       return patch(config, config.parser.tokenize(node.value), start)
     }
   }
 }
 
-// Transform all nodes in `parent`.
+/**
+ * Transform all nodes in `parent`.
+ * @param {Context} config
+ * @param {Parent} parent
+ * @returns {Array.<Node>}
+ */
 function all(config, parent) {
+  /** @type {Array.<Node>} */
   var result = []
   var index = -1
+  /** @type {Node} */
   var lineEnding
+  /** @type {Content} */
   var child
+  /** @type {Point} */
   var end
+  /** @type {Point} */
   var start
 
   while (++index < parent.children.length) {
+    // @ts-ignore Assume `parent` is an mdast parent.
     child = parent.children[index]
     start = pointStart(child)
 
@@ -111,7 +169,11 @@ function all(config, parent) {
       )
       patch(config, [lineEnding], end.offset)
 
-      if (lineEnding.value.length < 2) {
+      if (
+        'value' in lineEnding &&
+        typeof lineEnding.value === 'string' &&
+        lineEnding.value.length < 2
+      ) {
         lineEnding.value = '\n\n'
       }
 
@@ -125,18 +187,29 @@ function all(config, parent) {
   return result
 }
 
-// Patch a position on each node in `nodes`.
-// `offset` is the offset in `file` this run of content starts at.
+/**
+ * Patch a position on each node in `nodes`.
+ * `offset` is the offset in `file` this run of content starts at.
+ *
+ * @template {Array.<Node>} T
+ * @param {Context} config
+ * @param {T} nodes
+ * @param {number} offset
+ * @returns {T}
+ */
 function patch(config, nodes, offset) {
   var index = -1
   var start = offset
+  /** @type {number} */
   var end
+  /** @type {Node} */
   var node
 
   while (++index < nodes.length) {
     node = nodes[index]
 
-    if (node.children) {
+    if ('children' in node) {
+      // @ts-ignore looks like a parent.
       patch(config, node.children, start)
     }
 

diff --git a/package.json b/package.json
@@ -28,16 +28,22 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
+    "@types/repeat-string": "^1.0.0",
+    "@types/unist": "^2.0.0",
     "nlcst-to-string": "^3.0.0",
     "repeat-string": "^1.0.0",
     "unist-util-position": "^4.0.0",
     "vfile-location": "^3.1.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "is-hidden": "^2.0.0",
     "parse-dutch": "^5.0.0",
@@ -49,15 +55,20 @@
     "remark-frontmatter": "^3.0.0",
     "remark-gfm": "^1.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
-    "to-vfile": "^6.1.0",
+    "to-vfile": "^6.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"{test/**,}*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo --ignore-pattern test/ && 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 format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -78,5 +89,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }
diff --git a/test/index.js b/test/index.js
@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('vfile').VFile} VFile
+ */
+
 import fs from 'fs'
 import path from 'path'
 import test from 'tape'
@@ -14,6 +19,7 @@ import {toNlcst} from '../index.js'
 test('mdast-util-to-nlcst', function (t) {
   t.throws(
     function () {
+      // @ts-ignore runtime.
       toNlcst()
     },
     /mdast-util-to-nlcst expected node/,
@@ -22,6 +28,7 @@ test('mdast-util-to-nlcst', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       toNlcst({})
     },
     /mdast-util-to-nlcst expected node/,
@@ -30,6 +37,7 @@ test('mdast-util-to-nlcst', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       toNlcst({type: 'foo'})
     },
     /mdast-util-to-nlcst expected file/,
@@ -38,6 +46,7 @@ test('mdast-util-to-nlcst', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       toNlcst({type: 'foo'})
     },
     /mdast-util-to-nlcst expected file/,
@@ -46,6 +55,7 @@ test('mdast-util-to-nlcst', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       toNlcst({type: 'text', value: 'foo'}, {foo: 'bar'})
     },
     /mdast-util-to-nlcst expected file/,
@@ -54,6 +64,7 @@ test('mdast-util-to-nlcst', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       toNlcst({type: 'text', value: 'foo'}, vfile({contents: 'foo'}))
     },
     /mdast-util-to-nlcst expected parser/,
@@ -98,6 +109,7 @@ test('mdast-util-to-nlcst', function (t) {
         {
           type: 'text',
           value: 'foo',
+          // @ts-ignore runtime.
           position: {start: {}, end: {}}
         },
         vfile(),
@@ -132,10 +144,15 @@ test('Fixtures', function (t) {
   var base = path.join('test', 'fixtures')
   var files = fs.readdirSync(base)
   var index = -1
+  /** @type {string} */
   var name
+  /** @type {VFile} */
   var input
+  /** @type {Node} */
   var expected
+  /** @type {Node} */
   var mdast
+  /** @type {Object.<string, unknown>} */
   var options
 
   while (++index < files.length) {
@@ -151,12 +168,12 @@ test('Fixtures', function (t) {
         vfile.readSync(path.join(base, name, 'options.json'))
       )
     } catch {
-      options = null
+      options = undefined
     }
 
     mdast = remark()
-      .use(options && options.useRemarkGfm ? gfm : [])
-      .use(options && options.useRemarkFrontmatter ? frontmatter : [])
+      .use(options && options.useRemarkGfm ? gfm : undefined)
+      .use(options && options.useRemarkFrontmatter ? frontmatter : undefined)
       .parse(input)
 
     t.deepEqual(

diff --git a/tsconfig.json b/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "include": ["*.js", "test/**/*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}