tessl/npm-path-scurry

Extremely high performant utility for building tools that read the file system, minimizing filesystem and path string munging operations to the greatest degree possible

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Path Resolution

Name: tessl/npm-path-scurry
Author: tessl

Core path resolution functionality providing intelligent caching and cross-platform path handling. Significantly faster than Node's built-in path.resolve() for repeated operations due to comprehensive caching mechanisms.

Capabilities

PathScurry Constructor

Creates a new PathScurry instance with specified working directory and options.

/**
 * Create a new PathScurry instance
 * @param cwd - Starting working directory (defaults to process.cwd())
 * @param opts - Configuration options
 */
constructor(cwd?: URL | string, opts?: PathScurryOpts);

interface PathScurryOpts {
  /** Perform case-insensitive path matching (default: true on Windows/macOS, false elsewhere) */
  nocase?: boolean;
  /** Number of child entries to cache (default: 16384) */
  childrenCacheSize?: number;
  /** Override default filesystem methods */
  fs?: FSOption;
}

Usage Example:

import { PathScurry } from "path-scurry";

// Default (current working directory)
const pw1 = new PathScurry();

// Specific directory
const pw2 = new PathScurry("/home/user/project");

// With options
const pw3 = new PathScurry("/project", {
  nocase: true,
  childrenCacheSize: 8192
});

Path Resolution

Resolve one or more path segments to an absolute path with intelligent caching.

/**
 * Resolve path segments to absolute path
 * @param paths - Path segments to resolve
 * @returns Fully resolved absolute path
 */
resolve(...paths: string[]): string;

/**
 * Resolve path segments to absolute POSIX path
 * @param paths - Path segments to resolve  
 * @returns Fully resolved absolute path using forward slashes
 */
resolvePosix(...paths: string[]): string;

Usage Examples:

const pw = new PathScurry("/project");

// Basic resolution
const resolved = pw.resolve("src", "index.ts");
console.log(resolved); // "/project/src/index.ts"

// Absolute path handling
const abs = pw.resolve("/etc", "hosts");
console.log(abs); // "/etc/hosts"

// POSIX-style resolution (always forward slashes)
const posix = pw.resolvePosix("src\\utils\\helper.js");
console.log(posix); // "/project/src/utils/helper.js"

Relative Path Calculation

Calculate relative paths from the current working directory to target paths.

/**
 * Get relative path from current working directory
 * @param entry - Target path (string or Path object)
 * @returns Relative path string
 */
relative(entry?: PathBase | string): string;

/**
 * Get relative path using POSIX separators
 * @param entry - Target path (string or Path object)
 * @returns Relative path string with forward slashes
 */
relativePosix(entry?: PathBase | string): string;

Usage Examples:

const pw = new PathScurry("/home/user");

// Relative path calculation
const rel = pw.relative("/home/user/projects/app/src");
console.log(rel); // "projects/app/src"

// POSIX relative paths
const relPosix = pw.relativePosix("C:\\Users\\data\\file.txt");
console.log(relPosix); // "../../data/file.txt" (on Windows)

Path Component Extraction

Extract basename and dirname components from paths.

/**
 * Get basename of path
 * @param entry - Path to analyze (defaults to current working directory)
 * @returns Base filename or directory name
 */
basename(entry?: PathBase | string): string;

/**
 * Get parent directory path
 * @param entry - Path to analyze (defaults to current working directory)
 * @returns Parent directory path
 */
dirname(entry?: PathBase | string): string;

Usage Examples:

const pw = new PathScurry();

const base = pw.basename("/path/to/file.txt");
console.log(base); // "file.txt"

const dir = pw.dirname("/path/to/file.txt");
console.log(dir); // "/path/to"

Working Directory Management

Change the effective working directory and calculate path depths.

/**
 * Change current working directory
 * @param path - New working directory path
 */
chdir(path: string | Path): void;

/**
 * Calculate depth of path within directory tree
 * @param path - Path to analyze (defaults to current working directory)
 * @returns Depth level (root = 0)
 */
depth(path?: Path | string): number;

Usage Examples:

const pw = new PathScurry("/home");

// Change working directory
pw.chdir("user/projects");
console.log(pw.cwd.fullpath()); // "/home/user/projects"

// Calculate depth
const depth1 = pw.depth("/");           // 0 (root)
const depth2 = pw.depth("/home/user");  // 2

Platform-Specific Classes

Use specific implementations for cross-platform development or testing.

/**
 * Windows-specific PathScurry implementation
 */
class PathScurryWin32 extends PathScurryBase {
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
  sep: '\\';
}

/**
 * POSIX-specific PathScurry implementation  
 */
class PathScurryPosix extends PathScurryBase {
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
  sep: '/';
}

/**
 * Darwin (macOS) specific implementation with case-insensitive defaults
 */
class PathScurryDarwin extends PathScurryPosix {
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
}

Usage Example:

import { PathScurryWin32, PathScurryPosix } from "path-scurry";

// Force Windows behavior regardless of platform
const winPw = new PathScurryWin32("/project");
console.log(winPw.resolve("src", "file.js")); // "C:\\project\\src\\file.js"

// Force POSIX behavior
const posixPw = new PathScurryPosix("/project");  
console.log(posixPw.resolve("src", "file.js")); // "/project/src/file.js"

Install with Tessl CLI