process: fix symbol key and mark experimental new node:process methods

aduh95 · aduh95 · commit 3f69b18a2319 · 2025-02-06T01:10:44.000+01:00
PR-URL: #56517 Backport-PR-URL: #56571 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/doc/api/process.md b/doc/api/process.md
@@ -3227,11 +3227,13 @@ console.log(`The parent process is pid ${ppid}`);
 added: REPLACEME
 -->
 
+> Stability: 1 - Experimental
+
 * `maybeRefable` {any} An object that may be "refable".
 
 An object is "refable" if it implements the Node.js "Refable protocol".
-Specifically, this means that the object implements the `Symbol.for('node:ref')`
-and `Symbol.for('node:unref')` methods. "Ref'd" objects will keep the Node.js
+Specifically, this means that the object implements the `Symbol.for('nodejs.ref')`
+and `Symbol.for('nodejs.unref')` methods. "Ref'd" objects will keep the Node.js
 event loop alive, while "unref'd" objects will not. Historically, this was
 implemented by using `ref()` and `unref()` methods directly on the objects.
 This pattern, however, is being deprecated in favor of the "Refable protocol"
@@ -4284,11 +4286,13 @@ In [`Worker`][] threads, `process.umask(mask)` will throw an exception.
 added: REPLACEME
 -->
 
+> Stability: 1 - Experimental
+
 * `maybeUnfefable` {any} An object that may be "unref'd".
 
 An object is "unrefable" if it implements the Node.js "Refable protocol".
-Specifically, this means that the object implements the `Symbol.for('node:ref')`
-and `Symbol.for('node:unref')` methods. "Ref'd" objects will keep the Node.js
+Specifically, this means that the object implements the `Symbol.for('nodejs.ref')`
+and `Symbol.for('nodejs.unref')` methods. "Ref'd" objects will keep the Node.js
 event loop alive, while "unref'd" objects will not. Historically, this was
 implemented by using `ref()` and `unref()` methods directly on the objects.
 This pattern, however, is being deprecated in favor of the "Refable protocol"
diff --git a/lib/internal/process/per_thread.js b/lib/internal/process/per_thread.js
@@ -425,12 +425,14 @@ function toggleTraceCategoryState(asyncHooksEnabled) {
 const { arch, platform, version } = process;
 
 function ref(maybeRefable) {
-  const fn = maybeRefable?.[SymbolFor('node:ref')] || maybeRefable?.ref;
+  const fn = maybeRefable?.[SymbolFor('nodejs.ref')] || maybeRefable?.[SymbolFor('node:ref')] || maybeRefable?.ref;
   if (typeof fn === 'function') FunctionPrototypeCall(fn, maybeRefable);
 }
 
 function unref(maybeRefable) {
-  const fn = maybeRefable?.[SymbolFor('node:unref')] || maybeRefable?.unref;
+  const fn = maybeRefable?.[SymbolFor('nodejs.unref')] ||
+             maybeRefable?.[SymbolFor('node:unref')] ||
+             maybeRefable?.unref;
   if (typeof fn === 'function') FunctionPrototypeCall(fn, maybeRefable);
 }
 
diff --git a/test/parallel/test-process-ref-unref.js b/test/parallel/test-process-ref-unref.js
@@ -23,6 +23,18 @@ class Foo {
 }
 
 class Foo2 {
+  refCalled = 0;
+  unrefCalled = 0;
+  [Symbol.for('nodejs.ref')]() {
+    this.refCalled++;
+  }
+  [Symbol.for('nodejs.unref')]() {
+    this.unrefCalled++;
+  }
+}
+
+// TODO(aduh95): remove support for undocumented symbol
+class Foo3 {
   refCalled = 0;
   unrefCalled = 0;
   [Symbol.for('node:ref')]() {
@@ -39,14 +51,19 @@ describe('process.ref/unref work as expected', () => {
     // just work.
     const foo1 = new Foo();
     const foo2 = new Foo2();
+    const foo3 = new Foo3();
     process.ref(foo1);
     process.unref(foo1);
     process.ref(foo2);
     process.unref(foo2);
+    process.ref(foo3);
+    process.unref(foo3);
     strictEqual(foo1.refCalled, 1);
     strictEqual(foo1.unrefCalled, 1);
     strictEqual(foo2.refCalled, 1);
     strictEqual(foo2.unrefCalled, 1);
+    strictEqual(foo3.refCalled, 1);
+    strictEqual(foo3.unrefCalled, 1);
 
     // Objects that implement the legacy API also just work.
     const i = setInterval(() => {}, 1000);

Original file line number	Diff line number	Diff line change
`@@ -425,12 +425,14 @@ function toggleTraceCategoryState(asyncHooksEnabled) {`
`425`	`425`	`const { arch, platform, version } = process;`
`426`	`426`
`427`	`427`	`function ref(maybeRefable) {`
`428`		`- const fn = maybeRefable?.[SymbolFor('node:ref')] \|\| maybeRefable?.ref;`
	`428`	`+ const fn = maybeRefable?.[SymbolFor('nodejs.ref')] \|\| maybeRefable?.[SymbolFor('node:ref')] \|\| maybeRefable?.ref;`
`429`	`429`	`if (typeof fn === 'function') FunctionPrototypeCall(fn, maybeRefable);`
`430`	`430`	`}`
`431`	`431`
`432`	`432`	`function unref(maybeRefable) {`
`433`		`- const fn = maybeRefable?.[SymbolFor('node:unref')] \|\| maybeRefable?.unref;`
	`433`	`+ const fn = maybeRefable?.[SymbolFor('nodejs.unref')] \|\|`
	`434`	`+ maybeRefable?.[SymbolFor('node:unref')] \|\|`
	`435`	`+ maybeRefable?.unref;`
`434`	`436`	`if (typeof fn === 'function') FunctionPrototypeCall(fn, maybeRefable);`
`435`	`437`	`}`
`436`	`438`