@mnrendra/stack-trace

A lightweight stack trace utility to retrieve CallSite objects from a specific caller.

Useful for debugging, logging, or building tools that need to trace call origins at runtime.

Features

• ✅ Supports both ES Modules and CommonJS from a single source - see package
• ✅ Minified and cleansed of unnecessary dependencies, files, and attributes - see contents
• ✅ Tiny package - see size
• ✅ Well tested - see coverage
• ✅ Security checked - see scorecard
• ✅ Verified all commits - see signatures
• ✅ Semantic versioning - see commits
• ✅ Actively maintained - pull requests, issues, discussions, and contributions are welcome!

Install

1npm i @mnrendra/stack-trace

API Reference

stackTrace

Captures v8 stack trace from a specific caller.

Type

1(callee?: ((...args: any) => any) | null, options?: Options) => NodeJS.CallSite[]

Parameters

Name	Type	Description
callee	((...args: any) => any) | null	Optional callee function to specify the caller. If undefined or null, tracing starts from the current caller.
options	Options	Optional options to affect the captured frames. By default, the limit option is set to Infinity to capture all frames. To capture only a specific number of frames, set the limit option to a positive number.

Return

1NodeJS.CallSite[]

Array of CallSite objects representing the captured stack trace frames.

Options

Name	Type	Default	Description
limit	number	Infinity	Specifies the number of stack frames to be collected by a stack trace. The default value is Infinity, but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

getCallerSite

Gets the caller's CallSite object captured from stackTrace.

Type

1(callee?: ((...args: any) => any) | null) => NodeJS.CallSite

Parameters

Name	Type	Description
callee	((...args: any) => any) | null	Optional callee function to specify the caller. If undefined or null, tracing starts from the current caller.

Return

1NodeJS.CallSite

First CallSite object captured in the stack trace.

extractFilePath

Extracts the file name from a CallSite object and converts it to a file path if the value is a file URL.
This utility ensures that the returned value is an absolute path.

Type

1(callSite: NodeJS.CallSite) => string

Parameters

Name	Type	Description
callSite	NodeJS.CallSite	CallSite object captured from stackTrace.

Return

1string

Absolute path of the file name extracted from a CallSite object.

Throws

If the extracted file name is not a string or not absolute.

getCallerFile

Gets the caller's file extracted from the result of getCallerSite and ensures it returns an absolute path using extractFilePath.

Type

1(callee?: ((...args: any) => any) | null) => string

Parameters

Name	Type	Description
callee	((...args: any) => any) | null	Optional callee function to specify the caller. If undefined or null, tracing starts from the current caller.

Return

1string

Absolute path of the caller's file.

Throws

If the extracted file name is not a string or not absolute.

getCallerDir

Gets the caller's directory extracted from the result of getCallerFile.

Type

1(callee?: ((...args: any) => any) | null) => string

Parameters

Name	Type	Description
callee	((...args: any) => any) | null	Optional callee function to specify the caller. If undefined or null, tracing starts from the current caller.

Return

1string

Absolute path of the caller's directory.

Throws

If the extracted file name is not a string or not absolute.

Usage

ES Modules

/foo/callee.mjs

1import { dirname } from 'node:path'
2
3import {
4  stackTrace,
5  getCallerSite,
6  extractFilePath,
7  getCallerFile,
8  getCallerDir
9} from '@mnrendra/stack-trace'
10
11const callee = () => {
12  // `stackTrace`:
13  const [callSite1] = stackTrace()
14  const [callSite2] = stackTrace(callee, { limit: 1 }) // Pass the `callee` function as the callee.
15
16  console.log(callSite1.getFileName()) // Output: file:///foo/callee.mjs
17  console.log(callSite2.getFileName()) // Output: file:///foo/caller.mjs
18
19  console.log(callSite1.getFunctionName()) // Output: callee
20  console.log(callSite2.getFunctionName()) // Output: caller
21
22  // `getCallerSite`:
23  const callerSite1 = getCallerSite()
24  const callerSite2 = getCallerSite(callee) // Pass the `callee` function as the callee.
25
26  console.log(callerSite1.getFileName() === callSite1.getFileName()) // Output: true
27  console.log(callerSite2.getFileName() === callSite2.getFileName()) // Output: true
28
29  console.log(callerSite1.getFileName()) // Output: file:///foo/callee.mjs
30  console.log(callerSite2.getFileName()) // Output: file:///foo/caller.mjs
31
32  console.log(callerSite1.getFunctionName() === callSite1.getFunctionName()) // Output: true
33  console.log(callerSite2.getFunctionName() === callSite2.getFunctionName()) // Output: true
34
35  console.log(callerSite1.getFunctionName()) // Output: callee
36  console.log(callerSite2.getFunctionName()) // Output: caller
37
38  // `extractFilePath`:
39  const filePath1 = extractFilePath(callerSite1)
40  const filePath2 = extractFilePath(callerSite2)
41
42  console.log(filePath1) // Output: /foo/callee.mjs
43  console.log(filePath2) // Output: /foo/caller.mjs
44
45  // `getCallerFile`:
46  const callerFile1 = getCallerFile()
47  const callerFile2 = getCallerFile(callee) // Pass the `callee` function as the callee.
48
49  console.log(callerFile1 === filePath1) // Output: true
50  console.log(callerFile2 === filePath2) // Output: true
51
52  console.log(callerFile1) // Output: /foo/callee.mjs
53  console.log(callerFile2) // Output: /foo/caller.mjs
54
55  // `getCallerDir`:
56  const callerDir1 = getCallerDir()
57  const callerDir2 = getCallerDir(callee) // Pass the `callee` function as the callee.
58
59  console.log(callerDir1 === dirname(filePath1)) // Output: true
60  console.log(callerDir2 === dirname(filePath2)) // Output: true
61
62  console.log(callerDir1) // Output: /foo
63  console.log(callerDir2) // Output: /foo
64}
65
66export default callee

/foo/caller.mjs

1import callee from './callee.mjs'
2const caller = () => callee()
3caller()

CommonJS

/foo/callee.cjs

1const { dirname } = require('node:path')
2
3const {
4  stackTrace,
5  getCallerSite,
6  extractFilePath,
7  getCallerFile,
8  getCallerDir
9} = require('@mnrendra/stack-trace')
10
11const callee = () => {
12  // `stackTrace`:
13  const [callSite1] = stackTrace()
14  const [callSite2] = stackTrace(callee, { limit: 1 }) // Pass the `callee` function as the callee.
15
16  console.log(callSite1.getFileName()) // Output: /foo/callee.cjs
17  console.log(callSite2.getFileName()) // Output: /foo/caller.cjs
18
19  console.log(callSite1.getFunctionName()) // Output: callee
20  console.log(callSite2.getFunctionName()) // Output: caller
21
22  // `getCallerSite`:
23  const callerSite1 = getCallerSite()
24  const callerSite2 = getCallerSite(callee) // Pass the `callee` function as the callee.
25
26  console.log(callerSite1.getFileName() === callSite1.getFileName()) // Output: true
27  console.log(callerSite2.getFileName() === callSite2.getFileName()) // Output: true
28
29  console.log(callerSite1.getFileName()) // Output: /foo/callee.cjs
30  console.log(callerSite2.getFileName()) // Output: /foo/caller.cjs
31
32  console.log(callerSite1.getFunctionName() === callSite1.getFunctionName()) // Output: true
33  console.log(callerSite2.getFunctionName() === callSite2.getFunctionName()) // Output: true
34
35  console.log(callerSite1.getFunctionName()) // Output: callee
36  console.log(callerSite2.getFunctionName()) // Output: caller
37
38  // `extractFilePath`:
39  const filePath1 = extractFilePath(callerSite1)
40  const filePath2 = extractFilePath(callerSite2)
41
42  console.log(filePath1) // Output: /foo/callee.cjs
43  console.log(filePath2) // Output: /foo/caller.cjs
44
45  // `getCallerFile`:
46  const callerFile1 = getCallerFile()
47  const callerFile2 = getCallerFile(callee) // Pass the `callee` function as the callee.
48
49  console.log(callerFile1 === filePath1) // Output: true
50  console.log(callerFile2 === filePath2) // Output: true
51
52  console.log(callerFile1) // Output: /foo/callee.cjs
53  console.log(callerFile2) // Output: /foo/caller.cjs
54
55  // `getCallerDir`:
56  const callerDir1 = getCallerDir()
57  const callerDir2 = getCallerDir(callee) // Pass the `callee` function as the callee.
58
59  console.log(callerDir1 === dirname(filePath1)) // Output: true
60  console.log(callerDir2 === dirname(filePath2)) // Output: true
61
62  console.log(callerDir1) // Output: /foo
63  console.log(callerDir2) // Output: /foo
64}
65
66module.exports = callee

/foo/caller.cjs

