Skip to content

Commit bef1e14

Browse files
authored
feat(type-parsing): use oxc-parser (#887)
1 parent 9fe36c0 commit bef1e14

30 files changed

Lines changed: 1556 additions & 920 deletions

‎docs/specification.md‎

Lines changed: 70 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Specification
22

3-
**Version**: 1.0.0
3+
**Version**: 1.0.1
44

55
**Authored By**: Aviv Keller (<me@aviv.sh>)
66

@@ -98,15 +98,9 @@ in the relevant section.
9898
- [7.6. Placement](#76-placement)
9999
- [8. Type Annotations](#8-type-annotations)
100100
- [8.1. Syntax](#81-syntax)
101-
- [8.2. Primitive Types](#82-primitive-types)
102-
- [8.3. Global Types](#83-global-types)
103-
- [8.4. Custom Types](#84-custom-types)
104-
- [8.5. Compound Types](#85-compound-types)
105-
- [8.5.1. Union Types](#851-union-types)
106-
- [8.5.2. Array Types](#852-array-types)
107-
- [8.5.3. Generic Types](#853-generic-types)
108-
- [8.6. Resolution Order](#86-resolution-order)
109-
- [8.7. Unresolved Types](#87-unresolved-types)
101+
- [8.2. Parsing](#82-parsing)
102+
- [8.3. Resolution](#83-resolution)
103+
- [8.4. Rendering](#84-rendering)
110104
- [9. Typed Parameter Lists](#9-typed-parameter-lists)
111105
- [9.1. Identification](#91-identification)
112106
- [9.2. Item Structure](#92-item-structure)
@@ -178,9 +172,10 @@ providing version-history and classification metadata for the enclosing
178172
the compact `key=value` pattern, providing [document][term-document]-level or
179173
[section][term-section]-level metadata. See [§6.2][§6.2].
180174

181-
**Type annotation.** A reference to a type enclosed in `{curly braces}` within
182-
a [typed list][term-typed-list] item, or in prose, that is resolved to a
183-
hyperlink. See [§8][§8].
175+
**Type annotation.** A [TypeScript][typescript] type expression enclosed in
176+
balanced `{curly braces}` within a [typed list][term-typed-list] item, or in
177+
prose. It is rendered as a single code fragment whose type names are resolved
178+
to hyperlinks. See [§8][§8].
184179

185180
---
186181

@@ -844,91 +839,61 @@ A [stability indicator][term-stability] on the depth-1 heading applies to the
844839

845840
### 8.1. Syntax
846841

847-
[Type annotations][term-type-annotation] are enclosed in curly braces, such as
848-
`{Type}`. They appear in two contexts:
849-
850-
- **In [typed parameter lists][§9]:** as part of item structure.
851-
- **In prose text:** as inline references.
852-
853-
Both forms are auto-linked to documentation for the referenced type (see
854-
[§8.6][§8.6]).
855-
856-
### 8.2. Primitive Types
857-
858-
Primitive types use lowercase names: `string`, `number`, `boolean`, `bigint`,
859-
`symbol`, `null`, `undefined`, `integer`.
860-
861-
These MUST be resolved to documentation for JavaScript primitive data types.
862-
863-
### 8.3. Global Types
864-
865-
JavaScript built-in globals use PascalCase: `Array`, `Object`, `Function`,
866-
`Promise`, `Error`, `RegExp`, `Map`, `Set`, `Date`, `Uint8Array`, `Buffer`,
867-
and others.
868-
869-
These MUST be resolved to documentation for JavaScript global objects.
870-
871-
### 8.4. Custom Types
872-
873-
Types not in the primitive or global sets are resolved via a configurable type
874-
map provided to the toolchain. The type map associates type names with
875-
documentation URLs. An example type-map is available for viewing [here][nodejs-typemap].
876-
877-
### 8.5. Compound Types
878-
879-
#### 8.5.1. Union Types
880-
881-
Multiple types are separated by `|` (pipe):
882-
883-
```
884-
{string|Buffer|URL}
885-
```
886-
887-
Spaces around the pipe are OPTIONAL. Both `{string|Buffer}` and
888-
`{string | Buffer}` MUST be accepted.
889-
890-
#### 8.5.2. Array Types
891-
892-
The `[]` suffix denotes an array of the base type:
893-
894-
```
895-
{string[]}
896-
{Buffer[]}
897-
```
898-
899-
#### 8.5.3. Generic Types
900-
901-
Generic types use angle brackets:
902-
903-
```
904-
{Promise<string>}
905-
{Map<string, number>}
906-
```
907-
908-
The outer type and each inner type parameter are resolved independently. Inner
909-
types MAY include [unions][§8.5.1]:
910-
911-
```
912-
{Promise<string|Buffer>}
913-
```
914-
915-
### 8.6. Resolution Order
916-
917-
Types are resolved in the following order. The first tier that produces a
918-
match terminates resolution.
919-
920-
1. JavaScript primitives (see [§8.2][§8.2]).
921-
2. JavaScript built-in globals (see [§8.3][§8.3]).
922-
3. Implementation-defined external type mappings.
923-
4. Custom type map entries (see [§8.4][§8.4]).
924-
5. Dotted-name heuristic: types containing `.` are split on the first `.` to
842+
A [type annotation][term-type-annotation] is any balanced `{curly brace}`
843+
span in text. The content between the braces is a [TypeScript][typescript]
844+
type expression — anything valid on the right-hand side of a TypeScript
845+
`type X = ...` alias.
846+
847+
Annotations appear both in [typed parameter lists][§9] (as part of item
848+
structure) and in prose text (as inline references); both forms are parsed
849+
and rendered identically.
850+
851+
### 8.2. Parsing
852+
853+
Implementations MUST parse each annotation whose value is not a whole-value
854+
[map match][§8.3] under the TypeScript type grammar. Implementations SHOULD
855+
collect every annotation in a [document][term-document] and parse them in a
856+
single batch.
857+
858+
An annotation that fails to parse MUST produce a warning identifying the
859+
source location, and MUST be rendered as plain, unlinked code.
860+
861+
### 8.3. Resolution
862+
863+
Each annotation resolves to a set of hyperlinks:
864+
865+
1. **Whole-value lookup.** If the entire annotation value matches a type-map
866+
entry verbatim, the whole annotation becomes a single link. This permits
867+
display-name keys that are not valid TypeScript identifiers (e.g.
868+
`zlib options`).
869+
2. **Identifier resolution.** Otherwise, every type name in the parsed
870+
expression resolves individually: keyword types (`string`, `number`,
871+
`boolean`, ...), type-reference names, qualified names (`vm.Module`),
872+
`typeof` targets, and `import('mod').X` qualifiers. Structural names —
873+
function parameter names, object property keys — are never resolved.
874+
875+
Each name resolves through the following tiers; the first match wins:
876+
877+
1. The configurable type map provided to the toolchain, which associates
878+
names with documentation URLs. An example type map is available for
879+
viewing [here][nodejs-typemap].
880+
2. JavaScript primitives and built-in (TC39) globals, matched
881+
case-insensitively: `string`, `number`, `boolean`, `bigint`, `symbol`,
882+
`null`, `undefined`, `integer`, `Array`, `Object`, `Function`, `Promise`,
883+
and others.
884+
3. Web platform APIs documented on MDN, matched case-insensitively.
885+
4. Dotted-name heuristic: names containing `.` are split on the first `.` to
925886
derive a module name and member identifier, producing a cross-document
926887
link of the form `<module>.md#<identifier>`.
927888

928-
### 8.7. Unresolved Types
889+
A name that no tier resolves stays plain — this is not an error.
890+
891+
### 8.4. Rendering
929892

930-
If a type cannot be resolved through any tier, it WILL be rendered as
931-
unlinked formatted text.
893+
The whole annotation renders as ONE inline code fragment. Each resolved name
894+
becomes a hyperlink spanning exactly its character range within the fragment;
895+
unresolved names remain plain text inside it. Implementations MAY
896+
syntax-highlight the fragment as TypeScript.
932897

933898
---
934899

@@ -945,10 +910,9 @@ its first item matches any of these conditions:
945910

946911
1. It begins with text matching one of the [special prefixes][§9.3]
947912
(`Returns:`, `Extends:`, `Type:`).
948-
2. It begins with a [type-reference][§8] link (a link whose label is a type
949-
annotation such as `{Type}`).
913+
2. It begins with a [type annotation][§8].
950914
3. It begins with an inline code span (the parameter name) followed by a
951-
space and then a [type-reference][§8] link.
915+
space and then a [type annotation][§8].
952916

953917
### 9.2. Item Structure
954918

@@ -964,7 +928,8 @@ The components, in order, are:
964928
2. **Parameter name** - A backtick code span. REQUIRED for parameter items;
965929
absent for [`Returns:`][§9.3.1], [`Type:`][§9.3.3], and
966930
[`Extends:`][§9.3.2] items.
967-
3. **[Type annotation][§8]** - A `{Type}` reference. OPTIONAL.
931+
3. **[Type annotation][§8]** - A single `{...}` TypeScript type expression
932+
(a union belongs inside it, e.g. `{string|Buffer}`). OPTIONAL.
968933
4. **Description** - Free-form prose. OPTIONAL.
969934
5. **[Default value][§9.5]** - The exact pattern `**Default:** \`value\``.
970935
OPTIONAL.
@@ -1106,9 +1071,9 @@ documentation by conforming implementations.
11061071

11071072
### 11.5. Type Auto-Linking
11081073

1109-
[Type annotations][term-type-annotation] in prose text matching the
1110-
`{Type}` pattern ([§8.1][§8.1]) are automatically converted to hyperlinks
1111-
following the [resolution order][§8.6].
1074+
[Type annotations][term-type-annotation] in prose text ([§8.1][§8.1]) are
1075+
parsed ([§8.2][§8.2]), resolved ([§8.3][§8.3]), and rendered ([§8.4][§8.4])
1076+
exactly like annotations in [typed parameter lists][§9].
11121077

11131078
### 11.6. Link Reference Definitions
11141079

@@ -1132,6 +1097,7 @@ of the [document][term-document], after all content
11321097
[rfc-8174]: https://www.rfc-editor.org/rfc/rfc8174
11331098
[yaml-1.2]: https://yaml.org/spec/1.2.2/
11341099
[semver]: https://semver.org/
1100+
[typescript]: https://www.typescriptlang.org/
11351101
[nodejs-typemap]: https://github.com/nodejs/node/blob/main/doc/type-map.json
11361102

11371103
<!-- CommonMark spec sections -->
@@ -1187,11 +1153,9 @@ of the [document][term-document], after all content
11871153
[§7.3]: #73-sub-levels
11881154
[§8]: #8-type-annotations
11891155
[§8.1]: #81-syntax
1190-
[§8.2]: #82-primitive-types
1191-
[§8.3]: #83-global-types
1192-
[§8.4]: #84-custom-types
1193-
[§8.5.1]: #851-union-types
1194-
[§8.6]: #86-resolution-order
1156+
[§8.2]: #82-parsing
1157+
[§8.3]: #83-resolution
1158+
[§8.4]: #84-rendering
11951159
[§9]: #9-typed-parameter-lists
11961160
[§9.3]: #93-special-prefixes
11971161
[§9.3.1]: #931-returns

0 commit comments

Comments
 (0)