0
# Sane
1

2
Sane is a fast, small, and reliable file system watcher for Node.js applications that addresses common issues with native filesystem watching. It offers multiple watching strategies including fs.watch (default), Facebook Watchman, watchexec, and polling modes to ensure cross-platform compatibility and performance.
3

4
## Package Information
5

6
- **Package Name**: sane
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install sane`
10
- **CLI Installation**: `npm install sane -g`
11

12
## Core Imports
13

14
```javascript
15
const sane = require('sane');
16
```
17

18
ES6 modules:
19

20
```javascript
21
import sane from 'sane';
22
```
23

24
Individual watcher classes:
25

26
```javascript
27
const { NodeWatcher, PollWatcher, WatchmanWatcher, WatchexecWatcher } = require('sane');
28
```
29

30
## Basic Usage
31

32
```javascript
33
const sane = require('sane');
34

35
// Create a watcher with default fs.watch mode
36
const watcher = sane('path/to/dir', {
37
  glob: ['**/*.js', '**/*.css'],
38
  ignored: ['node_modules/**', '.git/**']
39
});
40

41
// Listen for events
42
watcher.on('ready', () => {
43
  console.log('Watcher is ready');
44
});
45

46
watcher.on('change', (filepath, root, stat) => {
47
  console.log('File changed:', filepath);
48
});
49

50
watcher.on('add', (filepath, root, stat) => {
51
  console.log('File added:', filepath);
52
});
53

54
watcher.on('delete', (filepath, root) => {
55
  console.log('File deleted:', filepath);
56
  // Note: stat parameter is null for delete events
57
});
58

59
// Clean up when done
60
watcher.close();
61
```
62

63
## Architecture
64

65
Sane is built around several key components:
66

67
- **Factory Function**: Main `sane()` function that selects appropriate watcher based on options
68
- **Watcher Classes**: Different implementations (NodeWatcher, PollWatcher, WatchmanWatcher, WatchexecWatcher) with consistent API
69
- **Event System**: EventEmitter-based interface with standardized event types across all watchers
70
- **Pattern Matching**: Glob-based file filtering with ignore patterns using micromatch and anymatch
71
- **Cross-Platform Support**: Handles filesystem quirks and limitations across different operating systems
72

73
## Capabilities
74

75
### Core Watcher Factory
76

77
Main factory function that creates watcher instances with automatic mode selection based on options.
78

79
```javascript { .api }
80
/**
81
 * Creates a file system watcher for the specified directory
82
 * @param {string} dir - Directory to watch
83
 * @param {Object} options - Watcher configuration options
84
 * @returns {NodeWatcher|PollWatcher|WatchmanWatcher|WatchexecWatcher} Watcher instance
85
 */
86
function sane(dir, options);
87
```
88

89
[Core Watcher Factory](./core-factory.md)
90

91
### Watcher Modes
92

93
Different watcher implementations for various use cases and environments.
94

95
```javascript { .api }
96
class NodeWatcher extends EventEmitter {
97
  constructor(dir, options);
98
  close(callback);
99
}
100

101
class PollWatcher extends EventEmitter {
102
  constructor(dir, options);
103
  close(callback);
104
}
105

106
class WatchmanWatcher extends EventEmitter {
107
  constructor(dir, options);
108
  close(callback);
109
}
110

111
class WatchexecWatcher extends EventEmitter {
112
  constructor(dir, options);
113
  close(callback);
114
}
115
```
116

117
[Watcher Modes](./watcher-modes.md)
118

119
### Command Line Interface
120

121
CLI tool for running commands when files change, with support for throttling and various watch modes.
122

123
```bash { .api }
124
sane <command> [...directory] [options]
125
```
126

127
[Command Line Interface](./cli.md)
128

129
### Module Constants
130

131
Constants exposed by the sane module for event names and configuration.
132

133
```javascript { .api }
134
const sane = require('sane');
135

136
/** Default debounce delay in milliseconds */
137
const DEFAULT_DELAY = 100;
138

139
/** Event type constants */
140
const CHANGE_EVENT = 'change';
141
const DELETE_EVENT = 'delete';
142
const ADD_EVENT = 'add';
143
const ALL_EVENT = 'all';
144
```
145

146
### Deprecated Components
147

148
Components that are no longer supported but may appear in legacy code.
149

150
```javascript { .api }
151
/**
152
 * Deprecated FSEvents watcher (throws error when accessed)
153
 * @deprecated Use WatchmanWatcher instead on macOS
154
 * @throws {Error} Always throws "Sane >= 4 no longer support the fsevents module."
155
 */
156
const FSEventsWatcher = sane.FSEventsWatcher; // Throws error
157
```
158

159
## Types
160

161
```javascript { .api }
162
interface WatcherOptions {
163
  /** Glob patterns to watch */
164
  glob?: string | string[];
165
  /** Watch dot files */
166
  dot?: boolean;
167
  /** Patterns to ignore */
168
  ignored?: string | RegExp | Function | Array<string | RegExp | Function>;
169
  /** Use polling mode */
170
  poll?: boolean;
171
  /** Polling interval in milliseconds (PollWatcher only) */
172
  interval?: number;
173
  /** Use Watchman mode */
174
  watchman?: boolean;
175
  /** Custom Watchman binary path */
176
  watchmanPath?: string;
177
  /** Use Watchexec mode */
178
  watchexec?: boolean;
179
  /** Custom watcher module path */
180
  watcher?: string;
181
  /** Deprecated - throws error if used */
182
  fsevents?: boolean;
183
}
184

185
interface WatcherEvents {
186
  /** Emitted when watcher is ready */
187
  'ready': () => void;
188
  /** Emitted when file is changed */
189
  'change': (filepath: string, root: string, stat: fs.Stats) => void;
190
  /** Emitted when file/directory is added */
191
  'add': (filepath: string, root: string, stat: fs.Stats) => void;
192
  /** Emitted when file/directory is deleted (stat parameter is null) */
193
  'delete': (filepath: string, root: string, stat: null) => void;
194
  /** Emitted for all change types */
195
  'all': (eventType: string, filepath: string, root: string, stat?: fs.Stats) => void;
196
  /** Emitted when errors occur */
197
  'error': (error: Error) => void;
198
}
199
```