Skip to main content

financial_api/types/
fund.rs

1use std::str::FromStr;
2
3use serde::{Deserialize, Deserializer, Serialize};
4
5use super::wire::wire_enum;
6use crate::ValidationError;
7
8macro_rules! identifier_type {
9    ($(#[$meta:meta])* $name:ident, $field:literal) => {
10        $(#[$meta])*
11        #[derive(
12            Debug,
13            Clone,
14            PartialEq,
15            Eq,
16            PartialOrd,
17            Ord,
18            Hash,
19            Serialize,
20            derive_more::Display,
21        )]
22        #[serde(transparent)]
23        pub struct $name(String);
24
25        impl $name {
26            pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
27                let value = value.into();
28                let value = value.trim();
29                if value.is_empty() {
30                    return Err(ValidationError::new($field, "must not be empty"));
31                }
32                Ok(Self(value.to_owned()))
33            }
34
35            #[must_use]
36            pub fn as_str(&self) -> &str {
37                &self.0
38            }
39        }
40
41        impl FromStr for $name {
42            type Err = ValidationError;
43
44            fn from_str(value: &str) -> Result<Self, Self::Err> {
45                Self::new(value)
46            }
47        }
48
49        impl<'de> Deserialize<'de> for $name {
50            fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
51                let value = String::deserialize(deserializer)?;
52                Self::new(value).map_err(serde::de::Error::custom)
53            }
54        }
55    };
56}
57
58identifier_type!(
59    /// Opaque fund-manager identifier discovered from fund profile data.
60    ManagerId,
61    "manager_id"
62);
63identifier_type!(
64    /// Opaque fund-company identifier discovered from fund profile data.
65    CompanyId,
66    "company_id"
67);
68identifier_type!(
69    /// Fund disclosure report type discovered from a report-dates endpoint.
70    ReportType,
71    "report_type"
72);
73identifier_type!(
74    /// Opaque fund category code observed in diagnostics data.
75    FundCategoryCode,
76    "fund_type"
77);
78
79/// Opaque pagination cursor returned by a cursor-paged endpoint.
80#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, derive_more::Display)]
81#[serde(transparent)]
82pub struct Cursor(String);
83
84impl Cursor {
85    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
86        let value = value.into();
87        if value.trim().is_empty() {
88            return Err(ValidationError::new("offset", "must not be empty"));
89        }
90        Ok(Self(value))
91    }
92
93    #[must_use]
94    pub fn as_str(&self) -> &str {
95        &self.0
96    }
97}
98
99impl FromStr for Cursor {
100    type Err = ValidationError;
101
102    fn from_str(value: &str) -> Result<Self, Self::Err> {
103        Self::new(value)
104    }
105}
106
107impl<'de> Deserialize<'de> for Cursor {
108    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
109        let value = String::deserialize(deserializer)?;
110        Self::new(value).map_err(serde::de::Error::custom)
111    }
112}
113
114wire_enum! {
115    /// Fund target universe.
116    pub enum FundType {
117        Otc => "otc",
118        Exchange => "exchange",
119        Reits => "reits",
120    }
121}
122
123wire_enum! {
124    /// Holder record merge policy.
125    pub enum HolderMergeScope {
126        All => "all",
127        Merged => "merged",
128        Separate => "separate",
129    }
130}
131
132wire_enum! {
133    /// Fund NAV history range.
134    pub enum FundRange {
135        Week => "week",
136        Month => "month",
137        ThreeMonths => "tmonth",
138        HalfYear => "hyear",
139        Year => "year",
140        TwoYears => "twoyear",
141        ThreeYears => "tyear",
142        FiveYears => "fyear",
143    }
144}
145
146wire_enum! {
147    /// Fund NAV series selection.
148    pub enum FundNavType {
149        Unit => "unit",
150        Adjusted => "adj",
151        UnitAndAdjusted => "unit,adj",
152    }
153}
154
155wire_enum! {
156    /// Fund manager performance range.
157    pub enum ManagerPerformanceRange {
158        Month => "month",
159        ThreeMonths => "tmonth",
160        Year => "year",
161        CurrentYear => "nowyear",
162        SinceInception => "now",
163    }
164}
165
166wire_enum! {
167    /// New fund offering subscription state.
168    pub enum OfferingStatus {
169        Active => "active",
170        Upcoming => "upcoming",
171    }
172}
173
174wire_enum! {
175    /// Actual disclosure scope returned for a fund-holder record.
176    pub enum HolderRecordScope {
177        Merged => "merged",
178        Separate => "separate",
179    }
180}
181
182wire_enum! {
183    /// Asset class used in a disclosed fund portfolio.
184    pub enum PortfolioAssetType {
185        Stock => "stock",
186        Bond => "bond",
187        Fund => "fund",
188    }
189}
190
191#[cfg(test)]
192mod tests {
193    use super::{CompanyId, Cursor, FundCategoryCode, ManagerId, ReportType};
194
195    #[test]
196    fn endpoint_identifiers_have_distinct_validated_types() {
197        assert_eq!(ManagerId::new("manager-1").unwrap().as_str(), "manager-1");
198        assert_eq!(CompanyId::new("company-1").unwrap().as_str(), "company-1");
199        assert_eq!(
200            Cursor::new("opaque+/cursor==").unwrap().as_str(),
201            "opaque+/cursor=="
202        );
203        assert_eq!(ReportType::new("quarter").unwrap().as_str(), "quarter");
204        assert_eq!(
205            FundCategoryCode::new("282001003").unwrap().as_str(),
206            "282001003"
207        );
208        assert_eq!(ManagerId::new(" manager-1 ").unwrap().as_str(), "manager-1");
209        assert_eq!(
210            CompanyId::new("\tcompany-1\n").unwrap().as_str(),
211            "company-1"
212        );
213        assert_eq!(ReportType::new(" quarter ").unwrap().as_str(), "quarter");
214        assert_eq!(
215            Cursor::new(" opaque+/cursor== ").unwrap().as_str(),
216            " opaque+/cursor== "
217        );
218
219        assert!(ManagerId::new(" ").is_err());
220        assert!(CompanyId::new("").is_err());
221        assert!(Cursor::new("\t").is_err());
222        assert!(ReportType::new("\n").is_err());
223        assert!(FundCategoryCode::new(" ").is_err());
224    }
225}