Struct FileHandler 

#[non_exhaustive]
pub struct FileHandler;

Handler for file I/O operations (JSON and CSV)

Implementations

impl FileHandler

pub fn save<T: Serialize>( data: &[T], format: &FileFormat, filename_prefix: &str, ) -> Result<String>

Save data to a file in the data directory.

Files are saved to the data/ directory (created if it doesn’t exist) with a timestamp in the filename.

Arguments

• data - Data to save (must implement Serialize)
• format - File format to save as (FileFormat::Json for JSON or FileFormat::Csv for CSV)
• filename_prefix - Prefix for the filename. The final filename will be {prefix}_{timestamp}.{extension}

Errors

• std::io::Error - If the file cannot be opened or written to, or if the data directory cannot be created
• serde_json::Error - If the JSON cannot be serialized

Returns

• Result<String> - Full path to the saved file (e.g., data/recent_tracks_20240101_120000.json)

pub fn load_ndjson<T: DeserializeOwned>(file_path: &str) -> Result<Vec<T>>

Load existing NDJSON data from a file - one item per line.

Arguments

• file_path - Path to the NDJSON file to read

Errors

• std::io::Error - If the file cannot be opened
• serde_json::Error - If a line cannot be deserialized into T

pub fn append_or_create_ndjson<T: Serialize>( new_data: &[T], file_path: &str, ) -> Result<()>

Append new items to an existing NDJSON file, or create it if it does not exist.

Arguments

• new_data - New items to append
• file_path - Path to the target NDJSON file

Errors

• std::io::Error - If the file cannot be opened or written

pub fn save_single<T: Serialize>(data: &T, filename: &str) -> Result<()>

Save a single item to a JSON file

Errors

• std::io::Error - If there was an error reading or writing the file
• serde_json::Error - If there was an error serializing the data

Arguments

• data - Data to save
• filename - Filename to save as

pub fn load<T: DeserializeOwned>(file_path: &str) -> Result<Vec<T>>

Load existing JSON data from a file.

Arguments

• file_path - Path to the JSON file to read

Errors

• std::io::Error - If the file cannot be opened
• serde_json::Error - If the JSON cannot be deserialized into Vec<T>

pub fn sidecar_path(file_path: &str) -> String

Return the path of the sidecar metadata file for file_path.

The sidecar stores the latest known Unix timestamp so subsequent update calls do not need to deserialize the full data file.

pub fn read_sidecar_timestamp(file_path: &str) -> Option<u32>

Read the latest timestamp from a sidecar metadata file.

Returns None if the sidecar does not exist or cannot be parsed.

pub fn write_sidecar_timestamp(file_path: &str, timestamp: u32) -> Result<()>

Write a timestamp to the sidecar metadata file associated with file_path.

Errors

• std::io::Error - If the sidecar file cannot be written

pub fn append_or_create_csv<T: Serialize>( new_data: &[T], file_path: &str, ) -> Result<()>

Append new items to an existing CSV file, or create it with headers if it does not exist.

When appending to an existing file the header row is omitted so it is not duplicated.

Arguments

• new_data - New items to append
• file_path - Path to the target CSV file

Errors

• std::io::Error - If the file cannot be opened or written
• csv::Error - If serialization fails

pub fn prepend_json<T: Serialize + DeserializeOwned + Clone>( new_data: &[T], file_path: &str, ) -> Result<()>

Prepend new items to an existing JSON file, or create the file if it does not exist.

New items are placed before existing items so the result remains sorted newest-first, which matches the order returned by the Last.fm API.

Arguments

• new_data - New items to prepend
• file_path - Path to the target JSON file

Errors

• std::io::Error - If the file cannot be read or written
• serde_json::Error - If serialization or deserialization fails

Trait Implementations

impl Debug for FileHandler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.