126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# Oxc Parser
|
||
|
||
## Features
|
||
|
||
### Supports WASM
|
||
|
||
See https://stackblitz.com/edit/oxc-parser for usage example.
|
||
|
||
### ESTree
|
||
|
||
When parsing JS or JSX files, the AST returned is fully conformant with the
|
||
[ESTree standard](https://github.com/estree/estree), the same as produced by
|
||
[Acorn](https://www.npmjs.com/package/acorn).
|
||
|
||
When parsing TypeScript, the AST conforms to [@typescript-eslint/typescript-estree](https://www.npmjs.com/package/@typescript-eslint/typescript-estree)'s TS-ESTree format.
|
||
|
||
If you need all ASTs in the same with-TS-properties format, use the `astType: 'ts'` option.
|
||
|
||
The only differences between Oxc's AST and ESTree / TS-ESTree are:
|
||
|
||
- Support for Stage 3 [decorators](https://github.com/tc39/proposal-decorators).
|
||
- Support for Stage 3 ECMA features [`import defer`](https://github.com/tc39/proposal-defer-import-eval)
|
||
and [`import source`](https://github.com/tc39/proposal-source-phase-imports).
|
||
- In TS-ESTree AST, `import.defer(...)` and `import.source(...)` are represented as an `ImportExpression`
|
||
with `'defer'` or `'source'` in `phase` field (as in ESTree spec), where TS-ESLint represents these
|
||
as a `CallExpression` with `MetaProperty` as its `callee`.
|
||
- Addition of a non-standard `hashbang` field to `Program`.
|
||
|
||
That aside, the AST should completely align with Acorn's ESTree AST or TS-ESLint's TS-ESTree.
|
||
Any deviation would be considered a bug.
|
||
|
||
### AST Types
|
||
|
||
[@oxc-project/types](https://www.npmjs.com/package/@oxc-project/types) can be used. For example:
|
||
|
||
```typescript
|
||
import { Statement } from '@oxc-project/types';
|
||
```
|
||
|
||
### Visitor
|
||
|
||
[oxc-walker](https://www.npmjs.com/package/oxc-walker) or [estree-walker](https://www.npmjs.com/package/estree-walker) can be used.
|
||
|
||
### Fast Mode
|
||
|
||
By default, Oxc parser does not produce semantic errors where symbols and scopes are needed.
|
||
|
||
To enable semantic errors, apply the option `showSemanticErrors: true`.
|
||
|
||
For example,
|
||
|
||
```js
|
||
let foo;
|
||
let foo;
|
||
```
|
||
|
||
Does not produce any errors when `showSemanticErrors` is `false`, which is the default behavior.
|
||
|
||
Fast mode is best suited for parser plugins, where other parts of your build pipeline has already checked for errors.
|
||
|
||
Please note that turning off fast mode incurs a small performance overhead.
|
||
|
||
### Returns ESM information.
|
||
|
||
It is likely that you are writing a parser plugin that requires ESM information.
|
||
|
||
To avoid walking the AST again, Oxc Parser returns ESM information directly.
|
||
|
||
This information can be used to rewrite import and exports with the help of [`magic-string`](https://www.npmjs.com/package/magic-string),
|
||
without any AST manipulations.
|
||
|
||
```ts
|
||
export interface EcmaScriptModule {
|
||
/**
|
||
* Has ESM syntax.
|
||
*
|
||
* i.e. `import` and `export` statements, and `import.meta`.
|
||
*
|
||
* Dynamic imports `import('foo')` are ignored since they can be used in non-ESM files.
|
||
*/
|
||
hasModuleSyntax: boolean;
|
||
/** Import statements. */
|
||
staticImports: Array<StaticImport>;
|
||
/** Export statements. */
|
||
staticExports: Array<StaticExport>;
|
||
/** Dynamic import expressions. */
|
||
dynamicImports: Array<DynamicImport>;
|
||
/** Span positions` of `import.meta` */
|
||
importMetas: Array<Span>;
|
||
}
|
||
```
|
||
|
||
## API
|
||
|
||
```javascript
|
||
import oxc from 'oxc-parser';
|
||
|
||
const code = 'const url: String = /* 🤨 */ import.meta.url;';
|
||
|
||
// File extension is used to determine which dialect to parse source as.
|
||
const filename = 'test.tsx';
|
||
|
||
const result = oxc.parseSync(filename, code);
|
||
// or `await oxc.parseAsync(filename, code)`
|
||
|
||
// An array of errors, if any.
|
||
console.log(result.errors);
|
||
|
||
// AST and comments.
|
||
console.log(result.program, result.comments);
|
||
|
||
// ESM information - imports, exports, `import.meta`s.
|
||
console.log(result.module);
|
||
```
|
||
|
||
### Options
|
||
|
||
All options are optional.
|
||
|
||
- `lang`: `'js'` | `'jsx'` | `'ts'` | `'tsx'`. Set language of source. If omitted, language is deduced from file extension.
|
||
- `sourceType`: `'script'` | `'module'` | `'unambiguous'`. Set source type. Defaults to `'module'`.
|
||
- `astType`: `'js'` | `'ts'`. Set to `'ts'` if you want ASTs of plain JS/JSX files to contain TypeScript-specific properties.
|
||
- `range`: `true` | `false`. If `true`, AST nodes contain a `range` field. Defaults to `false`.
|
||
- `preserveParens`: `true` | `false`. If `true`, parenthesized expressions are represented by (non-standard) `ParenthesizedExpression` and `TSParenthesizedType` AST nodes. Defaults to `true`.
|
||
- `showSemanticErrors`: `true` | `false`. If `true`, check file for semantic errors which parser does not otherwise emit e.g. `let x; let x;`. Has a small performance cost. Defaults to `false`.
|