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

File System Metadata

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

Cached filesystem metadata operations providing efficient access to file statistics, symbolic link resolution, and real path determination. All operations cache results to minimize expensive filesystem calls.

Capabilities

File Statistics (lstat)

Get file metadata similar to Node's fs.lstat() but with caching and simplified return values.

/**
 * Get file statistics asynchronously
 * @param entry - Path to analyze (defaults to current working directory)
 * @returns Promise resolving to Path object with metadata, or undefined if error
 */
lstat(entry?: string | PathBase): Promise<PathBase | undefined>;

/**
 * Get file statistics synchronously
 * @param entry - Path to analyze (defaults to current working directory)
 * @returns Path object with metadata, or undefined if error
 */
lstatSync(entry?: string | PathBase): PathBase | undefined;

Usage Examples:

import { PathScurry } from "path-scurry";

const pw = new PathScurry();

// Async lstat
const fileInfo = await pw.lstat("package.json");
if (fileInfo) {
  console.log(`File type: ${fileInfo.getType()}`);
  console.log(`Size: ${fileInfo.size} bytes`);
  console.log(`Modified: ${fileInfo.mtime}`);
  console.log(`Is file: ${fileInfo.isFile()}`);
} else {
  console.log("File does not exist or cannot be accessed");
}

// Sync lstat
const dirInfo = pw.lstatSync("./src");
if (dirInfo?.isDirectory()) {
  console.log(`Directory depth: ${dirInfo.depth()}`);
}

// Using Path objects directly
const path = pw.cwd.resolve("./config.json");
const stats = await path.lstat();
if (stats) {
  console.log(`Full path: ${stats.fullpath()}`);
  console.log(`Is symlink: ${stats.isSymbolicLink()}`);
}

Symbolic Link Resolution (readlink)

Resolve symbolic links to their target paths with optional return format control.

/**
 * Read symbolic link target asynchronously
 * @param entry - Symbolic link to resolve (defaults to current working directory)
 * @param opt - Control return format (Path object vs string)
 * @returns Promise resolving to link target or undefined if not a symlink/error
 */
readlink(): Promise<string | undefined>;
readlink(opt: { withFileTypes: false }): Promise<string | undefined>;
readlink(opt: { withFileTypes: true }): Promise<PathBase | undefined>;
readlink(opt: { withFileTypes: boolean }): Promise<PathBase | string | undefined>;
readlink(entry: string | PathBase, opt?: { withFileTypes: false }): Promise<string | undefined>;
readlink(entry: string | PathBase, opt: { withFileTypes: true }): Promise<PathBase | undefined>;
readlink(entry: string | PathBase, opt: { withFileTypes: boolean }): Promise<string | PathBase | undefined>;

/**
 * Read symbolic link target synchronously
 * @param entry - Symbolic link to resolve
 * @param opt - Control return format (Path object vs string)
 * @returns Link target or undefined if not a symlink/error
 */
readlinkSync(entry?: string | PathBase): string | undefined;
readlinkSync(opt: { withFileTypes: false }): string | undefined;
readlinkSync(opt: { withFileTypes: true }): PathBase | undefined;
readlinkSync(opt: { withFileTypes: boolean }): PathBase | string | undefined;
readlinkSync(entry: string | PathBase, opt?: { withFileTypes: false }): string | undefined;
readlinkSync(entry: string | PathBase, opt: { withFileTypes: true }): PathBase | undefined;
readlinkSync(entry: string | PathBase, opt: { withFileTypes: boolean }): string | PathBase | undefined;

Usage Examples:

const pw = new PathScurry();

// Read symlink target as string
const target = await pw.readlink("./symlink-to-file");
if (target) {
  console.log(`Symlink points to: ${target}`);
}

// Read symlink target as Path object
const targetPath = await pw.readlink("./symlink-to-dir", { withFileTypes: true });
if (targetPath) {
  console.log(`Target is directory: ${targetPath.isDirectory()}`);
  console.log(`Target full path: ${targetPath.fullpath()}`);
}

// Using Path objects directly
const link = pw.cwd.resolve("./some-symlink");
if (link.canReadlink()) {
  const resolved = await link.readlink();
  if (resolved) {
    console.log(`Link resolved to: ${resolved.fullpath()}`);
  }
}

// Sync version
const syncTarget = pw.readlinkSync("./another-link");
if (syncTarget) {
  console.log(`Synchronous readlink result: ${syncTarget}`);
}

Real Path Resolution (realpath)

Resolve paths to their canonical absolute form, following all symbolic links.

/**
 * Resolve path to canonical absolute form asynchronously
 * @param entry - Path to resolve (defaults to current working directory)
 * @param opt - Control return format (Path object vs string)
 * @returns Promise resolving to canonical path or undefined if error
 */
