Skip to content

Commit 21144ef

Browse files
wooormwooorm
committed
Add smarter types
1 parent 9039274 commit 21144ef

File tree

4 files changed

+189
-61
lines changed

4 files changed

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

‎lib/index.js‎

Lines changed: 124 additions & 51 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,59 +76,66 @@ import {convert} from 'unist-util-is'
1076
* Find the first node in `parent` before another `node` or before 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-
export function findBefore(parent, index, test) {
38-
const is = convert(test)
88+
export const findBefore =
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+
* Parent node.
100+
* @param {UnistNode | number} index
101+
* Child node or index.
102+
* @param {Test} [test=undefined]
103+
* Test for child to look for.
104+
* @returns {UnistNode | undefined}
105+
* A child (matching `test`, if given) or `undefined`.
106+
*/
107+
function (parent, index, test) {
108+
const is = convert(test)
39109

40-
if (!parent || !parent.type || !parent.children) {
41-
throw new Error('Expected parent node')
42-
}
110+
if (!parent || !parent.type || !parent.children) {
111+
throw new Error('Expected parent node')
112+
}
43113

44-
if (typeof index === 'number') {
45-
if (index < 0 || index === Number.POSITIVE_INFINITY) {
46-
throw new Error('Expected positive finite number as index')
47-
}
48-
} else {
49-
index = parent.children.indexOf(index)
114+
if (typeof index === 'number') {
115+
if (index < 0 || index === Number.POSITIVE_INFINITY) {
116+
throw new Error('Expected positive finite number as index')
117+
}
118+
} else {
119+
index = parent.children.indexOf(index)
50120

51-
if (index < 0) {
52-
throw new Error('Expected child node or index')
53-
}
54-
}
121+
if (index < 0) {
122+
throw new Error('Expected child node or index')
123+
}
124+
}
55125

56-
// Performance.
57-
if (index > parent.children.length) {
58-
index = parent.children.length
59-
}
126+
// Performance.
127+
if (index > parent.children.length) {
128+
index = parent.children.length
129+
}
60130

61-
while (index--) {
62-
if (is(parent.children[index], index, parent)) {
63-
return parent.children[index]
64-
}
65-
}
131+
while (index--) {
132+
const child = parent.children[index]
133+
134+
if (is(child, index, parent)) {
135+
return child
136+
}
137+
}
66138

67-
return undefined
68-
}
139+
return undefined
140+
}
141+
)

‎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": {

‎test.js‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
/**
2-
* @typedef {import('unist').Node} Node
2+
* @typedef {import('mdast').Emphasis} Emphasis
3+
* @typedef {import('mdast').InlineCode} InlineCode
4+
* @typedef {import('unist').Node} UnistNode
35
*/
46

57
import assert from 'node:assert/strict'
@@ -25,6 +27,11 @@ test('`findBefore`', async function (t) {
2527
const next = paragraph.children[1]
2628
assert(next.type === 'emphasis')
2729

30+
/** @type {Emphasis} */
31+
const emphasis = {type: 'emphasis', children: []}
32+
/** @type {InlineCode} */
33+
const inlineCode = {type: 'inlineCode', value: 'a'}
34+
2835
await t.test('should fail without parent', async function () {
2936
assert.throws(function () {
3037
// @ts-expect-error: check that an error is thrown at runtime.
@@ -35,40 +42,40 @@ test('`findBefore`', async function (t) {
3542
await t.test('should fail without parent node', async function () {
3643
assert.throws(function () {
3744
// @ts-expect-error: check that an error is thrown at runtime.
38-
findBefore({type: 'foo'})
45+
findBefore(inlineCode)
3946
}, /Expected parent node/)
4047
})
4148

4249
await t.test('should fail without index (#1)', async function () {
4350
assert.throws(function () {
4451
// @ts-expect-error: check that an error is thrown at runtime.
45-
findBefore({type: 'foo', children: []})
52+
findBefore(emphasis)
4653
}, /Expected child node or index/)
4754
})
4855

4956
await t.test('should fail without index (#2)', async function () {
5057
assert.throws(function () {
51-
findBefore({type: 'foo', children: []}, -1)
58+
findBefore(emphasis, -1)
5259
}, /Expected positive finite number as index/)
5360
})
5461

5562
await t.test('should fail without index (#3)', async function () {
5663
assert.throws(function () {
57-
findBefore({type: 'foo', children: []}, {type: 'bar'})
64+
findBefore(emphasis, inlineCode)
5865
}, /Expected child node or index/)
5966
})
6067

6168
await t.test('should fail for invalid `test` (#1)', async function () {
6269
assert.throws(function () {
6370
// @ts-expect-error: check that an error is thrown at runtime.
64-
findBefore({type: 'foo', children: [{type: 'bar'}]}, 1, false)
71+
findBefore(emphasis, 1, false)
6572
}, /Expected function, string, or object as test/)
6673
})
6774

6875
await t.test('should fail for invalid `test` (#2)', async function () {
6976
assert.throws(function () {
7077
// @ts-expect-error: check that an error is thrown at runtime.
71-
findBefore({type: 'foo', children: [{type: 'bar'}]}, 1, true)
78+
findBefore(emphasis, 1, true)
7279
}, /Expected function, string, or object as test/)
7380
})
7481

@@ -205,8 +212,8 @@ test('`findBefore`', async function (t) {
205212
})
206213

207214
/**
208-
* @param {Node} _
209-
* @param {number | null | undefined} n
215+
* @param {UnistNode} _
216+
* @param {number | undefined} n
210217
*/
211218
function check(_, n) {
212219
return n === 3

0 commit comments

Comments
 (0)