https://github.com/neabytelab/superwatcher

Zero-dependency Deno file watcher that debounces filesystem events into batched callbacks with ignore patterns and write stability detection.
https://github.com/neabytelab/superwatcher

atomic-writes batch-events debounce deno deno-native developer-tools event-batching file-monitoring file-system-events file-watcher filesystem hot-reload ignore-filters jsr realtime recursive-watch typescript watch-files write-stability zero-dependencies

Last synced: 4 days ago
JSON representation

Zero-dependency Deno file watcher that debounces filesystem events into batched callbacks with ignore patterns and write stability detection.

• Host: GitHub
• URL: https://github.com/neabytelab/superwatcher
• Owner: NeaByteLab
• License: mit
• Created: 2026-05-30T08:40:36.000Z (5 days ago)
• Default Branch: main
• Last Pushed: 2026-05-30T11:11:53.000Z (5 days ago)
• Last Synced: 2026-05-30T12:11:01.270Z (5 days ago)
• Topics: atomic-writes, batch-events, debounce, deno, deno-native, developer-tools, event-batching, file-monitoring, file-system-events, file-watcher, filesystem, hot-reload, ignore-filters, jsr, realtime, recursive-watch, typescript, watch-files, write-stability, zero-dependencies
• Language: TypeScript
• Homepage: https://jsr.io/@neabyte/superwatcher
• Size: 37.1 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


# Superwatcher

Zero-dependency Deno file watcher with debounced batch event callbacks

[![Deno](https://img.shields.io/badge/deno-%3E%3D2.5.4-ffcb00?logo=deno&logoColor=000000)](https://deno.com) [![Module type: Deno/ESM](https://img.shields.io/badge/module%20type-deno%2Fesm-brightgreen)](https://github.com/NeaByteLab/Superwatcher) [![JSR](https://jsr.io/badges/@neabyte/superwatcher)](https://jsr.io/@neabyte/superwatcher) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)



## 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](https://deno.com/)).

**Deno (JSR):**

```bash

deno add jsr:@neabyte/superwatcher

```

Read [docs/README.md](docs/README.md) for full documentation.

## Testing

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

```bash

deno task check

```

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

```bash

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](LICENSE) file for details.