planter-core 0.0.7

use crate::identifiable::{self, Identifiable};
use crate::money::{Money, MultiCurrencyAmount};
use crate::stakeholders::Stakeholder;
use crate::title::Title;
use bon::Builder;
use chrono::{DateTime, Utc};
use uuid::Uuid;

/// A one-time cost: buying `quantity` units at `unit_price` each, optionally on a given `date`.
/// A [`Resource`] can have several over its life (an initial buy, later resupply at a new
/// price).
/// Built with [`Purchase::builder`]
///
/// # Example
/// ```
/// use planter_core::{resources::Purchase, money::{Money, Currency}};
///
/// let purchase = Purchase::builder()
///     .quantity(5)
///     .unit_price(Money::from_minor_units(150, Currency::EUR))
///     .build();
/// assert_eq!(purchase.total(), Money::from_minor_units(750, Currency::EUR));
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Builder)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Purchase {
    /// The stable identifier of this purchase, generated on construction.
    #[builder(skip = Uuid::new_v4())]
    id: Uuid,
    /// How many units were bought.
    quantity: u32,
    /// Price of one unit.
    unit_price: Money,
    /// When the purchase happened.
    date: Option<DateTime<Utc>>,
}

impl Identifiable for Purchase {
    fn id(&self) -> Uuid {
        self.id
    }
}

impl Purchase {
    /// Returns the stable identifier of this purchase.
    #[must_use]
    pub const fn id(&self) -> Uuid {
        self.id
    }

    /// Returns how many units this purchase bought.
    #[must_use]
    pub const fn quantity(&self) -> u32 {
        self.quantity
    }

    /// Returns the price of one unit.
    #[must_use]
    pub const fn unit_price(&self) -> Money {
        self.unit_price
    }

    /// Returns when this purchase happens/happened, if known.
    #[must_use]
    pub const fn date(&self) -> Option<DateTime<Utc>> {
        self.date
    }

    /// Returns the total cost of this purchase (`quantity * unit_price`, saturating).
    #[must_use]
    pub const fn total(&self) -> Money {
        Money::from_minor_units(
            self.unit_price
                .minor_units()
                .saturating_mul(self.quantity as u64), // u32 -> u64 is lossless
            self.unit_price.currency(),
        )
    }

    /// Sets how many units this purchase bought.
    pub const fn set_quantity(&mut self, quantity: u32) {
        self.quantity = quantity;
    }

    /// Sets the price of one unit.
    pub const fn set_unit_price(&mut self, unit_price: Money) {
        self.unit_price = unit_price;
    }

    /// Sets when this purchase happens/happened.
    pub const fn set_date(&mut self, date: DateTime<Utc>) {
        self.date = Some(date);
    }

    /// Clears this purchase's date.
    pub const fn clear_date(&mut self) {
        self.date = None;
    }
}

/// A resource is just a named, cost-bearing thing: "Timber", "Excavator", "Legal counsel".
/// Cost comes from two independent parts, either of which may be absent:
/// - [`purchases`](Self::purchases): one-time costs (buying materials, a machine, a licence),
/// - [`hourly_rate`](Self::hourly_rate): a cost per hour a task engages it (wages, rental, fuel
///   or wear).
///
/// An employee has only a rate, raw steel has only a purchase, a bought generator that also
/// burns fuel has both.
///
/// Optionally a resource has a [`contact`](Self::contact): whoever is responsible for it or
/// supplies it. If a resource is a person, the contact might be the person itself.
///
/// ```
/// use planter_core::{resources::{Purchase, Resource}, money::{Money, Currency}};
///
/// let mut excavator = Resource::new("Excavator".parse().unwrap())
///     .at_hourly_rate(Money::from_minor_units(3_000, Currency::EUR));
/// excavator.add_purchase(
///     Purchase::builder().quantity(1).unit_price(Money::from_minor_units(10_000, Currency::EUR)).build(),
/// );
/// ```
///
/// Each priced part carries its own [`Money`] currency independently: a resource's hourly rate
/// and its purchases need not agree (a truck bought in EUR might be fueled at an hourly rate
/// billed in USD). A resource with no rate and no purchases contributes nothing to cost.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Resource {
    /// The stable identifier of this resource, generated on construction.
    id: Uuid,
    /// A human-readable title: "Timber", "Excavator", "Legal counsel".
    title: Title,
    /// Who to contact about this resource. `None` when nobody is on record.
    contact: Option<Stakeholder>,
    /// One-time costs recorded against this resource, in the order they were added.
    purchases: Vec<Purchase>,
    /// Cost per hour a task engages this resource (wages, rental, fuel or wear). `None` for
    /// resources with no time-based cost, such as raw materials.
    hourly_rate: Option<Money>,
}

