oxc-parser 0.73.2 → 0.74.0

package/raw-transfer/lazy.js

@@ -1,14 +1,74 @@
 'use strict';
 
-const { parseSyncRawImpl, parseAsyncRawImpl, returnBufferToCache } = require('./index.js');
+const { parseSyncRawImpl, parseAsyncRawImpl, returnBufferToCache } = require('./common.js'),
+  { TOKEN } = require('./lazy-common.js'),
+  constructLazyData = require('../generated/deserialize/lazy.js').construct,
+  walkProgram = require('../generated/deserialize/lazy-visit.js'),
+  { Visitor, getVisitorsArr } = require('./visitor.js');
 
-module.exports = { parseSyncLazy, parseAsyncLazy };
+module.exports = { parseSyncLazy, parseAsyncLazy, Visitor };
 
+/**
+ * Parse JS/TS source synchronously on current thread.
+ *
+ * The data in buffer is not deserialized. Is deserialized to JS objects lazily, when accessing the
+ * properties of objects.
+ *
+ * e.g. `program` in returned object is an instance of `Program` class, with getters for `start`, `end`,
+ * `body` etc.
+ *
+ * Returned object contains a `visit` function which can be used to visit the AST with a `Visitor`
+ * (`Visitor` class can be obtained by calling `experimentalGetLazyVisitor()`).
+ *
+ * Returned object contains a `dispose` method. When finished with this AST, it's advisable to call
+ * `dispose`, to return the buffer to the cache, so it can be reused.
+ * Garbage collector should do this anyway at some point, but on an unpredictable schedule,
+ * so it's preferable to call `dispose` manually, to ensure the buffer can be reused immediately.
+ *
+ * @param {string} filename - Filename
+ * @param {string} sourceText - Source text of file
+ * @param {Object} options - Parsing options
+ * @returns {Object} - Object with property getters for `program`, `module`, `comments`, and `errors`,
+ *   and `dispose` and `visit` methods
+ * @throws {Error} - If raw transfer is not supported on this platform
+ */
 function parseSyncLazy(filename, sourceText, options) {
+  let _;
+  ({ experimentalLazy: _, ...options } = options);
   return parseSyncRawImpl(filename, sourceText, options, construct);
 }
 
+/**
+ * Parse JS/TS source asynchronously on a separate thread.
+ *
+ * The data in buffer is not deserialized. Is deserialized to JS objects lazily, when accessing the
+ * properties of objects.
+ *
+ * e.g. `program` in returned object is an instance of `Program` class, with getters for `start`, `end`,
+ * `body` etc.
+ *
+ * Because this function does not deserialize the AST, unlike `parseAsyncRaw`, very little work happens
+ * on current thread in this function. Deserialization work only occurs when properties of the objects
+ * are accessed.
+ *
+ * Returned object contains a `visit` function which can be used to visit the AST with a `Visitor`
+ * (`Visitor` class can be obtained by calling `experimentalGetLazyVisitor()`).
+ *
+ * Returned object contains a `dispose` method. When finished with this AST, it's advisable to call
+ * `dispose`, to return the buffer to the cache, so it can be reused.
+ * Garbage collector should do this anyway at some point, but on an unpredictable schedule,
+ * so it's preferable to call `dispose` manually, to ensure the buffer can be reused immediately.
+ *
+ * @param {string} filename - Filename
+ * @param {string} sourceText - Source text of file
+ * @param {Object} options - Parsing options
+ * @returns {Object} - Object with property getters for `program`, `module`, `comments`, and `errors`,
+ *   and `dispose` and `visit` methods
+ * @throws {Error} - If raw transfer is not supported on this platform
+ */
 function parseAsyncLazy(filename, sourceText, options) {
+  let _;
+  ({ experimentalLazy: _, ...options } = options);
   return parseAsyncRawImpl(filename, sourceText, options, construct);
 }
 
@@ -23,15 +83,18 @@ const bufferRecycleRegistry = typeof FinalizationRegistry === 'undefined'
   ? null
   : new FinalizationRegistry(returnBufferToCache);
 
