oxc-parser 0.38.0 → 0.40.0

package/README.md

@@ -1,21 +1,51 @@
-# The JavaScript Oxidation Compiler
+# Oxc Parser
 
-See `index.d.ts` for `parseSync` and `parseAsync` API.
+## 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.
+
+## Caveat
+
+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.
+
+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.
+
+## API
 
 ```javascript
-import assert from 'assert';
-import oxc from 'oxc-parser';
+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.
+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);
 
-const sourceText = "let foo: Foo = 'foo';";
-// Filename extension is used to determine which
-// dialect to parse source as
-const options = { sourceFilename: 'text.tsx' };
+// ESM information - imports, exports, `import.meta`s.
+console.log(result.module);
 
-test(oxc.parseSync(sourceText, options));
-test(await oxc.parseAsync(sourceText, options));
+// 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;
 
-function test(ret) {
-  assert(ret.program.body.length == 1);
-  assert(ret.errors.length == 0);
+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

@@ -361,8 +361,13 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-module.exports.moduleLexerAsync = nativeBinding.moduleLexerAsync
-module.exports.moduleLexerSync = nativeBinding.moduleLexerSync
+module.exports.MagicString = nativeBinding.MagicString
+module.exports.ParseResult = nativeBinding.ParseResult
+module.exports.ExportExportNameKind = nativeBinding.ExportExportNameKind
+module.exports.ExportImportNameKind = nativeBinding.ExportImportNameKind
+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,6 +2,34 @@
 /* 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
+  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
+}
+
+export declare class ParseResult {
+  get program(): import("@oxc-project/types").Program
+  get module(): EcmaScriptModule
+  get comments(): Array<Comment>
+  get errors(): Array<Error>
+  get magicString(): MagicString
+}
+
 export interface Comment {
   type: 'Line' | 'Block'
   value: string
@@ -9,104 +37,125 @@ export interface Comment {
   end: number
 }
 
-export interface ModuleLexer {
-  imports: Array<ModuleLexerImportSpecifier>
-  exports: Array<ModuleLexerExportSpecifier>
+export interface EcmaScriptModule {
   /**
-   * ESM syntax detection
+   * Has ESM syntax.
+   *
+   * i.e. `import` and `export` statements, and `import.meta`.
    *
-   * The use of ESM syntax: import / export statements and `import.meta`
+   * Dynamic imports `import('foo')` are ignored since they can be used in non-ESM files.
    */
   hasModuleSyntax: boolean
-  /** Facade modules that only use import / export syntax */
-  facade: boolean
+  /** Import Statements. */
+  staticImports: Array<StaticImport>
+  /** Export Statements. */
+  staticExports: Array<StaticExport>
+  /** Span positions` of `import.meta` */
+  importMetas: Array<Span>
 }
 
