source: trip-planner-front/node_modules/es-module-lexer/README.md@ 1ad8e64

Last change on this file since 1ad8e64 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.7 KB
Line 
1# ES Module Lexer
2
3[![Build Status][travis-image]][travis-url]
4
5A JS module syntax lexer used in [es-module-shims](https://github.com/guybedford/es-module-shims).
6
7Outputs the list of exports and locations of import specifiers, including dynamic import and import meta handling.
8
9A very small single JS file (4KiB gzipped) that includes inlined Web Assembly for very fast source analysis of ECMAScript module syntax only.
10
11For an example of the performance, Angular 1 (720KiB) is fully parsed in 5ms, in comparison to the fastest JS parser, Acorn which takes over 100ms.
12
13_Comprehensively handles the JS language grammar while remaining small and fast. - ~10ms per MB of JS cold and ~5ms per MB of JS warm, [see benchmarks](#benchmarks) for more info._
14
15### Usage
16
17```
18npm install es-module-lexer
19```
20
21For use in CommonJS:
22
23```js
24const { init, parse } = require('es-module-lexer');
25
26(async () => {
27 // either await init, or call parse asynchronously
28 // this is necessary for the Web Assembly boot
29 await init;
30
31 const [imports, exports] = parse('export var p = 5');
32 exports[0] === 'p';
33})();
34```
35
36An ES module version is also available:
37
38```js
39import { init, parse } from 'es-module-lexer';
40
41(async () => {
42 await init;
43
44 const source = `
45 import { name } from 'mod';
46 import json from './json.json' assert { type: 'json' }
47 export var p = 5;
48 export function q () {
49
50 };
51
52 // Comments provided to demonstrate edge cases
53 import /*comment!*/ ('asdf', { assert: { type: 'json' }});
54 import /*comment!*/.meta.asdf;
55 `;
56
57 const [imports, exports] = parse(source, 'optional-sourcename');
58
59 // Returns "mod"
60 imports[0].n
61 source.substring(imports[0].s, imports[0].e);
62 // "s" = start
63 // "e" = end
64
65 // Returns "import { name } from 'mod'"
66 source.substring(imports[0].ss, imports[0].se);
67 // "ss" = statement start
68 // "se" = statement end
69
70 // Returns "{ type: 'json' }"
71 source.substring(imports[1].a, imports[1].se);
72 // "a" = assert
73
74 // Returns "p,q"
75 exports.toString();
76
77 // Dynamic imports are indicated by imports[2].d > -1
78 // In this case the "d" index is the start of the dynamic import
79 // Returns true
80 imports[2].d > -1;
81
82 // Returns "asdf"
83 imports[2].n
84 // Returns "'asdf'"
85 source.substring(imports[2].s, imports[2].e);
86 // Returns "import /*comment!*/ ("
87 source.substring(imports[2].d, imports[2].s);
88 // Returns "import /*comment!*/ ('asdf', { assert: { type: 'json' } })"
89 source.substring(imports[2].d, imports[2].se + 1);
90 // Returns "{ assert: { type: 'json' } }"
91 source.substring(imports[2].a, imports[2].e);
92 // ss is the same as d
93 // as, ae not used for dynamic imports
94
95 // import.meta is indicated by imports[2].d === -2
96 // Returns true
97 imports[2].d === -2;
98 // Returns "import /*comment!*/.meta"
99 source.substring(imports[2].s, imports[2].e);
100})();
101```
102
103### Escape Sequences
104
105To handle escape sequences in specifier strings, the `.n` field of imported specifiers will be provided where possible.
106
107For dynamic import expressions, this field will be empty if not a valid JS string.
108
109### Facade Detection
110
111Facade modules that only use import / export syntax can be detected via the third return value:
112
113```js
114const [,, facade] = parse(`
115 export * from 'external';
116 import * as ns from 'external2';
117 export { a as b } from 'external3';
118 export { ns };
119`);
120facade === true;
121```
122
123### Environment Support
124
125Node.js 10+, and [all browsers with Web Assembly support](https://caniuse.com/#feat=wasm).
126
127### Grammar Support
128
129* Token state parses all line comments, block comments, strings, template strings, blocks, parens and punctuators.
130* Division operator / regex token ambiguity is handled via backtracking checks against punctuator prefixes, including closing brace or paren backtracking.
131* Always correctly parses valid JS source, but may parse invalid JS source without errors.
132
133### Limitations
134
135The lexing approach is designed to deal with the full language grammar including RegEx / division operator ambiguity through backtracking and paren / brace tracking.
136
137The only limitation to the reduced parser is that the "exports" list may not correctly gather all export identifiers in the following edge cases:
138
139```js
140// Only "a" is detected as an export, "q" isn't
141export var a = 'asdf', q = z;
142
143// "b" is not detected as an export
144export var { a: b } = asdf;
145```
146
147The above cases are handled gracefully in that the lexer will keep going fine, it will just not properly detect the export names above.
148
149### Benchmarks
150
151Benchmarks can be run with `npm run bench`.
152
153Current results:
154
155```
156Module load time
157> 7ms
158Cold Run, All Samples
159test/samples/*.js (3057 KiB)
160> 33ms
161
162Warm Runs (average of 25 runs)
163test/samples/angular.js (719 KiB)
164> 4.08ms
165test/samples/angular.min.js (188 KiB)
166> 2.08ms
167test/samples/d3.js (491 KiB)
168> 4.72ms
169test/samples/d3.min.js (274 KiB)
170> 3ms
171test/samples/magic-string.js (34 KiB)
172> 0.04ms
173test/samples/magic-string.min.js (20 KiB)
174> 0ms
175test/samples/rollup.js (902 KiB)
176> 8.16ms
177test/samples/rollup.min.js (429 KiB)
178> 4.28ms
179
180Warm Runs, All Samples (average of 25 runs)
181test/samples/*.js (3057 KiB)
182> 25.68ms
183```
184
185### Building
186
187To build download the WASI SDK from https://github.com/WebAssembly/wasi-sdk/releases.
188
189The Makefile assumes the existence of "wasi-sdk-11.0" and "wabt" (optional) as sibling folders to this project.
190
191The build through the Makefile is then run via `make lib/lexer.wasm`, which can also be triggered via `npm run build-wasm` to create `dist/lexer.js`.
192
193On Windows it may be preferable to use the Linux subsystem.
194
195After the Web Assembly build, the CJS build can be triggered via `npm run build`.
196
197### License
198
199MIT
200
201[travis-url]: https://travis-ci.org/guybedford/es-module-lexer
202[travis-image]: https://travis-ci.org/guybedford/es-module-lexer.svg?branch=master
203
Note: See TracBrowser for help on using the repository browser.