validate-this-path/dist/index.d.ts

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

/**
 * Supported operating system types for path validation
 */
type OSType = 'windows' | 'posix' | 'auto';
/**
 * Options for path validation
 */
interface ValidationOptions {
    /**
     * Target operating system for validation rules
     * @default 'auto'
     */
    os?: OSType;
    /**
     * Whether to allow path traversal (..)
     * @default false
     */
    allowTraversal?: boolean;
    /**
     * Maximum allowed path length
     * @default 260 for Windows, 4096 for POSIX
     */
    maxLength?: number;
    /**
     * Whether to allow absolute paths
     * @default true
     */
    allowAbsolute?: boolean;
    /**
     * Whether to allow relative paths
     * @default true
     */
    allowRelative?: boolean;
}
/**
 * Options for path normalization
 */
interface NormalizationOptions {
    /**
     * Target operating system for normalization
     * @default 'auto'
     */
    os?: OSType;
    /**
     * Whether to force forward slashes
     * @default true
     */
    forceForwardSlash?: boolean;
    /**
     * Whether to remove trailing slashes
     * @default true
     */
    removeTrailingSlash?: boolean;
    /**
     * Whether to lowercase the path (Windows only)
     * @default true for Windows
     */
    toLowerCase?: boolean;
}
/**
 * Error codes for path validation
 */
type ValidationErrorCode = 'ILLEGAL_CHAR' | 'TOO_LONG' | 'TRAVERSAL' | 'SYNTAX' | 'ABSOLUTE_NOT_ALLOWED' | 'RELATIVE_NOT_ALLOWED' | 'EMPTY_PATH';
/**
 * Validation error details
 */
interface ValidationError {
    /**
     * Error code indicating the type of validation failure
     */
    code: ValidationErrorCode;
    /**
     * Human-readable error message
     */
    message: string;
    /**
     * Position in the path string where the error occurred (if applicable)
     */
    position?: number;
}
/**
 * Result of path validation
 */
interface ValidationResult {
    /**
     * Whether the path is valid according to the validation options
     */
    isValid: boolean;
    /**
     * Array of validation errors (if any)
     */
    errors?: ValidationError[];
    /**
     * Normalized path (if validation succeeded)
     */
    normalizedPath?: string;
}

/**
 * Determines the current operating system type
 */
declare function getCurrentOS(): OSType;
/**
 * Validates a path string against OS-specific rules
 * @param pathStr - The path to validate
 * @param options - Validation options
 */
declare function validatePath(pathStr: string, options?: ValidationOptions): ValidationResult;
/**
 * Normalizes a path according to the specified options
 * @param pathStr - The path to normalize
 * @param options - Normalization options
 */
declare function normalizePath(pathStr: string, options?: NormalizationOptions): string;
/**
 * Safely joins path segments
 * @param paths - Path segments to join
 */
declare function joinPaths(...paths: string[]): string;
/**
 * Gets a relative path from one path to another
 * @param from - Source path
 * @param to - Target path
 */
declare function getRelativePath(from: string, to: string): string;
/**
 * Checks if a path contains traversal
 * @param pathStr - The path to check
 */
declare function isPathTraversal(pathStr: string): boolean;
/**
 * Sanitizes a path by removing illegal characters and normalizing it
 * @param pathStr - The path to sanitize
 * @param os - Target operating system
 */
declare function sanitizePath(pathStr: string, os?: OSType): string;

export { type NormalizationOptions, type OSType, type ValidationError, type ValidationErrorCode, type ValidationOptions, type ValidationResult, getCurrentOS, getRelativePath, isPathTraversal, joinPaths, normalizePath, sanitizePath, validatePath };