-/**
- * # Panics
- *
- * * Tokio crashes
- */
-export declare function moduleLexerAsync(sourceText: string, options?: ParserOptions | undefined | null): Promise<ModuleLexer>
-
-export interface ModuleLexerExportSpecifier {
-  /** Exported name */
-  n: string
-  /** Local name, or undefined. */
-  ln?: string
-  /** Start of exported name */
-  s: number
-  /** End of exported name */
-  e: number
-  /** Start of local name */
-  ls?: number
-  /** End of local name */
-  le?: number
-}
-
-export interface ModuleLexerImportSpecifier {
-  /**
-   * Module name
-   *
-   * To handle escape sequences in specifier strings, the .n field of imported specifiers will be provided where possible.
-   *
-   * For dynamic import expressions, this field will be empty if not a valid JS string.
-   */
-  n?: string
-  /** Start of module specifier */
-  s: number
-  /** End of module specifier */
-  e: number
-  /** Start of import statement */
-  ss: number
-  /** End of import statement */
-  se: number
-  /**
-   * Import Type
-   * * If this import keyword is a dynamic import, this is the start value.
-   * * If this import keyword is a static import, this is -1.
-   * * If this import keyword is an import.meta expression, this is -2.
-   * * If this import is an `export *`, this is -3.
-   */
-  d: number
+export interface Error {
+  severity: Severity
+  message: string
+  labels: Array<ErrorLabel>
+  helpMessage?: string
+}
+
+export interface ErrorLabel {
+  message?: string
+  start: number
+  end: number
+}
+
+export interface ExportExportName {
+  kind: ExportExportNameKind
+  name?: string
+  start?: number
+  end?: number
+}
+
+export declare const enum ExportExportNameKind {
+  /** `export { name } */
+  Name = 'Name',
+  /** `export default expression` */
+  Default = 'Default',
+  /** `export * from "mod" */
+  None = 'None'
+}
+
+export interface ExportImportName {
+  kind: ExportImportNameKind
+  name?: string
+  start?: number
+  end?: number
+}
+
+export declare const enum ExportImportNameKind {
+  /** `export { name } */
+  Name = 'Name',
+  /** `export * as ns from "mod"` */
+  All = 'All',
+  /** `export * from "mod"` */
+  AllButDefault = 'AllButDefault',
+  /** Does not have a specifier. */
+  None = 'None'
+}
+
+export interface ExportLocalName {
+  kind: ExportLocalNameKind
+  name?: string
+  start?: number
+  end?: number
+}
+
+export declare const enum ExportLocalNameKind {
+  /** `export { name } */
+  Name = 'Name',
+  /** `export default expression` */
+  Default = 'Default',
   /**
-   * If this import has an import assertion, this is the start value
-   * Otherwise this is `-1`.
+   * If the exported value is not locally accessible from within the module.
+   * `export default function () {}`
    */
-  a: number
+  None = 'None'
 }
 
-/**
- * Outputs the list of exports and locations of import specifiers,
- * including dynamic import and import meta handling.
- *
- * # Panics
- *
- * * File extension is invalid
- */
-export declare function moduleLexerSync(sourceText: string, options?: ParserOptions | undefined | null): ModuleLexer
+export interface ImportName {
+  kind: ImportNameKind
+  name?: string
+  start?: number
+  end?: number
+}
 
-/**
- * # Panics
- *
- * * Tokio crashes
- */
-export declare function parseAsync(sourceText: string, options?: ParserOptions | undefined | null): Promise<ParseResult>
+export declare const enum ImportNameKind {
+  /** `import { x } from "mod"` */
+  Name = 'Name',
+  /** `import * as ns from "mod"` */
+  NamespaceObject = 'NamespaceObject',
+  /** `import defaultExport from "mod"` */
+  Default = 'Default'
+}
 
-export interface ParseResult {
-  program: import("@oxc-project/types").Program
-  comments: Array<Comment>
-  errors: Array<string>
+export interface LineColumn {
+  line: number
+  column: number
+}
+
+export interface OverwriteOptions {
+  contentOnly: boolean
 }
 
 /**
- * Babel Parser Options
+ * Parse asynchronously.
  *
- * <https://github.com/babel/babel/blob/v7.26.2/packages/babel-parser/typings/babel-parser.d.ts>
+ * Note: This function can be slower than `parseSync` due to the overhead of spawning a thread.
  */
+export declare function parseAsync(filename: string, sourceText: string, options?: ParserOptions | undefined | null): Promise<ParseResult>
+
 export interface ParserOptions {
   sourceType?: 'script' | 'module' | 'unambiguous' | undefined
-  sourceFilename?: string
+  /** Treat the source text as `js`, `jsx`, `ts`, or `tsx`. */
+  lang?: 'js' | 'jsx' | 'ts' | 'tsx'
   /**
    * Emit `ParenthesizedExpression` in AST.
    *
@@ -119,22 +168,110 @@ export interface ParserOptions {
   preserveParens?: boolean
 }
 
-/**
- * # Panics
- *
- * * File extension is invalid
- * * Serde JSON serialization
- */
-export declare function parseSync(sourceText: string, options?: ParserOptions | undefined | null): ParseResult
+/** 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.
- *
- * # Panics
  *
- * * File extension is invalid
- * * Serde JSON serialization
+ * This is for benchmark purposes such as measuring napi communication overhead.
  */
-export declare function parseWithoutReturn(sourceText: string, options?: ParserOptions | undefined | null): void
+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 SourceMapOptions {
+  includeContent?: boolean
+  source?: string
+  hires?: boolean
+}
+
+export interface Span {
+  start: number
+  end: number
+}
+
+export interface StaticExport {
+  start: number
+  end: number
+  entries: Array<StaticExportEntry>
+}
+
+export interface StaticExportEntry {
+  start: number
+  end: number
+  moduleRequest?: ValueSpan
+  /** The name under which the desired binding is exported by the module`. */
+  importName: ExportImportName
+  /** The name used to export this binding by this module. */
+  exportName: ExportExportName
+  /** The name that is used to locally access the exported value from within the importing module. */
+  localName: ExportLocalName
+}
+
+export interface StaticImport {
+  /** Start of import statement. */
+  start: number
+  /** End of import statement. */
+  end: number
+  /**
+   * Import source.
+   *
+   * ```js
+   * import { foo } from "mod";
+   * //                   ^^^
+   * ```
+   */
+  moduleRequest: ValueSpan
+  /**
+   * Import specifiers.
+   *
+   * Empty for `import "mod"`.
+   */
+  entries: Array<StaticImportEntry>
+}
+
+export interface StaticImportEntry {
+  /**
+   * The name under which the desired binding is exported by the module.
+   *
+   * ```js
+   * import { foo } from "mod";
+   * //       ^^^
+   * import { foo as bar } from "mod";
+   * //       ^^^
+   * ```
+   */
+  importName: ImportName
+  /**
+   * The name that is used to locally access the imported value from within the importing module.
+   * ```js
+   * import { foo } from "mod";
+   * //       ^^^
+   * import { foo as bar } from "mod";
+   * //              ^^^
+   * ```
+   */
+  localName: ValueSpan
+  /**
+   * Whether this binding is for a TypeScript type-only import.
+   *
+   * `true` for the following imports:
+   * ```ts
+   * import type { foo } from "mod";
+   * import { type foo } from "mod";
+   * ```
+   */
+  isType: boolean
+}
+
+export interface ValueSpan {
+  value: string
+  start: number
+  end: number
+}
 

package/index.js

@@ -1,16 +1,44 @@
 const bindings = require('./bindings.js');
 
-module.exports.moduleLexerAsync = bindings.moduleLexerAsync;
-module.exports.moduleLexerSync = bindings.moduleLexerSync;
+module.exports.MagicString = bindings.MagicString;
+module.exports.ParseResult = bindings.ParseResult;
+module.exports.ExportExportNameKind = bindings.ExportExportNameKind;
+module.exports.ExportImportNameKind = bindings.ExportImportNameKind;
+module.exports.ExportLocalNameKind = bindings.ExportLocalNameKind;
+module.exports.ImportNameKind = bindings.ImportNameKind;
 module.exports.parseWithoutReturn = bindings.parseWithoutReturn;
+module.exports.Severity = bindings.Severity;
+
+function wrap(result) {
+  let program, module, comments, errors, magicString;
+  return {
+    get program() {
+      if (!program) program = JSON.parse(result.program);
+      return program;
+    },
+    get module() {
+      if (!module) module = result.module;
+      return module;
+    },
+    get comments() {
+      if (!comments) comments = result.comments;
+      return comments;
+    },
+    get errors() {
+      if (!errors) errors = result.errors;
+      return errors;
+    },
+    get magicString() {
+      if (!magicString) magicString = result.magicString;
+      return magicString;
+    },
+  };
+}
 
 module.exports.parseAsync = async function parseAsync(...args) {
-  const result = await bindings.parseAsync(...args);
-  result.program = JSON.parse(result.program);
-  return result;
+  return wrap(await bindings.parseAsync(...args));
 };
+
 module.exports.parseSync = function parseSync(...args) {
-  const result = bindings.parseSync(...args);
-  result.program = JSON.parse(result.program);
-  return result;
+  return wrap(bindings.parseSync(...args));
 };

package/package.json

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