0
# Core Watcher Factory
1

2
The main factory function that creates file system watcher instances with automatic mode selection based on options.
3

4
## Capabilities
5

6
### Main Factory Function
7

8
Creates a file system watcher for the specified directory with automatic watcher selection.
9

10
```javascript { .api }
11
/**
12
 * Creates a file system watcher for the specified directory
13
 * @param {string} dir - Directory to watch (relative or absolute path)
14
 * @param {Object} options - Watcher configuration options
15
 * @returns {NodeWatcher|PollWatcher|WatchmanWatcher|WatchexecWatcher} Watcher instance
16
 */
17
function sane(dir, options);
18
```
19

20
**Watcher Selection Logic:**
21
- If `options.watcher` is specified, requires and uses that custom watcher module
22
- If `options.poll` is true, returns PollWatcher instance
23
- If `options.watchman` is true, returns WatchmanWatcher instance  
24
- If `options.watchexec` is true, returns WatchexecWatcher instance
25
- If `options.fsevents` is true, throws error (deprecated/unsupported)
26
- Otherwise returns NodeWatcher instance (default fs.watch mode)
27

28
**Usage Examples:**
29

30
```javascript
31
const sane = require('sane');
32

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

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

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

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

51
// Custom watcher module
52
const watcher5 = sane('/path/to/watch', {
53
  watcher: './custom-watcher.js'
54
});
55
```
56

57
### Exposed Watcher Classes
58

59
Direct access to watcher class constructors for explicit instantiation.
60

61
```javascript { .api }
62
/**
63
 * Default fs.watch-based watcher class
64
 */
65
const NodeWatcher = sane.NodeWatcher;
66

67
/**
68
 * Polling-based watcher class using fs.watchFile
69
 */
70
const PollWatcher = sane.PollWatcher;
71

72
/**
73
 * Facebook Watchman-based watcher class
74
 */
75
const WatchmanWatcher = sane.WatchmanWatcher;
76

77
/**
78
 * Watchexec-based watcher class
79
 */
80
const WatchexecWatcher = sane.WatchexecWatcher;
81

82
/**
83
 * Deprecated FSEvents property (throws error when accessed)
84
 */
85
const FSEventsWatcher = sane.FSEventsWatcher; // Throws error
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
const { NodeWatcher, PollWatcher } = require('sane');
92

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

98
const pollWatcher = new PollWatcher('/path/to/watch', {
99
  interval: 1000
100
});
101
```
102

103
## Configuration Options
104

105
### Core Options
106

107
```javascript { .api }
108
interface CoreOptions {
109
  /** Glob patterns to match files (string or array of strings) */
110
  glob?: string | string[];
111
  /** Enable watching of dot files (files starting with .) */
112
  dot?: boolean;
113
  /** Patterns to ignore (glob, regex, function, or array) */
114
  ignored?: string | RegExp | Function | Array<string | RegExp | Function>;
115
}
116
```
117

118
### Mode Selection Options
119

120
```javascript { .api }
121
interface ModeOptions {
122
  /** Use polling mode (fs.watchFile) */
123
  poll?: boolean;
124
  /** Use Facebook Watchman */
125
  watchman?: boolean;
126
  /** Custom path to Watchman binary */
127
  watchmanPath?: string;
128
  /** Use watchexec external tool */
129
  watchexec?: boolean;
130
  /** Path to custom watcher module */
131
  watcher?: string;
132
  /** Deprecated - throws error if used */
133
  fsevents?: boolean;
134
}
135
```
136

137
### Polling-Specific Options
138

139
```javascript { .api }
140
interface PollingOptions {
141
  /** Polling interval in milliseconds (default: 100) */
142
  interval?: number;
143
}
144
```
145

146
## Error Handling
147

148
The factory function handles several error conditions:
149

150
```javascript
151
const sane = require('sane');
152

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

160
// Custom watcher module errors
161
try {
162
  const watcher = sane('/path', { watcher: './non-existent-watcher.js' });
163
} catch (error) {
164
  console.error('Failed to load custom watcher:', error.message);
165
}
166
```
167

168
## Compatibility Notes
169

170
- **FSEvents**: Sane >= 4 no longer supports the fsevents module, use Watchman instead on macOS
171
- **Node.js Versions**: Requires Node.js 10.* or >= 12.*
172
- **External Dependencies**: Watchman and watchexec modes require their respective tools to be installed separately