🧿 Vigilite

Relentlessly vigilant. Vigilite gives you total awareness of the filesystem. Instantly detect additions, changes, and deletions across files and directories with precise filtering and event-driven control. Power live editing, automate workflows, trigger intelligent responses, and sync content in real time.
Detect instantly. Respond intelligently.

🌟 Features

• 📂 Directory + File Watching – Monitor folders and individual files side-by-side
• 🎯 Extension Filtering – Limit reactions to specific file types like .json, .md, .txt
• ⚡ Instant Event Signals – Get notified on added, changed, and deleted events
• 🧠 Context-Rich Callbacks – Each signal includes label, path, name, type, timestamp, and readFile()
• 🛡️ Custom Reveal Logic – Override how files are read before use
• 🧪 Signal Filtering – Decide whether a change should trigger an event with onSignalIf
• 🧘 Minimal Setup – No complex configuration—just pass a few paths and go

🧪 Use Cases

• 🧬 Reactively reload config or docs as they change
• 🧹 Automatically clean or archive generated files
• 📦 Trigger workflows on file drops (e.g., uploads or exports)
• 🔄 Sync local changes to remote destinations
• 📊 Feed real-time file logs into monitoring dashboards

⚙️ System Requirements

| Requirement | Version | |----------------|--------------------| | Node.js | ≥ 18.x | | npm | ≥ 9.x (recommended)| | OS | Windows, macOS, Linux |

📜 API Specifications

🔧 Constructor

Initialize with an options object.

new Vigilite(options)

options Object

| Key | Description | Default | |-----------------|-----------------------------------------------------------------------------|--------------------------| | directories | Object of label → directory path to watch | {} | | extensions | Array of allowed extensions (e.g., .json, .md) | [".json", ".md"] | | onSignalIf | Optional async predicate (filePath, context) => boolean | null | | onReveal | Optional async function to customize file reading | null | | onSignal | Callback when a file change is detected | () => {} |

🧩 Signal Event Object

Each emitted event provides the following structure:

| Key | Description | |-------------|--------------------------------------------------| | label | The label of the directory or file watcher | | name | Filename without the extension | | type | "added", "changed", or "deleted" | | path | Full absolute file path | | timestamp | Event timestamp in ms | | readFile()| Async method to retrieve the file content |

🧰 Methods

| Method | Description | Async | |----------------------------------|---------------------------------------------------------|--------| | watch() | Begin watching all configured directories | ❌ | | stop() | Stop all watchers | ❌ | | watchFile(filePath, label?) | Watch a specific file | ❌ | | watchFiles(filePaths, prefix?) | Watch multiple files | ❌ | | unwatchFile(filePath) | Stop watching a specific file | ❌ | | unwatchDirectory(label) | Stop watching a specific directory by label | ❌ | | getWatchedFiles() | Get currently watched file paths | ❌ | | getWatchedDirectories() | Get labels of all watched directories | ❌ |

✨ Example Usage

📦 Installation

npm install @trap_stevo/vigilite

Watching Logs Directory

const Vigilite = require("@trap_stevo/vigilite");

const vigil = new Vigilite({
     directories : {
          logs : `${process.cwd()}/logs`
     },

     extensions : [".json", ".md"],

     onSignalIf : async (filePath, context) =>  {
          // Optional: skip ignored files
          return !filePath.includes("ignore");
     },

     onReveal : async (filePath, event, encoding) =>  {
          const fs = require("fs");
          return await fs.promises.readFile(filePath, encoding);
     },

     onSignal : async (event) =>  {
          console.log(`🔔 [${event.label}] "${event.name}" ${event.type}`);

          if (event.type !== "deleted") {
               const content = await event.readFile();
               console.log(`Content:\n${content}`);
               
               // - Logic to send to a client or service
          }
     }
});

vigil.watch();

✨ License

See License in LICENSE.md

🧠 Stay Aware. Stay in Control.

Whether watching a single file or orchestrating entire directory trees, Vigilite ensures that every change becomes an opportunity to act—cleanly, efficiently, and with intent.