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

$3

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.
}
`

$3

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
`

---

$3

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
`

---

$3

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
`

---

$3

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

$3

`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
`

$3

`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

$3

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