oxc-parser 0.54.0 → 0.56.0

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,37 @@ 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
+
+/** Returns `true` if raw transfer is supported on this platform. */
+export declare function rawTransferSupported(): boolean
+
 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,99 @@ 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) {
+  if (!rawTransferSupported()) {
+    throw new Error('`experimentalRawTransfer` option is not supported on 32-bit or big-endian systems');
+  }
+
+  // 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);
+}
+
+let rawTransferIsSupported = null;
+
+// Returns `true` if `experimentalRawTransfer` is option is supported.
+// Raw transfer is only available on 64-bit little-endian systems.
+function rawTransferSupported() {
+  if (rawTransferIsSupported === null) rawTransferIsSupported = bindings.rawTransferSupported();
+  return rawTransferIsSupported;
+}
+
+module.exports.rawTransferSupported = rawTransferSupported;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxc-parser",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "Oxc Parser Node API",
   "keywords": [
     "Parser"
@@ -21,19 +21,21 @@
   "files": [
     "index.d.ts",
     "index.js",
-    "bindings.js"
+    "bindings.js",
+    "deserialize-js.js",
+    "deserialize-ts.js"
   ],
   "dependencies": {
-    "@oxc-project/types": "^0.54.0"
+    "@oxc-project/types": "^0.56.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.56.0",
+    "@oxc-parser/binding-win32-arm64-msvc": "0.56.0",
+    "@oxc-parser/binding-linux-x64-gnu": "0.56.0",
+    "@oxc-parser/binding-linux-arm64-gnu": "0.56.0",
+    "@oxc-parser/binding-linux-x64-musl": "0.56.0",
+    "@oxc-parser/binding-linux-arm64-musl": "0.56.0",
+    "@oxc-parser/binding-darwin-x64": "0.56.0",
+    "@oxc-parser/binding-darwin-arm64": "0.56.0"
   }
 }