POSIX Path Normalizer

Common errors

• TypeError: path.split is not a function

  cause The input provided to `ensurePosixPath` was not a string.
  fix Ensure that the argument passed to `ensurePosixPath` is always a string. For example: `ensurePosixPath(String(myVariable))`.

• Paths like 'dir/../file.txt' are not simplified to 'file.txt' after conversion.

  cause The `ensure-posix-path` utility strictly converts path separators (`\` to `/`). It does not perform semantic path normalization like resolving `..` or `.` components.
  fix If semantic normalization is required, use Node.js's `path.posix.normalize()` after converting to a POSIX path: `path.posix.normalize(ensurePosixPath(myPath))`.

Warnings

• gotcha This utility exclusively converts path separators from backslashes to forward slashes. It does not perform other path normalization tasks such as resolving `..` or `.` segments, which are handled by Node.js's `path.normalize()` or `path.resolve()`.
  Fix: For full path resolution and normalization, chain with `path.normalize()` or `path.resolve()` from Node.js's built-in `path` module after using `ensure-posix-path`.
• gotcha The package was last published seven years ago (as of 2026), meaning it is stable but unlikely to receive updates for new Node.js features, evolving path specifications, or edge cases beyond its core functionality.
  Fix: For projects requiring active maintenance or more comprehensive path manipulation, consider alternatives like `@flex-development/pathe` or `crosspath` which offer broader `path` module replacements.
• gotcha Providing non-string input to `ensurePosixPath` will result in a runtime error because the function internally expects string methods like `split()` to be available on its input. The package does not perform type validation on its input.
  Fix: Always ensure the input argument is a string before passing it to `ensurePosixPath` to prevent `TypeError: path.split is not a function`.

Install

• npm install ensure-posix-path npm
• yarn add ensure-posix-path yarn
• pnpm add ensure-posix-path pnpm

Imports

• ensurePosixPath
  wrong:

  import { ensurePosixPath } from 'ensure-posix-path';

  correct:

  import ensurePosixPath from 'ensure-posix-path';

  This package exports a single function as its default export. While some bundlers might allow named imports, the canonical way is a default import.
• ensurePosixPath

  const ensurePosixPath = require('ensure-posix-path');

  For CommonJS environments, the utility function is directly exported.
• Calling the function
  wrong:

  const posixPath = ensurePosixPath.normalize('C:\\Users\\Doc\\file.txt');

  correct:

  const posixPath = ensurePosixPath('C:\\Users\\Doc\\file.txt');

  The imported value is the function itself; it does not have additional methods like a 'normalize' property.

Quickstart

Demonstrates how to import and use `ensurePosixPath` to convert various path strings into their POSIX-compliant forward-slash equivalents.

import ensurePosixPath from 'ensure-posix-path';

// Example 1: Basic Windows path conversion
const windowsPath1 = 'C:\\Projects\\my-app\\src\\index.js';
const posixPath1 = ensurePosixPath(windowsPath1);
console.log(`Windows Path: ${windowsPath1}`);
console.log(`POSIX Path:   ${posixPath1}`);
// Expected: C:/Projects/my-app/src/index.js

// Example 2: Path with mixed separators (still normalizes to POSIX)
const mixedPath = 'folder\\sub/file.txt';
const posixPath2 = ensurePosixPath(mixedPath);
console.log(`Mixed Path:   ${mixedPath}`);
console.log(`POSIX Path:   ${posixPath2}`);
// Expected: folder/sub/file.txt

// Example 3: Already POSIX path (remains unchanged)
const alreadyPosix = '/var/www/html/app.js';
const posixPath3 = ensurePosixPath(alreadyPosix);
console.log(`Already POSIX: ${alreadyPosix}`);
console.log(`POSIX Path:    ${posixPath3}`);
// Expected: /var/www/html/app.js

// Note: This utility only handles separator conversion; it does not resolve '..' or '.' segments.
const unresolvedPath = 'dir/../another-dir/file.js';
const posixPath4 = ensurePosixPath(unresolvedPath);
console.log(`Unresolved: ${unresolvedPath}`);
console.log(`POSIX (unresolved): ${posixPath4}`);
// Expected: dir/../another-dir/file.js (no change as no backslashes)