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.
- ✅ 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!
npm i @mnrendra/stack-traceCaptures v8 stack trace from a specific caller.
(callee?: ((...args: any)=>any)|null,options?: Options)=>NodeJS.CallSite[]| 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. |
NodeJS.CallSite[]Array of CallSite objects representing the captured stack trace frames.
| 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. |
Gets the caller's CallSite object captured from stackTrace.
(callee?: ((...args: any)=>any)|null)=>NodeJS.CallSite| 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. |
NodeJS.CallSiteFirst CallSite object captured in the stack trace.
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.
(callSite: NodeJS.CallSite)=>string| Name | Type | Description |
|---|---|---|
callSite | NodeJS.CallSite | CallSite object captured from stackTrace. |
stringAbsolute path of the file name extracted from a CallSite object.
If the extracted file name is not a string or not absolute.
Gets the caller's file extracted from the result of getCallerSite and ensures it returns an absolute path using extractFilePath.
(callee?: ((...args: any)=>any)|null)=>string| 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. |
stringAbsolute path of the caller's file.
If the extracted file name is not a string or not absolute.
Gets the caller's directory extracted from the result of getCallerFile.
(callee?: ((...args: any)=>any)|null)=>string| 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. |
stringAbsolute path of the caller's directory.
If the extracted file name is not a string or not absolute.
/foo/callee.mjs
import{dirname}from'node:path'import{stackTrace,getCallerSite,extractFilePath,getCallerFile,getCallerDir}from'@mnrendra/stack-trace'constcallee=()=>{// `stackTrace`:const[callSite1]=stackTrace()const[callSite2]=stackTrace(callee,{limit: 1})// Pass the `callee` function as the callee.console.log(callSite1.getFileName())// Output: file:///foo/callee.mjsconsole.log(callSite2.getFileName())// Output: file:///foo/caller.mjsconsole.log(callSite1.getFunctionName())// Output: calleeconsole.log(callSite2.getFunctionName())// Output: caller// `getCallerSite`:constcallerSite1=getCallerSite()constcallerSite2=getCallerSite(callee)// Pass the `callee` function as the callee.console.log(callerSite1.getFileName()===callSite1.getFileName())// Output: trueconsole.log(callerSite2.getFileName()===callSite2.getFileName())// Output: trueconsole.log(callerSite1.getFileName())// Output: file:///foo/callee.mjsconsole.log(callerSite2.getFileName())// Output: file:///foo/caller.mjsconsole.log(callerSite1.getFunctionName()===callSite1.getFunctionName())// Output: trueconsole.log(callerSite2.getFunctionName()===callSite2.getFunctionName())// Output: trueconsole.log(callerSite1.getFunctionName())// Output: calleeconsole.log(callerSite2.getFunctionName())// Output: caller// `extractFilePath`:constfilePath1=extractFilePath(callerSite1)constfilePath2=extractFilePath(callerSite2)console.log(filePath1)// Output: /foo/callee.mjsconsole.log(filePath2)// Output: /foo/caller.mjs// `getCallerFile`:constcallerFile1=getCallerFile()constcallerFile2=getCallerFile(callee)// Pass the `callee` function as the callee.console.log(callerFile1===filePath1)// Output: trueconsole.log(callerFile2===filePath2)// Output: trueconsole.log(callerFile1)// Output: /foo/callee.mjsconsole.log(callerFile2)// Output: /foo/caller.mjs// `getCallerDir`:constcallerDir1=getCallerDir()constcallerDir2=getCallerDir(callee)// Pass the `callee` function as the callee.console.log(callerDir1===dirname(filePath1))// Output: trueconsole.log(callerDir2===dirname(filePath2))// Output: trueconsole.log(callerDir1)// Output: /fooconsole.log(callerDir2)// Output: /foo}exportdefaultcallee/foo/caller.mjs
importcalleefrom'./callee.mjs'constcaller=()=>callee()caller()/foo/callee.cjs
const{ dirname }=require('node:path')const{
stackTrace,
getCallerSite,
extractFilePath,
getCallerFile,
getCallerDir
}=require('@mnrendra/stack-trace')constcallee=()=>{// `stackTrace`:const[callSite1]=stackTrace()const[callSite2]=stackTrace(callee,{limit: 1})// Pass the `callee` function as the callee.console.log(callSite1.getFileName())// Output: /foo/callee.cjsconsole.log(callSite2.getFileName())// Output: /foo/caller.cjsconsole.log(callSite1.getFunctionName())// Output: calleeconsole.log(callSite2.getFunctionName())// Output: caller// `getCallerSite`:constcallerSite1=getCallerSite()constcallerSite2=getCallerSite(callee)// Pass the `callee` function as the callee.console.log(callerSite1.getFileName()===callSite1.getFileName())// Output: trueconsole.log(callerSite2.getFileName()===callSite2.getFileName())// Output: trueconsole.log(callerSite1.getFileName())// Output: /foo/callee.cjsconsole.log(callerSite2.getFileName())// Output: /foo/caller.cjsconsole.log(callerSite1.getFunctionName()===callSite1.getFunctionName())// Output: trueconsole.log(callerSite2.getFunctionName()===callSite2.getFunctionName())// Output: trueconsole.log(callerSite1.getFunctionName())// Output: calleeconsole.log(callerSite2.getFunctionName())// Output: caller// `extractFilePath`:constfilePath1=extractFilePath(callerSite1)constfilePath2=extractFilePath(callerSite2)console.log(filePath1)// Output: /foo/callee.cjsconsole.log(filePath2)// Output: /foo/caller.cjs// `getCallerFile`:constcallerFile1=getCallerFile()constcallerFile2=getCallerFile(callee)// Pass the `callee` function as the callee.console.log(callerFile1===filePath1)// Output: trueconsole.log(callerFile2===filePath2)// Output: trueconsole.log(callerFile1)// Output: /foo/callee.cjsconsole.log(callerFile2)// Output: /foo/caller.cjs// `getCallerDir`:constcallerDir1=getCallerDir()constcallerDir2=getCallerDir(callee)// Pass the `callee` function as the callee.console.log(callerDir1===dirname(filePath1))// Output: trueconsole.log(callerDir2===dirname(filePath2))// Output: trueconsole.log(callerDir1)// Output: /fooconsole.log(callerDir2)// Output: /foo}module.exports=callee/foo/caller.cjs
constcallee=require('./callee.cjs')constcaller=()=>callee()caller()Note:
In ES Modules,
getFileNamereturns a file URL (e.g.,file:///foo), instead of a file path (/foo).
To convert it to a file path, use eitherurl.fileURLToPathor theextractFilePathutility.By default
stackTracewill capture all caller's frames.
To capture only a specific number of frames, set thelimitoption to a positive number.
- Call from a development project
/foo/project-name/src/index.mjs:
import{dirname}from'node:path'import{fileURLToPath}from'node:url'import{stackTrace,getCallerSite,extractFilePath,getCallerFile,getCallerDir}from'@mnrendra/stack-trace'// `stackTrace`:constcaller1=()=>stackTrace()const[callSite]=caller1()constfileName=callSite.getFileName()console.log(fileName)// Output: file:///foo/project-name/src/index.mjsconsole.log(fileURLToPath(fileName))// Output: /foo/project-name/src/index.mjs// `getCallerSite`:constcaller2=()=>getCallerSite()constcallerSite=caller2()constcallerFileName=callerSite.getFileName()console.log(callerFileName===fileName)// Output: trueconsole.log(callerFileName)// Output: file:///foo/project-name/src/index.mjsconsole.log(fileURLToPath(callerFileName))// Output: /foo/project-name/src/index.mjs// `extractFilePath`:constfilePath=extractFilePath(callerSite)console.log(filePath===fileURLToPath(callerFileName))// Output: trueconsole.log(filePath)// Output: /foo/project-name/src/index.mjs// `getCallerFile`:constcaller3=()=>getCallerFile()constcallerFile=caller3()console.log(callerFile===filePath)// Output: trueconsole.log(callerFile)// Output: /foo/project-name/src/index.mjs// `getCallerDir`:constcaller4=()=>getCallerDir()constcallerDir=caller4()console.log(callerDir===dirname(filePath))// Output: trueconsole.log(callerDir)// Output: /foo/project-name/src- Call from a production package
/foo/consumer/node_modules/module-name/dist/index.cjs:
"use strict";const{ dirname }=require("node:path");const{
stackTrace,
getCallerSite,
extractFilePath,
getCallerFile,
getCallerDir
}=require("@mnrendra/stack-trace");// `stackTrace`:constcaller1=()=>stackTrace();const[callSite]=caller1();constfileName=callSite.getFileName();console.log(fileName);// Output: /foo/consumer/node_modules/module-name/dist/index.cjs// `getCallerSite`:constcaller2=()=>getCallerSite();constcallerSite=caller2();constcallerFileName=callerSite.getFileName();console.log(callerFileName===fileName);// Output: trueconsole.log(callerFileName);// Output: /foo/consumer/node_modules/module-name/dist/index.cjs// `extractFilePath`:constfilePath=extractFilePath(callerSite);console.log(filePath===callerFileName);// Output: trueconsole.log(filePath);// Output: /foo/consumer/node_modules/module-name/dist/index.cjs// `getCallerFile`:constcaller3=()=>getCallerFile()constcallerFile=caller3()console.log(callerFile===filePath)// Output: trueconsole.log(callerFile)// Output: /foo/consumer/node_modules/module-name/dist/index.cjs// `getCallerDir`:constcaller4=()=>getCallerDir();constcallerDir=caller4();console.log(callerDir===dirname(filePath));// Output: trueconsole.log(callerDir);// Output: /foo/consumer/node_modules/module-name/diststackTrace's options interface.
import{typeOptions,stackTrace}from'@mnrendra/stack-trace'constoptions: Options={limit: 1}constcaller=(): NodeJS.CallSite[]=>stackTrace(caller,options)constcallSites=caller()console.log(callSites.length)// Output: 1We 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.
We appreciate your help in making this project better. Please follow the guidelines to ensure that your contributions are smoothly integrated.