oxc-parser 0.52.0 → 0.54.0

package/README.md

@@ -2,24 +2,58 @@
 
 ## Features
 
-- Returns ESM information.
-- Built-in `magic-string` on the Rust side exposed through N-API.
-- "clever" approach to overcome the Rust UTF8 vs JavaScript UTF16 length problem.
+### Fast Mode
 
-## Caveat
+By default, Oxc parser does not produce semantic errors where symbols and scopes are needed.
 
-The parser alone does not fully check for syntax errors that are associated with semantic data (symbols and scopes).
-The full compiler is needed for such case, as the compiler does an additional semantic pass.
+To enable semantic errors, apply the option `showSemanticErrors: true`.
 
-With this caveat, `oxc-parser` is best suited for parser plugins,
-where you need quick access to ESM information, as well as fast `magic-string` operations.
+For example,
+
+```js
+let foo;
+let foo;
+```
+
+Does not produce any errors when `showSemanticErrors` is `false`, which is the default behavior.
+
+This mode is best suited for parser plugins, where other parts of your build pipeline has already checked for errors.
+
+### 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 './index.js';
 
-// The emoji makes the span of `import.meta.url` to be different in UTF8 and UTF16.
 const code = 'const url: String = /* 🤨 */ import.meta.url;';
 
 // File extension is used to determine which dialect to parse source as.
@@ -36,16 +70,4 @@ console.log(result.program, result.comments);
 
 // ESM information - imports, exports, `import.meta`s.
 console.log(result.module);
