Tuulbelt

Appearance

Cross-Platform Path Normalizer ​

Convert Windows/Unix paths with zero dependencies. Handle UNC paths, mixed separators, and drive letters seamlessly.

Overview ​

Cross-Platform Path Normalizer provides bidirectional path conversion between Windows and Unix formats. It automatically detects path formats, handles edge cases like UNC paths and mixed separators, and works entirely with zero runtime dependencies.

Status: Production Ready (v0.1.0)

Language: TypeScript

Repository: tuulbelt/cross-platform-path-normalizer

Features ​

Bidirectional Conversion ​

Convert Windows paths to Unix format and vice versa. Auto-detect source format or force specific output. Handles drive letters (C: ↔ /c) and path separators (\ ↔ /).

UNC Path Support ​

Handle network paths correctly. Convert \\server\share ↔ //server/share with proper double-slash preservation for network file systems.

Mixed Separator Handling ​

Normalize paths with both forward and backslashes. Clean up messy paths like C:/Users\Documents/file.txt automatically.

Type Safe ​

Written in TypeScript with strict mode enabled. Full type definitions and Result pattern for error handling with detailed error messages.

CLI & Library ​

Use as a command-line tool for quick conversions or integrate as a library in your Node.js/TypeScript projects.

Zero Runtime Dependencies ​

Uses only Node.js built-ins. No npm install required in production.

Quick Start ​

bash
# Clone the repository
git clone https://github.com/tuulbelt/cross-platform-path-normalizer.git
cd cross-platform-path-normalizer

# Install dev dependencies (for TypeScript)
npm install

# Convert a path
normpath --format unix "C:\Users\file.txt"
# Output: /c/Users/file.txt

# Library usage
import { normalizePath } from './src/index.js';
const result = normalizePath('C:\\Users\\file.txt', { format: 'unix' });
// { success: true, path: '/c/Users/file.txt', format: 'unix' }

Use Cases ​

  • Cross-Platform Testing: Normalize test fixture paths across Windows/Linux/macOS
  • Build Scripts: Handle paths consistently in npm scripts and CI/CD pipelines
  • Path Validation: Convert user input paths to canonical format
  • Documentation Examples: Show paths in consistent format regardless of platform
  • Git Workflows: Normalize paths before committing or comparing diffs

Why Cross-Platform Path Normalizer? ​

Building cross-platform tools requires handling different path conventions:

  1. Incompatible Formats: Windows uses \ and drive letters, Unix uses /
  2. Mixed Input: Users provide paths in inconsistent formats
  3. Heavy Dependencies: Existing solutions pull in large dependency trees
  4. Edge Cases: UNC paths, relative paths, and mixed separators need special handling
  5. Type Safety: Runtime validation needed to catch path errors early

This tool provides zero-dependency path normalization with comprehensive edge case handling.

Dogfooding: Tool Composition ​

This tool demonstrates composability by being VALIDATED BY other Tuulbelt tools:

Test Flakiness Detector - Validate test reliability:

bash
./scripts/dogfood-flaky.sh 10
# ✅ NO FLAKINESS DETECTED
# 145 tests × 10 runs = 1,450 executions

Output Diffing Utility - Prove identical outputs:

bash
./scripts/dogfood-diff.sh
# Compares outputs to ensure no random data

Used By: Output Diffing Utility, File-Based Semaphore, Test Flakiness Detector

See DOGFOODING_STRATEGY.md in the repository for implementation details.

Demo ​

See the tool in action:

Cross-Platform Path Normalizer Demo

▶ View interactive recording on asciinema.org

Try it online:Open in StackBlitz

Run the tool directly in your browser with zero setup. Try converting Windows and Unix paths, test edge cases, and explore the full API.

Demos are automatically generated via GitHub Actions when demo scripts are updated.

Next Steps ​

License ​

MIT License - see repository for details.

Released under the MIT License.

Copyright © 2025 Tuulbelt