@guanghechen/path

Path utilities for file system operations with safe path resolution and workspace management. Provides strict path validation to prevent directory traversal attacks.

Install

npm
```
npm install --save @guanghechen/path
```
yarn
```
yarn add @guanghechen/path
```

Usage

PathResolver

Standard path resolver with safety checks:

import { PathResolver, pathResolver } from '@guanghechen/path'

// Use the default singleton
pathResolver.normalize('/foo/bar/../baz') // '/foo/baz'
pathResolver.basename('/foo/bar/file.txt') // 'file.txt'
pathResolver.dirname('/foo/bar/file.txt') // '/foo/bar'
pathResolver.join('/foo', 'bar', 'baz') // '/foo/bar/baz'
pathResolver.relative('/foo/bar', '/foo/baz') // '../baz'

// Check if path is within a root directory (safe from traversal)
pathResolver.isSafeRelative('/workspace', '/workspace/src/file.ts') // true
pathResolver.isSafeRelative('/workspace', '/etc/passwd') // false

// Safe relative path (throws if unsafe)
pathResolver.safeRelative('/workspace', '/workspace/src/file.ts') // 'src/file.ts'

// Safe resolve (resolve relative path within root)
pathResolver.safeResolve('/workspace', './src/file.ts') // '/workspace/src/file.ts'
pathResolver.safeResolve('/workspace', '../outside') // throws Error

// Create custom resolver with slash preference
const resolver = new PathResolver({ preferSlash: true })
resolver.relative('/foo/bar', '/foo/baz') // '../baz' (uses forward slashes on Windows)

WorkspacePathResolver

Workspace-scoped path operations:

import { WorkspacePathResolver, pathResolver } from '@guanghechen/path'

const workspace = new WorkspacePathResolver('/project/workspace', pathResolver)

// Check if path is within workspace
workspace.isSafePath('/project/workspace/src/index.ts') // true
workspace.isSafePath('/etc/passwd') // false

// Resolve relative paths within workspace
workspace.resolve('./src/index.ts') // '/project/workspace/src/index.ts'
workspace.resolve('package.json') // '/project/workspace/package.json'

// Get relative path from workspace root
workspace.relative('/project/workspace/src/index.ts') // 'src/index.ts'

UrlPathResolver

URL-style path resolution (forward slashes):

import { UrlPathResolver, urlPathResolver } from '@guanghechen/path'

urlPathResolver.normalize('/foo/bar/../baz') // '/foo/baz'
urlPathResolver.join('/api', 'users', '123') // '/api/users/123'

Locate Utilities

Find files by traversing up the directory tree:

import { locateNearestFilepath, findNearestFilepath } from '@guanghechen/path'

// Find nearest file by name(s)
const packageJson = locateNearestFilepath('/project/src/utils', 'package.json')
// Returns: '/project/package.json' (if exists)

// Find nearest file matching multiple names
const config = locateNearestFilepath('/project/src', [
  'tsconfig.json',
  'jsconfig.json',
])

// Find nearest file with custom predicate
const readme = findNearestFilepath('/project/src', (filepath) => {
  return filepath.toLowerCase().endsWith('readme.md')
})

Reference

homepage