Complete API documentation for @visulima/path including all methods and utilities.

API Reference

Complete API documentation for @visulima/path.

Imports

Main Module

// Default import
import path from "@visulima/path";

// Named imports
import {
    basename,
    delimiter,
    dirname,
    extname,
    format,
    isAbsolute,
    join,
    matchesGlob,
    normalize,
    normalizeString,
    parse,
    relative,
    resolve,
    sep,
    toNamespacedPath,
} from "@visulima/path";

Utilities

import {
    filename,
    normalizeAliases,
    resolveAlias,
    reverseResolveAlias,
    isRelative,
    isBinaryPath,
    toPath,
    isWindows,
} from "@visulima/path/utils";

Standard Path Methods

`basename(path: string, suffix?: string): string`

Get the last portion of a path.

Parameters:

path (string): The file path
suffix (string, optional): Extension to remove

Returns: The filename

Example:

basename("/home/user/file.txt");
// Returns: 'file.txt'

basename("/home/user/file.txt", ".txt");
// Returns: 'file'

`delimiter: string`

The platform-specific path delimiter (always : for consistency).

Example:

console.log(delimiter);
// Returns: ':'

`dirname(path: string): string`

Get the directory name of a path.

Parameters:

path (string): The file path

Returns: The directory portion

Example:

dirname("/home/user/documents/file.txt");
// Returns: '/home/user/documents'

`extname(path: string): string`

Get the file extension.

Parameters:

path (string): The file path

Returns: The extension (including the dot)

Example:

extname("file.txt");
// Returns: '.txt'

extname("archive.tar.gz");
// Returns: '.gz'

`format(pathObject: ParsedPath): string`

Create a path string from an object.

Parameters:

pathObject (ParsedPath): Path components

ParsedPath Interface:

interface ParsedPath {
    root?: string;
    dir?: string;
    base?: string;
    ext?: string;
    name?: string;
}

Returns: The formatted path string

Example:

format({
    dir: "/home/user",
    base: "file.txt",
});
// Returns: '/home/user/file.txt'

format({
    root: "/",
    dir: "/home/user",
    name: "file",
    ext: ".txt",
});
// Returns: '/home/user/file.txt'

`isAbsolute(path: string): boolean`

Determine if a path is absolute.

Parameters:

path (string): The path to check

Returns: true if absolute, false otherwise

Example:

isAbsolute("/home/user");
// Returns: true

isAbsolute("src/index.ts");
// Returns: false

`join(...paths: string[]): string`

Join path segments.

Parameters:

...paths (string[]): Path segments to join

Returns: The joined path

Example:

join("src", "components", "Button.tsx");
// Returns: 'src/components/Button.tsx'

join("/home", "user", "documents");
// Returns: '/home/user/documents'

`matchesGlob(path: string, pattern: string): boolean`

Check if a path matches a glob pattern.

Parameters:

path (string): The path to test
pattern (string): The glob pattern

Returns: true if matches, false otherwise

Example:

matchesGlob("src/index.ts", "src/**/*.ts");
// Returns: true

matchesGlob("test.js", "**/*.test.js");
// Returns: false

`normalize(path: string): string`

Normalize a path by resolving . and ...

Parameters:

path (string): The path to normalize

Returns: The normalized path

Example:

normalize("/foo/bar//baz/asdf/quux/..");
// Returns: '/foo/bar/baz/asdf'

normalize("src/../dist/./index.js");
// Returns: 'dist/index.js'

`normalizeString(path: string): string`

Low-level path normalization (internal use).

Parameters:

path (string): The path to normalize

Returns: The normalized path string

`parse(path: string): ParsedPath`

Parse a path into its components.

Parameters:

path (string): The path to parse

Returns: ParsedPath object

ParsedPath Type:

type ParsedPath = {
    root: string;    // Root (e.g., '/', 'C:/')
    dir: string;     // Directory path
    base: string;    // Filename with extension
    ext: string;     // Extension (including dot)
    name: string;    // Filename without extension
};

Example:

parse("/home/user/file.txt");
// Returns: {
//   root: '/',
//   dir: '/home/user',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file'
// }

`relative(from: string, to: string): string`

Get the relative path from one location to another.

Parameters:

from (string): The starting path
to (string): The destination path

Returns: The relative path

Example:

relative("/home/user/docs", "/home/user/pictures");
// Returns: '../pictures'

relative("/src", "/dist");
// Returns: '../dist'

`resolve(...paths: string[]): string`

Resolve path segments into an absolute path.

Parameters:

...paths (string[]): Path segments to resolve

