als-store/docs/4-file-api/2-methods.md

Library for streamlined file management and advanced data caching, featuring intelligent file searching, dynamic cache control, and flexible file operations

### Asynchronous Methods in the `File` Class

#### `async getStats()`
- **Purpose**: Retrieves and updates the statistical information of the file such as size, access time, modification time, and creation time.
- **Functionality**:
  - Checks if statistics are already loaded to avoid unnecessary file system access.
  - Retrieves stats using `stat` from `fs-extra` if the file exists.
  - Updates the internal `#stats` property with relevant statistical data.
  - Depends on `File.stats`, which is a configurable array defining which statistical properties to load and cache.
  - Only the properties specified in `File.stats` are stored in the cache, making it customizable based on application needs.
- **Usage**: Typically called to get updated file information, especially after file operations that might change these statistics. It allows for selective caching of file statistics as defined in `File.stats`.

#### `async getValue()`
- **Purpose**: Loads and returns the content of the file.
- **Functionality**:
  - Checks if the file content is already loaded in the cache.
  - Reads the file content asynchronously using `readFile` from `fs-extra`.
  - Updates the internal `#value` property with the file content.
- **Usage**: Useful for accessing the file content without directly interacting with the file system, leveraging the internal caching mechanism.

#### `async save()`
- **Purpose**: Saves changes to the file, including content and metadata.
- **Functionality**:
  - Handles new file creation or updating existing files.
  - Manages file renaming and ensures synchronization with the cache.
  - Writes the file content to the disk, updating the file system.
  - Retrieves the latest file stats after saving.
- **Usage**: Called to persist modifications to the file, ensuring that changes in content or metadata are accurately reflected in the file system.
- **returns** instance of file

#### `async remove()`
- **Purpose**: Deletes the file from the file system and removes its data from the cache.
- **Functionality**:
  - Uses `unlink` from `fs-extra` to delete the file.
  - Handles errors during the deletion process, capturing them in an `errors` array.
  - Cleans up the cache by calling `removeFromCache`.
- **Usage**: Utilized to permanently delete a file, effectively removing it from both the file system and the internal cache.