Add math to mdast node type registry

When using this utility, the math types will automatically be added
to mdast in the correct places.
See DefinitelyTyped/DefinitelyTyped#54421 for more information.

Author: wooorm

.gitignore

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

complex-types.d.ts

@@ -0,0 +1,21 @@
+import type {Literal} from 'mdast'
+
+export interface Math extends Literal {
+  type: 'math'
+  lang?: string | null
+  meta?: string | null
+}
+
+export interface InlineMath extends Literal {
+  type: 'inlineMath'
+}
+
+declare module 'mdast' {
+  interface StaticPhrasingContentMap {
+    inlineMath: InlineMath
+  }
+
+  interface BlockContentMap {
+    math: Math
+  }
+}

index.js

@@ -1,12 +1,10 @@
 /**
- * @typedef {import('mdast').Literal} Literal
  * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
  * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
  * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
  * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
- *
- * @typedef {Literal & {type: 'math', lang?: string|null, meta?: string|null}} Math
- * @typedef {Literal & {type: 'inlineMath'}} InlineMath
+ * @typedef {import('./complex-types').Math} Math
+ * @typedef {import('./complex-types').InlineMath} InlineMath
  */
 
 import {longestStreak} from 'longest-streak'
@@ -44,19 +42,19 @@ inlineMath.peek = inlineMathPeek
 
 /** @type {FromMarkdownHandle} */
 function enterMathFlow(token) {
-  /** @type {Math} */
-  const node = {
-    type: 'math',
-    meta: null,
-    value: '',
-    data: {
-      hName: 'div',
-      hProperties: {className: ['math', 'math-display']},
-      hChildren: [{type: 'text', value: ''}]
-    }
-  }
-  // @ts-expect-error: custom node.
-  this.enter(node, token)
+  this.enter(
+    {
+      type: 'math',
+      meta: null,
+      value: '',
+      data: {
+        hName: 'div',
+        hProperties: {className: ['math', 'math-display']},
+        hChildren: [{type: 'text', value: ''}]
+      }
+    },
+    token
+  )
 }
 
 /** @type {FromMarkdownHandle} */
@@ -67,7 +65,8 @@ function enterMathFlowMeta() {
 /** @type {FromMarkdownHandle} */
 function exitMathFlowMeta() {
   const data = this.resume()
-  this.stack[this.stack.length - 1].meta = data
+  const node = /** @type {Math} */ (this.stack[this.stack.length - 1])
+  node.meta = data
 }
 
 /** @type {FromMarkdownHandle} */
@@ -81,7 +80,7 @@ function exitMathFlowFence() {
 /** @type {FromMarkdownHandle} */
 function exitMathFlow(token) {
   const data = this.resume().replace(/^(\r?\n|\r)|(\r?\n|\r)$/g, '')
-  const node = this.exit(token)
+  const node = /** @type {Math} */ (this.exit(token))
   node.value = data
   // @ts-expect-error: we defined it.
   node.data.hChildren[0].value = data
@@ -90,25 +89,25 @@ function exitMathFlow(token) {
 
 /** @type {FromMarkdownHandle} */
 function enterMathText(token) {
-  /** @type {InlineMath} */
-  const node = {
-    type: 'inlineMath',
-    value: '',
-    data: {
-      hName: 'span',
-      hProperties: {className: ['math', 'math-inline']},
-      hChildren: [{type: 'text', value: ''}]
-    }
-  }
-  // @ts-expect-error: custom node.
-  this.enter(node, token)
+  this.enter(
+    {
+      type: 'inlineMath',
+      value: '',
+      data: {
+        hName: 'span',
+        hProperties: {className: ['math', 'math-inline']},
+        hChildren: [{type: 'text', value: ''}]
+      }
+    },
+    token
+  )
   this.buffer()
 }
 
 /** @type {FromMarkdownHandle} */
 function exitMathText(token) {
   const data = this.resume()
-  const node = this.exit(token)
+  const node = /** @type {Math} */ (this.exit(token))
   node.value = data
   // @ts-expect-error: we defined it.
   node.data.hChildren[0].value = data
@@ -129,11 +128,9 @@ function math(node, _, context) {
   const fence = '$'.repeat(Math.max(longestStreak(raw, '$') + 1, 2))
   const exit = context.enter('mathFlow')
   let value = fence
-  /** @type {ReturnType<context['enter']>} */
-  let subexit
 
   if (node.meta) {
-    subexit = context.enter('mathFlowMeta')
+    const subexit = context.enter('mathFlowMeta')
     value += safe(context, node.meta, {before: '$', after: ' ', encode: ['$']})
     subexit()
   }

package.json

@@ -31,6 +31,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
+    "complex-types.d.ts",
     "index.d.ts",
     "index.js"
   ],
@@ -54,7 +55,7 @@
     "xo": "^0.39.0"
   },
   "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "rimraf \"{index,test}.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --conditions development test.js",

test.js

@@ -148,6 +148,7 @@ test('mdast -> markdown', (t) => {
   )
 
   t.deepEqual(
+    // @ts-expect-error: `value` missing.
     toMarkdown({type: 'inlineMath'}, {extensions: [mathToMarkdown]}),
     '$$\n',
     'should serialize math (text) w/o `value`'
@@ -187,12 +188,14 @@ test('mdast -> markdown', (t) => {
   )
 
   t.deepEqual(
+    // @ts-expect-error: `value` missing.
     toMarkdown({type: 'math'}, {extensions: [mathToMarkdown]}),
     '$$\n$$\n',
     'should serialize math (flow) w/o `value`'
   )
 
   t.deepEqual(
+    // @ts-expect-error: `value` missing.
     toMarkdown({type: 'math', meta: 'a'}, {extensions: [mathToMarkdown]}),
     '$$a\n$$\n',
     'should serialize math (flow) w/ `meta`'
@@ -205,6 +208,7 @@ test('mdast -> markdown', (t) => {
   )
 
   t.deepEqual(
+    // @ts-expect-error: `value` missing.
     toMarkdown({type: 'math', meta: 'a'}, {extensions: [mathToMarkdown]}),
     '$$a\n$$\n',
     'should serialize math (flow) w/ `meta`'
@@ -237,21 +241,33 @@ test('mdast -> markdown', (t) => {
 
   t.deepEqual(
     toMarkdown(
-      {type: 'definition', label: 'a', url: 'b', title: 'a\n$\nb'},
+      {
+        type: 'definition',
+        label: 'a',
+        identifier: 'a',
+        url: 'b',
+        title: 'a\n$\nb'
+      },
       {extensions: [mathToMarkdown]}
     ),
     '[a]: b "a\n$\nb"\n',
     'should not escape `$` at the start of a line'
   )
 
   t.deepEqual(
-    toMarkdown({type: 'math', meta: 'a\rb\nc'}, {extensions: [mathToMarkdown]}),
+    toMarkdown(
+      {type: 'math', meta: 'a\rb\nc', value: ''},
+      {extensions: [mathToMarkdown]}
+    ),
     '$$a
b\nc\n$$\n',
     'should escape `\\r`, `\\n` when in `meta` of math (flow)'
   )
 
   t.deepEqual(
-    toMarkdown({type: 'math', meta: 'a$b'}, {extensions: [mathToMarkdown]}),
+    toMarkdown(
+      {type: 'math', meta: 'a$b', value: ''},
+      {extensions: [mathToMarkdown]}
+    ),
     '$$a$b\n$$\n',
     'should escape `$` when in `meta` of math (flow)'
   )