Skip to content

feat(module-register-to-register-hooks): add DEP0205 recipe - #572

Open
GeoffreyBooth wants to merge 2 commits into
nodejs:mainfrom
GeoffreyBooth:module-register-to-register-hooks
Open

GeoffreyBooth wants to merge 2 commits into
nodejs:mainfrom
GeoffreyBooth:module-register-to-register-hooks

Conversation

@GeoffreyBooth

@GeoffreyBooth GeoffreyBooth commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Closes #561

Adds a recipe for DEP0205: migrating module.register() and asynchronous customization hooks to the synchronous, in-thread module.registerHooks().

The codemod is conservative: it rewrites a file only when the result behaves the same, and leaves everything else untouched.

  • Registration files: register('./hooks.mjs', import.meta.url) becomes registerHooks(hooks), with the hooks module imported (ESM) or required (CommonJS). Handles named, aliased and namespace bindings and new URL(…) specifiers.
  • Hooks modules: async resolve/load hooks whose only async work is awaiting nextResolve()/nextLoad() lose async and the awaits.
  • Skipped: data/transferList, initialize/globalPreload exports, any other async work, dynamic specifiers, calls not at the top level of an ES module, and files where any one of several register() calls can't be converted. The README documents these under Limitations.

Testing: 21 fixture tests (npm test in the recipe), tsc --noEmit and biome lint are clean. I also ran the codemod on a scratch project with a virtual-module hook: the output was identical under Node before and after, minus the DEP0205 warning.

Context: this accompanies the removal of module.register() in nodejs/node#67090, and a Learn guide on customization hooks is being reworked in nodejs/learn#190 (this recipe would be linked from its end-of-life section).

🤖 Generated with Claude Code

Migrate module.register() calls and asynchronous resolve/load hooks to
module.registerHooks(). The codemod is conservative and leaves any file
it cannot prove equivalent untouched.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@JakobJingleheimer
JakobJingleheimer requested review from JakobJingleheimer and brunocroh and a balanced review from Copilot and removed request for Copilot November 15, 2026 13:50
@JakobJingleheimer JakobJingleheimer added the dep:26.x Migrate a deprecation for node 26.x label Nov 15, 2026

@JakobJingleheimer JakobJingleheimer left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this @GeoffreyBooth!

I looked at the test-cases, and many things are blindly changed based on assumptions the migration can't make: #561 (comment)

TLDR: The migration needs to actually run the chains in order to get sufficient info to know what it can/n't change. The correct-ts-specifiers migration has to do something similar, so that's not without precedent (but don't try to follow its implementation as an example—it's using legacy codemod things which have been vastly improved since that migration was written).

@JakobJingleheimer JakobJingleheimer added the await:author Reviewer has requested something from the author label Nov 15, 2026
@AugustinMauroy

Copy link
Copy Markdown
Member

IMO this is good. and yeah I agree with Jacob we cannot cover complex thing. but I think we can cover 75% of async ESM hooks usage.

@AugustinMauroy

Copy link
Copy Markdown
Member

@GeoffreyBooth did you use https://docs.codemod.com/community/model-context-protocol to have good result ?

@GeoffreyBooth

Copy link
Copy Markdown
Member Author

No, I did this quickly to have a place to put a migration guide since there was a request to remove that from the learn article. But that article still has that somewhat so maybe this isn't needed? I feel like most people probably have only one call to register per app so maybe a codemod isn't necessary?

…en safety checks

Read the file that register() points at and only convert the call when
that file passes the same checks as a hooks module. Only treat a file as a
hooks module when its exported resolve/load call their third argument.
Skip hooks that may return promises (.then/.catch, Promise types, async or
imported helpers, for await, generators), feature-detected registrations,
and hooks files in node_modules. Import CommonJS hooks by default export.

Add 33 regression fixtures, each verified to fail when its guard is removed,
and update the README to match.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@GeoffreyBooth

Copy link
Copy Markdown
Member Author

@JakobJingleheimer @AugustinMauroy Do you think we want this codemod or should I close this PR?

@JakobJingleheimer

Copy link
Copy Markdown
Member

We definitely want a codemod that covers this depreciation 🙂

@AugustinMauroy AugustinMauroy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Jacob it's not analyse the whole import chain to know if it's migrate correctly but it's cover a big part of the migration so for now we should keep this codemod as it and improve in the future if needed.

if have done a first review on code and oh gosh it's huge.

*/
export default function transform(root: SgRoot<Js>): string | null {
const rootNode = root.root();
const edits: Edit[] = [

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const edits: Edit[] = [
const edits: Edit[] = [

Comment on lines +123 to +135
const bodyText = body.text();
const signature = fn.text().slice(0, body.range().start.index - fn.range().start.index);

// `registerHooks()` hooks are synchronous, whatever they are declared as: a
// hook that hands back a promise can't be migrated by this codemod.
if (/\bPromise\b/.test(signature)) return null;
if (/\bPromise\b|\.(then|catch|finally)\s*\(|\bimport\s*\(/.test(bodyText)) {
return null;
}
if (/\bfor\s+await\b/.test(bodyText)) return null;
for (const name of asyncNames) {
if (new RegExp(`\\b${escapeRegExp(name)}\\b`).test(bodyText)) return null;
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this part use a lot of text manipulation can we achieve it by using ast ?

}
if (callsRiskyBinding(body, risky)) return null;

const asyncKeyword = fn.children().find((child) => child.kind() === "async");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const asyncKeyword = fn.children().find((child) => child.kind() === "async");
const asyncKeyword = fn.children().find((child) => child.is("async"));

if (!next) return null;
const nextReferences = identifiersNamed(body, next);
if (!nextReferences.length) return null;
for (const reference of nextReferences) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
for (const reference of nextReferences) {
for (const reference of nextReferences) {

const edits: Edit[] = [];
for (const expression of body.findAll({ rule: { kind: "await_expression" } })) {
const argument = expression.children().find((c) => c.kind() !== "await");
if (argument?.kind() !== "call_expression") return null;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
if (argument?.kind() !== "call_expression") return null;
if (!argument?.is( "call_expression")) return null;

rule: { kind: "function_declaration" },
})) {
const name = declaration.field("name")?.text();
const isAsync = declaration.children().some((c) => c.kind() === "async");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const isAsync = declaration.children().some((c) => c.kind() === "async");
const isAsync = declaration.children().some((c) => c.is("async"));

})) {
const name = declarator.field("name")?.text();
const value = declarator.field("value");
const isAsync = value?.children().some((c) => c.kind() === "async");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const isAsync = value?.children().some((c) => c.kind() === "async");
const isAsync = value?.children().some((c) => c.is("async"));

*/
function riskyBindings(rootNode: Node): Set<string> {
const risky = new Set<string>();
const isRisky = (source: string) => {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const isRisky = (source: string) => {
const isRisky = (source: string) => {

}

for (const declarator of rootNode.findAll({
rule: { kind: "variable_declarator" },

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can improve this ast query to catch with value that is call_expresison ... instead of doing some js check

Comment on lines +672 to +678
function argumentNodes(call: Node): Node[] {
const args = call.field("arguments");
if (!args) return [];
return args
.children()
.filter((child) => !PUNCTUATION.includes(child.kind().toString()));
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@brunocroh I'm pretty sure you already done something like that but with a cheaper way

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

await:author Reviewer has requested something from the author dep:26.x Migrate a deprecation for node 26.x

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(DEP0205): migrate compatible module hooks to module.registerHooks()

3 participants