README.md

@mnrendra/stack-trace

A utility for tracing the caller's call sites starting from a specific callee.
Useful for debugging, logging, or building tools that need to get the call origins or file locations at runtime.

Install

npm i @mnrendra/stack-trace

API

stackTrace

Traces the caller's call sites starting from a specific callee.
Captures the current stack trace as an array of NodeJS.CallSite objects. If a callee is provided, the trace will start from the caller of the callee.

Type:

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

Parameters

Name	Type	Description
callee	((...args: any) => any) | null	Optional callee function or method to start tracing from. If undefined or null, tracing starts from the current caller.
options	Options	Configuration options for tracing behavior. 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 Type:

NodeJS.CallSite[]

An array of call sites representing the captured stack trace.

Usage

CommonJS

/foo/callee.cjs

const { stackTrace } = require('@mnrendra/stack-trace')

const callee = () => {
  const [callSite1] = stackTrace()
  const [callSite2] = stackTrace(callee, { limit: 1 }) // set the `callee` function as the callee.

  console.log(callSite1.getFileName()) // output: /foo/callee.cjs
  console.log(callSite2.getFileName()) // output: /foo/caller.cjs

  console.log(callSite1.getFunctionName()) // output: callee
  console.log(callSite2.getFunctionName()) // output: caller
}

module.exports = callee

/foo/caller.cjs

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

ES Modules

/foo/callee.mjs

import { stackTrace } from '@mnrendra/stack-trace'

const callee = () => {
  const [callSite1] = stackTrace()
  const [callSite2] = stackTrace(callee, { limit: 1 }) // set the `callee` function as the callee.

  console.log(callSite1.getFileName()) // output: file:///foo/callee.mjs
  console.log(callSite2.getFileName()) // output: file:///foo/caller.mjs

  console.log(callSite1.getFunctionName()) // output: callee
  console.log(callSite2.getFunctionName()) // output: caller
}

export default callee

/foo/caller.mjs

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

Note:

• When calling getFileName in an ES Modules, the file name will be returned as a file URL (e.g., 'file:///foo') instead of a file path (e.g., '/foo').
  You can use url.fileURLToPath to convert the file URL to a file path.
• By default stackTrace will capture all caller frames.
  To capture only a specific number of frames, set the limit option to a positive number.

Examples

1. Call from your development project:
   /foo/project-name/src/index.mjs:

import { fileURLToPath } from 'node:url'
import { stackTrace } from '@mnrendra/stack-trace'

const caller = () => stackTrace()
const [stack] = caller()

const fileName = stack.getFileName()

console.log(fileName) // output: file:///foo/project-name/src/index.mjs
console.log(fileURLToPath(fileName)) // output: /foo/project-name/src/index.mjs

2. Call from your production package:
   /foo/consumer/node_modules/module-name/dist/index.js:

"use strict";

const { stackTrace } = require("@mnrendra/stack-trace");

const caller = () => stackTrace();
const [stack] = caller();

const fileName = stack.getFileName();

console.log(fileName); // output: /foo/consumer/node_modules/module-name/dist/index.js

Options

limit

Type: number

Default: 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.

Types

import type {
  Options
} from '@mnrendra/stack-trace'

License

MIT

Author

@mnrendra