file-read-events

Watch for read events on the given file and byte

Purpose

In certain scenarios, it becomes essential to track the bytes read from a file by the operating system's file system. This module aims to provide a solution by providing a mechanism to receive events whenever a read operation occurs on a specified file, including details such as the number of bytes read and the read offset.

A major use case is end-to-end and integration tests. You can check if a specific part of the file is read (or is not read), so you can assert that your code is working as intended in terms of correct file access.

Installation

npm install file-read-events

Basic Usage

import { FileReadEvents } from "../src/FileReadEvents";

const fileEvents = new FileReadEvents('C:/temp/target-file.txt');

fileEvents.on('read', ({ offset, ioSize, path }) => {
    console.log(offset, ioSize, path); 
    // 0 2048 C:/temp/target-file.txt
});

// start watching
fileEvents.start(); 

Close the watcher process at the cleanup.

fileEvents.end();

API

With specifying target byte.

const fileEvents = new FileReadEvents('C:/temp/target-file.txt', 1234);
fileEvents.on('read', ({ offset, ioSize, path, isTargetByte }) => {
    console.log(offset, ioSize, path, isTargetByte); 
});
fileEvents.start();

Methods

Method	Description
constructor	The first parameter is the path to the file to watch. The second parameter (optional) is the target byte (zero-indexed)
start	Start the watcher process
end	End the watcher process
on, off	FileReadEvents extends EventEmitter, so you can use on and off to manage event handlers.

Events

Event name	Description
ready	The process is launched and ready to watch
error	Encountered an error
read	A read event was observed on the target file
exit	The process was killed

read Event properties

The handlers you add for the read event are called with an event object as their only argument. This object has the following properties:

Property	Description
offset	Number of bytes skipped from the beginning of the file
ioSize	Number of bytes that has been read by the file system
path	Absolute path to the file being read
isTargetByte	Is the specified target byte read in this event

Example

Without specifying target byte.

const fileEvents = new FileReadEvents('C:/temp/target-file.txt');
fileEvents.on('read', ({ offset, ioSize, path }) => {
    console.log(offset, ioSize, path); 
});
fileEvents.start();

Compatibility

This is currently working on Windows, contributions are welcome if you can help with adding support for other operating systems. Read "How does it work" section below for more details on this.

How does it work

This package essentially serves as a wrapper around WinFileReadEvents, a Windows CLI utility written in C#. It utilizes Event Tracing for Windows (ETW) to capture these events from the operating system. The precompiled standalone binary is downloaded to the bin directory during the postinstall script of this package.

IMPORTANT: Due to Windows restrictions, the executable must be run as an administrator. Please ensure that you run the code in a terminal with administrator privileges; otherwise, it will emit an error event and will not work.