smartwatch/readme.hints.md

smartchok - Technical Hints

Native File Watching (v2.0.0+)

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):

import { Smartwatch } from '@push.rocks/smartchok';

Architecture

ts/
├── smartwatch.classes.smartwatch.ts   # Main Smartwatch class
├── smartwatch.plugins.ts              # Dependencies (smartenv, picomatch, etc.)
├── watchers/
│   ├── index.ts                       # Factory with runtime detection
│   ├── interfaces.ts                  # IWatcher interface and types
│   ├── watcher.node.ts                # Node.js/Bun implementation (fs.watch)
│   └── watcher.deno.ts                # Deno implementation (Deno.watchFs)
└── utils/
    └── write-stabilizer.ts            # awaitWriteFinish polling implementation

Runtime Detection

Uses @push.rocks/smartenv v6.x for runtime detection:

• Node.js/Bun: Uses native fs.watch() with { recursive: true }
• Deno: Uses Deno.watchFs() async iterable

Dependencies

• picomatch: Glob pattern matching (zero deps, well-maintained)
• @push.rocks/smartenv: Runtime detection (Node.js, Deno, Bun)
• @push.rocks/smartrx: RxJS Subject/Observable management
• @push.rocks/smartpromise: Deferred promise utilities
• @push.rocks/lik: Stringmap for pattern storage

Why picomatch?

Native file watching APIs don't support glob patterns. Picomatch provides glob pattern matching with:

• Zero dependencies
• 164M+ weekly downloads
• Excellent security profile
• Full glob syntax support

Event Handling

Native events are normalized to a consistent interface:

Node.js/Bun Event	Deno Event	Normalized Event
rename (file exists)	create	add
rename (file gone)	remove	unlink
change	modify	change

awaitWriteFinish Implementation

The WriteStabilizer class replaces chokidar's built-in write stabilization:

• Polls file size until stable (configurable threshold: 300ms default)
• Configurable poll interval (100ms default)
• Handles file deletion during write detection

Platform Requirements

• Node.js 20+: Required for native recursive watching on all platforms
• Deno: Works on all versions with Deno.watchFs()
• Bun: Uses Node.js compatibility layer

Testing

pnpm test

Tests verify:

• Creating Smartwatch instance
• Adding glob patterns
• Receiving 'add' events for new files
• Graceful shutdown

Dev Dependencies

• Using @git.zone/tstest v3.x with tapbundle
• Import from @git.zone/tstest/tapbundle