impl Identifiable for Resource {
    fn id(&self) -> Uuid {
        self.id
    }
}

impl Resource {
    /// Creates a resource with the given title, no contact, no purchases and no rate.
    ///
    /// The title is a validated [`Title`]; build one with `"…".parse()` or
    /// [`Title::try_new`](crate::title::Title::try_new).
    ///
    /// # Example
    /// ```
    /// use planter_core::resources::Resource;
    ///
    /// let stimpack = Resource::new("Stimpack".parse().unwrap());
    /// assert_eq!(stimpack.title(), "Stimpack");
    /// assert_eq!(stimpack.purchases().count(), 0);
    /// assert_eq!(stimpack.hourly_rate(), None);
    /// ```
    #[must_use]
    pub fn new(title: Title) -> Self {
        Resource {
            id: Uuid::new_v4(),
            title,
            contact: None,
            purchases: Vec::new(),
            hourly_rate: None,
        }
    }

    /// Sets this resource's hourly rate and returns `self`. Chainable form of
    /// [`Self::update_hourly_rate`].
    ///
    /// # Example
    /// ```
    /// use planter_core::{resources::Resource, money::{Money, Currency}};
    ///
    /// let drill = Resource::new("Excavator".parse().unwrap())
    ///     .at_hourly_rate(Money::from_minor_units(2_000, Currency::EUR));
    /// assert_eq!(drill.hourly_rate(), Some(Money::from_minor_units(2_000, Currency::EUR)));
    /// ```
    #[must_use]
    pub const fn at_hourly_rate(mut self, hourly_rate: Money) -> Self {
        self.hourly_rate = Some(hourly_rate);
        self
    }

    /// Sets this resource's contact and returns `self`. Chainable form of
    /// [`Self::set_contact`].
    ///
    /// # Example
    /// ```
    /// use planter_core::{person::Person, resources::Resource, stakeholders::Stakeholder};
    ///
    /// let peppino = Stakeholder::individual(Person::new("Mastro", "Peppino").unwrap(), None);
    /// let timber = Resource::new("Timber".parse().unwrap()).with_contact(peppino);
    /// assert!(timber.contact().is_some());
    /// ```
    #[must_use]
    pub fn with_contact(mut self, contact: Stakeholder) -> Self {
        self.contact = Some(contact);
        self
    }

    /// Returns the stable identifier of this resource.
    #[must_use]
    pub const fn id(&self) -> Uuid {
        self.id
    }

    /// Returns this resource's title.
    #[must_use]
    pub fn title(&self) -> &str {
        &self.title
    }

    /// Retitles this resource.
    pub fn set_title(&mut self, title: Title) {
        self.title = title;
    }

    /// Returns this resource's contact, if one is on record.
    #[must_use]
    pub const fn contact(&self) -> Option<&Stakeholder> {
        self.contact.as_ref()
    }

    /// Sets this resource's contact, replacing any previous one.
    pub fn set_contact(&mut self, contact: Stakeholder) {
        self.contact = Some(contact);
    }

    /// Clears this resource's contact.
    pub fn clear_contact(&mut self) {
        self.contact = None;
    }

    /// Returns the hourly rate, if set.
    #[must_use]
    pub const fn hourly_rate(&self) -> Option<Money> {
        self.hourly_rate
    }

    /// Sets the hourly rate.
    ///
    /// # Example
    /// ```
    /// use planter_core::{resources::Resource, money::{Money, Currency}};
    ///
    /// let mut worker = Resource::new("Backend Engineer".parse().unwrap());
    /// worker.update_hourly_rate(Money::from_minor_units(4_500, Currency::EUR));
    /// assert_eq!(worker.hourly_rate(), Some(Money::from_minor_units(4_500, Currency::EUR)));
    /// ```
    pub const fn update_hourly_rate(&mut self, hourly_rate: Money) {
        self.hourly_rate = Some(hourly_rate);
    }

    /// Clears the hourly rate.
    pub const fn remove_hourly_rate(&mut self) {
        self.hourly_rate = None;
    }

    /// Returns the purchases recorded for this resource, in the order they were added.
    pub fn purchases(&self) -> impl Iterator<Item = &Purchase> {
        self.purchases.iter()
    }

