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
```