Path class

Concrete path that layers filesystem I/O on top of PurePath semantics.

Signature:

export declare class Path extends PurePath

Extends: PurePath

Remarks

Mirrors CPython’s `pathlib.Path`. The runtime selects PosixPath or WindowsPath during construction so the instance can call into Node’s filesystem APIs safely. Each I/O method provides an asynchronous default that resolves to a promise, alongside a synchronous companion suffixed with Sync, preserving ergonomic parity with the reference implementation while embracing JavaScript’s async-first patterns.

Path also introduces policy-driven behaviour for relative computations to accommodate module-resolution workflows common in the JS ecosystem. The lexical defaults remain faithful to CPython.

Example

Reading text from a sibling file

import { Path } from "pathlib-ts";

const readme = new Path("./README.md");
const contents = await readme.readText();

console.log(contents.slice(0, 40));

Properties

Property	Modifiers	Type	Description
info	`readonly`	PathInfo \| DirEntryInfo	Provides cached stat-like information gathered during directory iteration.
infoCache?	`protected`	PathInfo \| DirEntryInfo	(Optional)
isRelativeTo		PathIsRelativeToFn	Determines whether this path can be expressed relative to another according to the selected policy.
relativeTo		PathRelativeToFn	Return the relative path to another path identified by the passed arguments. If the operation is not possible (because this is not related to the other path), raise ValueError.

Methods

Method	Modifiers	Description
absolute()		Return an absolute version of this path without resolving symlinks.
absoluteSync()		Return an absolute path without resolving symlinks, synchronously.
copy(target, options)		Recursively copy this file or directory tree to the destination.
copySync(target, options)		Recursively copy the file or directory tree to the destination synchronously.
cwd()	`static`	Return a new path pointing to the current working directory.
cwdSync()	`static`	Create a Path pointing to the current working directory synchronously.
exists(options)		Resolves to `true` when the path exists.
existsSync(options)		Checks for path existence synchronously.
expandUser()		Return a new path with expanded `~` and `~user` constructs.
expandUserSync()		Expand leading `~` markers synchronously.
glob(pattern, options)		Globs files within this subtree asynchronously. Iterate over this subtree and yields all existing files (of any kind, including directories) matching the given relative pattern.
globSync(pattern, options)		Performs a blocking glob search relative to this subtree and yield all existing files (of any kind, including directories) matching the given relative pattern.
home()	`static`	Return a new path pointing to the user’s home directory.
homeSync()	`static`	Return the user’s home directory synchronously.
isDir(options)		Resolves to `true` when the path points to a directory.
isDirSync(options)		Tests whether the path is a directory synchronously.
isFile(options)		Resolves to `true` when the path points to a regular file (`also` true for symlinks pointing to regular files).
isFileSync(options)		Tests whether the path is a regular file synchronously.
isSymlink()		Resolves to `true` when the path is a symbolic link.
isSymlinkSync()		Determines synchronously whether the path points to a symbolic link.
iterdir(options)		Resolves directory entries asynchronously as Path instances or native Dirents.
iterdir(options)
iterdirStream(options)		Streams directory entries lazily using async iteration without materialising the entire directory listing.
iterdirStream(options)
iterdirStream(options)
iterdirStreamSync(options)		Streams directory entries synchronously using generators.
iterdirStreamSync(options)
iterdirStreamSync(options)
iterdirSync(options)		Enumerates directory contents synchronously.
iterdirSync(options)
lstat()		Asynchronously retrieves metadata about a symlink rather than its target. Like Path.stat(), except if the path points to a symlink, the symlink’s status information is returned, rather than its target’s.
lstatSync()		Retrieves symlink metadata synchronously.
mkdir(options)		Create a directory with optional `parents` and `existOk` semantics.
mkdirSync(options)		Create a directory synchronously with optional `parents` and `existOk`.
open(mode)		Open the file with the given mode and return a Node.js stream-like handle.
openSync(mode)		Open the file with the given mode using the synchronous helper.
readBytes()		Read the file as raw bytes and return a promise that resolves to the binary contents of the pointed-to file as a bytes object.
readBytesSync()		Read the file as raw bytes.
readlink()		Return the path to which the symbolic link points.
readlinkSync()		Read the target of a symbolic link synchronously.
readText(encoding)		Read the file as text using the provided encoding and return a promise that resolves to the decoded contents of pointed-to file as a string.
readTextSync(encoding)		Read the file as text using the provided encoding.
rename(target)		Rename this path to the given target and return the new path instance.
renameSync(target)		Rename the file or directory to a new target synchronously.
replace(target)		Replace the target path, overwriting it if necessary, and return the new Path.
replaceSync(target)		Replace the file or directory synchronously, overwriting the destination.
resolve()		Make the path absolute, resolving symlinks and normalizing segments.
resolveSync()		Resolve the path synchronously, following symlinks and normalizing.
rglob(pattern, options)		Asynchronously performs a recursive glob in this subtree, and yields all existing files (of any kind, including directories) matching the given relative pattern.
rglobSync(pattern, options)		Performs a recursive glob search synchronously.
rmdir()		Remove this directory; the directory must already be empty.
rmdirSync()		Remove the directory synchronously.
stat(options)		Returns filesystem metadata asynchronously.
statSync(options)		Retrieves filesystem metadata synchronously.
touch(options)		Create the file or update its timestamps with optional mode overrides.
touchSync(options)		Create the file or update its timestamps synchronously.
unlink(options)		Remove this file or link. Use Path.rmdir() for directories.
unlinkSync(options)		Remove the file or link synchronously.
walk(options)		Walk the directory tree from this directory.
walkSync(options)		Traverse the directory tree synchronously and return the walk tuples.
withSegments(this, segments)
writeBytes(data)		Asynchronously write raw bytes to the file. An existing file of the same name is overwritten.
writeBytesSync(data)		Write raw bytes to the file. An existing file of the same name is overwritten.
writeText(data, encoding)		Asynchronously write the given text to the file using the provided encoding. An existing file of the same name is overwritten.
writeTextSync(data, encoding)		Write the given text to the file using the provided encoding. An existing file of the same name is overwritten.