Superwatcher

Zero-dependency Deno file watcher with debounced batch event callbacks

Features

• Zero dependencies - No external packages, built entirely on Deno native file system APIs.
• Debounced batch events - Groups rapid file changes into one batched callback per flush cycle.
• Ignore filters - Skips unwanted paths using string suffix, RegExp, or custom function matchers.
• Write stability - Delays event emission until file size stops changing after large writes.
• Atomic write detection - Collapses delete-then-recreate within debounce window into single modify event.
• Multi-path support - Watches any combination of directories and individual files in one instance.
• Recursive control - Disables subdirectory watching when recursive: false is set on directories.
• Error isolation - Catches thrown errors inside onChange callback without stopping the watcher.

Installation

Note

Prerequisites: Deno >= 2.5.4 (install from deno.com).

Deno (JSR):

deno add jsr:@neabyte/superwatcher

Read docs/README.md for full documentation.

Testing

Type check - format, lint, and type-check:

deno task check

Unit tests - format/lint tests and run all tests:

deno task test

• Tests live under tests/ (utils and watcher tests).
• The test task uses --allow-read, --allow-write, and --allow-env.

License

This project is licensed under the MIT license. See the LICENSE file for details.