validate-this-path/dist/index.mjs

A lightweight TypeScript utility package for validating, sanitizing, and manipulating file paths across different operating systems

// src/lib/pathUtils.ts
import * as path from "path";
import { platform } from "os";
var WINDOWS_MAX_PATH = 260;
var POSIX_MAX_PATH = 4096;
var WINDOWS_ILLEGAL_CHARS = /[<>:"|?*\x00-\x1F]/g;
var POSIX_ILLEGAL_CHARS = /\x00/g;
function getCurrentOS() {
  return platform() === "win32" ? "windows" : "posix";
}
function getMaxPathLength(os) {
  return os === "windows" ? WINDOWS_MAX_PATH : POSIX_MAX_PATH;
}
function validatePath(pathStr, options = {}) {
  const errors = [];
  const os = options.os === "auto" || !options.os ? getCurrentOS() : options.os;
  const maxLength = options.maxLength || getMaxPathLength(os);
  const allowTraversal = options.allowTraversal ?? false;
  const allowAbsolute = options.allowAbsolute ?? true;
  const allowRelative = options.allowRelative ?? true;
  if (!pathStr) {
    return {
      isValid: false,
      errors: [
        {
          code: "EMPTY_PATH",
          message: "Path cannot be empty"
        }
      ]
    };
  }
  if (pathStr.length > maxLength) {
    errors.push({
      code: "TOO_LONG",
      message: `Path exceeds maximum length of ${maxLength} characters`
    });
  }
  const illegalChars = os === "windows" ? WINDOWS_ILLEGAL_CHARS : POSIX_ILLEGAL_CHARS;
  const illegalMatch = pathStr.match(illegalChars);
  if (illegalMatch) {
    errors.push({
      code: "ILLEGAL_CHAR",
      message: `Path contains illegal character: ${illegalMatch[0]}`,
      position: illegalMatch.index
    });
  }
  if (!allowTraversal && pathStr.includes("..")) {
    errors.push({
      code: "TRAVERSAL",
      message: "Path traversal (..) is not allowed"
    });
  }
  const isAbsolute2 = path.isAbsolute(pathStr);
  if (isAbsolute2 && !allowAbsolute) {
    errors.push({
      code: "ABSOLUTE_NOT_ALLOWED",
      message: "Absolute paths are not allowed"
    });
  }
  if (!isAbsolute2 && !allowRelative) {
    errors.push({
      code: "RELATIVE_NOT_ALLOWED",
      message: "Relative paths are not allowed"
    });
  }
  if (errors.length === 0) {
    return {
      isValid: true,
      normalizedPath: normalizePath(pathStr, { os })
    };
  }
  return {
    isValid: false,
    errors
  };
}
function normalizePath(pathStr, options = {}) {
  if (!pathStr) {
    return "";
  }
  const os = options.os === "auto" || !options.os ? getCurrentOS() : options.os;
  const forceForwardSlash = options.forceForwardSlash ?? true;
  const removeTrailingSlash = options.removeTrailingSlash ?? true;
  const toLowerCase = options.toLowerCase ?? os === "windows";
  let normalized = path.normalize(pathStr);
  if (normalized === ".") {
    return pathStr;
  }
  if (forceForwardSlash) {
    normalized = normalized.replace(/\\/g, "/");
  }
  if (removeTrailingSlash && normalized.length > 1) {
    normalized = normalized.replace(/[/\\]$/, "");
  }
  if (toLowerCase) {
    normalized = normalized.toLowerCase();
  }
  return normalized;
}
function joinPaths(...paths) {
  return path.join(...paths);
}
function getRelativePath(from, to) {
  return path.relative(from, to);
}
function isPathTraversal(pathStr) {
  if (!pathStr) {
    return false;
  }
  const normalized = normalizePath(pathStr);
  return normalized.includes("..");
}
function sanitizePath(pathStr, os = getCurrentOS()) {
  if (!pathStr) {
    return "";
  }
  const illegalChars = os === "windows" ? WINDOWS_ILLEGAL_CHARS : POSIX_ILLEGAL_CHARS;
  const sanitized = pathStr.replace(illegalChars, "");
  return normalizePath(sanitized, { os });
}
export {
  getCurrentOS,
  getRelativePath,
  isPathTraversal,
  joinPaths,
  normalizePath,
  sanitizePath,
  validatePath
};