Skip to content

Commit 4680aec

Browse files
brettz9brettz9
committed
docs: indicate return of EspreeTokens from tokenize 
1 parent 968d5d9 commit 4680aec

10 files changed

+106
-91
lines changed

‎dist/espree.cjs

+45-36
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ var visitorKeys__namespace = /*#__PURE__*/_interopNamespace(visitorKeys);
4242
/**
4343
* @local
4444
* @typedef {import('acorn')} acorn
45-
* @typedef {import('../lib/espree').EnhancedTokTypes} EnhancedTokTypes
45+
* @typedef {import('./espree').EnhancedTokTypes} EnhancedTokTypes
46+
* @typedef {import('../espree').ecmaVersion} ecmaVersion
4647
*/
4748

4849
// ----------------------------------------------------------------------------
@@ -75,23 +76,21 @@ var visitorKeys__namespace = /*#__PURE__*/_interopNamespace(visitorKeys);
7576
* }} BaseEsprimaToken
7677
*
7778
* @typedef {{
78-
* type: string;
79-
* } & BaseEsprimaToken} EsprimaToken
80-
*
81-
* @typedef {{
82-
* type: string | acorn.TokenType;
83-
* } & BaseEsprimaToken} EsprimaTokenFlexible
84-
*
85-
* @typedef {{
8679
* jsxAttrValueToken: boolean;
87-
* ecmaVersion: acorn.ecmaVersion;
80+
* ecmaVersion: ecmaVersion;
8881
* }} ExtraNoTokens
8982
*
9083
* @typedef {{
91-
* tokens: EsprimaTokenFlexible[]
84+
* tokens: EsprimaToken[]
9285
* } & ExtraNoTokens} Extra
9386
*/
9487

88+
/**
89+
* @typedef {{
90+
* type: string;
91+
* } & BaseEsprimaToken} EsprimaToken
92+
*/
93+
9594
//------------------------------------------------------------------------------
9695
// Requirements
9796
//------------------------------------------------------------------------------
@@ -179,7 +178,7 @@ class TokenTranslator {
179178
}
180179

181180
/**
182-
* Translates a single Esprima token to a single Acorn token. This may be
181+
* Translates a single Acorn token to a single Esprima token. This may be
183182
* inaccurate due to how templates are handled differently in Esprima and
184183
* Acorn, but should be accurate for all other tokens.
185184
* @param {acorn.Token} token The Acorn token to translate.
@@ -364,6 +363,7 @@ class TokenTranslator {
364363
/**
365364
* @local
366365
* @typedef {import('../espree').ParserOptions} ParserOptions
366+
* @typedef {import('../espree').ecmaVersion} ecmaVersion
367367
*/
368368

