oxc-parser 0.39.0 → 0.40.0

package/README.md

@@ -1,20 +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';
 
-const sourceText = "let foo: Foo = 'foo';";
-// Filename extension is used to determine which dialect to parse source as.
+// 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';
 
-test(oxc.parseSync(filename, sourceText, options));
-test(await oxc.parseAsync(filename, sourceText, options));
+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);
+
+// 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,6 +361,8 @@ 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
 module.exports.ExportLocalNameKind = nativeBinding.ExportLocalNameKind
@@ -368,3 +370,4 @@ 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
@@ -10,10 +38,33 @@ export interface Comment {
 }
 
 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>
+  /** Span positions` of `import.meta` */
+  importMetas: Array<Span>
+}
+
+export interface Error {
+  severity: Severity
+  message: string
+  labels: Array<ErrorLabel>
+  helpMessage?: string
+}
+
+export interface ErrorLabel {
+  message?: string
+  start: number
+  end: number
 }
 
 export interface ExportExportName {
@@ -85,6 +136,15 @@ export declare const enum ImportNameKind {
   Default = 'Default'
 }
 
+export interface LineColumn {
+  line: number
+  column: number
+}
+
+export interface OverwriteOptions {
+  contentOnly: boolean
+}
+
 /**
  * Parse asynchronously.
  *
@@ -92,13 +152,6 @@ export declare const enum ImportNameKind {
  */
 export declare function parseAsync(filename: string, sourceText: string, options?: ParserOptions | undefined | null): Promise<ParseResult>
 
-export interface ParseResult {
-  program: import("@oxc-project/types").Program
-  module: EcmaScriptModule
-  comments: Array<Comment>
-  errors: Array<string>
-}
-
 export interface ParserOptions {
   sourceType?: 'script' | 'module' | 'unambiguous' | undefined
   /** Treat the source text as `js`, `jsx`, `ts`, or `tsx`. */
@@ -125,6 +178,23 @@ export declare function parseSync(filename: string, sourceText: string, options?
  */
 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

package/index.js

@@ -1,14 +1,44 @@
 const bindings = require('./bindings.js');
 
+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.39.0",
+  "version": "0.40.0",
   "description": "Oxc Parser Node API",
   "keywords": [
     "Parser"
@@ -24,16 +24,16 @@
     "bindings.js"
   ],
   "dependencies": {
-    "@oxc-project/types": "^0.39.0"
+    "@oxc-project/types": "^0.40.0"
   },
   "optionalDependencies": {
-    "@oxc-parser/binding-win32-x64-msvc": "0.39.0",
-    "@oxc-parser/binding-win32-arm64-msvc": "0.39.0",
-    "@oxc-parser/binding-linux-x64-gnu": "0.39.0",
-    "@oxc-parser/binding-linux-arm64-gnu": "0.39.0",
-    "@oxc-parser/binding-linux-x64-musl": "0.39.0",
-    "@oxc-parser/binding-linux-arm64-musl": "0.39.0",
-    "@oxc-parser/binding-darwin-x64": "0.39.0",
-    "@oxc-parser/binding-darwin-arm64": "0.39.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"
   }
 }