Returns: The absolute path

Example:

resolve("src", "index.ts");
// Returns: '/current/working/directory/src/index.ts'

resolve("/home", "user", "documents");
// Returns: '/home/user/documents'

`sep: string`

The platform-specific path segment separator (always / for consistency).

Example:

console.log(sep);
// Returns: '/'

"src/components".split(sep);
// Returns: ['src', 'components']

`toNamespacedPath(path: string): string`

Convert path to namespaced path (Windows UNC path support).

Parameters:

path (string): The path to convert

Returns: The namespaced path

Example:

toNamespacedPath("C:/Users/file.txt");
// Returns: 'C:/Users/file.txt' (normalized)

Extra Utilities

`filename(path: string): string`

Get filename without extension.

Parameters:

path (string): The file path

Returns: Filename without extension

Example:

filename("/home/user/document.pdf");
// Returns: 'document'

filename("archive.tar.gz");
// Returns: 'archive.tar'

`normalizeAliases(aliases: Record<string, string>): Record<string, string>`

Normalize alias mappings for resolution.

Parameters:

aliases (Record<string, string>): Alias mappings

Returns: Normalized aliases

Example:

normalizeAliases({
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
});
// Returns: Sorted and resolved alias mappings

`resolveAlias(path: string, aliases: Record<string, string>): string`

Resolve a path using alias mappings.

Parameters:

path (string): The path to resolve
aliases (Record<string, string>): Alias mappings

Returns: The resolved path

Example:

const aliases = { "@/*": "./src/*" };
resolveAlias("@/config/app", aliases);
// Returns: './src/config/app'

`reverseResolveAlias(path: string, aliases: Record<string, string>): string`

Convert absolute path back to alias format.

Parameters:

path (string): The absolute path
aliases (Record<string, string>): Alias mappings

Returns: The aliased path or original if no match

Example:

const aliases = { "@/*": "./src/*" };
reverseResolveAlias("./src/config/app", aliases);
// Returns: '@/config/app'

`isRelative(path: string): boolean`

Check if a path is relative.

Parameters:

path (string): The path to check

Returns: true if relative, false otherwise

Example:

isRelative("./src/index.ts");
// Returns: true

isRelative("/home/user/file.txt");
// Returns: false

`isBinaryPath(path: string): boolean`

Check if a file path points to a binary file.

Parameters:

path (string): The file path

Returns: true if binary file, false otherwise

Example:

isBinaryPath("image.png");
// Returns: true

isBinaryPath("document.json");
// Returns: false

`toPath(urlOrPath: string): string`

Convert file URL to path or return path as-is.

Parameters:

urlOrPath (string): File URL or path string

Returns: The path string

Example:

toPath("file:///home/user/file.txt");
// Returns: '/home/user/file.txt'

toPath("/home/user/file.txt");
// Returns: '/home/user/file.txt'

`isWindows(): boolean`

Check if running on Windows platform.

Returns: true if Windows, false otherwise

Example:

if (isWindows()) {
    console.log("Running on Windows");
}

TypeScript Types

`Path`

The main path module type:

import type { Path } from "@visulima/path";

const path: Path = await import("@visulima/path");

`ParsedPath`

Object returned by parse():

interface ParsedPath {
    root: string;
    dir: string;
    base: string;
    ext: string;
    name: string;
}

Compatibility

vs. Node.js `path`

All methods are compatible with Node.js path API:

Method	@visulima/path	Node.js path
`basename()`	✅	✅
`delimiter`	✅	✅
`dirname()`	✅	✅
`extname()`	✅	✅
`format()`	✅	✅
`isAbsolute()`	✅	✅
`join()`	✅	✅
`normalize()`	✅	✅
`parse()`	✅	✅
`relative()`	✅	✅
`resolve()`	✅	✅
`sep`	✅	✅
`toNamespacedPath()`	✅	✅
`posix`	⚠️ (stub)	✅
`win32`	⚠️ (stub)	✅

Note: posix and win32 are exported but point to the same normalized implementation.

Extra Methods

Methods not in Node.js path:

Method	Description
`matchesGlob()`	Glob pattern matching
`filename()`	Get name without extension
`normalizeAliases()`	Prepare alias mappings
`resolveAlias()`	Resolve path aliases
`reverseResolveAlias()`	Convert back to alias
`isRelative()`	Check if path is relative
`isBinaryPath()`	Check if file is binary
`toPath()`	Convert file URL to path
`isWindows()`	Check if on Windows

API Reference

On this page

Contribute to our work and keep us going

Ready to help us out?

Submit a pull request

Good first issues