Caller Path

Caller Path is a lightweight utility library that gets the file path of the calling function in JavaScript. It provides a simple API for determining the source location of function calls, which is useful for debugging, logging, and development tooling scenarios where you need to programmatically identify the source location of code execution.

Package Information

• Package Name: caller-path
• Package Type: npm
• Language: JavaScript (ES modules) with TypeScript definitions
• Installation: npm install caller-path
• Node.js Compatibility: ^12.20.0 || ^14.13.1 || >=16.0.0 (ES modules required)

Core Imports

import callerPath from "caller-path";

Note: This package is ESM-only and does not support CommonJS require().

Basic Usage

import callerPath from "caller-path";

// foo.js
export default function foo() {
  console.log(callerPath());
  //=> '/Users/username/project/bar.js'
}

// bar.js
import foo from './foo.js';
foo(); // This will print the path to bar.js

Capabilities

Get Caller Path

Gets the file path of the calling function with optional depth traversal to go back multiple levels in the call stack.

/**
 * Get the path of the caller function
 * @param options - Configuration options
 * @returns The file path of the caller, or undefined if unable to determine
 */
function callerPath(options?: Options): string | undefined;

interface Options {
  /**
   * The caller path depth, meaning how many levels we follow back on the stack trace
   * @default 0
   */
  readonly depth?: number;
}

Usage Examples:

import callerPath from "caller-path";

// Basic usage - get immediate caller
function logCaller() {
  console.log(callerPath());
  //=> '/path/to/calling/file.js'
}

// With depth parameter - traverse call stack
function deepFunction() {
  console.log(callerPath());        // depth 0 - immediate caller
  console.log(callerPath({depth: 1}));  // depth 1 - one level back
  console.log(callerPath({depth: 2}));  // depth 2 - two levels back
}

// Example call stack traversal:
// foo.js calls bar.js calls baz.js calls deepFunction()
// depth: 0 => baz.js
// depth: 1 => bar.js  
// depth: 2 => foo.js

Error Handling:

The function returns undefined if the caller's callsite object getFileName is not defined for some reason, such as:

• When called from the top-level scope with no caller
• When the call stack information is unavailable
• When called from certain runtime contexts where stack traces are limited

Stack Trace Depth:

The depth parameter controls how many levels to traverse back in the call stack:

• depth: 0 (default): Returns the immediate caller's file path
• depth: 1: Returns the caller of the caller's file path
• depth: 2: Returns two levels back in the call stack
• And so on...

This is particularly useful in wrapper functions or middleware where you need to identify the original source of a call rather than just the immediate wrapper.