or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-path-parse

Node.js path.parse() ponyfill for cross-platform path parsing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/path-parse@1.0.x

To install, run

npx @tessl/cli install tessl/npm-path-parse@1.0.0

index.mddocs/

path-parse

path-parse is a Node.js ponyfill for the path.parse() method, providing cross-platform path parsing functionality. It parses file paths into their constituent parts (root, directory, base filename, extension, and name) with automatic platform detection and explicit platform-specific parsers.

Package Information

  • Package Name: path-parse
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install path-parse

Core Imports

const pathParse = require("path-parse");

For ES modules (if supported by your environment):

import pathParse from "path-parse";

Basic Usage

const pathParse = require("path-parse");

// Parse a POSIX path (automatic platform detection)
const result = pathParse("/home/user/documents/file.txt");
console.log(result);
// {
//   root: "/",
//   dir: "/home/user/documents",
//   base: "file.txt",
//   ext: ".txt",
//   name: "file"
// }

// Parse a Windows path (automatic platform detection)
const winResult = pathParse("C:\\Users\\user\\Documents\\file.txt");
console.log(winResult);
// {
//   root: "C:\\",
//   dir: "C:\\Users\\user\\Documents",
//   base: "file.txt",
//   ext: ".txt",
//   name: "file"
// }

// Use platform-specific parsers explicitly
const posixResult = pathParse.posix("/home/user/file.txt");
const win32Result = pathParse.win32("C:\\Users\\user\\file.txt");

Capabilities

Default Path Parser

Parses file paths using automatic platform detection based on process.platform.

/**
 * Parse a file path into its constituent parts using platform-aware logic
 * @param {string} pathString - The file path to parse
 * @returns {ParsedPath} Object containing parsed path components
 * @throws {TypeError} If pathString is not a string or is invalid
 */
function pathParse(pathString);

POSIX Path Parser

Explicitly parses paths using POSIX (Unix/Linux/macOS) conventions.

/**
 * Parse a file path using POSIX conventions
 * @param {string} pathString - The file path to parse  
 * @returns {ParsedPath} Object containing parsed path components
 * @throws {TypeError} If pathString is not a string or is invalid
 */
pathParse.posix(pathString);

Windows Path Parser

Explicitly parses paths using Windows conventions.

/**
 * Parse a file path using Windows conventions
 * @param {string} pathString - The file path to parse
 * @returns {ParsedPath} Object containing parsed path components  
 * @throws {TypeError} If pathString is not a string or is invalid
 */
pathParse.win32(pathString);

Types

/**
 * Parsed path object returned by all parse functions
 */
interface ParsedPath {
  /** The root portion of the path (e.g., "/" on POSIX, "C:\\" on Windows) */
  root: string;
  /** The directory path without trailing separator */
  dir: string;
  /** The filename including extension */
  base: string;
  /** The file extension including the dot (e.g., ".txt") */
  ext: string;
  /** The filename without extension */
  name: string;
}

Error Handling

All parse functions validate input and throw TypeError in the following cases:

  • Invalid input type: When pathString is not a string (null, undefined, number, object, boolean)
  • Invalid path format: When the path doesn't match expected format patterns
// Examples that throw TypeError
try {
  pathParse(null); // TypeError: Parameter 'pathString' must be a string, not object
  pathParse(123); // TypeError: Parameter 'pathString' must be a string, not number
  pathParse(undefined); // TypeError: Parameter 'pathString' must be a string, not undefined
} catch (err) {
  console.error(err.message);
}

Platform Behavior

  • Automatic Detection: The default export automatically detects the platform using process.platform === 'win32'
  • Windows Behavior: Recognizes drive letters, UNC paths, and Windows path separators (\\)
  • POSIX Behavior: Uses forward slashes (/) as path separators
  • Cross-Platform: Platform-specific methods allow parsing paths from different systems regardless of current platform

Usage Examples

Parsing Different Path Types

const pathParse = require("path-parse");

// File with extension
pathParse("/path/to/file.html");
// { root: "/", dir: "/path/to", base: "file.html", ext: ".html", name: "file" }

// File without extension  
pathParse("/path/to/README");
// { root: "/", dir: "/path/to", base: "README", ext: "", name: "README" }

// Directory path (trailing slash ignored)
pathParse("/path/to/directory/");
// { root: "/", dir: "/path/to", base: "directory", ext: "", name: "directory" }

// Root directory
pathParse("/");
// { root: "/", dir: "/", base: "", ext: "", name: "" }

// Windows UNC path
pathParse.win32("\\\\server\\share\\file.txt");
// { root: "\\\\server\\share\\", dir: "\\\\server\\share", base: "file.txt", ext: ".txt", name: "file" }

Cross-Platform Path Parsing

const pathParse = require("path-parse");

// Parse Windows path on any platform
const winPath = pathParse.win32("C:\\Users\\john\\Desktop\\document.pdf");
console.log(winPath.name); // "document"

// Parse POSIX path on any platform  
const posixPath = pathParse.posix("/home/john/Desktop/document.pdf");
console.log(posixPath.dir); // "/home/john/Desktop"