als-path-tree/readme.md

A Node.js library for managing a virtual file system structure, offering functionalities for file and directory operations with a shared storage system.

# als-path-tree v3

> **Important:** Version 3.0 of `als-path-tree` is **not** backward compatible with the older v2.0.  
> The entire structure has been redesigned to provide a more flexible, event-driven path tree and caching system.

## Overview
The `als-path-tree` library provides a robust caching system for file-like structures. It supports hierarchical directories and files, integrating an event emitter and a memory monitoring mechanism to optimize resource usage. The library is ideal for managing in-memory representations of file systems, including local disks, cloud-based systems like S3, or any other custom backend.

## Key Features
- Flexible directory and file structures.
- Event-driven operations using `als-event-emitter`.
- Memory management with automatic cleanup.
- Configurable through global options for various use cases.

## Installation

```bash
npm install als-path-tree
```

## Import

```js
const { Item, File, Directory, MemoryMonitor, options } = require('als-path-tree');
```

## Architecture
1. **`Item` Class:** The base class for all entities (`File` and `Directory`).
2. **`Directory` Class:** Represents directories and manages nested structures.
3. **`File` Class:** Represents files, including content and metadata.
4. **`MemoryMonitor` Class:** Handles memory management for files.
5. **Global `options`:** Configure thresholds, weights, and logging.

---

## Classes and APIs

### `Item` Class
A foundational class for file and directory entities. Provides utilities for path management and event-driven behavior.

#### API
```js
class Item {
   static get options(); // Returns the global options object.
   static memMonitor;    // Shared MemoryMonitor instance.
   static emitter;       // EventEmitter instance.
   get main();           // Returns the Item class itself (useful in extended classes).
   constructor(name, parent, isFile = false); // Initializes the entity.
   get path();           // Full path of the item.
   get root();           // Returns the root directory.
   getParts(path);       // Splits a path into segments.
   splitPath(path);      // Splits a path into parts and filename.
   rename(newName);      // Renames the item.
}
```


### `Directory` Class
Extends `Item` and represents a directory.

#### API
```js
class Directory extends Item {
   constructor(name, parent = null);
   get isEmpty();                // Returns true if the directory is empty.
   get dirs();                   // Returns all nested directories as an array.
   get list();                   // Returns all nested files and directories.
   getItem(path);                // Retrieves an item by path.
   addDir(path);                 // Adds a new directory.
   addFile(path, meta, content); // Adds a new file.
   removeIfEmpty();              // Removes the directory if it's empty.
   delete();                     // Deletes the directory and its contents.
   copyTo(destPath);             // Copies the directory and its tree.
   moveTo(destPath);             // Moves the directory to a new path.
}
```

#### Example
```js
const root = new Directory('root');
const subDir = root.addDir('subdir');
const file = root.addFile('subdir/file.txt', { size: 512 }, 'File Content');

console.log(root.getItem('subdir/file.txt') === file); // true
subDir.delete();
console.log(root.getItem('subdir/file.txt')); // null
```

---

### `File` Class
Extends `Item` and represents an individual file with content and metadata.

#### API
```js
class File extends Item {
   constructor(name, meta, parent, content);
   prepareMeta(meta = {});       // Prepares file metadata.
   get buffer();                // Returns the file's buffer (increments access count).
   save(value);                 // Saves new content to the file.
   compare(content);            // Compares the current buffer with new content.
   delete();                    // Deletes the file.
   copyTo(destPath);            // Copies the file to a new path.
   moveTo(destPath);            // Moves the file to a new path.
   get lastAccessTime();        // Returns the last access time.
   get age();                   // Returns the file's age in hours.
   get content();               // Returns the file's content as a string.
   get json();                  // Parses and returns the file's content as JSON.
}
```

#### Example
```js
const root = new Directory('root');
const file = root.addFile('example.json', {}, JSON.stringify({ key: 'value' }));

console.log(file.json); // Output: { key: 'value' }
file.save('New Content');
console.log(file.content); // Output: New Content
```

---

### `MemoryMonitor` Class
Manages memory usage by clearing file buffers when resources are low.

#### API
```js
class MemoryMonitor {
   static get options();         // Returns global options.
   filesWithContent;             // Set of files with content in memory.
   constructor();
   get freeMemoryPercentage();   // Percentage of free system memory.
   get isMemOk();                // Checks if memory is sufficient.
   add(file);                    // Adds a file to memory management.
   clear(force = false);         // Clears memory by removing file buffers.
   calculateRating(file);        // Calculates a file's rating for clearing priority.
   remove(...files);             // Removes files from memory monitoring.
}
```

#### Example
```js
const memoryMonitor = new MemoryMonitor();
const root = new Directory('root');
const file = root.addFile('temp.txt', {}, 'Temporary Content');

memoryMonitor.add(file);
memoryMonitor.clear();
console.log(file.buffer); // null if memory is full
```

---

### Global Options
Configure thresholds, logging, and file rating.

#### Default Options
```js
{
   logger: console,
   thresholdRating: 3,
   thresholdPercentage: 20,
   maxStoreTime: 1000 * 60 * 60 * 24, // 24 hours
   weights: {
      accessCount: 5, // Higher priority for frequently accessed files.
      lastAccess: -3, // Lower priority for older files.
      size: -1,       // Lower priority for larger files.
   }
}
```

#### Example
```js
options.thresholdRating = 5;
options.logger = {
   warn: msg => console.warn(`[Custom Logger] ${msg}`),
   log: console.log,
   error: console.error,
};
```

---

## Examples

### File and Directory Management
```js
const root = new Directory('root');
root.addDir('subdir');
root.addFile('subdir/example.txt', {}, 'Example Content');

const file = root.getItem('subdir/example.txt');
console.log(file.content); // Output: Example Content
```

### Memory Management
```js
const root = new Directory('root');
const file = root.addFile('largeFile.txt', {}, Buffer.alloc(1024 * 1024 * 10)); // 10 MB

MemoryMonitor.add(file);
MemoryMonitor.clear();
console.log(file.buffer); // null if memory is cleared
```

---

## Advanced Usage
### Replacing the `File` Class
You can replace the default `File` class with your custom implementation:
```js
class CustomFile extends File {
   customMethod() {
      console.log('Custom logic');
   }
}
Directory.File = CustomFile;
```