@hyperfrontend/project-scope/core/path

path

Cross-platform path manipulation utilities that normalize between POSIX and native (Windows) separators.

Grouped into four concerns: joining (join, joinPosix, joinPath), normalization (normalizePath, normalizeToForwardSlashes, normalizeToNative, trailing-slash helpers), resolution (resolvePath, resolveRealPath, resolveFromWorkspace, relativePath, offsetFromRoot, isAbsolute), and segment extraction (getDirname, getBasename, getExtension, getFileNameWithoutExtension, parsePath, pathSegments).

All functions emit forward-slash paths by default to keep downstream string comparisons portable across operating systems.

API Reference

ƒ Functions

§function

ensureTrailingSlash(filePath: string): string

Append a forward slash to the path if not already present.

Parameters

Name	Type	Description
§filePath	`string`	Path to process

Returns

string

Path with trailing forward slash

Example

Ensuring trailing slash

ensureTrailingSlash('src/components')
// => 'src/components/'

ensureTrailingSlash('already/has/')
// => 'already/has/'

§function

getBasename(filePath: string, ext?: string): string

Get basename of path.

Parameters

Name	Type	Description
§filePath	`string`	Path to extract basename from
§ext?	`string`	Optional extension to strip

Returns

string

Basename of path

Example

Getting basename

getBasename('src/components/Button.tsx')
// => 'Button.tsx'

getBasename('src/components/Button.tsx', '.tsx')
// => 'Button'

§function

getDirname(filePath: string): string

Get directory name of path.

Parameters

Name	Type	Description
§filePath	`string`	Path to extract directory from

Returns

string

Directory name

Example

Getting directory name

getDirname('src/components/Button.tsx')
// => 'src/components'

§function

getExtension(filePath: string): string

Get file extension (including dot).

Parameters

Name	Type	Description
§filePath	`string`	Path to extract extension from

Returns

string

Extension including dot (e.g., '.ts')

Example

Getting file extension

getExtension('src/utils/helpers.ts')
// => '.ts'

getExtension('package.json')
// => '.json'

§function

getFileNameWithoutExtension(filePath: string): string

Get filename without extension.

Parameters

Name	Type	Description
§filePath	`string`	Path to extract name from

Returns

string

Filename without extension

Example

Getting filename without extension

getFileNameWithoutExtension('src/utils/helpers.ts')
// => 'helpers'

§function

isAbsolute(filePath: string): boolean

Check if path is absolute.

Parameters

Name	Type	Description
§filePath	`string`	Path to check

Returns

boolean

True if path is absolute

Example

Checking absolute path

isAbsolute('/workspace/src/index.ts')
// => true

isAbsolute('./src/index.ts')
// => false

§function

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

Join path segments. Uses platform-specific separators (e.g., / or \).

Parameters

Name	Type	Description
§...paths	`string[]`	Path segments to join

Returns

string

Joined path

Example

Joining path segments

const fullPath = join('src', 'components', 'Button.tsx')
// => 'src/components/Button.tsx' (or 'src\\components\\Button.tsx' on Windows)

§function

joinPath(...segments: string[]): string

Join path segments.

Parameters

Name	Type	Description
§...segments	`string[]`	Path segments to join

Returns

string

Joined path with normalized separators

Example

Joining path segments

joinPath('src', 'components', 'Button.tsx')
// => 'src/components/Button.tsx'

§function

joinPosix(...paths: string[]): string

Join path segments using POSIX separators (/). Always uses forward slashes regardless of platform.

Parameters

Name	Type	Description
§...paths	`string[]`	Path segments to join

Returns

string

Joined path with forward slashes

Example

Joining paths with forward slashes

const configPath = joinPosix('config', 'settings', 'app.json')
// => 'config/settings/app.json'

§function

normalizePath(filePath: string): string

Normalize path separators to forward slashes.

Parameters

Name	Type	Description
§filePath	`string`	Path to normalize

Returns

string

Normalized path with forward slashes

Example

Normalizing path separators

const path = normalizePath('src\\components\\Button.tsx')
// => 'src/components/Button.tsx'

§function

normalizeToForwardSlashes(filePath: string): string

Convert path separators to forward slashes using POSIX style. Resolves . and .. segments for cross-platform configuration.

Parameters

Name	Type	Description
§filePath	`string`	The input path to convert

Returns

string

Path with forward slashes and resolved segments

Example

Converting to forward slashes

const path = normalizeToForwardSlashes('./src/../lib/utils')
// => 'lib/utils'

§function

normalizeToNative(filePath: string): string

Convert path to use the operating system's native separator.

Parameters

Name	Type	Description
§filePath	`string`	The input path to convert

Returns

string

Path with native separators (backslash on Windows, forward slash elsewhere)

Example

Converting to native separators

const path = normalizeToNative('src/components/Button.tsx')
// => 'src\\components\\Button.tsx' on Windows
// => 'src/components/Button.tsx' on Unix

§function

offsetFromRoot(filePath: string): string

Calculate offset from root (e.g., "../../../").

Parameters

Name	Type	Description
§filePath	`string`	Path to calculate offset for

Returns

string

Relative offset path (e.g., "../../")

Example

Calculating offset from root

offsetFromRoot('libs/utils/src')
// => '../../../'

offsetFromRoot('apps')
// => '../'

§function

parsePath(filePath: string): ParsedPath

Parse path into components.

Parameters

Name	Type	Description
§filePath	`string`	Path to parse

Returns

ParsedPath

Parsed path components

Example

Parsing path components

const parsed = parsePath('/workspace/src/index.ts')
// => { root: '/', dir: '/workspace/src', base: 'index.ts', ext: '.ts', name: 'index' }

§function

pathSegments(filePath: string): string[]

Split path into segments.

Parameters

Name	Type	Description
§filePath	`string`	Path to split

Returns

string[]

Array of path segments

Example

Splitting path into segments

pathSegments('src/components/Button.tsx')
// => ['src', 'components', 'Button.tsx']

§function

relativePath(from: string, to: string): string

Compute the normalized path from source directory to target.

Parameters

Name	Type	Description
§from	`string`	Source path (base directory)
§to	`string`	Target path to reach

Returns

string

Relative path from source to target with forward slashes

Example

Computing relative path

relativePath('/workspace/src/utils', '/workspace/lib/helpers')
// => '../../lib/helpers'

§function

removeTrailingSlash(filePath: string): string

Strip any trailing forward or back slashes from a path.

Parameters

Name	Type	Description
§filePath	`string`	Path that may have trailing slashes

Returns

string

Path with trailing slashes removed

Example

Removing trailing slashes

removeTrailingSlash('src/components/')
// => 'src/components'

removeTrailingSlash('path\\to\\dir\\')
// => 'path\\to\\dir'

§function

resolveFromWorkspace(workspaceRoot: string, ...segments: string[]): string

Resolve path relative to workspace root.

Parameters

Name	Type	Description
§workspaceRoot	`string`	Workspace root directory
§...segments	`string[]`	Path segments relative to workspace

Returns

string

Resolved absolute path with normalized separators

Example

Resolving from workspace root

const configPath = resolveFromWorkspace('/workspace', 'config', 'app.json')
// => '/workspace/config/app.json'

§function

resolvePath(...segments: string[]): string

Resolve path segments to an absolute path.

Parameters

Name	Type	Description
§...segments	`string[]`	Path segments to resolve

Returns

string

Resolved absolute path with normalized separators

Example

Resolving to absolute path

const absPath = resolvePath('src', 'components', 'Button.tsx')
// => '/workspace/project/src/components/Button.tsx'

§function

resolveRealPath(filePath: string): string

Resolve symlinks to real path.

Parameters

Name	Type	Description
§filePath	`string`	Path to resolve

Returns

string

Real path or null if path doesn't exist

Example

Resolving symlinks

const realPath = resolveRealPath('./node_modules/.bin/tsc')
// => '/workspace/node_modules/typescript/bin/tsc'

◈ Interfaces

§interface

ParsedPath

Parsed path components.

Properties

§base:string—

Base name with extension

§dir:string—

Directory name

§ext:string—

File extension including dot

§name:string—

File name without extension

§root:string—

Root of the path (e.g., "/" or "C:\\")