-
-// A `magic-string` instance for accessing and manipulating the source text.
-// All returned spans are in UTF8 offsets, which cannot be used directly on our JavaScript.
-// JavaScript string lengths are in UTF16 offsets.
-const ms = result.magicString;
-
-for (const span of result.module.importMetas) {
-  // Extra methods for access the source text through spans with UTF8 offsets.
-  console.log(ms.getSourceText(span.start, span.end)); // prints `import.meta`
-  console.log(ms.getLineColumnNumber(span.start)); // prints `{ line: 0, column: 20 }`
-  console.log(code.substring(ms.getUtf16ByteOffset(span.start)).startsWith('import.meta.url')); // prints `true`
-}
 ```

package/bindings.js

@@ -370,7 +370,6 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-module.exports.MagicString = nativeBinding.MagicString
 module.exports.ParseResult = nativeBinding.ParseResult
 module.exports.ExportExportNameKind = nativeBinding.ExportExportNameKind
 module.exports.ExportImportNameKind = nativeBinding.ExportImportNameKind
@@ -378,5 +377,4 @@ module.exports.ExportLocalNameKind = nativeBinding.ExportLocalNameKind
 module.exports.ImportNameKind = nativeBinding.ImportNameKind
 module.exports.parseAsync = nativeBinding.parseAsync
 module.exports.parseSync = nativeBinding.parseSync
-module.exports.parseWithoutReturn = nativeBinding.parseWithoutReturn
 module.exports.Severity = nativeBinding.Severity

package/index.d.ts

@@ -2,47 +2,11 @@
 /* eslint-disable */
 
 export * from '@oxc-project/types';
-export declare class MagicString {
-  /** Get source text from utf8 offset. */
-  getSourceText(start: number, end: number): string
-  /** Get 0-based line and column number from utf8 offset. */
-  getLineColumnNumber(offset: number): LineColumn
-  /** Get UTF16 byte offset from UTF8 byte offset. */
-  getUtf16ByteOffset(offset: number): number
-  length(): number
-  toString(): string
-  hasChanged(): boolean
-  append(input: string): this
-  appendLeft(index: number, input: string): this
-  appendRight(index: number, input: string): this
-  indent(): this
-  prepend(input: string): this
-  prependLeft(index: number, input: string): this
-  prependRight(index: number, input: string): this
-  relocate(start: number, end: number, to: number): this
-  remove(start: number, end: number): this
-  generateMap(options?: Partial<GenerateDecodedMapOptions>): {
-    toString: () => string;
-    toUrl: () => string;
-    toMap: () => {
-      file?: string
-      mappings: string
-      names: Array<string>
-      sourceRoot?: string
-      sources: Array<string>
-      sourcesContent?: Array<string>
-      version: number
-      x_google_ignoreList?: Array<number>
-    }
-  }
-}
-
 export declare class ParseResult {
   get program(): import("@oxc-project/types").Program
   get module(): EcmaScriptModule
   get comments(): Array<Comment>
   get errors(): Array<OxcError>
-  get magicString(): MagicString
 }
 
 export interface Comment {
@@ -136,15 +100,6 @@ export declare const enum ExportLocalNameKind {
   None = 'None'
 }
 
-export interface GenerateDecodedMapOptions {
-  /** The filename of the file containing the original source. */
-  source?: string
-  /** Whether to include the original content in the map's `sourcesContent` array. */
-  includeContent: boolean
-  /** Whether the mapping should be high-resolution. */
-  hires: boolean | 'boundary'
-}
-
 export interface ImportName {
   kind: ImportNameKind
   name?: string
@@ -161,15 +116,6 @@ export declare const enum ImportNameKind {
   Default = 'Default'
 }
 
-export interface LineColumn {
-  line: number
-  column: number
-}
-
-export interface OverwriteOptions {
-  contentOnly: boolean
-}
-
 export interface OxcError {
   severity: Severity
   message: string
@@ -195,49 +141,28 @@ export interface ParserOptions {
    * (non-standard) `ParenthesizedExpression` nodes that have a single `expression` property
    * containing the expression inside parentheses.
    *
-   * Default: true
+   * @default true
    */
   preserveParens?: boolean
   /**
-   * Default: false
-   * @experimental Only for internal usage on Rolldown and Vite.
+   * Produce semantic errors with an additional AST pass.
+   * Semantic errors depend on symbols and scopes, where the parser does not construct.
+   * This adds a small performance overhead.
+   *
+   * @default false
    */
-  convertSpanUtf16?: boolean
+  showSemanticErrors?: boolean
 }
 
 /** Parse synchronously. */
 export declare function parseSync(filename: string, sourceText: string, options?: ParserOptions | undefined | null): ParseResult
 
-/**
- * Parse without returning anything.
- *
- * This is for benchmark purposes such as measuring napi communication overhead.
- */
-export declare function parseWithoutReturn(filename: string, sourceText: string, options?: ParserOptions | undefined | null): void
-
 export declare const enum Severity {
   Error = 'Error',
   Warning = 'Warning',
   Advice = 'Advice'
 }
 
-export interface SourceMap {
-  file?: string
-  mappings: string
-  names: Array<string>
-  sourceRoot?: string
-  sources: Array<string>
-  sourcesContent?: Array<string>
-  version: number
-  x_google_ignoreList?: Array<number>
-}
-
-export interface SourceMapOptions {
-  includeContent?: boolean
-  source?: string
-  hires?: boolean
-}
-
 export interface Span {
   start: number
   end: number

package/index.js

@@ -9,7 +9,7 @@ module.exports.parseWithoutReturn = bindings.parseWithoutReturn;
 module.exports.Severity = bindings.Severity;
 
 function wrap(result) {
-  let program, module, comments, errors, magicString;
+  let program, module, comments, errors;
   return {
     get program() {
       if (!program) {
@@ -48,17 +48,6 @@ function wrap(result) {
       if (!errors) errors = result.errors;
       return errors;
     },
-    get magicString() {
-      if (!magicString) magicString = result.magicString;
-      magicString.generateMap = function generateMap(options) {
-        return {
-          toString: () => magicString.toSourcemapString(options),
-          toUrl: () => magicString.toSourcemapUrl(options),
-          toMap: () => magicString.toSourcemapObject(options),
-        };
-      };
-      return magicString;
-    },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxc-parser",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Oxc Parser Node API",
   "keywords": [
     "Parser"
@@ -24,16 +24,16 @@
     "bindings.js"
   ],
   "dependencies": {
-    "@oxc-project/types": "^0.52.0"
+    "@oxc-project/types": "^0.54.0"
   },
   "optionalDependencies": {
-    "@oxc-parser/binding-win32-x64-msvc": "0.52.0",
-    "@oxc-parser/binding-win32-arm64-msvc": "0.52.0",
-    "@oxc-parser/binding-linux-x64-gnu": "0.52.0",
-    "@oxc-parser/binding-linux-arm64-gnu": "0.52.0",
-    "@oxc-parser/binding-linux-x64-musl": "0.52.0",
-    "@oxc-parser/binding-linux-arm64-musl": "0.52.0",
-    "@oxc-parser/binding-darwin-x64": "0.52.0",
-    "@oxc-parser/binding-darwin-arm64": "0.52.0"
+    "@oxc-parser/binding-win32-x64-msvc": "0.54.0",
+    "@oxc-parser/binding-win32-arm64-msvc": "0.54.0",
+    "@oxc-parser/binding-linux-x64-gnu": "0.54.0",
+    "@oxc-parser/binding-linux-arm64-gnu": "0.54.0",
+    "@oxc-parser/binding-linux-x64-musl": "0.54.0",
+    "@oxc-parser/binding-linux-arm64-musl": "0.54.0",
+    "@oxc-parser/binding-darwin-x64": "0.54.0",
+    "@oxc-parser/binding-darwin-arm64": "0.54.0"
   }
 }