Path Parsing

/**
 * Returns the directory portion of a path
 * @param {string} path - Path to extract directory from
 * @returns {string} Directory portion of path
 */
function dirname(path: string): string;

const path = require("path");

// Extract directory from file path
path.dirname("/users/john/document.txt");
// Result: "/users/john"

path.dirname("/users/john/");
// Result: "/users"

// Handle relative paths
path.dirname("docs/readme.md");
// Result: "docs"

// No directory returns "."
path.dirname("file.txt");
// Result: "."

// Root directory
path.dirname("/");
// Result: "/"

// Windows paths
path.win32.dirname("C:\\Users\\John\\file.txt");
// Result: "C:\\Users\\John"

path.win32.dirname("C:\\");
// Result: "C:\\"

// UNC paths
path.win32.dirname("\\\\server\\share\\file.txt");
// Result: "\\\\server\\share"

/**
 * Returns the last portion of a path
 * @param {string} path - Path to extract basename from
 * @param {string} [ext] - Optional extension to remove
 * @returns {string} Basename of path
 */
function basename(path: string, ext?: string): string;

const path = require("path");

// Extract filename from path
path.basename("/users/john/document.txt");
// Result: "document.txt"

// Remove specific extension
path.basename("/users/john/document.txt", ".txt");
// Result: "document"

// Extension must match exactly
path.basename("/users/john/document.txt", ".md");
// Result: "document.txt" (extension doesn't match)

// Directory paths
path.basename("/users/john/");
// Result: "john"

// Handle relative paths
path.basename("docs/readme.md");
// Result: "readme.md"

// Root path
path.basename("/");
// Result: ""

// Windows paths
path.win32.basename("C:\\Users\\John\\file.txt");
// Result: "file.txt"

path.win32.basename("C:\\Users\\John\\", ".John");
// Result: "John" (if extension matches)

/**
 * Returns the extension of a path
 * @param {string} path - Path to extract extension from
 * @returns {string} Extension including leading dot, or empty string
 */
function extname(path: string): string;

const path = require("path");

// Extract file extension
path.extname("document.txt");
// Result: ".txt"

path.extname("archive.tar.gz");
// Result: ".gz"

// No extension
path.extname("readme");
// Result: ""

// Hidden files starting with dot
path.extname(".gitignore");
// Result: ""

path.extname(".config.json");
// Result: ".json"

// Directory paths
path.extname("/users/john/");
// Result: ""

// Complex paths
path.extname("/users/john.doe/document.pdf");
// Result: ".pdf"

/**
 * Parses a path string into components
 * @param {string} pathString - Path to parse
 * @returns {ParsedPath} Object with path components
 * @throws {TypeError} If pathString is not a string
 */
function parse(pathString: string): ParsedPath;

interface ParsedPath {
  /** Root portion of path (e.g., '/', 'C:\\') */
  root: string;
  /** Directory portion of path */
  dir: string;
  /** File name including extension */
  base: string;
  /** File extension including leading dot */
  ext: string;
  /** File name without extension */
  name: string;
}

const path = require("path");

// Parse a complete file path
const parsed = path.parse("/users/john/document.txt");
console.log(parsed);
// Result: {
//   root: "/",
//   dir: "/users/john", 
//   base: "document.txt",
//   ext: ".txt",
//   name: "document"
// }

// Parse relative path
const relative = path.parse("docs/readme.md");
// Result: {
//   root: "",
//   dir: "docs",
//   base: "readme.md", 
//   ext: ".md",
//   name: "readme"
// }

// Parse directory path
const directory = path.parse("/users/john/");
// Result: {
//   root: "/",
//   dir: "/users",
//   base: "john",
//   ext: "",
//   name: "john"
// }

// Windows path parsing
const winParsed = path.win32.parse("C:\\Users\\John\\file.txt");
// Result: {
//   root: "C:\\",
//   dir: "C:\\Users\\John",
//   base: "file.txt",
//   ext: ".txt", 
//   name: "file"
// }

// UNC path parsing
const uncParsed = path.win32.parse("\\\\server\\share\\file.txt");
// Result: {
//   root: "\\\\server\\share\\",
//   dir: "\\\\server\\share",
//   base: "file.txt",
//   ext: ".txt",
//   name: "file"
// }

/**
 * Formats a path object into a path string
 * @param {PathObject} pathObject - Object with path components
 * @returns {string} Formatted path string
 * @throws {TypeError} If pathObject is not an object or if root is not string/undefined
 */
function format(pathObject: PathObject): string;

interface PathObject {
  /** Root portion of path */
  root?: string;
  /** Directory portion of path */
  dir?: string;
  /** File name including extension */
  base?: string;
  /** File name without extension (used with ext if base not provided) */
  name?: string;
  /** File extension (used with name if base not provided) */
  ext?: string;
}

const path = require("path");

// Format with dir and base
path.format({
  dir: "/users/john",
  base: "document.txt"
});
// Result: "/users/john/document.txt"

// Format with root, name, and ext
path.format({
  root: "/",
  name: "document",
  ext: ".txt"
});
// Result: "/document.txt"

// Dir takes precedence over root
path.format({
  root: "/usr",
  dir: "/users/john",
  base: "file.txt"
});
// Result: "/users/john/file.txt"

// Base takes precedence over name + ext
path.format({
  dir: "/users",
  base: "document.txt",
  name: "readme",
  ext: ".md"
});
// Result: "/users/document.txt"

// Minimal object
path.format({
  base: "file.txt"
});
// Result: "file.txt"

// Windows formatting
path.win32.format({
  root: "C:\\",
  dir: "C:\\Users\\John", 
  base: "file.txt"
});
// Result: "C:\\Users\\John\\file.txt"

// POSIX formatting
path.posix.format({
  root: "/",
  dir: "/usr/local",
  base: "bin"
});
// Result: "/usr/local/bin"

// Throws TypeError for invalid pathObject
try {
  path.format("not an object");
} catch (error) {
  console.log(error.message); // "Parameter 'pathObject' must be an object..."
}

// Throws TypeError for invalid root type
try {
  path.format({ root: 123 });
} catch (error) {
  console.log(error.message); // "'pathObject.root' must be a string or undefined..."
}