tessl/npm-tsickle

Transpile TypeScript code to JavaScript with Closure annotations.

—

Pending

Overview

Eval results

Files

Path Utilities

Name: tessl/npm-tsickle
Author: tessl

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

Capabilities

Path Testing

Functions for testing path properties and formats.

/**
 * Tests if a path is absolute
 */
function isAbsolute(path: string): boolean;

Usage Examples:

import { isAbsolute } from "tsickle";

console.log(isAbsolute("/usr/local/file.ts"));     // true (Unix)
console.log(isAbsolute("C:\\Windows\\file.ts"));   // true (Windows)  
console.log(isAbsolute("./relative/file.ts"));     // false
console.log(isAbsolute("relative/file.ts"));       // false

Path Manipulation

Functions for joining, resolving, and manipulating file paths.

/**
 * Joins two path segments
 */
function join(p1: string, p2: string): string;

/**
 * Gets directory name from path
 */
function dirname(path: string): string;

/**
 * Gets relative path from base to target
 */
function relative(base: string, rel: string): string;

/**
 * Normalizes path separators and removes redundant segments
 */
function normalize(path: string): string;

Usage Examples:

import { join, dirname, relative, normalize } from "tsickle";

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

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

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

// Normalize path
const normalized = normalize("/project/src/../lib/./file.ts");
// Result: "/project/lib/file.ts"

Cross-Platform Compatibility

The path utilities handle cross-platform differences automatically:

Path Separators

import { join, normalize } from "tsickle";

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

Absolute Path Detection

import { isAbsolute } from "tsickle";

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

Module Resolution Integration

These utilities integrate with tsickle's module resolution system:

Converting File Paths to Module Names

import { relative, normalize } from "tsickle";

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

// Usage
const moduleName = filePathToModuleName(
  "/project/src",
  "/project/src/components/Button.tsx"
);
// Result: "components.Button"

Working with Import Paths

import { isAbsolute, join, dirname } from "tsickle";

function resolveImportPath(currentFile: string, importPath: string): string {
  if (isAbsolute(importPath)) {
    return importPath;
  }
  
  // Resolve relative import
  const currentDir = dirname(currentFile);
  return join(currentDir, importPath);
}

// Usage
const resolved = resolveImportPath(
  "/project/src/app.ts",
  "./utils/helpers"
);
// Result: "/project/src/utils/helpers"

Error Handling

The path utilities include error handling for common edge cases:

Invalid Path Handling

import { normalize, join } from "tsickle";

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

// Handles null/undefined inputs
try {
  normalize(null as any);  // May throw or return safe default
} catch (error) {
  console.error("Invalid path input");
}

Path Traversal Protection

import { normalize, relative } from "tsickle";

function safePath(basePath: string, userPath: string): string {
  const normalized = normalize(userPath);
  const rel = relative(basePath, join(basePath, normalized));
  
  // Ensure path doesn't escape base directory
  if (rel.startsWith('..')) {
    throw new Error("Path traversal not allowed");
  }
  
  return join(basePath, rel);
}

Performance Considerations

The path utilities are optimized for performance:

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

Common Patterns

Build System Integration

import { relative, normalize, dirname } from "tsickle";

class BuildPathManager {
  constructor(private rootDir: string, private outDir: string) {}
  
  getOutputPath(inputPath: string): string {
    // Get relative path from root
    const relativePath = relative(this.rootDir, inputPath);
    
    // Change extension and join with output directory
    const outputRelative = relativePath.replace(/\.tsx?$/, '.js');
    return normalize(join(this.outDir, outputRelative));
  }
  
  getSourceMapPath(jsPath: string): string {
    return jsPath + '.map';
  }
}

// Usage
const pathManager = new BuildPathManager('/src', '/dist');
const outputPath = pathManager.getOutputPath('/src/components/App.tsx');
// Result: "/dist/components/App.js"

Module Dependency Tracking

import { relative, dirname, isAbsolute } from "tsickle";

function trackModuleDependencies(sourceFile: string, imports: string[]): string[] {
  const sourceDir = dirname(sourceFile);
  
  return imports.map(importPath => {
    if (isAbsolute(importPath)) {
      return importPath;  // Already absolute
    }
    
    // Resolve relative import to absolute path
    return normalize(join(sourceDir, importPath));
  });
}

// Usage  
const dependencies = trackModuleDependencies(
  "/project/src/app.ts",
  ["./utils", "../lib/helpers", "/absolute/path"]
);
// Results in absolute paths for all imports

Configuration Path Resolution

import { isAbsolute, join, normalize } from "tsickle";

function resolveConfigPaths(configDir: string, paths: Record<string, string>): Record<string, string> {
  const resolved: Record<string, string> = {};
  
  for (const [key, path] of Object.entries(paths)) {
    if (isAbsolute(path)) {
      resolved[key] = normalize(path);
    } else {
      resolved[key] = normalize(join(configDir, path));
    }
  }
  
  return resolved;
}

// Usage
const resolvedPaths = resolveConfigPaths("/project", {
  src: "./src",
  dist: "./dist", 
  types: "/absolute/types"
});
// Results in absolute normalized paths

Install with Tessl CLI