tktax-account

tktax-account is a Rust crate offering robust account transaction analytics within the broader tktax financial suite. It provides traits and data structures for:

• Processing CSV-based transaction logs
• Categorizing and summarizing transaction data
• Generating monthly aggregates and annual summaries
• Deriving arithmetic totals (credits, debits, checks, deposits)
• Assembling advanced financial insights based on transaction patterns

Grounded in oikonomikós (οἰκονομικός, Ancient Greek for household management), this crate helps manage account-related data with strong type safety and production-grade error handling.

Overview

This library implements an Account struct encapsulating:

• An AccountKind (e.g., Checking, Credit, or Savings)
• A TrackedYear for annual grouping
• A collection of Transaction entries parsed from CSV

Multiple traits define how accounts produce analytics:

• Filtering & Searching: GetTransactionsByKeyword, GetTransactionsWithinDates, etc.
• Summaries & Aggregates: GetAccountSummary, CreateMonthlySummary.
• Total Computations: GetTotalDebits, GetTotalCredits, GetTotalChecks, and more.

Integrated error handling uses error_tree! variants (e.g., TransactionFileReadError) to ensure robust runtime resilience without resorting to .unwrap() or .expect().

Key Features

1. Highly Typed
   Avoids string-based error returns. All business logic uses specialized types (e.g., MonetaryAmount, TransactionType).

2. Production-Grade Error Handling
   Custom errors (AccountCreationError, TransactionFileReadError, etc.) unify the codebase for consistent error paths.

3. Efficient Data Processing
   Aggregates monthly data, sums credits/debits, and categorizes transactions with minimal overhead.

4. Expandability
   New categories and account behaviors can be integrated by implementing the core traits (like TransactionCategory).

5. Extensive Trait Implementations
   Simplifies advanced queries (e.g., transactions_over(price)) for in-depth financial analyses.

Example Usage

use tktax_account::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Suppose we have a ProgramConfig from tktax_config
    let config: ProgramConfig = ...;

    let year = TrackedYear::from(2024);
    let account = Account::new(&year, AccountKind::Checking, &config)?;

    // Print a monthly summary
    let monthly_data = account.monthly_summary();
    for summary in monthly_data {
        println!("{:?}", summary);
    }

    // Categorize and display transactions in short format
    let category_map: CategoryMap<MyTxCat> = ...; // from tktax_line_item
    account.print_categorized_transactions_short(&category_map);

    Ok(())
}

Additional Notes

• CSV Parsing: Transaction::try_from_csv_contents reads transaction logs, ensuring minimal data loss and robust type-conversion.
• Summaries: The AccountSummary type offers a concise overview of an account's yearly activity (credits, debits, etc.).
• Expand or Integrate: Extend this crate by adding custom filtering logic or new transaction types via the trait system.