diff --git a/changelog.md b/changelog.md index d914071..3a44d0f 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,15 @@ # Changelog +## 2025-11-30 - 4.0.0 - BREAKING CHANGE(watchers) +Replace chokidar with native platform watchers and add cross-runtime support (Node.js, Deno, Bun); introduce write stabilization and internal glob matching + +- Replaced chokidar-based implementation with native file watching APIs (Node.js fs.watch, Deno.watchFs). +- Added platform-specific watchers: NodeWatcher and DenoWatcher (Bun uses Node compatibility). +- Implemented polling-based write stabilization (awaitWriteFinish replacement) to avoid duplicate events during writes. +- Keep glob pattern support by matching events internally using picomatch; base-path extraction used to limit watch scope. +- API/runtime requirement increased: Node.js >= 20.0.0 is required for native recursive fs.watch. +- Package/documentation name and examples updated to @push.rocks/smartchok and export the Smartwatch class. + ## 2025-11-30 - 3.0.0 - BREAKING CHANGE(smartwatch) Introduce Smartwatch: cross-runtime native file watching for Node.js, Deno and Bun; rename smartchok to smartwatch and bump major version to 2.0.0 diff --git a/readme.hints.md b/readme.hints.md index a7af2ed..ace60f3 100644 --- a/readme.hints.md +++ b/readme.hints.md @@ -4,6 +4,13 @@ The module now uses native file watching APIs instead of chokidar, providing cross-runtime support for Node.js, Deno, and Bun. +### Exported Class + +The package exports the `Smartwatch` class (not `Smartchok`): +```typescript +import { Smartwatch } from '@push.rocks/smartchok'; +``` + ### Architecture ``` diff --git a/readme.md b/readme.md index 428a8c7..274523f 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,6 @@ -# @push.rocks/smartwatch +# @push.rocks/smartchok -A smart wrapper for chokidar 5.x with glob pattern support, RxJS observable integration, and enhanced file watching features. +A cross-runtime file watcher with glob pattern support for **Node.js**, **Deno**, and **Bun**. Built with native file watching APIs for maximum performance and zero heavyweight dependencies. ## Issue Reporting and Security @@ -9,25 +9,27 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community ## Install ```sh -npm install @push.rocks/smartwatch +npm install @push.rocks/smartchok # or -pnpm add @push.rocks/smartwatch +pnpm add @push.rocks/smartchok ``` ## Features -🔍 **Glob Pattern Support** - Watch files using glob patterns like `**/*.ts` or `src/**/*.js` +🌐 **Cross-Runtime** - Works on Node.js 20+, Deno, and Bun +🔍 **Glob Pattern Support** - Watch files using familiar patterns like `**/*.ts` 📡 **RxJS Observables** - Subscribe to file system events using reactive streams 🔄 **Dynamic Watching** - Add or remove watch patterns at runtime -⚡ **Chokidar 5.x** - Built on the latest chokidar with improved performance +⚡ **Native Performance** - Uses `fs.watch()` and `Deno.watchFs()` directly 🎯 **TypeScript First** - Full TypeScript support with comprehensive type definitions +📦 **Minimal Dependencies** - No heavyweight watcher libraries required ## Usage ### Basic Setup ```typescript -import { Smartwatch } from '@push.rocks/smartwatch'; +import { Smartwatch } from '@push.rocks/smartchok'; // Create a watcher with glob patterns const watcher = new Smartwatch([ @@ -80,7 +82,6 @@ unlinkObservable.subscribe(([path]) => { | `unlinkDir` | Directory has been removed | | `error` | Error occurred | | `ready` | Initial scan complete | -| `raw` | Raw event from the underlying watcher | ### Dynamic Watch Management @@ -107,7 +108,7 @@ await watcher.stop(); ### Complete Example ```typescript -import { Smartwatch } from '@push.rocks/smartwatch'; +import { Smartwatch } from '@push.rocks/smartchok'; async function watchProject() { // Initialize with patterns @@ -152,13 +153,30 @@ watchProject(); ## How It Works -Since chokidar 4.x+ no longer supports glob patterns natively, smartwatch handles glob pattern matching internally using [picomatch](https://github.com/micromatch/picomatch). This means you get the familiar glob syntax while benefiting from chokidar's efficient file watching capabilities. +smartchok uses native file watching APIs for each runtime: -When you provide glob patterns: -1. **Base path extraction** - smartwatch extracts the static base path from each pattern -2. **Efficient watching** - chokidar watches the base directories +| Runtime | API Used | +|---------|----------| +| **Node.js 20+** | `fs.watch({ recursive: true })` | +| **Deno** | `Deno.watchFs()` | +| **Bun** | Node.js compatibility layer | + +Since native APIs don't support glob patterns, smartchok handles pattern matching internally using [picomatch](https://github.com/micromatch/picomatch): + +1. **Base path extraction** - Extracts the static base path from each glob pattern +2. **Efficient watching** - Native watchers monitor the base directories 3. **Pattern filtering** - Events are filtered through picomatch matchers before being emitted +### Write Stabilization + +smartchok includes built-in write stabilization (similar to chokidar's `awaitWriteFinish`). When a file is being written, events are held until the file size stabilizes, preventing multiple events for a single write operation. + +## Requirements + +- **Node.js 20+** - Required for native recursive watching +- **Deno** - Any version with `Deno.watchFs()` support +- **Bun** - Uses Node.js compatibility + ## API Reference ### `Smartwatch` diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 844b38d..406dfd6 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@push.rocks/smartchok', - version: '3.0.0', + version: '4.0.0', description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.' }