rewrite orchestrion in javascript by rochdev · Pull Request #41 · nodejs/orchestrion-js

rochdev · 2026-03-10T00:39:12Z

A few features were also carried over from the original iteration of the rewrite:

Supports an astQuery field to filter AST nodes with an esquery query. This
is mostly meant to be used when experimenting or if what needs to be queried
is not a function.
Supports replacing methods of child class instances in the base constructor.
~~Supports tracing iterator (sync/async) returning functions (sync/async)~~ will be added in a future PR

jsumners-nr

I haven't reviewed any of the functionality at this time. Just some maintenance type suggestions.

I'd like to see jsdoc blocks on all functions, classes, and methods. This will reduce the need to follow all paths to understand what shapes parameters are meant to be and clarify intentions.

bizob2828

This is my first pass and didn't get very far because i have a few failures with 2 of our migrated libraries. My biggest comment is why tracing channel api isn't getting used directly to tracePromise, traceCallback, and traceSync. I suspect this nuance is leading to my test failures

bizob2828 · 2026-03-19T16:13:55Z

+  }
+
+  /** Releases all cached transformers, freeing any associated resources. */
+  free () {


do we still need free methods or was this just to ensure the API was consistent with the rust/wasm one?

It's to avoid a breaking change, but they could technically be removed.

We are still at v0.

Yea I think it's safe to remove. The tracing-hooks package can get updated when we up orchestrion to get rid of calling free on the transformer

Can we do the break in another PR? I prefer to isolate breaking changes whenever possible instead of just sneaking them in a huge PR where it's less obvious where the breakage happened.

Yea that's fair

bizob2828 · 2026-03-19T16:42:20Z

+
+    const options = { module: moduleType === 'esm' }
+    const index = node.body.findIndex(child => child.directive === 'use strict')
+    const dcPolyfill = moduleType === 'esm'


why is this called polyfil when you could pass in an alternate dcModule but not always

I guess I figured the point was to allow passing dc-polyfill in the first place, but you're right that it could be anything, I'll rename it.

I would personally probably prefer to add an actual dependency on the polyfill and deprecate this option entirely, it's not as trivial as it looks to pass a module by name depending on how the caller is installed (for example mounted as a Docker volume instead of installed in node_modules) and allowing any name to be passed pushes the logic to figure out the actual install path (and that it can be imported properly in both CJS and ESM) to the caller.

I wouldn't make a dep. We use this package but don't support node 18 so we just rely on the diagnostics channel stdlib

bizob2828 · 2026-03-19T16:56:04Z

+   */
+  #visit (state, ...args) {
+    const transform = this.#customTransforms[state.operator] ?? transforms[state.operator]
+    const { index } = state.functionQuery


we had a loosely defined functionQuery where it was only method name. It turns out there were multiple classes in the same file with the method name. The previous iteration of this worked because it defaulted to the 1st index. now it appears to wrap every method in the file. We can def fix this in our function query but just calling out that this behavior is different now

I'm not a fan of having to explicitly set an option to null when it's a number. I think it's more natural to have it undefined by default, and then any number passed is the value you want. That is a breaking change though, so I will restore the previous behaviour for now and might open another PR if you think that makes sense.

I think defaulting to locating the first makes sense. I worry if this changes we'll have to update function queries to specify the index: 0 for most of the cases. I can't imagine a use case where you want to rewrite the same query multiple times for a file but i could be wrong.

bizob2828

Forgot to submit some comments

bizob2828 · 2026-03-19T20:11:57Z

+   * @param {string} name - Operator name (e.g. `'traceSync'`).
+   * @param {Function} fn - Transform function `(state, node, parent, ancestry) => void`.
+   */
+  addTransform (name, fn) {


this isn't in the rust version. can you explain how to use? Do you think this should be in a follow up?

The main reason I put it right away is because we need it for iterator support. My original PR had the support built-in but since the change in Node core was more contentious than expected I shelved it, so we need a way to be able to add support externally. Open to other suggestions, and we could always continue using our internal implementation for a little while instead but I was hoping to switch back to Orchestrion proper as soon as possible.

bizob2828 · 2026-03-19T20:15:00Z

+          ast = parse(code, { ...options, module: !options.module })
+        }
+
+        if (moduleType === 'esm') { // TODO: cjs


what is there to do for cjs here?

Same as ESM, so for example:

function t () {} module.exports.test = t

With the current code, patching test will not work because it's not able to find t from the test export. This was implemented in Rust for ESM but not for CJS, so I did the same here.

ah ok. Maybe this is a nuance of ESM because you can still wrap t by locating it by functionName

bizob2828 · 2026-03-20T15:23:11Z

+      queries.push(
+        `[id.name="${className}"]`,
+        `[id.name="${className}"] > ClassExpression`,
+        `[id.name="${className}"] > ClassBody > [key.name="${method}"][key.type=${type}] > [async]`,


It's been a while since i've used estree selectors but isn't this only matching methods on classes that are async? I don't see any sync versions of this

All function nodes have an async property, and this only checks for the presence of the property and not its value. It was basically just a hacky way to get the function node without specifying exactly which type since there are multiple.

I'm still unclear. can't it just be omitted?

How to ensure that the child is a function without it?

bizob2828 · 2026-03-20T21:03:43Z

+  }
+
+  /** Releases all cached transformers, freeing any associated resources. */
+  free () {


Yea I think it's safe to remove. The tracing-hooks package can get updated when we up orchestrion to get rid of calling free on the transformer

bizob2828

I verified this works as expected. Thanks for rewriting @rochdev 🙏🏻 . It will be nice to not have such a large binary getting loaded via wasm now.

bizob2828 · 2026-03-24T23:31:49Z

+          ast = parse(code, { ...options, module: !options.module })
+        }
+
+        if (moduleType === 'esm') { // TODO: cjs


ah ok. Maybe this is a nuance of ESM because you can still wrap t by locating it by functionName

bizob2828 · 2026-03-24T23:32:44Z

+      queries.push(
+        `[id.name="${className}"]`,
+        `[id.name="${className}"] > ClassExpression`,
+        `[id.name="${className}"] > ClassBody > [key.name="${method}"][key.type=${type}] > [async]`,


I'm still unclear. can't it just be omitted?

bizob2828 · 2026-03-24T23:37:41Z

+  }
+
+  /** Releases all cached transformers, freeing any associated resources. */
+  free () {


Yea that's fair

bizob2828 · 2026-03-24T23:39:12Z

+
+    const options = { module: moduleType === 'esm' }
+    const index = node.body.findIndex(child => child.directive === 'use strict')
+    const dcPolyfill = moduleType === 'esm'


I wouldn't make a dep. We use this package but don't support node 18 so we just rely on the diagnostics channel stdlib

bizob2828 · 2026-03-24T23:40:34Z

+   */
+  #visit (state, ...args) {
+    const transform = this.#customTransforms[state.operator] ?? transforms[state.operator]
+    const { index } = state.functionQuery


I think defaulting to locating the first makes sense. I worry if this changes we'll have to update function queries to specify the index: 0 for most of the cases. I can't imagine a use case where you want to rewrite the same query multiple times for a file but i could be wrong.

bizob2828 · 2026-03-24T23:49:03Z

+   * @param {string} name - Operator name (e.g. `'traceSync'`).
+   * @param {Function} fn - Transform function `(state, node, parent, ancestry) => void`.
+   */
+  addTransform (name, fn) {


bizob2828 · 2026-03-25T00:00:58Z

+
+      return ${channelVariable}.start.runStores(__apm$ctx, () => {
+        try {
+          let promise = __apm$traced();


I had hoped we could remove shim code we had in our agent for libraries like ioredis and openai but we still need it. Now that this is js, I hope to provide a PR in the future to make it work for libraries that mess up promises

rochdev added 10 commits March 6, 2026 12:35

wip

b17de5f

fix transformer tests

8521cef

fix typo

f5cf14f

rewrite tests to js and fix super support in constructors

a070d3e

add support for isExportAlias

82f2d96

add missing features from rust

5cd96c7

add oxc + tests and remove build requirement

41c8860

update type definitions

73f786d

add custom transforms

dec3766

rename old ci tests

c39a725

jsumners-nr requested changes Mar 10, 2026

View reviewed changes

Comment thread yarn.lock Outdated

Comment thread .github/workflows/ci.yml Outdated

Comment thread .github/workflows/ci.yml Outdated

Comment thread index.js Outdated

rochdev added 16 commits March 10, 2026 11:28

switch to npm in ci and fix typo

65bd0c8

downgrade meriyah for node 18 compat

cbbb118

add linting and fix errors

4117dbe

add jsdoc

0eb4999

add test for astQuery

66c92c0

add source map test

14164d4

fix support for node 18

5fa920f

remove iterator support for now

8a6ed12

simplify code and remove custom parser for now

bf0c5b1

update jsdoc

357cffb

remove all rust and update docs

d4fa04f

update 3rd party licenses

b3b1715

remove oxc-parser

4443619

temporarily revert lockfile ignore

ef0131a

delete yarn lockfile

5a55f86

add back ignore for lockfiles

0587761

rochdev marked this pull request as ready for review March 12, 2026 16:42

rochdev changed the title ~~rewrite in js except parsing that uses oxc with meriyah as fallback~~ rewrite orchestrion in javascript Mar 12, 2026

rochdev mentioned this pull request Mar 12, 2026

[RFC] Rewrite Orchestrion in JavaScript #42

Closed

rochdev added 3 commits March 17, 2026 23:21

fix import of dc when resolved to cjs and injected to esm

b16187c

code cleanup

f0140b6

code cleanup

5d7a851

Qard approved these changes Mar 18, 2026

View reviewed changes

bizob2828 reviewed Mar 19, 2026

View reviewed changes

Comment thread index.d.ts Outdated

Comment thread lib/transformer.js

bizob2828 reviewed Mar 19, 2026

View reviewed changes

Comment thread lib/transforms.js Outdated

bizob2828 reviewed Mar 19, 2026

View reviewed changes

Comment thread lib/transformer.js

bizob2828 reviewed Mar 20, 2026

View reviewed changes

rochdev added 5 commits March 21, 2026 17:24

move source-map to prod dependencies

7d0992e

rename variable

dda8ee3

update function index default and fix implementation

3d6b3af

update promise tracing with latest logic from node core

3ec8fd6

remove outdated comment

f4181a3

bizob2828 approved these changes Mar 25, 2026

View reviewed changes

bizob2828 merged commit 9237c9b into nodejs:main Mar 25, 2026
6 checks passed

This was referenced Mar 25, 2026

feat: Add wasm module build #12

Closed

update swc_ecma_visit dependency #27

Closed

chore: small refactoring #5

Closed

bizob2828 pushed a commit that referenced this pull request Mar 25, 2026

feat: Rewrite orchestrion in javascript (#41)

2069006

nodejs-github-bot mentioned this pull request Mar 25, 2026

chore: release v0.11.0 #43

Merged

bizob2828 mentioned this pull request Mar 27, 2026

fix: Updated release-please to handle publishing only javascript code #48

Merged

This was referenced Mar 27, 2026

chore: release v0.11.0 #49

Closed

chore: release v0.11.0 #51

Merged

chore: release v0.11.0 #52

Merged

bizob2828 mentioned this pull request Mar 27, 2026

fix: Updated Transformer.#visit to skip visiting VariableDeclarator nodes #55

Merged

bizob2828 mentioned this pull request Apr 6, 2026

fix: Updated transformer to prevent instrumenting a non-existent method on a class #59

Merged

dippas mentioned this pull request Apr 23, 2026

Newrelic >= 13.9.x breaks Next.js standalone + pnpm newrelic/node-newrelic#3917

Closed

bizob2828 mentioned this pull request May 28, 2026

fix: Supply 'esm' to transformer.transform() if format is 'module' apm-js-collab/tracing-hooks#32

Merged

Uh oh!

Conversation

rochdev commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jsumners-nr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bizob2828 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bizob2828 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bizob2828 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

rochdev commented Mar 10, 2026 •

edited

Loading