oxc-parser 0.53.0 → 0.55.0

package/README.md

@@ -2,20 +2,90 @@
 
 ## Features
 
-- Returns ESM information.
+### ESTree
 
-## Caveat
+The returned JavaScript AST follows the [ESTree](https://github.com/estree/estree) specification.
 
-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.
+It is fully aligned with Acorn's AST, and any deviation would be considered a bug.
 
-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.
+The returned TypeScript AST will conform to (`@typescript-eslint/typescript-estree`)[https://www.npmjs.com/package/@typescript-eslint/typescript-estree] in the near future.
+
+### 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.
+
+### ESTree compatibility
+
+When parsing JS or JSX files, the AST returned is fully conformant with the
+[ESTree standard](https://github.com/estree/estree).
+
+When parsing TS or TSX files, the AST has additional properties related to TypeScript syntax.
+These extra properties are broadly (but not entirely) in line with
+[TypeScript ESLint](https://typescript-eslint.io/packages/parser/)'s AST.
+
+If you need all ASTs in the same with-TS-properties format, use the `astType: 'ts'` option.
+
+### 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';
+import oxc from 'oxc-parser';
 
 const code = 'const url: String = /* 🤨 */ import.meta.url;';
 

package/bindings.js

@@ -374,8 +374,9 @@ module.exports.ParseResult = nativeBinding.ParseResult
 module.exports.ExportExportNameKind = nativeBinding.ExportExportNameKind
 module.exports.ExportImportNameKind = nativeBinding.ExportImportNameKind
 module.exports.ExportLocalNameKind = nativeBinding.ExportLocalNameKind
+module.exports.getBufferOffset = nativeBinding.getBufferOffset
 module.exports.ImportNameKind = nativeBinding.ImportNameKind
 module.exports.parseAsync = nativeBinding.parseAsync
 module.exports.parseSync = nativeBinding.parseSync
-module.exports.parseWithoutReturn = nativeBinding.parseWithoutReturn
+module.exports.parseSyncRaw = nativeBinding.parseSyncRaw
 module.exports.Severity = nativeBinding.Severity

package/index.d.ts

@@ -100,6 +100,14 @@ export declare const enum ExportLocalNameKind {
   None = 'None'
 }
 
+/**
+ * Get offset within a `Uint8Array` which is aligned on 4 GiB.
+ *
+ * Does not check that the offset is within bounds of `buffer`.
+ * To ensure it always is, provide a `Uint8Array` of at least 4 GiB size.
+ */
+export declare function getBufferOffset(buffer: Uint8Array): number
+
 export interface ImportName {
   kind: ImportNameKind
   name?: string
@@ -134,6 +142,14 @@ export interface ParserOptions {
   sourceType?: 'script' | 'module' | 'unambiguous' | undefined
   /** Treat the source text as `js`, `jsx`, `ts`, or `tsx`. */
   lang?: 'js' | 'jsx' | 'ts' | 'tsx'
+  /**
+   * Return an AST which includes TypeScript-related properties, or excludes them.
+   *
+   * `'js'` is default for JS / JSX files.
+   * `'ts'` is default for TS / TSX files.
+   * The type of the file is determined from `lang` option, or extension of provided `filename`.
+   */
+  astType?: 'js' | 'ts'
   /**
    * Emit `ParenthesizedExpression` in AST.
    *
@@ -141,20 +157,49 @@ export interface ParserOptions {
    * (non-standard) `ParenthesizedExpression` nodes that have a single `expression` property
    * containing the expression inside parentheses.
    *
-   * Default: true
+   * @default true
    */
   preserveParens?: boolean
+  /**
+   * 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
+   */
+  showSemanticErrors?: boolean
 }
 
 /** Parse synchronously. */
 export declare function parseSync(filename: string, sourceText: string, options?: ParserOptions | undefined | null): ParseResult
 
 /**
- * Parse without returning anything.
+ * Parses AST into provided `Uint8Array` buffer.
+ *
+ * Source text must be written into the start of the buffer, and its length (in UTF-8 bytes)
+ * provided as `source_len`.
+ *
+ * This function will parse the source, and write the AST into the buffer, starting at the end.
+ *
+ * It also writes to the very end of the buffer the offset of `Program` within the buffer.
+ *
+ * Caller can deserialize data from the buffer on JS side.
+ *
+ * # SAFETY
+ *
+ * Caller must ensure:
+ * * Source text is written into start of the buffer.
+ * * Source text's UTF-8 byte length is `source_len`.
+ * * The 1st `source_len` bytes of the buffer comprises a valid UTF-8 string.
+ *
+ * If source text is originally a JS string on JS side, and converted to a buffer with
+ * `Buffer.from(str)` or `new TextEncoder().encode(str)`, this guarantees it's valid UTF-8.
+ *
+ * # Panics
  *
- * This is for benchmark purposes such as measuring napi communication overhead.
+ * Panics if source text is too long, or AST takes more memory than is available in the buffer.
  */
-export declare function parseWithoutReturn(filename: string, sourceText: string, options?: ParserOptions | undefined | null): void
+export declare function parseSyncRaw(filename: string, buffer: Uint8Array, sourceLen: number, options?: ParserOptions | undefined | null): void
 
 export declare const enum Severity {
   Error = 'Error',

package/index.js

@@ -1,4 +1,6 @@
 const bindings = require('./bindings.js');
+const deserializeJS = require('./deserialize-js.js');
+const deserializeTS = require('./deserialize-ts.js');
 
 module.exports.ParseResult = bindings.ParseResult;
 module.exports.ExportExportNameKind = bindings.ExportExportNameKind;
@@ -55,6 +57,84 @@ module.exports.parseAsync = async function parseAsync(...args) {
   return wrap(await bindings.parseAsync(...args));
 };
 
-module.exports.parseSync = function parseSync(...args) {
-  return wrap(bindings.parseSync(...args));
+module.exports.parseSync = function parseSync(filename, sourceText, options) {
+  if (options?.experimentalRawTransfer) {
+    return parseSyncRaw(filename, sourceText, options);
+  }
+
+  return wrap(bindings.parseSync(filename, sourceText, options));
 };
+
+let buffer, encoder;
+
+function parseSyncRaw(filename, sourceText, options) {
+  // Delete `experimentalRawTransfer` option
+  let experimentalRawTransfer;
+  ({ experimentalRawTransfer, ...options } = options);
+
+  // Create buffer and `TextEncoder`
+  if (!buffer) {
+    buffer = createBuffer();
+    encoder = new TextEncoder();
+  }
+
+  // Write source into start of buffer.
+  // `TextEncoder` cannot write into a `Uint8Array` larger than 1 GiB,
+  // so create a view into buffer of this size to write into.
+  const sourceBuffer = new Uint8Array(buffer.buffer, buffer.byteOffset, ONE_GIB);
+  const { read, written: sourceByteLen } = encoder.encodeInto(sourceText, sourceBuffer);
+  if (read !== sourceText.length) {
+    throw new Error('Failed to write source text into buffer');
+  }
+
+  // Parse
+  bindings.parseSyncRaw(filename, buffer, sourceByteLen, options);
+
+  // Deserialize.
+  // We cannot lazily deserialize in the getters, because the buffer might be re-used to parse
+  // another file before the getter is called.
+
+  // (2 * 1024 * 1024 * 1024 - 12)
+  const astTypeFlagPos = 2147483636;
+  let isJsAst = buffer[astTypeFlagPos] === 0;
+
+  const data = isJsAst
+    ? deserializeJS(buffer, sourceText, sourceByteLen)
+    : deserializeTS(buffer, sourceText, sourceByteLen);
+
+  return {
+    get program() {
+      return data.program;
+    },
+    get module() {
+      return data.module;
+    },
+    get comments() {
+      return data.comments;
+    },
+    get errors() {
+      return data.errors;
+    },
+  };
+}
+
+const ONE_GIB = 1 << 30,
+  TWO_GIB = ONE_GIB * 2,
+  SIX_GIB = ONE_GIB * 6;
+
+// Create a `Uint8Array` which is 2 GiB in size, with its start aligned on 4 GiB.
+//
+// Achieve this by creating a 6 GiB `ArrayBuffer`, getting the offset within it that's aligned to 4 GiB,
+// chopping off that number of bytes from the start, and shortening to 2 GiB.
+//
+// It's always possible to obtain a 2 GiB slice aligned on 4 GiB within a 6 GiB buffer,
+// no matter how the 6 GiB buffer is aligned.
+//
+// Note: On systems with virtual memory, this only consumes 6 GiB of *virtual* memory.
+// It does not consume physical memory until data is actually written to the `Uint8Array`.
+// Physical memory consumed corresponds to the quantity of data actually written.
+function createBuffer() {
+  const arrayBuffer = new ArrayBuffer(SIX_GIB);
+  const offset = bindings.getBufferOffset(new Uint8Array(arrayBuffer));
+  return new Uint8Array(arrayBuffer, offset, TWO_GIB);
+}

package/package.json

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