Skip to content

Commit 16ac2e1

Browse files
wooormwooorm
committed
Add improved types
1 parent c31f7da commit 16ac2e1

File tree

4 files changed

+231
-78
lines changed

4 files changed

+231
-78
lines changed

‎index.test-d.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import {expectType} from 'tsd'
2+
import type {
3+
Heading,
4+
PhrasingContent,
5+
Root,
6+
RootContent,
7+
RowContent,
8+
TableCell,
9+
TableRow,
10+
Text
11+
} from 'mdast'
12+
import {findAfter} from './index.js'
13+
14+
const text: Text = {type: 'text', value: 'alpha'}
15+
const heading: Heading = {type: 'heading', depth: 1, children: [text]}
16+
const root: Root = {type: 'root', children: [heading]}
17+
const cell: TableCell = {type: 'tableCell', children: [text]}
18+
const row: TableRow = {type: 'tableRow', children: [cell]}
19+
20+
// @ts-expect-error: parent needed.
21+
findAfter()
22+
23+
// @ts-expect-error: child or index needed.
24+
findAfter(heading)
25+
26+
findAfter(
27+
// @ts-expect-error: parent needed.
28+
text,
29+
0
30+
)
31+
32+
expectType<PhrasingContent | undefined>(findAfter(heading, text))
33+
34+
expectType<Text | undefined>(findAfter(heading, text, 'text'))
35+
36+
expectType<Text | undefined>(findAfter(heading, 0, 'text'))
37+
38+
expectType<RootContent | undefined>(findAfter(root, 0))
39+
40+
expectType<Text | undefined>(findAfter(root, 0, 'text'))
41+
42+
expectType<RowContent | undefined>(findAfter(row, 0))

‎lib/index.js‎

Lines changed: 114 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,73 @@
11
/**
2-
* @typedef {import('unist').Node} Node
3-
* @typedef {import('unist').Parent} Parent
4-
* @typedef {import('unist-util-is').Test} Test
2+
* @typedef {import('unist').Node} UnistNode
3+
* @typedef {import('unist').Parent} UnistParent
4+
*/
5+
6+
/**
7+
* @typedef {Exclude<import('unist-util-is').Test, undefined> | undefined} Test
8+
* Test from `unist-util-is`.
9+
*
10+
* Note: we have remove and add `undefined`, because otherwise when generating
11+
* automatic `.d.ts` files, TS tries to flatten paths from a local perspective,
12+
* which doesn’t work when publishing on npm.
13+
*/
14+
15+
/**
16+
* @typedef {(
17+
* Fn extends (value: any) => value is infer Thing
18+
* ? Thing
19+
* : Fallback
20+
* )} Predicate
21+
* Get the value of a type guard `Fn`.
22+
* @template Fn
23+
* Value; typically function that is a type guard (such as `(x): x is Y`).
24+
* @template Fallback
25+
* Value to yield if `Fn` is not a type guard.
26+
*/
27+
28+
/**
29+
* @typedef {(
30+
* Check extends null | undefined // No test.
31+
* ? Value
32+
* : Value extends {type: Check} // String (type) test.
33+
* ? Value
34+
* : Value extends Check // Partial test.
35+
* ? Value
36+
* : Check extends Function // Function test.
37+
* ? Predicate<Check, Value> extends Value
38+
* ? Predicate<Check, Value>
39+
* : never
40+
* : never // Some other test?
41+
* )} MatchesOne
42+
* Check whether a node matches a primitive check in the type system.
43+
* @template Value
44+
* Value; typically unist `Node`.
45+
* @template Check
46+
* Value; typically `unist-util-is`-compatible test, but not arrays.
47+
*/
48+
49+
/**
50+
* @typedef {(
51+
* Check extends Array<any>
52+
* ? MatchesOne<Value, Check[keyof Check]>
53+
* : MatchesOne<Value, Check>
54+
* )} Matches
55+
* Check whether a node matches a check in the type system.
56+
* @template Value
57+
* Value; typically unist `Node`.
58+
* @template Check
59+
* Value; typically `unist-util-is`-compatible test.
60+
*/
61+
62+
/**
63+
* @typedef {(
64+
* Kind extends {children: Array<infer Child>}
65+
* ? Child
66+
* : never
67+
* )} Child
68+
* Collect nodes that can be parents of `Child`.
69+
* @template {UnistNode} Kind
70+
* All node types.
571
*/
672