realpath(): Promise<string | undefined>;
realpath(opt: { withFileTypes: false }): Promise<string | undefined>;
realpath(opt: { withFileTypes: true }): Promise<PathBase | undefined>;
realpath(opt: { withFileTypes: boolean }): Promise<PathBase | string | undefined>;
realpath(entry: string | PathBase, opt?: { withFileTypes: false }): Promise<string | undefined>;
realpath(entry: string | PathBase, opt: { withFileTypes: true }): Promise<PathBase | undefined>;
realpath(entry: string | PathBase, opt: { withFileTypes: boolean }): Promise<string | PathBase | undefined>;

/**
 * Resolve path to canonical absolute form synchronously
 * @param entry - Path to resolve
 * @param opt - Control return format (Path object vs string)
 * @returns Canonical path or undefined if error
 */
realpathSync(): string | undefined;
realpathSync(opt: { withFileTypes: false }): string | undefined;
realpathSync(opt: { withFileTypes: true }): PathBase | undefined;
realpathSync(opt: { withFileTypes: boolean }): PathBase | string | undefined;
realpathSync(entry: string | PathBase, opt?: { withFileTypes: false }): string | undefined;
realpathSync(entry: string | PathBase, opt: { withFileTypes: true }): PathBase | undefined;
realpathSync(entry: string | PathBase, opt: { withFileTypes: boolean }): string | PathBase | undefined;

Usage Examples:

const pw = new PathScurry();

// Resolve real path as string
const real = await pw.realpath("./some/path/with/symlinks");
if (real) {
  console.log(`Real path: ${real}`);
}

// Resolve real path as Path object
const realPath = await pw.realpath("./complex/symlink/chain", { withFileTypes: true });
if (realPath) {
  console.log(`Real path exists: ${!realPath.isENOENT()}`);
  console.log(`Real path type: ${realPath.getType()}`);
}

// Direct Path object usage
const path = pw.cwd.resolve("./might-be-symlink");
const resolved = await path.realpath();
if (resolved) {
  console.log(`Canonical path: ${resolved.fullpath()}`);
  if (resolved !== path) {
    console.log("Path was resolved through symlinks");
  }
}

// Sync version
const syncReal = pw.realpathSync("./symlinked-directory");
if (syncReal) {
  console.log(`Sync realpath: ${syncReal}`);
}

Path Object Metadata Methods

Metadata operations available directly on Path objects with additional caching checks.

/**
 * Get cached lstat result without filesystem access
 * @returns Path object if lstat has been called, undefined otherwise
 */
lstatCached(): PathBase | undefined;

/**
 * Get cached readlink result without filesystem access
 * @returns Cached link target or undefined if not cached
 */
readlinkCached(): PathBase | undefined;

/**
 * Get cached realpath result without filesystem access
 * @returns Cached real path or undefined if not cached
 */
realpathCached(): PathBase | undefined;

/**
 * Check if readlink operation is likely to succeed
 * @returns True if path might be a readable symbolic link
 */
canReadlink(): boolean;

/**
 * Check if path is known to not exist
 * @returns True if previous operations determined path doesn't exist
 */
isENOENT(): boolean;

Usage Examples:

const path = pw.cwd.resolve("./some-file");

// Check cached status before expensive operations
const cachedStats = path.lstatCached();
if (cachedStats) {
  console.log("Already have stats:", cachedStats.getType());
} else {
  const stats = await path.lstat();
  console.log("Fetched stats:", stats?.getType());
}

// Check if path is worth reading as symlink
if (path.canReadlink()) {
  const target = await path.readlink();
  console.log("Symlink target:", target?.fullpath());
} else {
  console.log("Not a symlink or readlink would fail");
}

// Check existence status
if (path.isENOENT()) {
  console.log("Path is known to not exist");
} else {
  console.log("Path might exist (or status unknown)");
}

Available Statistics Properties

Path objects expose filesystem statistics after successful lstat() calls:

interface PathBase {
  // File system statistics (available after lstat)
  readonly dev?: number;          // Device ID
  readonly mode?: number;         // File mode
  readonly nlink?: number;        // Number of hard links
  readonly uid?: number;          // User ID
  readonly gid?: number;          // Group ID
  readonly rdev?: number;         // Device ID (special files)
  readonly blksize?: number;      // Block size
  readonly ino?: number;          // Inode number
  readonly size?: number;         // File size in bytes
  readonly blocks?: number;       // Number of blocks
  readonly atimeMs?: number;      // Access time (milliseconds)
  readonly mtimeMs?: number;      // Modification time (milliseconds)
  readonly ctimeMs?: number;      // Status change time (milliseconds)
  readonly birthtimeMs?: number;  // Creation time (milliseconds)
  readonly atime?: Date;          // Access time
  readonly mtime?: Date;          // Modification time
  readonly ctime?: Date;          // Status change time
  readonly birthtime?: Date;      // Creation time
}

Usage Example:

const fileInfo = await pw.lstat("./large-file.dat");
if (fileInfo) {
  console.log(`File size: ${fileInfo.size} bytes`);
  console.log(`Last modified: ${fileInfo.mtime}`);
  console.log(`Inode: ${fileInfo.ino}`);
  console.log(`Mode: ${fileInfo.mode?.toString(8)}`); // Octal permissions
}

Install with Tessl CLI