0
# Path Utilities
1

2
Utilities for path manipulation and normalization, providing cross-platform path handling for module resolution and file system operations in tsickle transformations.
3

4
## Capabilities
5

6
### Path Testing
7

8
Functions for testing path properties and formats.
9

10
```typescript { .api }
11
/**
12
 * Tests if a path is absolute
13
 */
14
function isAbsolute(path: string): boolean;
15
```
16

17
**Usage Examples:**
18

19
```typescript
20
import { isAbsolute } from "tsickle";
21

22
console.log(isAbsolute("/usr/local/file.ts"));     // true (Unix)
23
console.log(isAbsolute("C:\\Windows\\file.ts"));   // true (Windows)  
24
console.log(isAbsolute("./relative/file.ts"));     // false
25
console.log(isAbsolute("relative/file.ts"));       // false
26
```
27

28
### Path Manipulation
29

30
Functions for joining, resolving, and manipulating file paths.
31

32
```typescript { .api }
33
/**
34
 * Joins two path segments
35
 */
36
function join(p1: string, p2: string): string;
37

38
/**
39
 * Gets directory name from path
40
 */
41
function dirname(path: string): string;
42

43
/**
44
 * Gets relative path from base to target
45
 */
46
function relative(base: string, rel: string): string;
47

48
/**
49
 * Normalizes path separators and removes redundant segments
50
 */
51
function normalize(path: string): string;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { join, dirname, relative, normalize } from "tsickle";
58

59
// Join path segments
60
const fullPath = join("/project/src", "utils/helpers.ts");
61
// Result: "/project/src/utils/helpers.ts"
62

63
// Get directory name
64
const dir = dirname("/project/src/app.ts");
65
// Result: "/project/src"
66

67
// Get relative path
68
const relPath = relative("/project/src", "/project/src/utils/helpers.ts");
69
// Result: "utils/helpers.ts"
70

71
// Normalize path
72
const normalized = normalize("/project/src/../lib/./file.ts");
73
// Result: "/project/lib/file.ts"
74
```
75

76
## Cross-Platform Compatibility
77

78
The path utilities handle cross-platform differences automatically:
79

80
### Path Separators
81

82
```typescript
83
import { join, normalize } from "tsickle";
84

85
// Works on both Unix and Windows
86
const path1 = join("src", "components");  // "src/components" or "src\\components"
87
const path2 = normalize("src\\..\\lib");  // "lib" (normalized regardless of input separators)
88
```
89

90
### Absolute Path Detection
91

92
```typescript
93
import { isAbsolute } from "tsickle";
94

95
// Correctly identifies absolute paths on different platforms
96
console.log(isAbsolute("/usr/local"));        // true on Unix
97
console.log(isAbsolute("C:\\Program Files")); // true on Windows  
98
console.log(isAbsolute("\\\\server\\share")); // true on Windows (UNC)
99
```
100

101
## Module Resolution Integration
102

103
These utilities integrate with tsickle's module resolution system:
104

105
### Converting File Paths to Module Names
106

107
```typescript
108
import { relative, normalize } from "tsickle";
109

110
function filePathToModuleName(rootDir: string, filePath: string): string {
111
  // Get relative path from root
112
  const relPath = relative(rootDir, filePath);
113
  
114
  // Normalize and convert to module name
115
  const normalized = normalize(relPath);
116
  return normalized
117
    .replace(/\.tsx?$/, '')  // Remove TypeScript extensions
118
    .replace(/[/\\]/g, '.')  // Convert path separators to dots
119
    .replace(/^\.+/, '');    // Remove leading dots
120
}
121

122
// Usage
123
const moduleName = filePathToModuleName(
124
  "/project/src",
125
  "/project/src/components/Button.tsx"
126
);
127
// Result: "components.Button"
128
```
129

130
### Working with Import Paths
131

132
```typescript
133
import { isAbsolute, join, dirname } from "tsickle";
134

135
function resolveImportPath(currentFile: string, importPath: string): string {
136
  if (isAbsolute(importPath)) {
137
    return importPath;
138
  }
139
  
140
  // Resolve relative import
141
  const currentDir = dirname(currentFile);
142
  return join(currentDir, importPath);
143
}
144

145
// Usage
146
const resolved = resolveImportPath(
147
  "/project/src/app.ts",
148
  "./utils/helpers"
149
);
150
// Result: "/project/src/utils/helpers"
151
```
152