    /// Records a purchase against this resource, returning its [`Purchase::id`]. Adding a
    /// purchase whose id already exists on this resource replaces it in place, without
    /// duplicating its slot in [`Self::purchases`].
    ///
    /// # Example
    /// ```
    /// use planter_core::{resources::{Purchase, Resource}, money::{Money, Currency}};
    ///
    /// let mut stimpack = Resource::new("Stimpack".parse().unwrap());
    /// stimpack.add_purchase(
    ///     Purchase::builder().quantity(40).unit_price(Money::from_minor_units(500, Currency::EUR)).build(),
    /// );
    /// assert_eq!(stimpack.purchases().count(), 1);
    /// ```
    pub fn add_purchase(&mut self, purchase: Purchase) -> Uuid {
        let id = purchase.id();
        identifiable::upsert(&mut self.purchases, purchase);
        id
    }

    /// Removes the purchase with the given id, returning it, or `None` if this resource has no
    /// such purchase.
    pub fn rm_purchase(&mut self, purchase_id: Uuid) -> Option<Purchase> {
        identifiable::remove_by_id(&mut self.purchases, purchase_id)
    }

    /// Mutable access to one of this resource's purchases, for editing it in place. `None` if
    /// this resource has no purchase with that id.
    ///
    /// # Example
    /// ```
    /// use planter_core::{resources::{Purchase, Resource}, money::{Money, Currency}};
    ///
    /// let mut stimpack = Resource::new("Stimpack".parse().unwrap());
    /// let purchase_id = stimpack.add_purchase(
    ///     Purchase::builder().quantity(40).unit_price(Money::from_minor_units(500, Currency::EUR)).build(),
    /// );
    /// stimpack.purchase_mut(purchase_id).unwrap().set_quantity(60);
    /// assert_eq!(stimpack.purchases().next().unwrap().quantity(), 60);
    /// ```
    pub fn purchase_mut(&mut self, purchase_id: Uuid) -> Option<&mut Purchase> {
        identifiable::find_mut(&mut self.purchases, purchase_id)
    }

    /// Returns the total of every [`Purchase`] recorded for this resource, grouped by currency.
    /// Empty when there are no purchases.
    ///
    /// # Example
    /// ```
    /// use planter_core::resources::{Purchase, Resource};
    /// use planter_core::money::{Currency, Money};
    ///
    /// let mut stimpack = Resource::new("Stimpack".parse().unwrap());
    /// stimpack.add_purchase(
    ///     Purchase::builder().quantity(40).unit_price(Money::from_minor_units(500, Currency::EUR)).build(),
    /// );
    /// assert_eq!(
    ///     stimpack.purchase_cost().in_currency(Currency::EUR),
    ///     Some(Money::from_minor_units(20_000, Currency::EUR)),
    /// );
    /// ```
    #[must_use]
    pub fn purchase_cost(&self) -> MultiCurrencyAmount {
        self.purchases().map(Purchase::total).sum()
    }

    /// Returns the cost this resource contributes for a task that engages `quantity` of it for
    /// `hours` hours: `hourly_rate * hours * quantity` (saturating). `None` when the resource
    /// has no hourly rate.
    ///
    /// # Example
    /// ```
    /// use planter_core::{resources::Resource, money::{Currency, Money}};
    ///
    /// let mut digger = Resource::new("Excavator".parse().unwrap());
    /// digger.update_hourly_rate(Money::from_minor_units(3_000, Currency::EUR));
    /// assert_eq!(
    ///     digger.usage_cost(4, 1),
    ///     Some(Money::from_minor_units(12_000, Currency::EUR)),
    /// );
    /// ```
    #[must_use]
    pub fn usage_cost(&self, hours: u64, quantity: u32) -> Option<Money> {
        let rate = self.hourly_rate?;
        let amount = rate
            .minor_units()
            .saturating_mul(hours)
            .saturating_mul(u64::from(quantity));
        Some(Money::from_minor_units(amount, rate.currency()))
    }
}

#[cfg(test)]
/// Utilities to test resources.
pub mod test_utils {
    use proptest::prelude::*;

    use super::{Purchase, Resource};
    use crate::money::{Currency, Money};
    use crate::title::test_utils::title_strategy;

    /// A random `Resource` priced in EUR, with an optional rate and no contact.
    pub fn resource_strategy() -> impl Strategy<Value = Resource> {
        (title_strategy(), proptest::option::of(0u64..10_000)).prop_map(|(title, rate)| {
            let mut resource = Resource::new(title);
            if let Some(rate) = rate {
                resource.update_hourly_rate(Money::from_minor_units(rate, Currency::EUR));
            }
            resource
        })
    }

