الإبلاغ عن مشكلة

node:path

Node.js path module, resolvable via both ESM import and CommonJS require. Provides path manipulation utilities for both POSIX and Windows, ported bug-for-bug from Node.js. require("node:path") returns the flavour matching the host platform; path.posix and path.win32 expose either flavour explicitly.

Available methods

MethodDescription
basename(path, suffix?)Return the last portion of a path, optionally stripping a suffix
dirname(path)Return the directory portion of a path
extname(path)Return the extension of the path (including the leading dot)
format(pathObject)Compose a path from {root, dir, base, name, ext}
isAbsolute(path)Test whether a path is absolute
join(...paths)Join segments with the separator and normalise
normalize(path)Resolve . and .. segments, collapse repeated separators
parse(path)Decompose a path into {root, dir, base, name, ext}
relative(from, to)Compute a relative path from from to to
resolve(...paths)Resolve a sequence of segments into an absolute path
toNamespacedPath(path)POSIX no-op; Windows converts to an extended-length (\\?\) path
matchesGlob(path, pattern)Test whether path matches the glob pattern

Attributes

AttributePOSIXWindows
sep/\
delimiter:;
The posix and win32 accessors return the corresponding flavour and are reachable from either one (for example, path.win32.posix.sep === "/").

Flavours — POSIX and Windows

path.win32 implements the full Windows surface: drive-letter roots (C:\), UNC paths (\\server\share), device roots (\\?\, \\.\), reserved device names (CON, COM1:, …), and mixed \// separators. path.posix uses / exclusively. The default export of node:path is the flavour matching the host.

Behaviour notes — parse / format / relative / resolve

parse(path)

Returns a plain object with five enumerable, writable, configurable properties (compatible with Object.keys, JSON.stringify, and spread syntax).

  • A leading-dot basename (e.g. .bashrc) has no extension: name = ".bashrc", ext = "".
  • All-dots basenames (.., ...) have no extension.
  • The last dot wins for multi-extension files: parse("archive.tar.gz") gives name = "archive.tar", ext = ".gz".
  • Trailing separators are stripped before determining base — parse("/foo/bar/") gives base = "bar", dir = "/foo".
  • The bare root "/" parses as root = "/", dir = "/", empty base/name/ext.

format(pathObject)

Inverse of parse. All object fields are optional (missing fields treated as empty strings). A non-object argument (null, undefined, primitive, array, or function) throws a TypeError, as in Node.

  • dir takes precedence over root — if both are present, root is ignored.
  • base takes precedence over name + ext — the latter only apply when base is empty. A bare ext without a leading dot is prefixed automatically ({ name: "file", ext: "txt" } → "file.txt").
  • When the effective directory equals root (e.g. both "/"), no extra separator is inserted — avoids producing //file for root-level paths.

relative(from, to)

Computes a relative path from from to to. Both inputs are resolved against the working directory and normalised before comparison, matching Node's semantics for absolute, relative, and mixed inputs.

resolve(...paths)

Processes segments right-to-left, prepending each until an absolute path is formed; any remaining gap is filled from the working directory. On Windows, drive-letter and UNC roots are honoured. The working directory is sourced from user.dir, which equals process.cwd() at startup.

toNamespacedPath(path)

On POSIX, returns the input unchanged. On Windows, resolves the path and converts drive-letter and UNC roots to the extended-length \\?\ form. A non-string argument is returned unchanged, as in Node.

matchesGlob(path, pattern)

Tests whether path matches the glob pattern, using the same minimatch engine and options as Node. Supports wildcards (, ?), globstar (*), character classes including POSIX classes ([[:alpha:]]), brace expansion ({a,b}, {1..9}), and extglobs (@(…), +(…), *(…), ?(…), !(…)).

Examples

javascript
const path = require("node:path");

// parse / format round-trip
const parsed = path.parse("/home/user/dir/file.txt");
// → { root: "/", dir: "/home/user/dir", base: "file.txt",
//     name: "file", ext: ".txt" }

path.format(parsed);
// → "/home/user/dir/file.txt"

// resolve / relative
path.resolve("/foo/bar", "../baz");  // → "/foo/baz"
path.relative("/a/b/c", "/a/d");     // → "../../d"

// Windows flavour (available on any host)
path.win32.normalize("C:\\temp\\\\foo\\..\\");  // → "C:\\temp\\"
path.win32.join("C:\\foo", "bar", "baz\\");      // → "C:\\foo\\bar\\baz\\"
path.win32.toNamespacedPath("C:\\foo");          // → "\\\\?\\C:\\foo"

// extension edge cases
path.parse(".bashrc").ext;          // → ""
path.parse("archive.tar.gz").ext;   // → ".gz"

// glob matching
path.matchesGlob("src/a/b.js", "src<<>>*.js");  // → true
path.matchesGlob("a.test.js", "!(*.test).js");  // → false

See also

  • Node.js upstream: