@hyperfrontend/project-scope/core/pathpath
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
Reports whether
The lexical check runs first and rejects
candidate resolves to a location inside root. The lexical check runs first and rejects
.. traversal and absolute escapes with no filesystem access at all, so a hostile path is never stat-ed. Only a path that is already lexically contained is then resolved through symlinks, so an in-tree link cannot tunnel outside the root, and that realpath touches only paths the caller would legitimately read anyway.Parameters
Returns
booleanTrue when the candidate is the root or contained within it.
Example
Confining a resolved import target
isWithinRoot('/project', '/project/src/index.ts') // true
isWithinRoot('/project', '/project/../etc/passwd') // falseAppend a forward slash to the path if not already present.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to process |
Returns
stringPath with trailing forward slash
Example
Ensuring trailing slash
ensureTrailingSlash('src/components')
// => 'src/components/'
ensureTrailingSlash('already/has/')
// => 'already/has/'Get basename of path.
Parameters
Returns
stringBasename of path
Example
Getting basename
getBasename('src/components/Button.tsx')
// => 'Button.tsx'
getBasename('src/components/Button.tsx', '.tsx')
// => 'Button'Get directory name of path.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to extract directory from |
Returns
stringDirectory name
Example
Getting directory name
getDirname('src/components/Button.tsx')
// => 'src/components'Get file extension (including dot).
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to extract extension from |
Returns
stringExtension including dot (e.g., '.ts')
Example
Getting file extension
getExtension('src/utils/helpers.ts')
// => '.ts'
getExtension('package.json')
// => '.json'Get filename without extension.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to extract name from |
Returns
stringFilename without extension
Example
Getting filename without extension
getFileNameWithoutExtension('src/utils/helpers.ts')
// => 'helpers'Check if path is absolute.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to check |
Returns
booleanTrue if path is absolute
Example
Checking absolute path
isAbsolute('/workspace/src/index.ts')
// => true
isAbsolute('./src/index.ts')
// => falseJoin path segments. Uses platform-specific separators (e.g., / or \).
Parameters
| Name | Type | Description |
|---|---|---|
§...paths | string[ | Path segments to join |
Returns
stringJoined path
Example
Joining path segments
const fullPath = join('src', 'components', 'Button.tsx')
// => 'src/components/Button.tsx' (or 'src\\components\\Button.tsx' on Windows)Join path segments.
Parameters
| Name | Type | Description |
|---|---|---|
§...segments | string[ | Path segments to join |
Returns
stringJoined path with normalized separators
Example
Joining path segments
joinPath('src', 'components', 'Button.tsx')
// => 'src/components/Button.tsx'Join path segments using POSIX separators (/). Always uses forward slashes regardless of platform.
Parameters
| Name | Type | Description |
|---|---|---|
§...paths | string[ | Path segments to join |
Returns
stringJoined path with forward slashes
Example
Joining paths with forward slashes
const configPath = joinPosix('config', 'settings', 'app.json')
// => 'config/settings/app.json'Normalize path separators to forward slashes.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to normalize |
Returns
stringNormalized path with forward slashes
Example
Normalizing path separators
const path = normalizePath('src\\components\\Button.tsx')
// => 'src/components/Button.tsx'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
stringPath with forward slashes and resolved segments
Example
Converting to forward slashes
const path = normalizeToForwardSlashes('./src/../lib/utils')
// => 'lib/utils'Convert path to use the operating system's native separator.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | The input path to convert |
Returns
stringPath 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 UnixCalculate offset from root (e.g., "../../../").
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to calculate offset for |
Returns
stringRelative offset path (e.g., "../../")
Example
Calculating offset from root
offsetFromRoot('libs/utils/src')
// => '../../../'
offsetFromRoot('apps')
// => '../'Parse path into components.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to parse |
Returns
ParsedPathParsed path components
Example
Parsing path components
const parsed = parsePath('/workspace/src/index.ts')
// => { root: '/', dir: '/workspace/src', base: 'index.ts', ext: '.ts', name: 'index' }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']Compute the normalized path from source directory to target.
Returns
stringRelative path from source to target with forward slashes
Example
Computing relative path
relativePath('/workspace/src/utils', '/workspace/lib/helpers')
// => '../../lib/helpers'Strip any trailing forward or back slashes from a path.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path that may have trailing slashes |
Returns
stringPath with trailing slashes removed
Example
Removing trailing slashes
removeTrailingSlash('src/components/')
// => 'src/components'
removeTrailingSlash('path\\to\\dir\\')
// => 'path\\to\\dir'Resolve path relative to workspace root.
Parameters
Returns
stringResolved absolute path with normalized separators
Example
Resolving from workspace root
const configPath = resolveFromWorkspace('/workspace', 'config', 'app.json')
// => '/workspace/config/app.json'Resolve path segments to an absolute path.
Parameters
| Name | Type | Description |
|---|---|---|
§...segments | string[ | Path segments to resolve |
Returns
stringResolved absolute path with normalized separators
Example
Resolving to absolute path
const absPath = resolvePath('src', 'components', 'Button.tsx')
// => '/workspace/project/src/components/Button.tsx'Resolve symlinks to real path.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to resolve |
Returns
stringReal path or null if path doesn't exist
Example
Resolving symlinks
const realPath = resolveRealPath('./node_modules/.bin/tsc')
// => '/workspace/node_modules/typescript/bin/tsc'