lib: add util.getCallSite() API

Author: RafaelGSS

doc/api/util.md

@@ -364,6 +364,56 @@ util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
 // when printed to a terminal.
 ```
 
+## `util.getCallSite()`
+
+> Stability: 1.1 - Active development
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {CallSite\[]} An array of CallSite objects, read more at <https://v8.dev/docs/stack-trace-api#customizing-stack-traces>.
+
+Returns an array of V8 CallSite objects containing the stacktrace of
+the caller function.
+
+```js
+const util = require('node:util');
+
+function exampleFunction() {
+  const callSites = util.getCallSite();
+
+  console.log('Call Sites:');
+  callSites.forEach((callSite, index) => {
+    console.log(`CallSite ${index + 1}:`);
+    console.log(`Function Name: ${callSite.getFunctionName()}`);
+    console.log(`File Name: ${callSite.getFileName()}`);
+    console.log(`Line Number: ${callSite.getLineNumber()}`);
+    console.log(`Column Number: ${callSite.getColumnNumber()}`);
+  });
+  // CallSite 1:
+  // Function Name: exampleFunction
+  // File Name: /home/example.js
+  // Line Number: 5
+  // Column Number: 26
+
+  // CallSite 2:
+  // Function Name: anotherFunction
+  // File Name: /home/example.js
+  // Line Number: 22
+  // Column Number: 3
+
+  // ...
+}
+
+// A function to simulate another stack layer
+function anotherFunction() {
+  exampleFunction();
+}
+
+anotherFunction();
+```
+
 ## `util.getSystemErrorName(err)`
 
 <!-- YAML

lib/util.js

@@ -275,6 +275,26 @@ function parseEnv(content) {
   return binding.parseEnv(content);
 }
 
+/**
+ * Returns the callSite
+ * @returns {CallSite[]}
+ */
+function getCallSite() { /* eslint-disable no-restricted-syntax */
+  const originalStackFormatter = Error.prepareStackTrace;
+  Error.prepareStackTrace = (_err, stack) => {
+    if (stack && stack.length > 1) {
+      // Remove node:util
+      return stack.slice(1);
+    }
+    return stack;
+  };
+  const err = new Error();
+  // With the V8 Error API, the stack is not formatted until it is accessed
+  err.stack; // eslint-disable-line no-unused-expressions
+  Error.prepareStackTrace = originalStackFormatter;
+  return err.stack;
+};
+
 // Keep the `exports =` so that various functions can still be monkeypatched
 module.exports = {
   _errnoException,
@@ -289,6 +309,7 @@ module.exports = {
   format,
   styleText,
   formatWithOptions,
+  getCallSite,
   getSystemErrorMap,
   getSystemErrorName,
   inherits,

test/fixtures/get-call-site.js

@@ -0,0 +1,4 @@
+const util = require('node:util');
+const assert = require('node:assert');
+assert.ok(util.getCallSite().length > 1);
+process.stdout.write(util.getCallSite()[0].getFileName());

test/parallel/test-util-getCallSite.js

@@ -0,0 +1,54 @@
+'use strict';
+
+require('../common');
+
+const fixtures = require('../common/fixtures');
+const file = fixtures.path('get-call-site.js');
+
+const { getCallSite } = require('node:util');
+const { spawnSync } = require('node:child_process');
+const assert = require('node:assert');
+
+{
+  const callsite = getCallSite();
+  assert.ok(callsite.length > 1);
+  assert.match(
+    callsite[0].getFileName(),
+    /test-util-getCallSite/,
+    'node:util should be ignored',
+  );
+}
+
+
+{
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '-e',
+      `const util = require('util');
+       const assert = require('assert');
+       assert.ok(util.getCallSite().length > 1);
+       process.stdout.write(util.getCallSite()[0].getFileName());
+      `,
+    ],
+  );
+  assert.strictEqual(status, 0, stderr.toString());
+  assert.strictEqual(stdout.toString(), '[eval]');
+}
+
+{
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [file],
+  );
+  assert.strictEqual(status, 0, stderr.toString());
+  assert.strictEqual(stdout.toString(), file);
+}
+
+{
+  const originalStackTraceLimit = Error.stackTraceLimit;
+  Error.stackTraceLimit = 0;
+  const callsite = getCallSite();
+  assert.strictEqual(callsite.length, 0);
+  Error.stackTraceLimit = originalStackTraceLimit;
+}