Skip to content

Commit a034fa6

Browse files
committed
Add CompileData type to track custom data
1 parent 04669b2 commit a034fa6

File tree

6 files changed

+111
-39
lines changed

6 files changed

+111
-39
lines changed

.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ node_modules/
66
*.log
77
.DS_Store
88
yarn.lock
9+
!/dev/index.d.ts

dev/index.d.ts

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
import type {OnEnterError} from './lib/index.js'
2+
3+
export type {
4+
CompileContext,
5+
Encoding,
6+
Extension,
7+
Handle,
8+
OnEnterError,
9+
OnExitError,
10+
Options,
11+
Token,
12+
Transform,
13+
Value
14+
} from './lib/index.js'
15+
16+
/**
17+
* Deprecated: use `OnEnterError`.
18+
*/
19+
// To do: next major: remove.
20+
export type OnError = OnEnterError
21+
22+
/**
23+
* Interface of tracked data.
24+
*
25+
* When working on extensions that use more data, extend the corresponding
26+
* interface to register their types:
27+
*
28+
* ```ts
29+
* declare module 'mdast-util-from-markdown' {
30+
* interface CompileData {
31+
* // Register a new field.
32+
* mathFlowInside?: boolean | undefined
33+
* }
34+
* }
35+
* ```
36+
*/
37+
// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
38+
export interface CompileData {
39+
/**
40+
* Whether we’re inside a hard break.
41+
*/
42+
atHardBreak?: boolean | undefined
43+
44+
/**
45+
* Current character reference type.
46+
*/
47+
characterReferenceType?:
48+
| 'characterReferenceMarkerHexadecimal'
49+
| 'characterReferenceMarkerNumeric'
50+
| undefined
51+
52+
/**
53+
* Whether a first list item value (`1` in `1. a`) is expected.
54+
*/
55+
expectingFirstListItemValue?: boolean | undefined
56+
57+
/**
58+
* Whether we’re in flow code.
59+
*/
60+
flowCodeInside?: boolean | undefined
61+
62+
/**
63+
* Whether we’re in a reference.
64+
*/
65+
inReference?: boolean | undefined
66+
67+
/**
68+
* Whether we’re expecting a line ending from a setext heading, which can be slurped.
69+
*/
70+
setextHeadingSlurpLineEnding?: boolean | undefined
71+
72+
/**
73+
* Current reference.
74+
*/
75+
referenceType?: 'collapsed' | 'full' | undefined
76+
}
77+
78+
export {fromMarkdown} from './lib/index.js'

dev/index.js

+1-18
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,2 @@
1-
/**
2-
* @typedef {import('./lib/index.js').CompileContext} CompileContext
3-
* @typedef {import('./lib/index.js').Encoding} Encoding
4-
* @typedef {import('./lib/index.js').Extension} Extension
5-
* @typedef {import('./lib/index.js').Handle} Handle
6-
* @typedef {import('./lib/index.js').OnEnterError} OnEnterError
7-
* @typedef {import('./lib/index.js').OnExitError} OnExitError
8-
* @typedef {import('./lib/index.js').Options} Options
9-
* @typedef {import('./lib/index.js').Token} Token
10-
* @typedef {import('./lib/index.js').Transform} Transform
11-
* @typedef {import('./lib/index.js').Value} Value
12-
*/
13-
14-
/**
15-
* @typedef {import('./lib/index.js').OnEnterError} OnError
16-
* To do: next major: remove.
17-
*/
18-
1+
// Note: types exported from `index.d.ts`.
192
export {fromMarkdown} from './lib/index.js'

dev/lib/index.js

+1-17
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
* @typedef {import('mdast').Text} Text
3333
* @typedef {import('mdast').ThematicBreak} ThematicBreak
3434
* @typedef {import('mdast').ReferenceType} ReferenceType
35+
* @typedef {import('../index.js').CompileData} CompileData
3536
*/
3637

3738
/**
@@ -42,23 +43,6 @@
4243
*/
4344

