Core Watcher Factory

/**
 * Creates a file system watcher for the specified directory
 * @param {string} dir - Directory to watch (relative or absolute path)
 * @param {Object} options - Watcher configuration options
 * @returns {NodeWatcher|PollWatcher|WatchmanWatcher|WatchexecWatcher} Watcher instance
 */
function sane(dir, options);

const sane = require('sane');

// Default mode (fs.watch)
const watcher1 = sane('/path/to/watch');

// Polling mode with custom interval
const watcher2 = sane('/path/to/watch', { 
  poll: true,
  interval: 1000 // Poll every second
});

// Watchman mode
const watcher3 = sane('/path/to/watch', { watchman: true });

// With glob patterns
const watcher4 = sane('/path/to/watch', {
  glob: ['**/*.js', '**/*.json'],
  ignored: ['node_modules/**', '.git/**']
});

// Custom watcher module
const watcher5 = sane('/path/to/watch', {
  watcher: './custom-watcher.js'
});

/**
 * Default fs.watch-based watcher class
 */
const NodeWatcher = sane.NodeWatcher;

/**
 * Polling-based watcher class using fs.watchFile
 */
const PollWatcher = sane.PollWatcher;

/**
 * Facebook Watchman-based watcher class
 */
const WatchmanWatcher = sane.WatchmanWatcher;

/**
 * Watchexec-based watcher class
 */
const WatchexecWatcher = sane.WatchexecWatcher;

/**
 * Deprecated FSEvents property (throws error when accessed)
 */
const FSEventsWatcher = sane.FSEventsWatcher; // Throws error

const { NodeWatcher, PollWatcher } = require('sane');

// Direct instantiation
const nodeWatcher = new NodeWatcher('/path/to/watch', {
  glob: ['**/*.js']
});

const pollWatcher = new PollWatcher('/path/to/watch', {
  interval: 1000
});

interface CoreOptions {
  /** Glob patterns to match files (string or array of strings) */
  glob?: string | string[];
  /** Enable watching of dot files (files starting with .) */
  dot?: boolean;
  /** Patterns to ignore (glob, regex, function, or array) */
  ignored?: string | RegExp | Function | Array<string | RegExp | Function>;
}

interface ModeOptions {
  /** Use polling mode (fs.watchFile) */
  poll?: boolean;
  /** Use Facebook Watchman */
  watchman?: boolean;
  /** Custom path to Watchman binary */
  watchmanPath?: string;
  /** Use watchexec external tool */
  watchexec?: boolean;
  /** Path to custom watcher module */
  watcher?: string;
  /** Deprecated - throws error if used */
  fsevents?: boolean;
}

interface PollingOptions {
  /** Polling interval in milliseconds (default: 100) */
  interval?: number;
}

const sane = require('sane');

try {
  // This will throw an error
  const watcher = sane('/path', { fsevents: true });
} catch (error) {
  console.error('FSEvents is no longer supported:', error.message);
}

// Custom watcher module errors
try {
  const watcher = sane('/path', { watcher: './non-existent-watcher.js' });
} catch (error) {
  console.error('Failed to load custom watcher:', error.message);
}