Skip to content

Commit cbf0a6f

Browse files
wooormwooorm
committed
Add improved types
1 parent 193b10b commit cbf0a6f

File tree

4 files changed

+240
-85
lines changed

4 files changed

+240
-85
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 {findAllBefore} 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+
findAllBefore()
22+
23+
// @ts-expect-error: child or index needed.
24+
findAllBefore(heading)
25+
26+
findAllBefore(
27+
// @ts-expect-error: parent needed.
28+
text,
29+
0
30+
)
31+
32+
expectType<PhrasingContent[]>(findAllBefore(heading, text))
33+
34+
expectType<Text[]>(findAllBefore(heading, text, 'text'))
35+
36+
expectType<Text[]>(findAllBefore(heading, 0, 'text'))
37+
38+
expectType<RootContent[]>(findAllBefore(root, 0))
39+
40+
expectType<Text[]>(findAllBefore(root, 0, 'text'))
41+
42+
expectType<RowContent[]>(findAllBefore(row, 0))

‎lib/index.js

Lines changed: 121 additions & 54 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,62 +76,63 @@ import {convert} from 'unist-util-is'
1076
* Find the nodes in `parent` before another `node` or before an index, that
1177
* pass `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 {Array<Kind>}
21-
*
22-
* @overload
23-
* @param {Parent} parent
24-
* @param {Node | number} index
25-
* @param {Test} [test]
26-
* @returns {Array<Node>}
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 {Array<Node>}
35-
* Children of `parent` that pass `test`.
81+
* @param index
82+
* Child node or index.
83+
* @param [test=undefined]
84+
* Test for child to look for (optional).
85+
* @returns
86+
* Children (matching `test`, if given).
3687
*/
37-
export function findAllBefore(parent, index, test) {
38-
const is = convert(test)
39-
/** @type {Array<Node>} */
40-
const results = []
41-
let offset = -1
88+
export const findAllBefore =
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) => Array<Matches<Child<Kind>, Check>>) &
93+
* (<Kind extends UnistParent>(parent: Kind, index: Child<Kind> | number, test?: null | undefined) => Array<Child<Kind>>)
94+
* )}
95+
*/
96+
(
97+
/**
98+
* @param {UnistParent} parent
99+
* @param {UnistNode | number} index
100+
* @param {Test} [test]
101+
* @returns {Array<UnistNode>}
102+
*/
103+
function (parent, index, test) {
104+
const is = convert(test)
105+
/** @type {Array<UnistNode>} */
106+
const results = []
107+
let offset = -1
42108

43-
if (!parent || !parent.type || !parent.children) {
44-
throw new Error('Expected parent node')
45-
}
109+
if (!parent || !parent.type || !parent.children) {
110+
throw new Error('Expected parent node')
111+
}
46112

47-
if (typeof index === 'number') {
48-
if (index < 0 || index === Number.POSITIVE_INFINITY) {
49-
throw new Error('Expected positive finite number as index')
50-
}
51-
} else {
52-
index = parent.children.indexOf(index)
113+
if (typeof index === 'number') {
114+
if (index < 0 || index === Number.POSITIVE_INFINITY) {
115+
throw new Error('Expected positive finite number as index')
116+
}
117+
} else {
118+
index = parent.children.indexOf(index)
53119

54-
if (index < 0) {
55-
throw new Error('Expected child node or index')
56-
}
57-
}
120+
if (index < 0) {
121+
throw new Error('Expected child node or index')
122+
}
123+
}
58124

59-
// Performance.
60-
if (index > parent.children.length) {
61-
index = parent.children.length
62-
}
125+
// Performance.
126+
if (index > parent.children.length) {
127+
index = parent.children.length
128+
}
63129

64-
while (++offset < index) {
65-
if (is(parent.children[offset], offset, parent)) {
66-
results.push(parent.children[offset])
67-
}
68-
}
130+
while (++offset < index) {
131+
if (is(parent.children[offset], offset, parent)) {
132+
results.push(parent.children[offset])
133+
}
134+
}
69135

70-
return results
71-
}
136+
return results
137+
}
138+
)

‎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.1",
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)