@synstack/path
Version:
Advanced path manipulation utilities
144 lines (104 loc) • 3.63 kB
Markdown
# /path
Advanced path manipulation utilities
## What is it for?
This package provides a strongly-typed interface for working with file system paths. It ensures type safety between absolute and relative paths while offering comprehensive utilities for path manipulation, extension handling, and MIME type detection:
```typescript
import { path } from "@synstack/path";
// Type-safe path resolution
const absolutePath = path.resolve("/base", "subdir", "file.txt");
console.log(absolutePath); // "/base/subdir/file.txt"
// Path type checking
const isAbs = path.isAbsolute("/absolute/path"); // true
const isAbs2 = path.isAbsolute("relative/path"); // false
// Path manipulation
const dirName = path.dirname("/path/to/file.txt"); // "/path/to"
const relativePath = path.relative("/base/dir", "/base/dir/subdir/file.txt"); // "subdir/file.txt"
```
## Installation
```bash
# Using npm
npm install /path
# Using yarn
yarn add /path
# Using pnpm
pnpm add /path
```
## Features
### Type-Safe Paths
The package provides type definitions for different kinds of paths:
```typescript
import type { AbsolutePath, RelativePath, AnyPath } from "@synstack/path";
// Type-safe path handling
function processPath(path: AbsolutePath) {
// Only absolute paths are accepted
}
function processRelative(path: RelativePath) {
// Only relative paths are accepted
}
function processAny(path: AnyPath) {
// Any path type is accepted
}
```
### Path Operations
#### Path Resolution and Validation
```typescript
import { path } from "@synstack/path";
// Resolve paths
const abs = path.resolve("relative/path"); // Converts to absolute path
const isAbs = path.isAbsolute("/some/path"); // Check if path is absolute
const dir = path.dirname("/path/to/file.txt"); // Get directory name
```
#### Path Relationships
```typescript
// Check path containment
path.isInPath("/base", "/base/subdir"); // true
path.isInPath("/base", "/other"); // false
// Create relative paths
path.relative("/base/dir", "/base/dir/subdir/file.txt"); // "subdir/file.txt"
```
#### Path Joining and Manipulation
```typescript
// Join paths
path.join("/absolute", "path", "file.txt"); // "/absolute/path/file.txt"
path.join("relative", "path", "file.txt"); // "relative/path/file.txt"
// Remove relative indicators
path.removeRelativeIndicator("./file.txt"); // "file.txt"
```
#### File Extensions
```typescript
// Add or ensure extensions
path.addMissingExtension("/path/to/file", "txt"); // "/path/to/file.txt"
path.ensureFileExtension("/path/to/file", ".txt"); // "/path/to/file.txt"
// extension can be provided without leading dot
path.ensureFileExtension("/path/to/file", "txt"); // "/path/to/file.txt"
// Get file information
path.filename("/path/to/file.txt"); // "file.txt"
path.filenameWithoutExtension("/path/to/file.txt"); // "file"
path.fileExtension("/path/to/file.txt"); // ".txt"
```
#### MIME Types
```typescript
// Get MIME type from path
path.mimeType("/path/to/image.png"); // "image/png"
path.mimeType("/path/to/unknown"); // null
```
#### ES Module Support
```typescript
// Convert import URLs to file system paths
const dirPath = path.importUrlToAbsolutePath(import.meta.url);
```
### Error Handling
The package includes custom error types for specific path-related issues:
```typescript
import { PathNotInCwdException } from "@synstack/path";
try {
// Operations that might throw PathNotInCwdException
} catch (error) {
if (error instanceof PathNotInCwdException) {
console.error(
"Path operation outside current working directory:",
error.message,
);
}
}
```