vmind_dir_scan/readme.md

A library to scan the file system based on a root folder. The library will scan recursively and send a callback for every file and directory it finds, including details such as age, name, path, and size.

# VMind Directory Scanner

![TypeScript](https://img.shields.io/badge/TypeScript-%233178C6.svg?style=flat&logo=typescript&logoColor=white)

An awesome package that does amazing things.

## 📦 Installation

```sh
npm install vmind_dir_scan
```

## Description

VMind Directory Scanner is a TypeScript/Node.js library that recursively scans a given directory, listing all files and directories while providing metadata such as name, path, size, and age. The library emits events for each file and directory found, allowing real-time processing.

## Features

- Recursively scans directories
- Emits events for files and directories
- Provides metadata: name, path, size, age (in days and seconds)
- Supports error handling via event emission

## Usage

The `FileSysScanHandler` class provides an easy way to iteratively scan a directory tree. You can listen to events to handle files and directories as they are discovered.

### Complete sample project on how to use the libarary

here is a sample integration on how to use the library, you can pull down the code

I show a more advanced way to use the library and manage retention in a file system and passing
a specified number of worker threads to scan in parallel large drive.

- request to recieve message if file / folder is older then specified days
- request to recieve message if file / folder is older then specified seconds

https://github.com/EmiRoberti77/vmind_dir_scan_client

### below is a simple integration to the library

### Importing the Library

```ts
import { FileSysScanHandler, FSEvent, FS_TYPE } from "vmind_scan_dir";
```

---

```ts
import { FileSysScanHandler, FSEvent, FS_TYPE } from "vmind_scan_dir";

// Create an instance of FileSysScanHandler
const scanner = new FileSysScanHandler("/path/to/start");

// Listen for directory events

scanner.on("FS_TYPE.DIR", (event) => {
  console.log("Directory found:", event);
});

// Listen for file events
scanner.on("FS_TYPE.FILE", (event) => {
  console.log("File found:", event);
});

// Listen for errors
scanner.on("FS_TYPE.ERROR", (error) => {
  console.error("Error encountered:", error);
});

// Start the scanning process
scanner.scanIterative(5).then(() => {
  console.log("Scanning complete.");
});
```

- `file`: Emitted when a file is found. Provides an `FSEvent` object.
- `dir`: Emitted when a directory is found. Provides an `FSEvent` object.
- `error`: Emitted when an error occurs. Provides an error message.

### FSEvent Object

```ts
interface FSEvent {
  name: string; // File or directory name
  path: string; // Full path
  type: "file" | "dir"; // Type
  ageInSeconds: number; // Age of file in seconds
  ageInDays: number; // Age of file in days
  size: number; // File size in MB
}
```

## License

MIT

## Author

Emi Roberti