tessl/npm-path

Node.js path module providing utilities for working with file and directory paths in a cross-platform manner

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Path Manipulation

Name: tessl/npm-path
Author: tessl

Essential path manipulation operations for joining path segments and computing relative paths between locations.

Capabilities

Join

Joins all given path segments together using the platform-specific separator as a delimiter, then normalizes the resulting path. Zero-length path segments are ignored.

/**
 * Joins path segments using platform-specific separator
 * @param {...string} paths - Path segments to join
 * @returns {string} Joined and normalized path
 * @throws {TypeError} If any argument is not a string
 */
function join(...paths: string[]): string;

Usage Examples:

const path = require("path");

// Basic path joining
path.join("users", "john", "documents");
// POSIX: "users/john/documents"
// Windows: "users\\john\\documents"

// Handle leading/trailing separators
path.join("/users", "john/", "/documents");
// POSIX: "/users/john/documents"
// Windows: "\\users\\john\\documents"

// Skip empty segments
path.join("users", "", "john", "documents");
// Result: "users/john/documents"

// Handle relative path segments
path.join("users", "../admin", "config");
// Result: "admin/config"

// Single argument normalization
path.join("/users//john/");
// POSIX: "/users/john/"
// Windows: "\\users\\john\\"

Platform Differences:

// Windows-specific joining
path.win32.join("C:", "Users", "John");
// Result: "C:\\Users\\John"

path.win32.join("//server", "share", "file.txt");
// Result: "\\\\server\\share\\file.txt"

// POSIX joining
path.posix.join("/usr", "local", "bin");
// Result: "/usr/local/bin"

Error Handling:

// Throws TypeError for non-string arguments
try {
  path.join("users", 123, "documents");
} catch (error) {
  console.log(error.message); // "Arguments to path.join must be strings"
}

Relative

Returns the relative path from from to to based on the current working directory. If from and to each resolve to the same path (after calling resolve() on each), a zero-length string is returned.

/**
 * Returns relative path from 'from' to 'to'
 * @param {string} from - Source path
 * @param {string} to - Target path  
 * @returns {string} Relative path from source to target
 */
function relative(from: string, to: string): string;

Usage Examples:

const path = require("path");

// Basic relative path calculation
path.relative("/users/john", "/users/jane");
// Result: "../jane"

path.relative("/users/john/docs", "/users/john/images");
// Result: "../images"

// Same path returns empty string
path.relative("/users/john", "/users/john");
// Result: ""

// Different drives on Windows
path.win32.relative("C:\\users\\john", "D:\\data");
// Result: "D:\\data" (absolute path when no common root)

// Nested directory navigation
path.relative("/a/b/c/d", "/a/b/x/y");
// Result: "../../x/y"

// Relative to parent
path.relative("/users/john/docs", "/users/john");
// Result: ".."

// Relative to subdirectory
path.relative("/users/john", "/users/john/docs");
// Result: "docs"

Platform Differences:

// Windows relative paths (case-insensitive)
path.win32.relative("C:\\Users\\John", "C:\\users\\jane");
// Result: "..\\jane"

// POSIX relative paths (case-sensitive)
path.posix.relative("/Users/John", "/users/jane");
// Result: "../../users/jane"

// UNC paths on Windows
path.win32.relative("\\\\server\\share\\folder", "\\\\server\\share\\other");
// Result: "..\\other"

Working with Current Directory:

// Relative from current working directory
const cwd = process.cwd(); // e.g., "/home/user/project"
path.relative(cwd, "/home/user/docs");
// Result: "../docs"

// Resolve first, then calculate relative
path.relative(path.resolve("./src"), path.resolve("./docs"));
// Calculates relative path between resolved absolute paths

Install with Tessl CLI