npm package: @retrigger/core
Description: Ultra-fast file system watcher with native performance for Node.js development tools
Author: Griffin Strier
Latest version: 1.0.4

# @retrigger/core

**Ultra-fast file system watcher with native performance for Node.js development tools**

Replace slow JavaScript-based file watchers with native Rust performance. Get 100-400x faster hot reload times in your webpack and Vite projects.

## 🚀 Quick Start

```bash
npm install @retrigger/core
```

### Webpack

```javascript
// webpack.config.js
const { RetriggerWebpackPlugin } = require('@retrigger/core');

module.exports = {
  plugins: [
    new RetriggerWebpackPlugin({
      watchPaths: ['./src', './config'],
      verbose: process.env.NODE_ENV === 'development',
    }),
  ],
};
```

### Vite

```javascript
// vite.config.js
import { createRetriggerVitePlugin } from '@retrigger/core';

export default {
  plugins: [
    createRetriggerVitePlugin({
      watchPaths: ['./src'],
      enableAdvancedHMR: true,
    }),
  ],
};
```

## 📈 Performance

| Metric             | Standard Watchers | Retrigger | Improvement |
| ------------------ | ----------------- | --------- | ----------- |
| Hot reload latency | 500-2000ms        | <5ms      | 100-400x    |
| CPU usage (idle)   | 5-15%             | <1%       | 5-15x       |
| Memory usage       | 50-200MB          | 10-30MB   | 2-7x        |

## 🛠️ Configuration

### Webpack Plugin Options

```javascript
new RetriggerWebpackPlugin({
  // Directories to watch for changes
  watchPaths: ['./src', './config'],

  // Enable detailed logging
  verbose: false,

  // Debounce time for file events (ms)
  debounceMs: 50,

  // Enable Hot Module Replacement
  enableHMR: true,

  // Use SharedArrayBuffer for ultra-fast communication
  useSharedBuffer: true,

  // SharedArrayBuffer size (bytes)
  sharedBufferSize: 2 * 1024 * 1024, // 2MB

  // Maximum events to batch together
  maxEventBatch: 200,

  // Enable advanced dependency-aware invalidation
  enableAdvancedInvalidation: true,

  // Watch options
  watchOptions: {
    recursive: true,
    exclude_patterns: [
      '**/node_modules/**',
      '**/.git/**',
      '**/dist/**',
      '**/build/**',
    ],
    include_patterns: ['**/*.{js,jsx,ts,tsx,vue,svelte}'],
    enable_hashing: true,
    hash_block_size: 4096,
  },
});
```

### Vite Plugin Options

```javascript
createRetriggerVitePlugin({
  // Directories to watch
  watchPaths: ['./src'],

  // Enable verbose logging
  verbose: false,

  // Debounce time (ms) - lower for Vite
  debounceMs: 10,

  // Enable source map updates
  enableSourceMapUpdate: true,

  // Use SharedArrayBuffer for speed
  useSharedBuffer: true,

  // Enable advanced HMR with dependency tracking
  enableAdvancedHMR: true,

  // HMR invalidation strategy
  hmrInvalidationStrategy: 'smart', // 'conservative' | 'smart' | 'aggressive'

  // Watch options (same as webpack)
  watchOptions: {
    /* ... */
  },
});
```

## 🎯 Features

### Core Benefits

- **Native Performance**: Rust-powered file watching with SIMD-optimized hashing
- **Zero Dependencies**: No heavy JavaScript file watcher dependencies
- **Cross-Platform**: Works on Linux, macOS, and Windows
- **TypeScript Support**: Full TypeScript definitions included
- **Graceful Degradation**: Falls back to JavaScript mode if native components unavailable

### Advanced Features

- **SharedArrayBuffer Communication**: Sub-millisecond event propagation
- **Dependency-Aware Invalidation**: Only rebuild what actually changed
- **Performance Monitoring**: Built-in metrics and optimization tracking
- **Multiple Build Tool Support**: Works with webpack, Vite, Rspack, and more

## 📊 Monitoring

### Performance Stats Endpoint

When using the Vite plugin, access real-time stats at:

- `http://localhost:3000/__retrigger_stats` - Basic performance metrics
- `http://localhost:3000/__retrigger_hmr_stats` - Advanced HMR statistics

### Programmatic Access

```javascript
// Get performance statistics
const stats = await retriggerPlugin.getPerformanceStats();
console.log(`Events processed: ${stats.total_events}`);
console.log(`Average latency: ${stats.averageEventLatency}ms`);
```

## 🔧 Troubleshooting

### Common Issues

**High CPU Usage**

```javascript
// Reduce CPU usage by excluding more directories
new RetriggerWebpackPlugin({
  watchOptions: {
    exclude_patterns: [
      '**/node_modules/**',
      '**/dist/**',
      '**/coverage/**',
      '**/.next/**',
      '**/.nuxt/**',
    ],
  },
});
```

**Slow Initial Scan**

```javascript
// Disable hashing for faster startup
new RetriggerWebpackPlugin({
  watchOptions: {
    enable_hashing: false,
  },
});
```

**Memory Usage**

```javascript
// Reduce SharedArrayBuffer size
new RetriggerWebpackPlugin({
  sharedBufferSize: 512 * 1024, // 512KB instead of 2MB
  maxEventBatch: 50, // Process fewer events at once
});
```

## 📝 TypeScript

Full TypeScript support is included:

```typescript
import {
  RetriggerWebpackPlugin,
  createRetriggerVitePlugin,
  type FileEvent,
  type WatchOptions,
} from '@retrigger/core';

const plugin = new RetriggerWebpackPlugin({
  watchPaths: ['./src'],
  verbose: true,
});
```

## 🏗️ Requirements

- **Node.js**: 16.0.0 or higher
- **Operating System**: Linux, macOS, or Windows
- **Architecture**: x64, ARM64 (Apple Silicon supported)

## 🤝 Contributing

This package is part of the larger [Retrigger](https://github.com/yourusername/retrigger) project. See the main repository for contribution guidelines.

## 📄 License

MIT License - see LICENSE file for details.

---

**Made with ⚡ by developers, for developers who value performance.**