773
import {convert} from 'unist-util-is'
@@ -10,55 +76,55 @@ import {convert} from 'unist-util-is'
1076
* Find the first node in `parent` after another `node` or after an index,
1177
* that passes `test`.
1278
*
13-
* @template {Node} Kind
14-
* Node type.
15-
*
16-
* @overload
17-
* @param {Parent} parent
18-
* @param {Node | number} index
19-
* @param {import('unist-util-is').Test} test
20-
* @returns {Kind | undefined}
21-
*
22-
* @overload
23-
* @param {Parent} parent
24-
* @param {Node | number} index
25-
* @param {Test} [test]
26-
* @returns {Node | undefined}
27-
*
28-
* @param {Parent} parent
79+
* @param parent
2980
* Parent node.
30-
* @param {Node | number} index
31-
* Child of `parent` or it’s index.
32-
* @param {Test} [test]
33-
* `unist-util-is`-compatible test.
34-
* @returns {Node | undefined}
35-
* Child of `parent` or `undefined`.
81+
* @param index
82+
* Child node or index.
83+
* @param [test=undefined]
84+
* Test for child to look for (optional).
85+
* @returns
86+
* A child (matching `test`, if given) or `undefined`.
3687
*/
37-
// To do: next major: `undefined`.
38-
export function findAfter(parent, index, test) {
39-
const is = convert(test)
88+
export const findAfter =
89+
// Note: overloads like this are needed to support optional generics.
90+
/**
91+
* @type {(
92+
* (<Kind extends UnistParent, Check extends Test>(parent: Kind, index: Child<Kind> | number, test: Check) => Matches<Child<Kind>, Check> | undefined) &
93+
* (<Kind extends UnistParent>(parent: Kind, index: Child<Kind> | number, test?: null | undefined) => Child<Kind> | undefined)
94+
* )}
95+
*/
96+
(
97+
/**
98+
* @param {UnistParent} parent
99+
* @param {UnistNode | number} index
100+
* @param {Test} [test]
101+
* @returns {UnistNode | undefined}
102+
*/
103+
function (parent, index, test) {
104+
const is = convert(test)
40105

41-
if (!parent || !parent.type || !parent.children) {
42-
throw new Error('Expected parent node')
43-
}
106+
if (!parent || !parent.type || !parent.children) {
107+
throw new Error('Expected parent node')
108+
}
44109

45-
if (typeof index === 'number') {
46-
if (index < 0 || index === Number.POSITIVE_INFINITY) {
47-
throw new Error('Expected positive finite number as index')
48-
}
49-
} else {
50-
index = parent.children.indexOf(index)
110+
if (typeof index === 'number') {
111+
if (index < 0 || index === Number.POSITIVE_INFINITY) {
112+
throw new Error('Expected positive finite number as index')
113+
}
114+
} else {
115+
index = parent.children.indexOf(index)
51116

52-
if (index < 0) {
53-
throw new Error('Expected child node or index')
54-
}
55-
}
117+
if (index < 0) {
118+
throw new Error('Expected child node or index')
119+
}
120+
}
56121

57-
while (++index < parent.children.length) {
58-
if (is(parent.children[index], index, parent)) {
59-
return parent.children[index]
60-
}
61-
}
122+
while (++index < parent.children.length) {
123+
if (is(parent.children[index], index, parent)) {
124+
return parent.children[index]
125+
}
126+
}
62127

63-
return undefined
64-
}
128+
return undefined
129+
}
130+
)

‎package.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,19 +35,21 @@
3535
"unist-util-is": "^6.0.0"
3636
},
3737
"devDependencies": {
38+
"@types/mdast": "^4.0.0",
3839
"@types/node": "^20.0.0",
3940
"c8": "^8.0.0",
4041
"mdast-util-from-markdown": "^1.0.0",
4142
"prettier": "^2.0.0",
4243
"remark-cli": "^11.0.0",
4344
"remark-preset-wooorm": "^9.0.0",
45+
"tsd": "^0.28.0",
4446
"type-coverage": "^2.0.0",
4547
"typescript": "^5.0.0",
4648
"xo": "^0.54.0"
4749
},
4850
"scripts": {
4951
"prepack": "npm run build && npm run format",
50-
"build": "tsc --build --clean && tsc --build && type-coverage",
52+
"build": "tsc --build --clean && tsc --build && tsd && type-coverage",
5153
"format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
5254
"test-api": "node --conditions development test.js",
5355
"test-coverage": "c8 --100 --reporter lcov npm run test-api",
@@ -70,6 +72,10 @@
7072
"atLeast": 100,
7173
"detail": true,
7274
"ignoreCatch": true,
75+
"#": "needed `any`s",
76+
"ignoreFiles": [
77+
"lib/index.d.ts"
78+
],
7379
"strict": true
7480
},
7581
"xo": {

0 commit comments

Comments
 (0)