-let constructLazyData = null, TOKEN;
-
-// Get an object with getters which lazy deserialize AST from buffer
+/**
+ * Get an object with getters which lazy deserialize AST and other data from buffer.
+ *
+ * Object also includes `dispose` and `visit` functions.
+ *
+ * @param {Uint8Array} buffer - Buffer containing AST in raw form
+ * @param {string} sourceText - Source for the file
+ * @param {number} sourceByteLen - Length of source text in UTF-8 bytes
+ * @returns {Object} - Object with property getters for `program`, `module`, `comments`, and `errors`,
+ *   and `dispose` and `visit` methods
+ */
 function construct(buffer, sourceText, sourceLen) {
-  // Lazy load deserializer, and get `TOKEN` to store in `ast` objects
-  if (constructLazyData === null) {
-    ({ construct: constructLazyData, TOKEN } = require('../generated/deserialize/lazy.js'));
-  }
-
   // Create AST object
   const sourceIsAscii = sourceText.length === sourceLen;
   const ast = { buffer, sourceText, sourceLen, sourceIsAscii, nodes: new Map(), token: TOKEN };
@@ -57,21 +120,32 @@ function construct(buffer, sourceText, sourceLen) {
       return data.errors;
     },
     dispose: dispose.bind(null, ast),
+    visit(visitor) {
+      // (2 * 1024 * 1024 * 1024 - 16) >> 2
+      const metadataPos32 = 536870908;
+      const pos = buffer.uint32[metadataPos32];
+      walkProgram(pos, ast, getVisitorsArr(visitor));
+    },
   };
 }
 
