Directory Monitor

File monitoring utility that tracks filesystem changes (creation and deletion of directories) and reports them in real time via a callback.

Overview

The monitor maintains an internal event loop (epoll-based) and allows dynamically adding or removing directories to watch. It reports directory-level events with normalized paths, even when parent directories are removed recursively.

Key characteristics demonstrated by the output:

• Multiple watch roots can be added and removed at runtime
• The active watch list is queryable
• Recursive directory creation and deletion events are detected
• Deleted path segments are explicitly marked as (deleted) when intermediate directories disappear

Usage

const {creat,destroy} = require("nd-file-notify");

const o = creat((ftype, event_name, path)=>{
            //ftype        : dire |  file
            //event_name   : created | deleted | modified| moved_from | moved_to | attr
            console.log({ftype, event_name, path})
});
o.start();

.....

o.destroy(); //MUST when you exist

getter

 .ftypes
 .event\_names

 .fan\_fd
 .epfd
 .stop\_fd

accessor

.cb
.cb = (ftype, event\_name, path)=>{} 

methods;

.start()
.stop()


.has(path);
.add(path);
.del(path);
 
.list();    

ftype

["dire","file"]

event_names

[
  '', 'created',
  'deleted', 'modified',
  'moved',   'moved',
  'attr',    'created',
  'deleted', 'modified',
  'moved',   'moved',
  'attr'
]

Monitor State

Example monitor initialization output:

Monitor [{
  "ptr": "0x38c51390",
  "fan_fd": 17,
  "epfd": 18,
  "stop_fd": 19
}] {
  _cb: [Function: cb],
  active: true
}

This indicates:

• fan_fd: fanotify file descriptor
• epfd: epoll file descriptor
• stop_fd: internal shutdown signal
• _cb: user-defined callback
• active: monitor is running

Managing Watch Directories

Initial Watch List

--- Current Watch List ---
(empty)
--------------------------
[]

No directories are being monitored initially.

Adding Directories

[System] Watch added: /tmp
[System] Watch added: /root

Resulting watch list:

--- Current Watch List ---
 - /root
 - /tmp
--------------------------
[ '/root', '/tmp' ]

Removing a Directory

[System] Watch removed: /root

Updated watch list:

--- Current Watch List ---
 - /tmp
--------------------------
[ '/tmp' ]

Event Model

Each filesystem event is delivered to the callback as a structured object:

{
  ftype: 'dire',
  event_name: 'created' | 'deleted',
  path: '/absolute/path'
}

• ftype: currently always 'dire' (directory)
• event_name: event type
• path: resolved absolute path

Deletion Events

When directories are removed recursively, the monitor reports deletions from deepest to shallowest levels. If an intermediate directory disappears before its children are fully resolved, it is annotated with (deleted).

Example:

{
  ftype: 'dire',
  event_name: 'deleted',
  path: '/tmp/watch/aaa/bbb (deleted)/ccc'
}

This means bbb was deleted before ccc could be fully traversed.

More examples:

{ ftype: 'dire', event_name: 'deleted', path: '/tmp/watch/aaa' }
{ ftype: 'dire', event_name: 'deleted', path: '/tmp/watch' }

Creation Events

Recursive directory creation is reported in order, from parent to child:

{ ftype: 'dire', event_name: 'created', path: '/tmp/watch' }
{ ftype: 'dire', event_name: 'created', path: '/tmp/watch/11' }
{ ftype: 'dire', event_name: 'created', path: '/tmp/watch/11/22' }
{ ftype: 'dire', event_name: 'created', path: '/tmp/watch/11/22/33' }
{ ftype: 'dire', event_name: 'created', path: '/tmp/watch/11/22/33/44' }

And similarly for other directory trees:

{ ftype: 'dire', event_name: 'created', path: '/tmp/watch/aaa/bbb/ccc/ddd' }

Notes

• Only directories are shown in this output; file events may be unsupported or intentionally filtered.
• The monitor is resilient to deep directory trees and rapid recursive changes.
• Output order reflects actual kernel event delivery, not synthetic ordering.

Typical Use Cases

License