    /// A random `Purchase` priced in EUR.
    pub fn purchase_strategy() -> impl Strategy<Value = Purchase> {
        (1u32..1000, 0u64..10_000).prop_map(|(quantity, unit_price)| {
            Purchase::builder()
                .quantity(quantity)
                .unit_price(Money::from_minor_units(unit_price, Currency::EUR))
                .build()
        })
    }
}

#[cfg(test)]
mod tests {
    use proptest::prelude::*;

    use crate::money::{Currency, Money};
    use crate::person::Person;
    use crate::stakeholders::Stakeholder;
    use crate::title::Title;

    use super::test_utils::{purchase_strategy, resource_strategy};
    use super::{Purchase, Resource};
    use uuid::Uuid;

    proptest! {
        #[test]
        fn purchase_total_is_quantity_times_unit_price(quantity in 0u32..10_000, unit_price in 0u64..10_000) {
            let purchase = Purchase::builder().quantity(quantity).unit_price(Money::from_minor_units(unit_price, Currency::EUR)).build();
            assert_eq!(purchase.total(), Money::from_minor_units(u64::from(quantity) * unit_price, Currency::EUR));
        }

        #[test]
        fn purchase_cost_sums_every_purchase(purchases in prop::collection::vec(purchase_strategy(), 0..5)) {
            let mut resource = Resource::new("Stimpack".parse().unwrap());
            let expected: u64 = purchases.iter().map(|p| p.total().minor_units()).sum();
            for purchase in purchases {
                resource.add_purchase(purchase);
            }
            assert_eq!(
                resource.purchase_cost().in_currency(Currency::EUR),
                (expected != 0).then(|| Money::from_minor_units(expected, Currency::EUR)),
            );
        }

        #[test]
        fn usage_cost_is_rate_times_hours_times_quantity(rate in 0u64..1000, hours in 0u64..1000, quantity in 0u32..100) {
            let mut resource = Resource::new("Excavator".parse().unwrap());
            resource.update_hourly_rate(Money::from_minor_units(rate, Currency::EUR));
            assert_eq!(
                resource.usage_cost(hours, quantity),
                Some(Money::from_minor_units(rate * hours * u64::from(quantity), Currency::EUR)),
            );
        }

        #[test]
        fn a_resource_keeps_its_id_across_edits(mut resource in resource_strategy()) {
            let id = resource.id();
            resource.update_hourly_rate(Money::from_minor_units(123, Currency::USD));
            resource.set_title("Reclassified".parse().unwrap());
            assert_eq!(resource.id(), id);
        }
    }

    #[test]
    fn usage_cost_is_none_without_a_rate() {
        let resource = Resource::new("Stimpack".parse().unwrap());
        assert_eq!(resource.usage_cost(10, 1), None);
    }

    #[test]
    fn a_resource_prices_its_rate_and_purchases_independently() {
        let mut resource = Resource::new("Excavator".parse().unwrap());
        resource.update_hourly_rate(Money::from_minor_units(100, Currency::USD));
        resource.add_purchase(
            Purchase::builder()
                .quantity(1)
                .unit_price(Money::from_minor_units(5000, Currency::EUR))
                .build(),
        );

        assert_eq!(
            resource.purchase_cost().in_currency(Currency::EUR),
            Some(Money::from_minor_units(5000, Currency::EUR)),
        );
        assert_eq!(
            resource.usage_cost(2, 1),
            Some(Money::from_minor_units(200, Currency::USD)),
        );
    }

    #[test]
    fn an_invalid_title_cannot_be_built() {
        assert!("   ".parse::<Title>().is_err());
        assert!("x".repeat(101).parse::<Title>().is_err());
    }

    #[test]
    fn a_contact_can_be_set_and_cleared() {
        let peppino = Stakeholder::individual(Person::new("Mastro", "Peppino").unwrap(), None);
        let mut timber = Resource::new("Timber".parse().unwrap());
        assert!(timber.contact().is_none());

        timber.set_contact(peppino.clone());
        assert_eq!(timber.contact(), Some(&peppino));

        timber.clear_contact();
        assert!(timber.contact().is_none());
    }