-// Dispose of this AST.
-//
-// After calling this method, trying to read any nodes from this AST may cause an error.
-//
-// Buffer is returned to the cache to be reused.
-//
-// The buffer would be returned to the cache anyway, once all nodes of the AST are garbage collected,
-// but calling `dispose` is preferable, as it will happen immediately.
-// Otherwise, garbage collector may take time to collect the `ast` object, and new buffers may be created
-// in the meantime, when we could have reused this one.
+/**
+ * Dispose of this AST.
+ *
+ * After calling this method, trying to read any nodes from this AST may cause an error.
+ *
+ * Buffer is returned to the cache to be reused.
+ *
+ * The buffer would be returned to the cache anyway, once all nodes of the AST are garbage collected,
+ * but calling `dispose` is preferable, as it will happen immediately.
+ * Otherwise, garbage collector may take time to collect the `ast` object, and new buffers may be created
+ * in the meantime, when we could have reused this one.
+ *
+ * @param {Object} ast - AST object containing buffer etc
+ * @returns {undefined}
+ */
 function dispose(ast) {
-  // Return buffer to cache to be reused
+  // Return buffer to cache, to be reused
   returnBufferToCache(ast.buffer);
 
   // Remove connection between `ast` and the buffer

package/raw-transfer/node-array.js

@@ -12,12 +12,14 @@ const nodeArrays = new WeakMap();
 // Function to get element from an array. Initialized in class static block below.
 let getElement;
 
-// An array of AST nodes where elements are deserialized lazily upon access.
-//
-// Extends `Array` to make `Array.isArray` return `true` for a `NodeArray`.
-//
-// TODO: Other methods could maybe be more optimal, avoiding going via proxy multiple times
-// e.g. `some`, `indexOf`.
+/**
+ * An array of AST nodes where elements are deserialized lazily upon access.
+ *
+ * Extends `Array` to make `Array.isArray` return `true` for a `NodeArray`.
+ *
+ * TODO: Other methods could maybe be more optimal, avoiding going via proxy multiple times
+ * e.g. `some`, `indexOf`.
+ */
 class NodeArray extends Array {
   #internal;
 
@@ -80,7 +82,14 @@ class NodeArray extends Array {
   // Defining dummy method here to prevent the later assignment altering the shape of class prototype.
   [Symbol.iterator]() {}
 
-  // Override `slice` method to return a `NodeArray`.
+  /**
+   * Override `slice` method to return a `NodeArray`.
+   *
+   * @this {NodeArray}
+   * @param {*} start - Start of slice
+   * @param {*} end - End of slice
+   * @returns {NodeArray} - `NodeArray` containing slice of this one
+   */
   slice(start, end) {
     // Get actual `NodeArray`. `this` is a proxy.
     const arr = nodeArrays.get(this);
@@ -142,8 +151,10 @@ NodeArray.prototype[Symbol.iterator] = NodeArray.prototype.values;
 
 module.exports = NodeArray;
 
-// Iterator over values of a `NodeArray`.
-// Returned by `values` method, and also used as iterator for `for (const node of nodeArray) {}`.
+/**
+ * Iterator over values of a `NodeArray`.
+ * Returned by `values` method, and also used as iterator for `for (const node of nodeArray) {}`.
+ */
 class NodeArrayValuesIterator {
   #internal;
 
@@ -173,7 +184,9 @@ class NodeArrayValuesIterator {
   }
 }
 
-// Iterator over keys of a `NodeArray`. Returned by `keys` method.
+/**
+ * Iterator over keys of a `NodeArray`. Returned by `keys` method.
+ */
 class NodeArrayKeysIterator {
   #internal;
 
@@ -196,7 +209,9 @@ class NodeArrayKeysIterator {
   }
 }
 
-// Iterator over values of a `NodeArray`. Returned by `entries` method.
+/**
+ * Iterator over values of a `NodeArray`. Returned by `entries` method.
+ */
 class NodeArrayEntriesIterator {
   #internal;
 

package/raw-transfer/supported.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const rawTransferSupportedBinding = require('../bindings.js').rawTransferSupported;
+
+module.exports = rawTransferSupported;
+
+let rawTransferIsSupported = null;
+
+/**
+ * Returns `true` if `experimentalRawTransfer` is option is supported.
+ *
+ * Raw transfer is only supported on 64-bit little-endian systems,
+ * and NodeJS >= v22.0.0 or Deno >= v2.0.0.
+ *
+ * Versions of NodeJS prior to v22.0.0 do not support creating an `ArrayBuffer` larger than 4 GiB.
+ * Bun (as at v1.2.4) also does not support creating an `ArrayBuffer` larger than 4 GiB.
+ * Support on Deno v1 is unknown and it's EOL, so treating Deno before v2.0.0 as unsupported.
+ *
+ * No easy way to determining pointer width (64 bit or 32 bit) in JS,
+ * so call a function on Rust side to find out.
+ *
+ * @returns {boolean} - `true` if raw transfer is supported on this platform
+ */
+function rawTransferSupported() {
+  if (rawTransferIsSupported === null) {
+    rawTransferIsSupported = rawTransferRuntimeSupported() && rawTransferSupportedBinding();
+  }
+  return rawTransferIsSupported;
+}
+
+// Checks copied from:
+// https://github.com/unjs/std-env/blob/ab15595debec9e9115a9c1d31bc7597a8e71dbfd/src/runtimes.ts
+// MIT license: https://github.com/unjs/std-env/blob/ab15595debec9e9115a9c1d31bc7597a8e71dbfd/LICENCE
+function rawTransferRuntimeSupported() {
+  let global;
+  try {
+    global = globalThis;
+  } catch (e) {
+    return false;
+  }
+
+  const isBun = !!global.Bun || !!global.process?.versions?.bun;
+  if (isBun) return false;
+
+  const isDeno = !!global.Deno;
+  if (isDeno) {
+    const match = Deno.version?.deno?.match(/^(\d+)\./);
+    return !!match && match[1] * 1 >= 2;
+  }
+
+  const isNode = global.process?.release?.name === 'node';
+  if (!isNode) return false;
+
+  const match = process.version?.match(/^v(\d+)\./);
+  return !!match && match[1] * 1 >= 22;
+}

package/raw-transfer/visitor.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const { NODE_TYPE_IDS_MAP, LEAF_NODES_COUNT } = require('../generated/deserialize/lazy-types.js');
+
+const NODE_TYPES_COUNT = NODE_TYPE_IDS_MAP.size;
+
+// Getter for private `#visitorsArr` property of `Visitor` class. Initialized in class body below.
+let getVisitorsArr;
+
+/**
+ * Visitor class, used to visit an AST.
+ */
+class Visitor {
+  #visitorsArr;
+
+  /**
+   * Create `Visitor`.
+   *
+   * Provide an object where keys are names of AST nodes you want to visit,
+   * and values are visitor functions which receive AST node objects of that type.
+   *
+   * Keys can also be postfixed with `:exit` to visit when exiting the node, rather than entering.
+   *
+   * ```js
+   * const visitor = new Visitor({
+   *     BinaryExpression(binExpr) {
+   *         // Do stuff when entering a `BinaryExpression`
+   *     },
+   *     'BinaryExpression:exit'(binExpr) {
+   *         // Do stuff when exiting a `BinaryExpression`
+   *     },
+   * });
+   * ```
+   *
+   * @constructor
+   * @param {Object} visitor - Object defining visit functions for AST nodes
+   * @returns {Visitor}
+   */
+  constructor(visitor) {
+    this.#visitorsArr = createVisitorsArr(visitor);
+  }
+
+  static {
+    getVisitorsArr = visitor => visitor.#visitorsArr;
+  }
+}
+
+module.exports = { Visitor, getVisitorsArr };
+
+/**
+ * Create array of visitors, keyed by node type ID.
+ *
+ * Each element of array is one of:
+ *
+ * * No visitor for this type = `null`.
+ * * Visitor for leaf node = visit function.
+ * * Visitor for non-leaf node = object of form `{ enter, exit }`,
+ *   where each property is either a visitor function or `null`.
+ *
+ * @param {Object} visitor - Visitors object from user
+ * @returns {Array<Object|function|null>} - Array of visitors
+ */
+function createVisitorsArr(visitor) {
+  if (visitor === null || typeof visitor !== 'object') {
+    throw new Error('`visitors` must be an object');
+  }
+
+  // Create empty visitors array
+  const visitorsArr = [];
+  for (let i = 0; i < NODE_TYPES_COUNT; i++) {
+    visitorsArr.push(null);
+  }
+
+  // Populate visitors array from provided object
+  for (let name of Object.keys(visitor)) {
+    const visitFn = visitor[name];
+    if (typeof visitFn !== 'function') {
+      throw new Error(`'${name}' property of \`visitors\` object is not a function`);
+    }
+
+    const isExit = name.endsWith(':exit');
+    if (isExit) name = name.slice(0, -5);
+
+    const typeId = NODE_TYPE_IDS_MAP.get(name);
+    if (typeId === void 0) throw new Error(`Unknown node type '${name}' in \`visitors\` object`);
+
+    if (typeId < LEAF_NODES_COUNT) {
+      // Leaf node. Store just 1 function.
+      const existingVisitFn = visitorsArr[typeId];
+      if (existingVisitFn === null) {
+        visitorsArr[typeId] = visitFn;
+      } else if (isExit) {
+        visitorsArr[typeId] = combineVisitFunctions(existingVisitFn, visitFn);
+      } else {
+        visitorsArr[typeId] = combineVisitFunctions(visitFn, existingVisitFn);
+      }
+      continue;
+    }
+
+    let enterExit = visitorsArr[typeId];
+    if (enterExit === null) {
+      enterExit = visitorsArr[typeId] = { enter: null, exit: null };
+    }
+
+    if (isExit) {
+      enterExit.exit = visitFn;
+    } else {
+      enterExit.enter = visitFn;
+    }
+  }
+
+  return visitorsArr;
+}
+
+/**
+ * Combine 2 visitor functions into 1.
+ *
+ * @param {function} visit1 - 1st visitor function
+ * @param {function} visit2 - 2nd visitor function
+ * @returns {function} - Combined visitor function
+ */
+function combineVisitFunctions(visit1, visit2) {
+  return function(node) {
+    visit1(node);
+    visit2(node);
+  };
+}