Add CompileData type to track custom data

.gitignore

@@ -6,3 +6,4 @@ node_modules/
 *.log
 .DS_Store
 yarn.lock
+!/dev/index.d.ts

dev/index.d.ts

@@ -0,0 +1,78 @@
+import type {OnEnterError} from './lib/index.js'
+
+export type {
+  CompileContext,
+  Encoding,
+  Extension,
+  Handle,
+  OnEnterError,
+  OnExitError,
+  Options,
+  Token,
+  Transform,
+  Value
+} from './lib/index.js'
+
+/**
+ * Deprecated: use `OnEnterError`.
+ */
+// To do: next major: remove.
+export type OnError = OnEnterError
+
+/**
+ * Interface of tracked data.
+ *
+ * When working on extensions that use more data, extend the corresponding
+ * interface to register their types:
+ *
+ * ```ts
+ * declare module 'mdast-util-from-markdown' {
+ *   interface CompileData {
+ *     // Register a new field.
+ *     mathFlowInside?: boolean | undefined
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface CompileData {
+  /**
+   * Whether we’re inside a hard break.
+   */
+  atHardBreak?: boolean | undefined
+
+  /**
+   * Current character reference type.
+   */
+  characterReferenceType?:
+    | 'characterReferenceMarkerHexadecimal'
+    | 'characterReferenceMarkerNumeric'
+    | undefined
+
+  /**
+   * Whether a first list item value (`1` in `1. a`) is expected.
+   */
+  expectingFirstListItemValue?: boolean | undefined
+
+  /**
+   * Whether we’re in flow code.
+   */
+  flowCodeInside?: boolean | undefined
+
+  /**
+   * Whether we’re in a reference.
+   */
+  inReference?: boolean | undefined
+
+  /**
+   * Whether we’re expecting a line ending from a setext heading, which can be slurped.
+   */
+  setextHeadingSlurpLineEnding?: boolean | undefined
+
+  /**
+   * Current reference.
+   */
+  referenceType?: 'collapsed' | 'full' | undefined
+}
+
+export {fromMarkdown} from './lib/index.js'

dev/index.js

@@ -1,19 +1,2 @@
-/**
- * @typedef {import('./lib/index.js').CompileContext} CompileContext
- * @typedef {import('./lib/index.js').Encoding} Encoding
- * @typedef {import('./lib/index.js').Extension} Extension
- * @typedef {import('./lib/index.js').Handle} Handle
- * @typedef {import('./lib/index.js').OnEnterError} OnEnterError
- * @typedef {import('./lib/index.js').OnExitError} OnExitError
- * @typedef {import('./lib/index.js').Options} Options
- * @typedef {import('./lib/index.js').Token} Token
- * @typedef {import('./lib/index.js').Transform} Transform
- * @typedef {import('./lib/index.js').Value} Value
- */
-
-/**
- * @typedef {import('./lib/index.js').OnEnterError} OnError
- *   To do: next major: remove.
- */
-
+// Note: types exported from `index.d.ts`.
 export {fromMarkdown} from './lib/index.js'

dev/lib/index.js

@@ -32,6 +32,7 @@
  * @typedef {import('mdast').Text} Text
  * @typedef {import('mdast').ThematicBreak} ThematicBreak
  * @typedef {import('mdast').ReferenceType} ReferenceType
+ * @typedef {import('../index.js').CompileData} CompileData
  */
 
 /**
@@ -42,23 +43,6 @@
  */
 
 /**
- * @typedef CompileData
- *   State.
- * @property {boolean | undefined} [atHardBreak]
- *   Whether we’re inside a hard break.
- * @property {'characterReferenceMarkerHexadecimal' | 'characterReferenceMarkerNumeric' | undefined} [characterReferenceType]
- *   Current character reference type.
- * @property {boolean | undefined} [expectingFirstListItemValue]
- *   Whether a first list item value (`1` in `1. a`) is expected.
- * @property {boolean | undefined} [flowCodeInside]
- *   Whether we’re in flow code.
- * @property {boolean | undefined} [inReference]
- *   Whether we’re in a reference.
- * @property {boolean | undefined} [setextHeadingSlurpLineEnding]
- *   Whether we’re expecting a line ending from a setext heading, which can be slurped.
- * @property {'collapsed' | 'full' | undefined} [referenceType]
- *   Current reference.
- *
  * @callback Transform
  *   Extra transform, to change the AST afterwards.
  * @param {Root} tree

readme.md

@@ -19,6 +19,7 @@
 *   [API](#api)
     *   [`fromMarkdown(value[, encoding][, options])`](#frommarkdownvalue-encoding-options)
     *   [`CompileContext`](#compilecontext)
+    *   [`CompileData`](#compiledata)
     *   [`Encoding`](#encoding)
     *   [`Extension`](#extension)
     *   [`Handle`](#handle)
@@ -169,9 +170,9 @@ mdast compiler context (TypeScript type).
 *   `tokenStack` (`Array<[Token, OnEnterError | undefined]>`)
     — stack of tokens
 *   `getData` (`(key: string) => unknown`)
-    — get data from the key/value store
+    — get data from the key/value store (see [`CompileData`][api-compiledata])
 *   `setData` (`(key: string, value?: unknown) => void`)
-    — set data into the key/value store
+    — set data into the key/value store (see [`CompileData`][api-compiledata])
 *   `buffer` (`() => void`)
     — capture some of the output data
 *   `resume` (`() => string`)
@@ -185,6 +186,28 @@ mdast compiler context (TypeScript type).
 *   `config` (`Required<Extension>`)
     — configuration
 
+### `CompileData`
+
+Interface of tracked data (TypeScript type).
+
+###### Type
+
+```ts
+interface CompileData { /* see code */ }
+```
+
+When working on extensions that use more data, extend the corresponding
+interface to register their types:
+
+```ts
+declare module 'mdast-util-from-markdown' {
+  interface CompileData {
+    // Register a new field.
+    mathFlowInside?: boolean | undefined
+  }
+}
+```
+
 ### `Encoding`
 
 Encodings supported by the [`Buffer`][buffer] class (TypeScript type).
@@ -363,6 +386,7 @@ The syntax tree is [mdast][].
 
 This package is fully typed with [TypeScript][].
 It exports the additional types [`CompileContext`][api-compilecontext],
+[`CompileData`][api-compiledata],
 [`Encoding`][api-encoding],
 [`Extension`][api-extension],
 [`Handle`][api-handle],
@@ -499,6 +523,8 @@ abide by its terms.
 
 [api-compilecontext]: #compilecontext
 
+[api-compiledata]: #compiledata
+
 [api-encoding]: #encoding
 
 [api-extension]: #extension

tsconfig.json

@@ -1,6 +1,6 @@
 {
-  "include": ["**/*.js"],
-  "exclude": ["coverage/", "node_modules/", "lib/index.js", "index.js"],
+  "include": ["dev/**/*.js", "test/**/*.js", "dev/index.d.ts"],
+  "exclude": ["coverage/", "node_modules/"],
   "compilerOptions": {
     "checkJs": true,
     "declaration": true,