369369
// ----------------------------------------------------------------------------
@@ -372,7 +372,7 @@ class TokenTranslator {
372372
/**
373373
* @local
374374
* @typedef {{
375-
* ecmaVersion: 10 | 9 | 8 | 7 | 6 | 5 | 3 | 11 | 12 | 13 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | "latest",
375+
* ecmaVersion: ecmaVersion,
376376
* sourceType: "script"|"module",
377377
* range?: boolean,
378378
* loc?: boolean,
@@ -385,7 +385,7 @@ class TokenTranslator {
385385
* ranges: boolean,
386386
* locations: boolean,
387387
* allowReturnOutsideFunction: boolean,
388-
* tokens?: boolean | null,
388+
* tokens?: boolean,
389389
* comment?: boolean
390390
* }} NormalizedParserOptions
391391
*/
@@ -541,18 +541,16 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
541541
* @local
542542
* @typedef {import('acorn')} acorn
543543
* @typedef {typeof import('acorn-jsx').tokTypes} tokTypesType
544-
* @typedef {typeof import('acorn-jsx').AcornJsxParser} AcornJsxParser
544+
* @typedef {import('acorn-jsx').AcornJsxParser} AcornJsxParser
545545
* @typedef {import('../espree').ParserOptions} ParserOptions
546+
* @typedef {import('../espree').ecmaVersion} ecmaVersion
546547
*/
547548

548549
// ----------------------------------------------------------------------------
549550
// Local types
550551
// ----------------------------------------------------------------------------
551552
/**
552553
* @local
553-
*
554-
* @typedef {acorn.ecmaVersion} ecmaVersion
555-
*
556554
* @typedef {{
557555
* generator?: boolean
558556
* } & acorn.Node} EsprimaNode
@@ -564,12 +562,6 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
564562
*/
565563

566564
/**
567-
* First three properties as in `acorn.Comment`; next two as in `acorn.Comment`
568-
* but optional. Last is different as has to allow `undefined`
569-
*/
570-
/**
571-
* @local
572-
*
573565
* @typedef {{
574566
* type: string,
575567
* value: string,
@@ -581,10 +573,16 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
581573
* end: acorn.Position | undefined
582574
* }
583575
* }} EsprimaComment
576+
*/
577+
578+
/**
579+
* First two properties as in `acorn.Comment`; next two as in `acorn.Comment`
580+
* but optional. Last is different as has to allow `undefined`
581+
*/
582+
/**
583+
* @local
584584
*
585-
* @typedef {{
586-
* comments?: EsprimaComment[]
587-
* } & acorn.Token[]} EspreeTokens
585+
* @typedef {import('../espree').EspreeTokens} EspreeTokens
588586
*
589587
* @typedef {{
590588
* tail?: boolean
@@ -611,7 +609,7 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
611609
* @typedef {{
612610
* sourceType?: "script"|"module"|"commonjs";
613611
* comments?: EsprimaComment[];
614-
* tokens?: acorn.Token[];
612+
* tokens?: EspreeTokens;
615613
* body: acorn.Node[];
616614
* } & acorn.Node} EsprimaProgramNode
617615
*/
@@ -1112,10 +1110,15 @@ const parsers = {
11121110
*/
11131111
get regular() {
11141112
if (this._regular === null) {
1115-
const espreeParserFactory = espree();
1113+
const espreeParserFactory = /** @type {unknown} */ (espree());
1114+
1115+
this._regular = /** @type {IEspreeParser} */ (
1116+
acorn__namespace.Parser.extend(
11161117

1117-
// Cast the `acorn.Parser` to our own for required properties not specified in *.d.ts
1118-
this._regular = espreeParserFactory(/** @type {AcornJsxParser} */ (acorn__namespace.Parser));
1118+
/** @type {(BaseParser: typeof acorn.Parser) => typeof acorn.Parser} */
1119+
(espreeParserFactory)
1120+
)
1121+
);
11191122
}
11201123
return this._regular;
11211124
},
@@ -1126,11 +1129,17 @@ const parsers = {
11261129
*/
11271130
get jsx() {
11281131
if (this._jsx === null) {
1129-
const espreeParserFactory = espree();
1132+
const espreeParserFactory = /** @type {unknown} */ (espree());
11301133
const jsxFactory = jsx__default["default"]();
11311134

1132-
// Cast the `acorn.Parser` to our own for required properties not specified in *.d.ts
1133-
this._jsx = espreeParserFactory(jsxFactory(acorn__namespace.Parser));
1135+
this._jsx = /** @type {IEspreeParser} */ (
1136+
acorn__namespace.Parser.extend(
1137+
jsxFactory,
1138+
1139+
/** @type {(BaseParser: typeof acorn.Parser) => typeof acorn.Parser} */
1140+
(espreeParserFactory)
1141+
)
1142+
);
11341143
}
11351144
return this._jsx;
11361145
},
@@ -1159,7 +1168,7 @@ const parsers = {
11591168
* Tokenizes the given code.
11601169
* @param {string} code The code to tokenize.
11611170
* @param {ParserOptions} options Options defining how to tokenize.
1162-
* @returns {acorn.Token[]|null} An array of tokens.
1171+
* @returns {EspreeTokens} An array of tokens.
11631172
* @throws {EnhancedSyntaxError} If the input code is invalid.
11641173
* @private
11651174
*/
@@ -1171,7 +1180,7 @@ function tokenize(code, options) {
11711180
options = Object.assign({}, options, { tokens: true }); // eslint-disable-line no-param-reassign
11721181
}
11731182

1174-
return new Parser(options, code).tokenize();
1183+
return /** @type {EspreeTokens} */ (new Parser(options, code).tokenize());
11751184
}
11761185

11771186
//------------------------------------------------------------------------------

‎dist/espree.cjs.map

+1-1
Large diffs are not rendered by default.

‎dist/espree.d.ts

+7-2
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22
* Tokenizes the given code.
33
* @param {string} code The code to tokenize.
44
* @param {ParserOptions} options Options defining how to tokenize.
5-
* @returns {import('acorn').Token[]} An array of tokens.
5+
* @returns {EspreeTokens} An array of tokens.
66
* @throws {import('./lib/espree').EnhancedSyntaxError} If the input code is invalid.
77
* @private
88
*/
9-
export function tokenize(code: string, options: ParserOptions): import('acorn').Token[];
9+
export function tokenize(code: string, options: ParserOptions): EspreeTokens;
1010
/**
1111
* Parses the given code.
1212
* @param {string} code The code to tokenize.
@@ -23,6 +23,11 @@ export const Syntax: {
2323
export const latestEcmaVersion: number;
2424
export const supportedEcmaVersions: number[];
2525
export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 'latest';
26+
export type EspreeToken = import('./lib/token-translator').EsprimaToken;
27+
export type EspreeComment = import('./lib/espree').EsprimaComment;
28+
export type EspreeTokens = {
29+
comments?: EspreeComment[];
30+
} & EspreeToken[];
2631
export type ParserOptions = {
2732
allowReserved?: boolean;
2833
ecmaVersion?: ecmaVersion;

‎dist/espree.d.ts.map

+1-1
Original file line numberDiff line numberDiff line change

‎dist/lib/espree.d.ts

+16-27
Original file line numberDiff line numberDiff line change
@@ -9,39 +9,17 @@ export class EspreeParser extends acorn.Parser {
99
constructor(opts: import('../espree').ParserOptions | null, code: string | object);
1010
/**
1111
* Returns Espree tokens.
12-
* @returns {{comments?: {type: string; value: string; range?: [number, number]; start?: number; end?: number; loc?: {start: import('acorn').Position | undefined; end: import('acorn').Position | undefined}}[]} & import('acorn').Token[] | null} Espree tokens
12+
* @returns {import('../espree').EspreeTokens | null} Espree tokens
1313
*/
14-
tokenize(): {
15-
comments?: {
16-
type: string;
17-
value: string;
18-
range?: [number, number];
19-
start?: number;
20-
end?: number;
21-
loc?: {
22-
start: import('acorn').Position | undefined;
23-
end: import('acorn').Position | undefined;
24-
};
25-
}[];
26-
} & import('acorn').Token[] | null;
14+
tokenize(): import('../espree').EspreeTokens | null;
2715
/**
2816
* Parses.
29-
* @returns {{sourceType?: "script" | "module" | "commonjs"; comments?: {type: string; value: string; range?: [number, number]; start?: number; end?: number; loc?: {start: import('acorn').Position | undefined; end: import('acorn').Position | undefined}}[]; tokens?: import('acorn').Token[]; body: import('acorn').Node[]} & import('acorn').Node} The program Node
17+
* @returns {{sourceType?: "script" | "module" | "commonjs"; comments?: EsprimaComment[]; tokens?: import('../espree').EspreeTokens; body: import('acorn').Node[]} & import('acorn').Node} The program Node
3018
*/
3119
parse(): {
3220
sourceType?: "script" | "module" | "commonjs";
33-
comments?: {
34-
type: string;
35-
value: string;
36-
range?: [number, number];
37-
start?: number;
38-
end?: number;
39-
loc?: {
40-
start: import('acorn').Position | undefined;
41-
end: import('acorn').Position | undefined;
42-
};
43-
}[];
44-
tokens?: import('acorn').Token[];
21+
comments?: EsprimaComment[];
22+
tokens?: import('../espree').EspreeTokens;
4523
body: import('acorn').Node[];
4624
} & import('acorn').Node;
4725
/**
@@ -71,5 +49,16 @@ export type EnhancedSyntaxError = {
7149
export type EnhancedTokTypes = {
7250
jsxAttrValueToken?: import('acorn').TokenType;
7351
} & typeof import('acorn-jsx').tokTypes;
52+
export type EsprimaComment = {
53+
type: string;
54+
value: string;
55+
range?: [number, number];
56+
start?: number;
57+
end?: number;
58+
loc?: {
59+
start: import('acorn').Position | undefined;
60+
end: import('acorn').Position | undefined;
61+
};
62+
};
7463
import * as acorn from "acorn";
7564
//# sourceMappingURL=espree.d.ts.map

‎dist/lib/espree.d.ts.map

+1-1
Original file line numberDiff line numberDiff line change

‎dist/lib/token-translator.d.ts.map

+1-1
Original file line numberDiff line numberDiff line change

‎espree.js

+16-2
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,20 @@
6363
* @typedef {3|5|6|7|8|9|10|11|12|13|2015|2016|2017|2018|2019|2020|2021|2022|'latest'} ecmaVersion
6464
*/
6565

66+
/**
67+
* @typedef {import('./lib/token-translator').EsprimaToken} EspreeToken
68+
*/
69+
70+
/**
71+
* @typedef {import('./lib/espree').EsprimaComment} EspreeComment
72+
*/
73+
74+
/**
75+
* @typedef {{
76+
* comments?: EspreeComment[]
77+
* } & EspreeToken[]} EspreeTokens
78+
*/
79+
6680
/**
6781
* `jsx.Options` gives us 2 optional properties, so extend it
6882
*
@@ -182,7 +196,7 @@ const parsers = {
182196
* Tokenizes the given code.
183197
* @param {string} code The code to tokenize.
184198
* @param {ParserOptions} options Options defining how to tokenize.
185-
* @returns {acorn.Token[]} An array of tokens.
199+
* @returns {EspreeTokens} An array of tokens.
186200
* @throws {EnhancedSyntaxError} If the input code is invalid.
187201
* @private
188202
*/
@@ -194,7 +208,7 @@ export function tokenize(code, options) {
194208
options = Object.assign({}, options, { tokens: true }); // eslint-disable-line no-param-reassign
195209
}
196210

197-
return /** @type {acorn.Token[]} */ (new Parser(options, code).tokenize());
211+
return /** @type {EspreeTokens} */ (new Parser(options, code).tokenize());
198212
}
199213

200214
//------------------------------------------------------------------------------

‎lib/espree.js

+10-10
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,6 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
5151
*/
5252

5353
/**
54-
* First three properties as in `acorn.Comment`; next two as in `acorn.Comment`
55-
* but optional. Last is different as has to allow `undefined`
56-
*/
57-
/**
58-
* @local
59-
*
6054
* @typedef {{
6155
* type: string,
6256
* value: string,
@@ -68,10 +62,16 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
6862
* end: acorn.Position | undefined
6963
* }
7064
* }} EsprimaComment
65+
*/
66+
67+
/**
68+
* First two properties as in `acorn.Comment`; next two as in `acorn.Comment`
69+
* but optional. Last is different as has to allow `undefined`
70+
*/
71+
/**
72+
* @local
7173
*
72-
* @typedef {{
73-
* comments?: EsprimaComment[]
74-
* } & acorn.Token[]} EspreeTokens
74+
* @typedef {import('../espree').EspreeTokens} EspreeTokens
7575
*
7676
* @typedef {{
7777
* tail?: boolean
@@ -98,7 +98,7 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode");
9898
* @typedef {{
9999
* sourceType?: "script"|"module"|"commonjs";
100100
* comments?: EsprimaComment[];
101-
* tokens?: acorn.Token[];
101+
* tokens?: EspreeTokens;
102102
* body: acorn.Node[];
103103
* } & acorn.Node} EsprimaProgramNode
104104
*/

0 commit comments

Comments
 (0)