Add comments to node types

Author: wooorm

.gitignore

@@ -5,3 +5,4 @@ node_modules/
 .DS_Store
 yarn.lock
 !/complex-types.d.ts
+!/index.d.ts

complex-types.d.ts

@@ -1,26 +1,4 @@
-import type {Literal} from 'mdast'
-import type {Program} from 'estree-jsx'
+// To do: next major: remove this file.
+export type {MdxjsEsm} from './index.js'
 
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface MdxjsEsm extends Literal {
-  type: 'mdxjsEsm'
-  data?: {estree?: Program}
-}
-
-declare module 'mdast' {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-  interface BlockContentMap {
-    mdxjsEsm: MdxjsEsm
-  }
-}
-
-declare module 'hast' {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-  interface RootContentMap {
-    mdxjsEsm: MdxjsEsm
-  }
-  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-  interface ElementContentMap {
-    mdxjsEsm: MdxjsEsm
-  }
-}
+/// <reference types="./index.js" />

index.d.ts

@@ -0,0 +1,55 @@
+import type {Literal} from 'mdast'
+import type {Program} from 'estree-jsx'
+
+export {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from './lib/index.js'
+
+/**
+ * MDX ESM (import/export) node.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface MdxjsEsm extends Literal {
+  /**
+   * Node type.
+   */
+  type: 'mdxjsEsm'
+
+  /**
+   * Data.
+   */
+  data?: {
+    /**
+     * Program node from estree.
+     */
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    estree?: Program | null | undefined
+  }
+}
+
+// Add nodes to content.
+declare module 'mdast' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface BlockContentMap {
+    /**
+     * MDX ESM.
+     */
+    mdxjsEsm: MdxjsEsm
+  }
+}
+
+declare module 'hast' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface RootContentMap {
+    /**
+     * MDX ESM.
+     */
+    mdxjsEsm: MdxjsEsm
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface ElementContentMap {
+    /**
+     * MDX ESM.
+     */
+    mdxjsEsm: MdxjsEsm
+  }
+}

index.js

@@ -1 +1,2 @@
+// Note: types exposed from `index.d.ts`.
 export {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from './lib/index.js'

lib/index.js

@@ -5,7 +5,7 @@
  * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
  * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
  * @typedef {import('estree-jsx').Program} Program
- * @typedef {import('../complex-types.js').MdxjsEsm} MdxjsEsm
+ * @typedef {import('../index.js').MdxjsEsm} MdxjsEsm
  *
  * @typedef {MdxjsEsm} MDXJSEsm
  *   Deprecated name, prefer `MdxjsEsm`.

tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "include": ["**/*.js"],
+  "include": ["**/*.js", "complex-types.d.ts", "index.d.ts"],
   "exclude": ["coverage/", "node_modules/"],
   "compilerOptions": {
     "checkJs": true,