153
## Error Handling
154

155
The path utilities include error handling for common edge cases:
156

157
### Invalid Path Handling
158

159
```typescript
160
import { normalize, join } from "tsickle";
161

162
// Handles empty paths gracefully
163
console.log(normalize(""));     // ""
164
console.log(join("", "file"));  // "file"
165

166
// Handles null/undefined inputs
167
try {
168
  normalize(null as any);  // May throw or return safe default
169
} catch (error) {
170
  console.error("Invalid path input");
171
}
172
```
173

174
### Path Traversal Protection
175

176
```typescript
177
import { normalize, relative } from "tsickle";
178

179
function safePath(basePath: string, userPath: string): string {
180
  const normalized = normalize(userPath);
181
  const rel = relative(basePath, join(basePath, normalized));
182
  
183
  // Ensure path doesn't escape base directory
184
  if (rel.startsWith('..')) {
185
    throw new Error("Path traversal not allowed");
186
  }
187
  
188
  return join(basePath, rel);
189
}
190
```
191

192
## Performance Considerations
193

194
The path utilities are optimized for performance:
195

196
- **String operations**: Efficient string manipulation for path processing
197
- **Caching**: Results can be cached when processing many paths with same base
198
- **Memory efficiency**: Minimal string allocation for temporary processing
199
- **Platform detection**: One-time platform detection for separator handling
200

201
## Common Patterns
202

203
### Build System Integration
204

205
```typescript
206
import { relative, normalize, dirname } from "tsickle";
207

208
class BuildPathManager {
209
  constructor(private rootDir: string, private outDir: string) {}
210
  
211
  getOutputPath(inputPath: string): string {
212
    // Get relative path from root
213
    const relativePath = relative(this.rootDir, inputPath);
214
    
215
    // Change extension and join with output directory
216
    const outputRelative = relativePath.replace(/\.tsx?$/, '.js');
217
    return normalize(join(this.outDir, outputRelative));
218
  }
219
  
220
  getSourceMapPath(jsPath: string): string {
221
    return jsPath + '.map';
222
  }
223
}
224

225
// Usage
226
const pathManager = new BuildPathManager('/src', '/dist');
227
const outputPath = pathManager.getOutputPath('/src/components/App.tsx');
228
// Result: "/dist/components/App.js"
229
```
230

231
### Module Dependency Tracking
232

233
```typescript
234
import { relative, dirname, isAbsolute } from "tsickle";
235

236
function trackModuleDependencies(sourceFile: string, imports: string[]): string[] {
237
  const sourceDir = dirname(sourceFile);
238
  
239
  return imports.map(importPath => {
240
    if (isAbsolute(importPath)) {
241
      return importPath;  // Already absolute
242
    }
243
    
244
    // Resolve relative import to absolute path
245
    return normalize(join(sourceDir, importPath));
246
  });
247
}
248

249
// Usage  
250
const dependencies = trackModuleDependencies(
251
  "/project/src/app.ts",
252
  ["./utils", "../lib/helpers", "/absolute/path"]
253
);
254
// Results in absolute paths for all imports
255
```
256

257
### Configuration Path Resolution
258

259
```typescript
260
import { isAbsolute, join, normalize } from "tsickle";
261

262
function resolveConfigPaths(configDir: string, paths: Record<string, string>): Record<string, string> {
263
  const resolved: Record<string, string> = {};
264
  
265
  for (const [key, path] of Object.entries(paths)) {
266
    if (isAbsolute(path)) {
267
      resolved[key] = normalize(path);
268
    } else {
269
      resolved[key] = normalize(join(configDir, path));
270
    }
271
  }
272
  
273
  return resolved;
274
}
275

276
// Usage
277
const resolvedPaths = resolveConfigPaths("/project", {
278
  src: "./src",
279
  dist: "./dist", 
280
  types: "/absolute/types"
281
});
282
// Results in absolute normalized paths
283
```