oxc-parser 0.54.0 → 0.55.0

package/README.md

@@ -2,6 +2,26 @@
 
 ## Features
 
+### ESTree
+
+The returned JavaScript AST follows the [ESTree](https://github.com/estree/estree) specification.
+
+It is fully aligned with Acorn's AST, and any deviation would be considered a bug.
+
+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.
@@ -17,7 +37,20 @@ 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.
+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.
 
@@ -52,7 +85,7 @@ export interface EcmaScriptModule {
 ## API
 
 ```javascript
-import oxc from './index.js';
+import oxc from 'oxc-parser';
 
 const code = 'const url: String = /* 🤨 */ import.meta.url;';
 

package/bindings.js

@@ -374,7 +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.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.
    *
@@ -157,6 +173,34 @@ export interface ParserOptions {
 /** Parse synchronously. */
 export declare function parseSync(filename: string, sourceText: string, options?: ParserOptions | undefined | null): ParseResult
 
+/**
+ * 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
+ *
+ * Panics if source text is too long, or AST takes more memory than is available in the buffer.
+ */
+export declare function parseSyncRaw(filename: string, buffer: Uint8Array, sourceLen: number, options?: ParserOptions | undefined | null): void
+
 export declare const enum Severity {
   Error = 'Error',
   Warning = 'Warning',

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.54.0",
+  "version": "0.55.0",
   "description": "Oxc Parser Node API",
   "keywords": [
     "Parser"
@@ -24,16 +24,16 @@
     "bindings.js"
   ],
   "dependencies": {
-    "@oxc-project/types": "^0.54.0"
+    "@oxc-project/types": "^0.55.0"
   },
   "optionalDependencies": {
-    "@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"
+    "@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"
   }
 }