Pattern Utilities

/**
 * Determine if a pattern is dynamic (contains wildcards) or static
 * @param pattern - Glob pattern to analyze
 * @param options - Configuration options affecting pattern interpretation
 * @returns true if pattern contains dynamic elements, false if static
 */
function isDynamicPattern(pattern: string, options?: Options): boolean;

import fg from "fast-glob";

// Static patterns (no wildcards)
fg.isDynamicPattern('file.txt');              // false
fg.isDynamicPattern('src/index.js');          // false
fg.isDynamicPattern('/absolute/path.js');     // false

// Dynamic patterns (contain wildcards)
fg.isDynamicPattern('*.js');                  // true
fg.isDynamicPattern('src/**/*.ts');           // true
fg.isDynamicPattern('test.{js,ts}');          // true
fg.isDynamicPattern('!(node_modules)/**');    // true

// Pattern with options affecting detection
fg.isDynamicPattern('src/file.js', { 
  baseNameMatch: true  // Makes pattern behave like **/src/file.js
});  // true

/**
 * Escape special characters in path for current platform
 * @param path - File path containing special characters
 * @returns Escaped path safe to use in glob patterns
 */
function escapePath(path: string): string;

/**
 * Convert file path to glob pattern for current platform
 * @param path - File path to convert
 * @returns Pattern string with proper escaping and path conversion
 */
function convertPathToPattern(path: string): string;

import fg from "fast-glob";

// Escape paths with special characters
const safePath = fg.escapePath('[OpenSource] project (2024)');
// Result: '\\[OpenSource\\] project \\(2024\\)'

const safePattern = safePath + '/**/*.js';
const files = await fg(safePattern);

// Convert paths to patterns
const pattern = fg.convertPathToPattern('C:\\Program Files\\app') + '/**/*';
// Windows: 'C:/Program Files \\(app\\)/**/*'
// POSIX: 'C:\\\\Program Files \\(app\\)/**/*'

// Safe handling of user input
function findInUserPath(userPath: string, extension: string) {
  const safePattern = fg.convertPathToPattern(userPath) + `/**/*.${extension}`;
  return fg(safePattern);
}

namespace posix {
  /**
   * Escape special characters using POSIX rules
   * @param path - File path to escape
   * @returns Path with POSIX-specific character escaping
   */
  function escapePath(path: string): string;
  
  /**
   * Convert path to pattern using POSIX rules
   * @param path - File path to convert  
   * @returns Pattern with POSIX-specific path conversion
   */
  function convertPathToPattern(path: string): string;
}

import fg from "fast-glob";

// Force POSIX handling regardless of current platform
const posixEscaped = fg.posix.escapePath('file (with) special [chars]');
// '\\file \\(with\\) special \\[chars\\]'

const posixPattern = fg.posix.convertPathToPattern('/usr/share/app (v1.0)');
// '/usr/share/app \\(v1.0\\)'

// Useful for cross-platform tools that need consistent behavior
function createPosixPattern(basePath: string, glob: string) {
  return fg.posix.convertPathToPattern(basePath) + '/' + glob;
}

namespace win32 {
  /**
   * Escape special characters using Windows rules
   * @param path - File path to escape
   * @returns Path with Windows-specific character escaping
   */
  function escapePath(path: string): string;
  
  /**
   * Convert path to pattern using Windows rules
   * @param path - File path to convert
   * @returns Pattern with Windows-specific path conversion
   */
  function convertPathToPattern(path: string): string;
}

import fg from "fast-glob";

// Force Windows handling regardless of current platform
const winEscaped = fg.win32.escapePath('Program Files (x86)');
// 'Program Files \\(x86\\)'

// Windows path conversion handles backslashes
const winPattern = fg.win32.convertPathToPattern('C:\\Program Files\\app');
// 'C:/Program Files \\(app\\)'

// Handle UNC paths
const uncPath = fg.win32.convertPathToPattern('\\\\server\\share\\folder');
// '//server/share/folder'

// Useful for Windows-specific tooling
function createWindowsPattern(programFiles: string, appName: string) {
  const safePath = fg.win32.convertPathToPattern(`${programFiles}\\${appName}`);
  return safePath + '/**/*';
}

// Safe pattern building for any platform
function buildSafePattern(userPath: string, globSuffix: string) {
  // Uses current platform's rules automatically
  return fg.convertPathToPattern(userPath) + '/' + globSuffix;
}

// Platform-specific pattern building
function buildPlatformSpecificPattern(path: string, targetPlatform: 'posix' | 'win32') {
  if (targetPlatform === 'posix') {
    return fg.posix.convertPathToPattern(path);
  } else {
    return fg.win32.convertPathToPattern(path);
  }
}

// Invalid input handling
try {
  fg.isDynamicPattern('');  // Throws TypeError: Patterns must be a string (non empty)
  fg.escapePath(null);      // Throws TypeError: Patterns must be a string (non empty)
} catch (error) {
  console.error('Invalid pattern input:', error.message);
}

// Safe utility wrapper
function safeEscapePath(path: unknown): string | null {
  try {
    if (typeof path === 'string' && path.length > 0) {
      return fg.escapePath(path);
    }
    return null;
  } catch {
    return null;
  }
}