    #[test]
    fn rm_purchase_with_an_unknown_id_is_none() {
        let mut resource = Resource::new("Stimpack".parse().unwrap());
        assert!(resource.rm_purchase(Uuid::new_v4()).is_none());
        let purchase_id = resource.add_purchase(
            Purchase::builder()
                .quantity(1)
                .unit_price(Money::from_minor_units(1, Currency::EUR))
                .build(),
        );
        assert!(resource.rm_purchase(Uuid::new_v4()).is_none());
        assert!(resource.rm_purchase(purchase_id).is_some());
        assert!(resource.rm_purchase(purchase_id).is_none());
    }

    #[test]
    fn purchase_mut_with_an_unknown_id_is_none() {
        let mut resource = Resource::new("Stimpack".parse().unwrap());
        assert!(resource.purchase_mut(Uuid::new_v4()).is_none());
    }

    #[test]
    fn purchases_are_iterated_in_insertion_order() {
        let mut resource = Resource::new("Stimpack".parse().unwrap());
        let unit_price = Money::from_minor_units(100, Currency::EUR);
        let a = resource.add_purchase(
            Purchase::builder()
                .quantity(1)
                .unit_price(unit_price)
                .build(),
        );
        let b = resource.add_purchase(
            Purchase::builder()
                .quantity(2)
                .unit_price(unit_price)
                .build(),
        );
        let c = resource.add_purchase(
            Purchase::builder()
                .quantity(3)
                .unit_price(unit_price)
                .build(),
        );

        let ids: Vec<_> = resource.purchases().map(Purchase::id).collect();
        assert_eq!(ids, vec![a, b, c]);
    }

    #[test]
    fn add_purchase_with_an_existing_id_replaces_it_in_place() {
        let mut resource = Resource::new("Stimpack".parse().unwrap());
        let purchase = Purchase::builder()
            .quantity(1)
            .unit_price(Money::from_minor_units(100, Currency::EUR))
            .build();
        let id = resource.add_purchase(purchase.clone());

        let mut updated = purchase;
        updated.set_quantity(5);
        let same_id = resource.add_purchase(updated);

        assert_eq!(same_id, id);
        assert_eq!(resource.purchases().count(), 1);
        assert_eq!(resource.purchase_mut(id).unwrap().quantity(), 5);
    }

    #[test]
    fn purchase_date_can_be_set_and_cleared() {
        let mut purchase = Purchase::builder()
            .quantity(1)
            .unit_price(Money::from_minor_units(1, Currency::EUR))
            .build();
        assert_eq!(purchase.date(), None);
        let now = chrono::Utc::now();
        purchase.set_date(now);
        assert_eq!(purchase.date(), Some(now));
        purchase.clear_date();
        assert_eq!(purchase.date(), None);
    }

    proptest! {
        #[test]
        fn purchase_setters_edit_in_place(
            q0 in 0u32..1000, p0 in 0u64..1000,
            q1 in 0u32..1000, p1 in 0u64..1000,
        ) {
            let mut resource = Resource::new("Excavator".parse().unwrap());
            let purchase_id =
                resource.add_purchase(Purchase::builder().quantity(q0).unit_price(Money::from_minor_units(p0, Currency::EUR)).build());

            let purchase = resource.purchase_mut(purchase_id).unwrap();
            purchase.set_quantity(q1);
            purchase.set_unit_price(Money::from_minor_units(p1, Currency::EUR));

            let purchase = resource.purchases().next().unwrap();
            assert_eq!(purchase.quantity(), q1);
            assert_eq!(purchase.unit_price(), Money::from_minor_units(p1, Currency::EUR));
            assert_eq!(purchase.total(), Money::from_minor_units(u64::from(q1) * p1, Currency::EUR));
        }
    }
}

#[cfg(all(test, feature = "serde"))]
mod serde_tests {
    use super::{Purchase, Resource};
    use crate::money::{Currency, Money};
    use crate::person::Person;
    use crate::stakeholders::Stakeholder;

    #[test]
    fn resource_serde_roundtrip() {
        let mut resource = Resource::new("Backend Engineer".parse().unwrap()).with_contact(
            Stakeholder::individual(Person::new("Margherita", "Hack").unwrap(), None),
        );
        resource.update_hourly_rate(Money::from_minor_units(4_500, Currency::USD));
        resource.add_purchase(
            Purchase::builder()
                .quantity(2)
                .unit_price(Money::from_minor_units(1_000, Currency::USD))
                .build(),
        );

        let json = serde_json::to_string(&resource).unwrap();
        let back: Resource = serde_json::from_str(&json).unwrap();
        assert_eq!(resource, back);
    }
}