4445
/**
45-
* @typedef CompileData
46-
* State.
47-
* @property {boolean | undefined} [atHardBreak]
48-
* Whether we’re inside a hard break.
49-
* @property {'characterReferenceMarkerHexadecimal' | 'characterReferenceMarkerNumeric' | undefined} [characterReferenceType]
50-
* Current character reference type.
51-
* @property {boolean | undefined} [expectingFirstListItemValue]
52-
* Whether a first list item value (`1` in `1. a`) is expected.
53-
* @property {boolean | undefined} [flowCodeInside]
54-
* Whether we’re in flow code.
55-
* @property {boolean | undefined} [inReference]
56-
* Whether we’re in a reference.
57-
* @property {boolean | undefined} [setextHeadingSlurpLineEnding]
58-
* Whether we’re expecting a line ending from a setext heading, which can be slurped.
59-
* @property {'collapsed' | 'full' | undefined} [referenceType]
60-
* Current reference.
61-
*
6246
* @callback Transform
6347
* Extra transform, to change the AST afterwards.
6448
* @param {Root} tree

readme.md

+28-2
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
* [API](#api)
2020
* [`fromMarkdown(value[, encoding][, options])`](#frommarkdownvalue-encoding-options)
2121
* [`CompileContext`](#compilecontext)
22+
* [`CompileData`](#compiledata)
2223
* [`Encoding`](#encoding)
2324
* [`Extension`](#extension)
2425
* [`Handle`](#handle)
@@ -169,9 +170,9 @@ mdast compiler context (TypeScript type).
169170
* `tokenStack` (`Array<[Token, OnEnterError | undefined]>`)
170171
— stack of tokens
171172
* `getData` (`(key: string) => unknown`)
172-
— get data from the key/value store
173+
— get data from the key/value store (see [`CompileData`][api-compiledata])
173174
* `setData` (`(key: string, value?: unknown) => void`)
174-
— set data into the key/value store
175+
— set data into the key/value store (see [`CompileData`][api-compiledata])
175176
* `buffer` (`() => void`)
176177
— capture some of the output data
177178
* `resume` (`() => string`)
@@ -185,6 +186,28 @@ mdast compiler context (TypeScript type).
185186
* `config` (`Required<Extension>`)
186187
— configuration
187188

189+
### `CompileData`
190+
191+
Interface of tracked data (TypeScript type).
192+
193+
###### Type
194+
195+
```ts
196+
interface CompileData { /* see code */ }
197+
```
198+
199+
When working on extensions that use more data, extend the corresponding
200+
interface to register their types:
201+
202+
```ts
203+
declare module 'mdast-util-from-markdown' {
204+
interface CompileData {
205+
// Register a new field.
206+
mathFlowInside?: boolean | undefined
207+
}
208+
}
209+
```
210+
188211
### `Encoding`
189212

190213
Encodings supported by the [`Buffer`][buffer] class (TypeScript type).
@@ -363,6 +386,7 @@ The syntax tree is [mdast][].
363386
364387
This package is fully typed with [TypeScript][].
365388
It exports the additional types [`CompileContext`][api-compilecontext],
389+
[`CompileData`][api-compiledata],
366390
[`Encoding`][api-encoding],
367391
[`Extension`][api-extension],
368392
[`Handle`][api-handle],
@@ -499,6 +523,8 @@ abide by its terms.
499523
500524
[api-compilecontext]: #compilecontext
501525
526+
[api-compiledata]: #compiledata
527+
502528
[api-encoding]: #encoding
503529
504530
[api-extension]: #extension

tsconfig.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
2-
"include": ["**/*.js"],
3-
"exclude": ["coverage/", "node_modules/", "lib/index.js", "index.js"],
2+
"include": ["dev/**/*.js", "test/**/*.js", "dev/index.d.ts"],
3+
"exclude": ["coverage/", "node_modules/"],
44
"compilerOptions": {
55
"checkJs": true,
66
"declaration": true,

0 commit comments

Comments
 (0)