or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcore-factory.mdindex.mdwatcher-modes.md
tile.json

tessl/npm-sane

Fast, small, and reliable file system watcher with multiple monitoring strategies.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/sane@5.0.x

To install, run

npx @tessl/cli install tessl/npm-sane@5.0.0

index.mddocs/

Sane

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.

Package Information

  • Package Name: sane
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install sane
  • CLI Installation: npm install sane -g

Core Imports

const sane = require('sane');

ES6 modules:

import sane from 'sane';

Individual watcher classes:

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

Basic Usage

const sane = require('sane');

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

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

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

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

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

// Clean up when done
watcher.close();

Architecture

Sane is built around several key components:

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

Capabilities

Core Watcher Factory

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

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

Core Watcher Factory

Watcher Modes

Different watcher implementations for various use cases and environments.

class NodeWatcher extends EventEmitter {
  constructor(dir, options);
  close(callback);
}

class PollWatcher extends EventEmitter {
  constructor(dir, options);
  close(callback);
}

class WatchmanWatcher extends EventEmitter {
  constructor(dir, options);
  close(callback);
}

class WatchexecWatcher extends EventEmitter {
  constructor(dir, options);
  close(callback);
}

Watcher Modes

Command Line Interface

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

sane <command> [...directory] [options]

Command Line Interface

Module Constants

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

const sane = require('sane');

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

/** Event type constants */
const CHANGE_EVENT = 'change';
const DELETE_EVENT = 'delete';
const ADD_EVENT = 'add';
const ALL_EVENT = 'all';

Deprecated Components

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

/**
 * Deprecated FSEvents watcher (throws error when accessed)
 * @deprecated Use WatchmanWatcher instead on macOS
 * @throws {Error} Always throws "Sane >= 4 no longer support the fsevents module."
 */
const FSEventsWatcher = sane.FSEventsWatcher; // Throws error

Types

interface WatcherOptions {
  /** Glob patterns to watch */
  glob?: string | string[];
  /** Watch dot files */
  dot?: boolean;
  /** Patterns to ignore */
  ignored?: string | RegExp | Function | Array<string | RegExp | Function>;
  /** Use polling mode */
  poll?: boolean;
  /** Polling interval in milliseconds (PollWatcher only) */
  interval?: number;
  /** Use Watchman mode */
  watchman?: boolean;
  /** Custom Watchman binary path */
  watchmanPath?: string;
  /** Use Watchexec mode */
  watchexec?: boolean;
  /** Custom watcher module path */
  watcher?: string;
  /** Deprecated - throws error if used */
  fsevents?: boolean;
}

interface WatcherEvents {
  /** Emitted when watcher is ready */
  'ready': () => void;
  /** Emitted when file is changed */
  'change': (filepath: string, root: string, stat: fs.Stats) => void;
  /** Emitted when file/directory is added */
  'add': (filepath: string, root: string, stat: fs.Stats) => void;
  /** Emitted when file/directory is deleted (stat parameter is null) */
  'delete': (filepath: string, root: string, stat: null) => void;
  /** Emitted for all change types */
  'all': (eventType: string, filepath: string, root: string, stat?: fs.Stats) => void;
  /** Emitted when errors occur */
  'error': (error: Error) => void;
}