From 44a41e02f9c06b19eb6b6ed6f7c8a7c61f77ec80 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Wed, 11 May 2022 08:14:33 +0800 Subject: [PATCH] docs: indicate return of EspreeTokens from `tokenize` --- dist/espree.d.ts | 9 +++++-- dist/espree.d.ts.map | 2 +- dist/lib/espree.d.ts | 43 +++++++++++------------------- dist/lib/espree.d.ts.map | 2 +- dist/lib/token-translator.d.ts.map | 2 +- espree.js | 18 +++++++++++-- lib/espree.js | 20 +++++++------- lib/token-translator.js | 18 ++++++------- 8 files changed, 60 insertions(+), 54 deletions(-) diff --git a/dist/espree.d.ts b/dist/espree.d.ts index b6ff73ad..31af4994 100644 --- a/dist/espree.d.ts +++ b/dist/espree.d.ts @@ -2,11 +2,11 @@ * Tokenizes the given code. * @param {string} code The code to tokenize. * @param {ParserOptions} options Options defining how to tokenize. - * @returns {import('acorn').Token[]} An array of tokens. + * @returns {EspreeTokens} An array of tokens. * @throws {import('./lib/espree').EnhancedSyntaxError} If the input code is invalid. * @private */ -export function tokenize(code: string, options: ParserOptions): import('acorn').Token[]; +export function tokenize(code: string, options: ParserOptions): EspreeTokens; /** * Parses the given code. * @param {string} code The code to tokenize. @@ -23,6 +23,11 @@ export const Syntax: { export const latestEcmaVersion: number; export const supportedEcmaVersions: number[]; export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 'latest'; +export type EspreeToken = import('./lib/token-translator').EsprimaToken; +export type EspreeComment = import('./lib/espree').EsprimaComment; +export type EspreeTokens = { + comments?: EspreeComment[]; +} & EspreeToken[]; export type ParserOptions = { allowReserved?: boolean; ecmaVersion?: ecmaVersion; diff --git a/dist/espree.d.ts.map b/dist/espree.d.ts.map index e12a2969..b09fe0c2 100644 --- a/dist/espree.d.ts.map +++ b/dist/espree.d.ts.map @@ -1 +1 @@ -{"version":3,"file":"espree.d.ts","sourceRoot":"","sources":["../tmp/espree.js"],"names":[],"mappings":"AAoHA;;;;;;;GAOG;AACH,+BANW,MAAM,WACN,aAAa,GACX,OAAO,OAAO,EAAE,KAAK,EAAE,CAUnC;AAED;;;;;;GAMG;AACH,4BALW,MAAM,WACN,aAAa,GACX,OAAO,OAAO,EAAE,IAAI,CAMhC;AACD,6BAAqC;AACrC,kDAEI;AACJ;;EAYI;AACJ,uCAAwD;AACxD,6CAAgE;0BAhHnD,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,QAAQ;4BAc5G;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IAAC,YAAY,CAAC,EAAE;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAC"} \ No newline at end of file +{"version":3,"file":"espree.d.ts","sourceRoot":"","sources":["../tmp/espree.js"],"names":[],"mappings":"AAgIA;;;;;;;GAOG;AACH,+BANW,MAAM,WACN,aAAa,GACX,YAAY,CAUxB;AAED;;;;;;GAMG;AACH,4BALW,MAAM,WACN,aAAa,GACX,OAAO,OAAO,EAAE,IAAI,CAMhC;AACD,6BAAqC;AACrC,kDAEI;AACJ;;EAYI;AACJ,uCAAwD;AACxD,6CAAgE;0BA5HnD,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,QAAQ;0BAI5G,OAAO,wBAAwB,EAAE,YAAY;4BAI7C,OAAO,cAAc,EAAE,cAAc;2BAIrC;IAAC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;CAAC,GAAG,WAAW,EAAE;4BAc5C;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IAAC,YAAY,CAAC,EAAE;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAC"} \ No newline at end of file diff --git a/dist/lib/espree.d.ts b/dist/lib/espree.d.ts index 8e0a977b..8fc305d9 100644 --- a/dist/lib/espree.d.ts +++ b/dist/lib/espree.d.ts @@ -9,39 +9,17 @@ export class EspreeParser extends acorn.Parser { constructor(opts: import('../espree').ParserOptions | null, code: string | object); /** * Returns Espree tokens. - * @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 + * @returns {import('../espree').EspreeTokens | null} Espree tokens */ - tokenize(): { - 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; + tokenize(): import('../espree').EspreeTokens | null; /** * Parses. - * @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 + * @returns {{sourceType?: "script" | "module" | "commonjs"; comments?: EsprimaComment[]; tokens?: import('../espree').EspreeTokens; body: import('acorn').Node[]} & import('acorn').Node} The program Node */ parse(): { 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[]; + comments?: EsprimaComment[]; + tokens?: import('../espree').EspreeTokens; body: import('acorn').Node[]; } & import('acorn').Node; /** @@ -71,5 +49,16 @@ export type EnhancedSyntaxError = { export type EnhancedTokTypes = { jsxAttrValueToken?: import('acorn').TokenType; } & typeof import('acorn-jsx').tokTypes; +export type EsprimaComment = { + type: string; + value: string; + range?: [number, number]; + start?: number; + end?: number; + loc?: { + start: import('acorn').Position | undefined; + end: import('acorn').Position | undefined; + }; +}; import * as acorn from "acorn"; //# sourceMappingURL=espree.d.ts.map \ No newline at end of file diff --git a/dist/lib/espree.d.ts.map b/dist/lib/espree.d.ts.map index 50e3cc78..c4cf4532 100644 --- a/dist/lib/espree.d.ts.map +++ b/dist/lib/espree.d.ts.map @@ -1 +1 @@ -{"version":3,"file":"espree.d.ts","sourceRoot":"","sources":["../../tmp/lib/espree.js"],"names":[],"mappings":"AAgDe,sCAIA,OAAO,WAAW,EAAE,cAAc,KAChC,mBAAmB,CA+QnC;;AACD;IAEY;;;;OAIG;IACH,kBAHW,OAAO,WAAW,EAAE,aAAa,GAAG,IAAI,QACxC,MAAM,GAAG,MAAM,EAIjC;IAEO;;;OAGG;IACH,YAFa;QAAC,QAAQ,CAAC,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE;gBAAC,KAAK,EAAE,OAAO,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;gBAAC,GAAG,EAAE,OAAO,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAA;aAAC,CAAA;SAAC,EAAE,CAAA;KAAC,GAAG,OAAO,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,CAIzP;IAwBO;;;OAGG;IACH,SAFa;QAAC,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;QAAC,QAAQ,CAAC,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE;gBAAC,KAAK,EAAE,OAAO,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;gBAAC,GAAG,EAAE,OAAO,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAA;aAAC,CAAA;SAAC,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,OAAO,EAAE,KAAK,EAAE,CAAC;QAAC,IAAI,EAAE,OAAO,OAAO,EAAE,IAAI,EAAE,CAAA;KAAC,GAAG,OAAO,OAAO,EAAE,IAAI,CAI9V;IAsBO;;;;;;OAMG;IACH,sBALW,MAAM,WACN,MAAM,GAEJ,IAAI,CAIxB;IAYO;;;;;;;;OAQG;IACH,sBAHW,MAAM,GACJ,IAAI,CAIxB;CACJ;kCAzaY;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,WAAW;+BAIpE;IAAC,iBAAiB,CAAC,EAAE,OAAO,OAAO,EAAE,SAAS,CAAA;CAAC,GAAG,cAAc,WAAW,EAAE,QAAQ"} \ No newline at end of file +{"version":3,"file":"espree.d.ts","sourceRoot":"","sources":["../../tmp/lib/espree.js"],"names":[],"mappings":"AAoDe,sCAIA,OAAO,WAAW,EAAE,cAAc,KAChC,mBAAmB,CA+QnC;;AACD;IAEY;;;;OAIG;IACH,kBAHW,OAAO,WAAW,EAAE,aAAa,GAAG,IAAI,QACxC,MAAM,GAAG,MAAM,EAIjC;IAEO;;;OAGG;IACH,YAFa,OAAO,WAAW,EAAE,YAAY,GAAG,IAAI,CAI3D;IAwBO;;;OAGG;IACH,SAFa;QAAC,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;QAAC,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,WAAW,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,OAAO,OAAO,EAAE,IAAI,EAAE,CAAA;KAAC,GAAG,OAAO,OAAO,EAAE,IAAI,CAIhM;IAsBO;;;;;;OAMG;IACH,sBALW,MAAM,WACN,MAAM,GAEJ,IAAI,CAIxB;IAYO;;;;;;;;OAQG;IACH,sBAHW,MAAM,GACJ,IAAI,CAIxB;CACJ;kCA7aY;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,WAAW;+BAIpE;IAAC,iBAAiB,CAAC,EAAE,OAAO,OAAO,EAAE,SAAS,CAAA;CAAC,GAAG,cAAc,WAAW,EAAE,QAAQ;6BAIrF;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE;QAAC,KAAK,EAAE,OAAO,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;QAAC,GAAG,EAAE,OAAO,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAA;KAAC,CAAA;CAAC"} \ No newline at end of file diff --git a/dist/lib/token-translator.d.ts.map b/dist/lib/token-translator.d.ts.map index 4cffda18..3c683e38 100644 --- a/dist/lib/token-translator.d.ts.map +++ b/dist/lib/token-translator.d.ts.map @@ -1 +1 @@ -{"version":3,"file":"token-translator.d.ts","sourceRoot":"","sources":["../../tmp/lib/token-translator.js"],"names":[],"mappings":";AA+DA;IAEI;;;;;OAKG;IACH,2BAJW,OAAO,UAAU,EAAE,gBAAgB,QACnC,MAAM,EAQhB;IAJG,oDAAmC;IAC3B,wCAAwC,CAAC,SAA9B,CAAC,OAAO,OAAO,EAAE,KAAK,CAAC,EAAE,CAAsB;IAClE,0CAAuB;IACvB,cAAiB;IAGrB;;;;;;;OAOG;IACH,iBAJW,OAAO,OAAO,EAAE,KAAK,SACrB;QAAC,iBAAiB,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,WAAW,EAAE,WAAW,CAAA;KAAC;cACjE,MAAM;;eAAY,GAAG;;;;;;mBAAgH,MAAM;qBAAW,MAAM;;MAkD/K;IAED;;;;;OAKG;IACH,eAJW,OAAO,OAAO,EAAE,KAAK;gBACZ,CAAC;YAAC,IAAI,EAAE,MAAM,GAAG,OAAO,OAAO,EAAE,SAAS,CAAA;SAAC,GAAG;YAAC,KAAK,EAAE,GAAG,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,OAAO,OAAO,EAAE,cAAc,CAAC;YAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAAC,KAAK,CAAC,EAAE;gBAAC,KAAK,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAC,CAAA;SAAC,CAAC,EAAE;;2BAAwB,OAAO;qBAAe,OAAO,WAAW,EAAE,WAAW;QACzR,IAAI,CAyDhB;CACJ"} \ No newline at end of file +{"version":3,"file":"token-translator.d.ts","sourceRoot":"","sources":["../../tmp/lib/token-translator.js"],"names":[],"mappings":";2BAkBa;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,OAAO,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC;AAiDlL;IAEI;;;;;OAKG;IACH,2BAJW,OAAO,UAAU,EAAE,gBAAgB,QACnC,MAAM,EAQhB;IAJG,oDAAmC;IAC3B,wCAAwC,CAAC,SAA9B,CAAC,OAAO,OAAO,EAAE,KAAK,CAAC,EAAE,CAAsB;IAClE,0CAAuB;IACvB,cAAiB;IAGrB;;;;;;;OAOG;IACH,iBAJW,OAAO,OAAO,EAAE,KAAK,SACrB;QAAC,iBAAiB,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,WAAW,EAAE,WAAW,CAAA;KAAC,GACxE,YAAY,CAkDxB;IAED;;;;;OAKG;IACH,eAJW,OAAO,OAAO,EAAE,KAAK;gBACZ,YAAY,EAAE;;2BAAwB,OAAO;qBAAe,OAAO,WAAW,EAAE,WAAW;QAClG,IAAI,CAyDhB;CACJ"} \ No newline at end of file diff --git a/espree.js b/espree.js index 94c997cc..db4f0452 100644 --- a/espree.js +++ b/espree.js @@ -63,6 +63,20 @@ * @typedef {3|5|6|7|8|9|10|11|12|13|2015|2016|2017|2018|2019|2020|2021|2022|'latest'} ecmaVersion */ +/** + * @typedef {import('./lib/token-translator').EsprimaToken} EspreeToken + */ + +/** + * @typedef {import('./lib/espree').EsprimaComment} EspreeComment + */ + +/** + * @typedef {{ + * comments?: EspreeComment[] + * } & EspreeToken[]} EspreeTokens + */ + /** * `jsx.Options` gives us 2 optional properties, so extend it * @@ -182,7 +196,7 @@ const parsers = { * Tokenizes the given code. * @param {string} code The code to tokenize. * @param {ParserOptions} options Options defining how to tokenize. - * @returns {acorn.Token[]} An array of tokens. + * @returns {EspreeTokens} An array of tokens. * @throws {EnhancedSyntaxError} If the input code is invalid. * @private */ @@ -194,7 +208,7 @@ export function tokenize(code, options) { options = Object.assign({}, options, { tokens: true }); // eslint-disable-line no-param-reassign } - return /** @type {acorn.Token[]} */ (new Parser(options, code).tokenize()); + return /** @type {EspreeTokens} */ (new Parser(options, code).tokenize()); } //------------------------------------------------------------------------------ diff --git a/lib/espree.js b/lib/espree.js index 5848bd50..9e506568 100644 --- a/lib/espree.js +++ b/lib/espree.js @@ -51,12 +51,6 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode"); */ /** - * First three properties as in `acorn.Comment`; next two as in `acorn.Comment` - * but optional. Last is different as has to allow `undefined` - */ -/** - * @local - * * @typedef {{ * type: string, * value: string, @@ -68,10 +62,16 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode"); * end: acorn.Position | undefined * } * }} EsprimaComment + */ + +/** + * First two properties as in `acorn.Comment`; next two as in `acorn.Comment` + * but optional. Last is different as has to allow `undefined` + */ +/** + * @local * - * @typedef {{ - * comments?: EsprimaComment[] - * } & acorn.Token[]} EspreeTokens + * @typedef {import('../espree').EspreeTokens} EspreeTokens * * @typedef {{ * tail?: boolean @@ -98,7 +98,7 @@ const ESPRIMA_FINISH_NODE = Symbol("espree's esprimaFinishNode"); * @typedef {{ * sourceType?: "script"|"module"|"commonjs"; * comments?: EsprimaComment[]; - * tokens?: acorn.Token[]; + * tokens?: EspreeTokens; * body: acorn.Node[]; * } & acorn.Node} EsprimaProgramNode */ diff --git a/lib/token-translator.js b/lib/token-translator.js index 062986e4..561acfbf 100644 --- a/lib/token-translator.js +++ b/lib/token-translator.js @@ -44,23 +44,21 @@ * }} BaseEsprimaToken * * @typedef {{ - * type: string; - * } & BaseEsprimaToken} EsprimaToken - * - * @typedef {{ - * type: string | acorn.TokenType; - * } & BaseEsprimaToken} EsprimaTokenFlexible - * - * @typedef {{ * jsxAttrValueToken: boolean; * ecmaVersion: ecmaVersion; * }} ExtraNoTokens * * @typedef {{ - * tokens: EsprimaTokenFlexible[] + * tokens: EsprimaToken[] * } & ExtraNoTokens} Extra */ +/** + * @typedef {{ + * type: string; + * } & BaseEsprimaToken} EsprimaToken + */ + //------------------------------------------------------------------------------ // Requirements //------------------------------------------------------------------------------ @@ -148,7 +146,7 @@ class TokenTranslator { } /** - * Translates a single Esprima token to a single Acorn token. This may be + * Translates a single Acorn token to a single Esprima token. This may be * inaccurate due to how templates are handled differently in Esprima and * Acorn, but should be accurate for all other tokens. * @param {acorn.Token} token The Acorn token to translate.