Throw instead of panic

Author: Sajjon

crates/core/src/logic/calendar_logic.rs

@@ -140,15 +140,20 @@ impl YearAndMonth {
     /// use klirr_core::prelude::*;
     /// let start = YearAndMonth::january(2025);
     /// let end = YearAndMonth::april(2025);
-    /// assert_eq!(end.elapsed_months_since(start), 3);
+    /// assert_eq!(end.elapsed_months_since(start).unwrap(), 3);
     /// ```
     ///
-    /// # Panics
-    /// Panics if the `start` month is after the `end` month.
-    pub fn elapsed_months_since(&self, start: impl Borrow<Self>) -> u16 {
+    /// # Throws
+    /// Throws an error if the `start` month is after the `end` month.
+    pub fn elapsed_months_since(&self, start: impl Borrow<Self>) -> Result<u16> {
         let end = self;
         let start = start.borrow();
-        assert!(start <= end, "Expected start <= end month");
+        if start > end {
+            return Err(Error::StartPeriodAfterEndPeriod {
+                start: start.to_string(),
+                end: end.to_string(),
+            });
+        }
         let start_year = **start.year();
         let start_month = **start.month() as u16;
         let end_year = **end.year();
@@ -159,7 +164,8 @@ impl YearAndMonth {
         let months_per_year = 12;
         let start_months = start_year * months_per_year + start_month;
         let end_months = end_year * months_per_year + end_month;
-        end_months - start_months
+        let months_elapsed = end_months - start_months;
+        Ok(months_elapsed)
     }
 }
 
@@ -192,7 +198,7 @@ impl IsPeriod for YearAndMonth {
         Granularity::Month
     }
 
-    fn elapsed_periods_since(&self, start: impl Borrow<Self>) -> u16 {
+    fn elapsed_periods_since(&self, start: impl Borrow<Self>) -> Result<u16> {
         self.elapsed_months_since(start)
     }
 
@@ -232,7 +238,7 @@ impl IsPeriod for YearAndMonth {
 ///     &target_month,
 ///     is_expenses,
 ///     &months_off_record,
-/// );
+/// ).unwrap();
 ///
 /// // The expected invoice number is calculated as follows:
 /// // - Offset is 100
@@ -248,13 +254,13 @@ pub fn calculate_invoice_number<Period: IsPeriod>(
     target_period: &Period,
     is_expenses: bool,
     record_of_periods_off: &RecordOfPeriodsOff<Period>,
-) -> InvoiceNumber {
-    assert!(
-        !record_of_periods_off.contains(offset.period()),
-        "Record of periods off contains offset.period(): {:?} but it should not.",
-        offset.period()
-    );
-    let periods_elapsed_since_offset = target_period.elapsed_periods_since(offset.period());
+) -> Result<InvoiceNumber> {
+    if record_of_periods_off.contains(offset.period()) {
+        return Err(Error::RecordsOffMustNotContainOffsetPeriod {
+            offset_period: format!("{:?}", offset.period()),
+        });
+    }
+    let periods_elapsed_since_offset = target_period.elapsed_periods_since(offset.period())?;
 
     let mut periods_off_to_subtract = 0;
     for period_off in record_of_periods_off.iter() {
@@ -271,7 +277,7 @@ pub fn calculate_invoice_number<Period: IsPeriod>(
         // expenses the same month, the expense invoice number is always higher.
         invoice_number += 1;
     }
-    InvoiceNumber::from(invoice_number)
+    Ok(InvoiceNumber::from(invoice_number))
 }
 
 /// Calculates the number of working days in a given month, excluding weekends.
@@ -589,7 +595,8 @@ mod tests {
             &YearAndMonth::from(target_period),
             is_expenses,
             information.record_of_periods_off(),
-        );
+        )
+        .unwrap();
         assert_eq!(invoice_number, expected.into());
     }
 
@@ -859,7 +866,7 @@ mod tests {
     fn test_elapsed_months_since_when_start_month_is_later_in_the_year_than_end_month() {
         let start = YearAndMonth::december(2024);
         let end = YearAndMonth::april(2025);
-        assert_eq!(end.elapsed_months_since(start), 4);
+        assert_eq!(end.elapsed_months_since(start).unwrap(), 4);
         assert!(start < end);
     }
 
@@ -871,16 +878,14 @@ mod tests {
     }
 
     #[test]
-    #[should_panic]
-    fn test_elapsed_months_since_panic() {
+    fn elapsed_months_since_throws_when_start_month_is_later_than_end_month() {
         let start = YearAndMonth::april(2025);
         let end = YearAndMonth::march(2025);
-        end.elapsed_months_since(start);
+        assert!(end.elapsed_months_since(start).is_err());
     }
 
     #[test]
-    #[should_panic]
-    fn test_calculate_invoice_number_panics_for_invalid_input() {
+    fn test_calculate_invoice_number_throws_for_invalid_input() {
         let month = YearAndMonth::may(2025);
         let invoice_info = ProtoInvoiceInfo::builder()
             .offset(
@@ -893,12 +898,13 @@ mod tests {
             .purchase_order(PurchaseOrder::sample())
             .build();
 
-        let _ = calculate_invoice_number(
+        let result = calculate_invoice_number(
             invoice_info.offset(),
             &YearAndMonth::december(2025),
             true,
             invoice_info.record_of_periods_off(),
         );
+        assert!(result.is_err());
     }
 
     #[test]

crates/core/src/models/data/data.rs

@@ -106,7 +106,7 @@ impl<Period: IsPeriod> Data<Period> {
             &target_period,
             is_expenses,
             self.information().record_of_periods_off(),
-        );
+        )?;
         let is_expenses_str_or_empty = if is_expenses { "_expenses" } else { "" };
         let vendor_name = self.vendor.company_name().replace(' ', "_");
 

crates/core/src/models/data/submodels/expenses_for_periods.rs

@@ -6,38 +6,41 @@ use crate::{define_item_struct, prelude::*};
 #[serde(transparent)]
 pub(super) struct ExpensesForPeriods(Vec<Item>);
 
+/// Ephemeral type used such that expensed items sharing all fields except for quantity
+/// are considered the same, allowing us to merge them into a single item with the total quantity.
 #[derive(Hash, Eq, PartialEq, Display, Clone, Debug, PartialOrd, Ord, Serialize, Deserialize)]
 struct QuantityIgnored;
-define_item_struct!(pub, Marker, QuantityIgnored);
+define_item_struct!(pub, ExpenseIdentifier, QuantityIgnored);
 
 impl ExpensesForPeriods {
     /// Inserts a vector of items into the `ExpensesForPeriods`, merging items that are the same
     /// except for their quantity.
     pub(super) fn insert(&mut self, items: Vec<Item>) {
         self.0.extend(items);
 
-        let mut map = IndexMap::<Marker, Quantity>::new();
+        let mut map = IndexMap::<ExpenseIdentifier, Quantity>::new();
         for item in &self.0 {
-            let marker = Marker::builder()
+            let identifier = ExpenseIdentifier::builder()
                 .name(item.name().clone())
                 .transaction_date(*item.transaction_date())
                 .unit_price(*item.unit_price())
                 .currency(*item.currency())
                 .quantity(QuantityIgnored)
                 .build();
 
-            map.entry(marker)
+            map.entry(identifier)
                 .and_modify(|q| *q += *item.quantity())
                 .or_insert(*item.quantity());
         }
 
-        self.0.retain(|_| false);
-        for (marker, quantity) in map {
+        self.0.clear();
+
+        for (identifier, quantity) in map {
             let item = Item::builder()
-                .name(marker.name().clone())
-                .transaction_date(*marker.transaction_date())
-                .unit_price(*marker.unit_price())
-                .currency(*marker.currency())
+                .name(identifier.name().clone())
+                .transaction_date(*identifier.transaction_date())
+                .unit_price(*identifier.unit_price())
+                .currency(*identifier.currency())
                 .quantity(quantity)
                 .build();
             self.0.push(item);

crates/core/src/models/data/submodels/is_period.rs

@@ -20,7 +20,7 @@ impl<T: Eq + PartialOrd + Hash + Clone + std::fmt::Debug + Into<PeriodAnno> + Tr
 
 pub trait IsPeriod: PeriodMarker {
     fn max_granularity(&self) -> Granularity;
-    fn elapsed_periods_since(&self, start: impl Borrow<Self>) -> u16;
+    fn elapsed_periods_since(&self, start: impl Borrow<Self>) -> Result<u16>;
     fn to_date_end_of_period(&self) -> Date;
     fn year(&self) -> &Year;
     fn month(&self) -> &Month;

crates/core/src/models/data/submodels/period_anno.rs

@@ -67,13 +67,18 @@ impl IsPeriod for PeriodAnno {
     }
 
     /// Number of periods that have elapsed since the given start period.
-    fn elapsed_periods_since(&self, start: impl Borrow<Self>) -> u16 {
+    fn elapsed_periods_since(&self, start: impl Borrow<Self>) -> Result<u16> {
         match (self, start.borrow()) {
             (Self::YearAndMonth(lhs), Self::YearAndMonth(rhs)) => lhs.elapsed_periods_since(rhs),
             (Self::YearMonthAndFortnight(lhs), Self::YearMonthAndFortnight(rhs)) => {
                 lhs.elapsed_periods_since(rhs)
             }
-            _ => panic!("Cannot mix period kinds"),
+            (Self::YearAndMonth(_), Self::YearMonthAndFortnight(_)) => {
+                Err(Error::PeriodIsNotYearAndMonth)
+            }
+            (Self::YearMonthAndFortnight(_), Self::YearAndMonth(_)) => {
+                Err(Error::PeriodIsNotYearMonthAndFortnight)
+            }
         }
     }
 
@@ -128,7 +133,7 @@ mod tests {
     fn test_elapsed_periods_since_year_and_month() {
         let early = Sut::YearAndMonth(YearAndMonth::december(2024));
         let late = Sut::YearAndMonth(YearAndMonth::february(2025));
-        assert_eq!(late.elapsed_periods_since(&early), 2);
+        assert_eq!(late.elapsed_periods_since(&early).unwrap(), 2);
     }
 
     #[test]
@@ -147,7 +152,7 @@ mod tests {
                 .half(MonthHalf::First)
                 .build(),
         );
-        assert_eq!(late.elapsed_periods_since(&early), 3); // whole of january (2) + half of december (1)
+        assert_eq!(late.elapsed_periods_since(&early).unwrap(), 3); // whole of january (2) + half of december (1)
     }
 
     #[test]
@@ -208,17 +213,17 @@ mod tests {
     }
 
     #[test]
-    #[should_panic(expected = "Cannot mix period kinds")]
-    fn test_mix_ym_ymf() {
-        let _ = Sut::YearAndMonth(YearAndMonth::sample())
+    fn mix_ym_ymf_throws() {
+        let result = Sut::YearAndMonth(YearAndMonth::sample())
             .elapsed_periods_since(Sut::YearMonthAndFortnight(YearMonthAndFortnight::sample()));
+        assert!(result.is_err(), "Expected error when mixing period kinds");
     }
 
     #[test]
-    #[should_panic(expected = "Cannot mix period kinds")]
-    fn test_mix_ymf_ym() {
-        let _ = Sut::YearMonthAndFortnight(YearMonthAndFortnight::sample())
+    fn mix_ymf_ym_throws() {
+        let result = Sut::YearMonthAndFortnight(YearMonthAndFortnight::sample())
             .elapsed_periods_since(Sut::YearAndMonth(YearAndMonth::sample()));
+        assert!(result.is_err(), "Expected error when mixing period kinds");
     }
 
     #[test]