1const callee = require('./callee.cjs')
2const caller = () => callee()
3caller()

Note:

• In ES Modules, getFileName returns a file URL (e.g., file:///foo), instead of a file path (/foo).
  To convert it to a file path, use either url.fileURLToPath or the extractFilePath utility.

• By default stackTrace will capture all caller's frames.
  To capture only a specific number of frames, set the limit option to a positive number.

Examples

1. Call from a development project

/foo/project-name/src/index.mjs:

1import { dirname } from 'node:path'
2import { fileURLToPath } from 'node:url'
3
4import {
5  stackTrace,
6  getCallerSite,
7  extractFilePath,
8  getCallerFile,
9  getCallerDir
10} from '@mnrendra/stack-trace'
11
12// `stackTrace`:
13const caller1 = () => stackTrace()
14const [callSite] = caller1()
15const fileName = callSite.getFileName()
16console.log(fileName) // Output: file:///foo/project-name/src/index.mjs
17console.log(fileURLToPath(fileName)) // Output: /foo/project-name/src/index.mjs
18
19// `getCallerSite`:
20const caller2 = () => getCallerSite()
21const callerSite = caller2()
22const callerFileName = callerSite.getFileName()
23console.log(callerFileName === fileName) // Output: true
24console.log(callerFileName) // Output: file:///foo/project-name/src/index.mjs
25console.log(fileURLToPath(callerFileName)) // Output: /foo/project-name/src/index.mjs
26
27// `extractFilePath`:
28const filePath = extractFilePath(callerSite)
29console.log(filePath === fileURLToPath(callerFileName)) // Output: true
30console.log(filePath) // Output: /foo/project-name/src/index.mjs
31
32// `getCallerFile`:
33const caller3 = () => getCallerFile()
34const callerFile = caller3()
35console.log(callerFile === filePath) // Output: true
36console.log(callerFile) // Output: /foo/project-name/src/index.mjs
37
38// `getCallerDir`:
39const caller4 = () => getCallerDir()
40const callerDir = caller4()
41console.log(callerDir === dirname(filePath)) // Output: true
42console.log(callerDir) // Output: /foo/project-name/src

2. Call from a production package

/foo/consumer/node_modules/module-name/dist/index.cjs:

1"use strict";
2
3const { dirname } = require("node:path");
4
5const {
6  stackTrace,
7  getCallerSite,
8  extractFilePath,
9  getCallerFile,
10  getCallerDir
11} = require("@mnrendra/stack-trace");
12
13// `stackTrace`:
14const caller1 = () => stackTrace();
15const [callSite] = caller1();
16const fileName = callSite.getFileName();
17console.log(fileName); // Output: /foo/consumer/node_modules/module-name/dist/index.cjs
18
19// `getCallerSite`:
20const caller2 = () => getCallerSite();
21const callerSite = caller2();
22const callerFileName = callerSite.getFileName();
23console.log(callerFileName === fileName); // Output: true
24console.log(callerFileName); // Output: /foo/consumer/node_modules/module-name/dist/index.cjs
25
26// `extractFilePath`:
27const filePath = extractFilePath(callerSite);
28console.log(filePath === callerFileName); // Output: true
29console.log(filePath); // Output: /foo/consumer/node_modules/module-name/dist/index.cjs
30
31// `getCallerFile`:
32const caller3 = () => getCallerFile()
33const callerFile = caller3()
34console.log(callerFile === filePath) // Output: true
35console.log(callerFile) // Output: /foo/consumer/node_modules/module-name/dist/index.cjs
36
37// `getCallerDir`:
38const caller4 = () => getCallerDir();
39const callerDir = caller4();
40console.log(callerDir === dirname(filePath)); // Output: true
41console.log(callerDir); // Output: /foo/consumer/node_modules/module-name/dist

Types

Options

stackTrace's options interface.

1import {
2  type Options,
3  stackTrace
4} from '@mnrendra/stack-trace'
5
6const options: Options = {
7  limit: 1
8}
9
10const caller = (): NodeJS.CallSite[] => stackTrace(caller, options)
11const callSites = caller()
12console.log(callSites.length) // Output: 1

Security

We take security seriously in this project. If you discover a vulnerability, we strongly encourage you to report it in a responsible manner.

Please open a Security Advisory to report any vulnerabilities.

For more information, please refer to our Security Policy.

Contributing

We appreciate your help in making this project better. Please follow the guidelines to ensure that your contributions are smoothly integrated.

License

MIT

Author

@mnrendra