als-path-tree

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

npm install als-path-tree

Import

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

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

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

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

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

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

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

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

{
   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

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

---

Examples

File and Directory Management

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

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:

class CustomFile extends File {
   customMethod() {
      console.log('Custom logic');
   }
}
Directory.File = CustomFile;