callsites

library4.2.0jsnpmunverified

Callsites is a low-level utility that retrieves an array of V8 CallSite objects from the current JavaScript stack trace. It provides direct access to the V8 stack trace API, allowing developers to inspect intricate details of each call in the stack, such as file names, line numbers, column numbers, function names, and execution context. This package is currently stable at version 4.2.0 and maintains an active release cadence, with recent updates adding Bun support and refining TypeScript definitions. It is a pure ESM package since v4.0.0, making it suitable for modern Node.js environments. Its primary differentiator is providing raw, unopinionated access to V8's callsite information, empowering advanced debugging, logging, and error reporting scenarios.

observability testing

npm install callsites

github ↗package ↗

INSTALL

IMPORT

SIG · CALLSITES

callsites

observabilityjavascriptv4.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

callsites

✓ import callsites from 'callsites';

✗ const callsites = require('callsites');

The package is pure ESM since v4.0.0. CommonJS `require()` is not supported.

CallSite

✓ import type { CallSite } from 'callsites';

✗ import { CallSite } from 'callsites';

Use `import type` for the TypeScript `CallSite` interface to avoid bundling issues and indicate it's a type-only import. The `CallSite` object itself is returned by the default export.

callsites() in async functions

✓ async function myAsyncFunc() { const stack = callsites(); const asyncCallsite = stack.find(c => c.isAsync()); // ... }

While `callsites()` itself is synchronous, the returned `CallSite` objects gained new methods like `isAsync()`, `isPromiseAll()`, and `getPromiseIndex()` in v4.2.0 to correctly identify and inspect asynchronous calls within the stack trace.

Demonstrates how to use `callsites` to retrieve the filename of the function that called the immediate parent function in the stack trace.

import callsites from 'callsites'; function getCallerFileName() { // callsites()[0] is the call to `callsites` itself // callsites()[1] is `getCallerFileName` // callsites()[2] is the function that called `getCallerFileName` const callerCallsite = callsites()[2]; if (callerCallsite) { return callerCallsite.getFileName(); } return 'Unknown file'; } function myApplicationLogic() { const filename = getCallerFileName(); console.log(`This function was called from: ${filename}`); } myApplicationLogic(); // Example output: This function was called from: /path/to/your/file.js

Debug

Known issues

breakingVersion 4.0.0 converted `callsites` to a pure ES Module (ESM). This means it can no longer be `require()`-d in CommonJS (CJS) contexts. Existing CJS projects must migrate to ESM or use an older version.

fix

Migrate your project to use ES Modules (`type: "module"` in `package.json` or `.mjs` files), or dynamically import `callsites` using `import()` if you must remain in CJS. For example: `const callsites = await import('callsites');`

affects: >=4.0.0

breakingVersion 4.0.0 raised the minimum Node.js requirement to 12.20. Projects running on older Node.js versions will need to upgrade their runtime.

fix

Ensure your Node.js environment is version 12.20 or newer. You can use tools like `nvm` or Docker to manage Node.js versions.

affects: >=4.0.0

gotchaCallSite objects returned by `callsites()` are not plain JavaScript objects. They expose methods (e.g., `getFileName()`, `getLineNumber()`) to access stack trace information, rather than direct properties.

fix

Always use the provided `get*` methods on the `CallSite` objects (e.g., `callsite.getFileName()`) instead of trying to access properties directly (e.g., `callsite.fileName`). Refer to the V8 Stack Trace API documentation for available methods.

affects: >=3.0.0

gotchaThe `getFunctionName()` and `getMethodName()` methods attempt to infer names, which can sometimes be unreliable or return `null` or empty strings, especially with anonymous functions, minified code, or complex execution contexts.

fix

Do not solely rely on function name inference for critical logic. Combine with other identifiers like `getFileName()` and `getLineNumber()` for more robust stack analysis. Consider providing named functions where possible.

affects: >=3.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/callsites/index.js from /path/to/your/file.js not supported.

Attempting to `require('callsites')` in a CommonJS module after `callsites` upgraded to pure ESM in v4.0.0.

fix

Either convert your project or the specific file to an ES Module (by adding `"type": "module"` to your `package.json` or changing the file extension to `.mjs`), or use dynamic `import()`: `const callsites = await import('callsites');`

TypeError: callsites is not a function

This error can occur if you are in a CJS module and tried `const callsites = require('callsites').default;` or if the module resolution incorrectly imported something other than the default export.

fix

Since v4.0.0, `callsites` is pure ESM and should be imported using `import callsites from 'callsites';`. If you *must* use CommonJS, use dynamic import: `const callsitesPromise = import('callsites'); callsitesPromise.then(mod => mod.default());`

TypeError: callsite.getFileName is not a function

Attempting to call a `get*` method on an object that is not a V8 `CallSite` instance, or trying to access a property directly like `callsite.fileName` instead of calling the method.

fix

Ensure the object you're interacting with is indeed a `CallSite` instance from the `callsites()` array, and always use the method syntax, e.g., `callsite.getFileName()`.

Upgrade

Version history

4.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sindresorhus/callsites ↗

packagehttps://www.npmjs.com/package/callsites ↗