Skip to main content

nautilus_coinapi/common/
enums.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! CoinAPI wire classifications shared by REST, WebSocket, and flat-file ingestion.
17
18use serde::{Deserialize, Serialize};
19use ustr::Ustr;
20
21/// An OHLCV period from the provider catalog.
22///
23/// The provider can add periods to its
24/// [catalog](https://www.coinapi.io/products/market-data-api/docs/rest-api/ohlcv/ohlcv/periods/get);
25/// unrecognized identifiers retain their wire value.
26#[derive(
27    Debug,
28    Clone,
29    Copy,
30    PartialEq,
31    Eq,
32    Hash,
33    Serialize,
34    Deserialize,
35    strum::AsRefStr,
36    strum::Display,
37    strum::EnumString,
38    strum::VariantNames,
39)]
40#[serde(from = "Ustr", into = "Ustr")]
41pub enum OhlcvPeriod {
42    #[strum(serialize = "1SEC")]
43    Second1,
44    #[strum(serialize = "2SEC")]
45    Second2,
46    #[strum(serialize = "3SEC")]
47    Second3,
48    #[strum(serialize = "4SEC")]
49    Second4,
50    #[strum(serialize = "5SEC")]
51    Second5,
52    #[strum(serialize = "6SEC")]
53    Second6,
54    #[strum(serialize = "10SEC")]
55    Second10,
56    #[strum(serialize = "15SEC")]
57    Second15,
58    #[strum(serialize = "20SEC")]
59    Second20,
60    #[strum(serialize = "30SEC")]
61    Second30,
62    #[strum(serialize = "1MIN")]
63    Minute1,
64    #[strum(serialize = "2MIN")]
65    Minute2,
66    #[strum(serialize = "3MIN")]
67    Minute3,
68    #[strum(serialize = "4MIN")]
69    Minute4,
70    #[strum(serialize = "5MIN")]
71    Minute5,
72    #[strum(serialize = "6MIN")]
73    Minute6,
74    #[strum(serialize = "10MIN")]
75    Minute10,
76    #[strum(serialize = "15MIN")]
77    Minute15,
78    #[strum(serialize = "20MIN")]
79    Minute20,
80    #[strum(serialize = "30MIN")]
81    Minute30,
82    #[strum(serialize = "1HRS")]
83    Hour1,
84    #[strum(serialize = "2HRS")]
85    Hour2,
86    #[strum(serialize = "3HRS")]
87    Hour3,
88    #[strum(serialize = "4HRS")]
89    Hour4,
90    #[strum(serialize = "6HRS")]
91    Hour6,
92    #[strum(serialize = "8HRS")]
93    Hour8,
94    #[strum(serialize = "12HRS")]
95    Hour12,
96    #[strum(serialize = "1DAY")]
97    Day1,
98    #[strum(serialize = "2DAY")]
99    Day2,
100    #[strum(serialize = "3DAY")]
101    Day3,
102    #[strum(serialize = "5DAY")]
103    Day5,
104    #[strum(serialize = "7DAY")]
105    Day7,
106    #[strum(serialize = "10DAY")]
107    Day10,
108    #[strum(serialize = "1MTH")]
109    Month1,
110    #[strum(serialize = "2MTH")]
111    Month2,
112    #[strum(serialize = "3MTH")]
113    Month3,
114    #[strum(serialize = "4MTH")]
115    Month4,
116    #[strum(serialize = "6MTH")]
117    Month6,
118    #[strum(serialize = "1YRS")]
119    Year1,
120    #[strum(serialize = "2YRS")]
121    Year2,
122    #[strum(serialize = "3YRS")]
123    Year3,
124    #[strum(serialize = "4YRS")]
125    Year4,
126    #[strum(serialize = "5YRS")]
127    Year5,
128    /// An unrecognized value, retained without changing its spelling.
129    #[strum(default, transparent)]
130    Other(Ustr),
131}
132
133impl From<Ustr> for OhlcvPeriod {
134    fn from(value: Ustr) -> Self {
135        value.as_str().into()
136    }
137}
138
139impl From<OhlcvPeriod> for Ustr {
140    fn from(value: OhlcvPeriod) -> Self {
141        Self::from(value.as_ref())
142    }
143}
144
145/// The provider-reported or estimated aggressor side of a trade.
146///
147/// Unrecognized values remain distinct from the documented `UNKNOWN` value.
148#[derive(
149    Debug,
150    Clone,
151    Copy,
152    PartialEq,
153    Eq,
154    Hash,
155    Serialize,
156    Deserialize,
157    strum::AsRefStr,
158    strum::Display,
159    strum::EnumString,
160)]
161#[serde(from = "Ustr", into = "Ustr")]
162#[strum(serialize_all = "SCREAMING_SNAKE_CASE")]
163pub enum TakerSide {
164    Buy,
165    Sell,
166    BuyEstimated,
167    SellEstimated,
168    Unknown,
169    /// An unrecognized value, retained without changing its spelling.
170    #[strum(default, transparent)]
171    Other(Ustr),
172}
173
174impl From<Ustr> for TakerSide {
175    fn from(value: Ustr) -> Self {
176        value.as_str().into()
177    }
178}
179
180impl From<TakerSide> for Ustr {
181    fn from(value: TakerSide) -> Self {
182        Self::from(value.as_ref())
183    }
184}
185
186/// The provider classification of a symbol.
187///
188/// Recognition does not imply support for a native instrument mapping.
189#[derive(
190    Debug,
191    Clone,
192    Copy,
193    PartialEq,
194    Eq,
195    Hash,
196    Serialize,
197    Deserialize,
198    strum::AsRefStr,
199    strum::Display,
200    strum::EnumString,
201)]
202#[serde(from = "Ustr", into = "Ustr")]
203#[strum(serialize_all = "SCREAMING_SNAKE_CASE")]
204pub enum SymbolType {
205    Spot,
206    Futures,
207    Option,
208    Perpetual,
209    DeployerPerpetual,
210    Index,
211    Credit,
212    Contract,
213    OptionCombo,
214    FutureCombo,
215    /// An unrecognized value, retained without changing its spelling.
216    #[strum(default, transparent)]
217    Other(Ustr),
218}
219
220impl From<Ustr> for SymbolType {
221    fn from(value: Ustr) -> Self {
222        value.as_str().into()
223    }
224}
225
226impl From<SymbolType> for Ustr {
227    fn from(value: SymbolType) -> Self {
228        Self::from(value.as_ref())
229    }
230}
231
232#[cfg(test)]
233mod tests {
234    use rstest::rstest;
235
236    use super::*;
237
238    #[rstest]
239    #[case("1SEC", OhlcvPeriod::Second1)]
240    #[case("2SEC", OhlcvPeriod::Second2)]
241    #[case("3SEC", OhlcvPeriod::Second3)]
242    #[case("4SEC", OhlcvPeriod::Second4)]
243    #[case("5SEC", OhlcvPeriod::Second5)]
244    #[case("6SEC", OhlcvPeriod::Second6)]
245    #[case("10SEC", OhlcvPeriod::Second10)]
246    #[case("15SEC", OhlcvPeriod::Second15)]
247    #[case("20SEC", OhlcvPeriod::Second20)]
248    #[case("30SEC", OhlcvPeriod::Second30)]
249    #[case("1MIN", OhlcvPeriod::Minute1)]
250    #[case("2MIN", OhlcvPeriod::Minute2)]
251    #[case("3MIN", OhlcvPeriod::Minute3)]
252    #[case("4MIN", OhlcvPeriod::Minute4)]
253    #[case("5MIN", OhlcvPeriod::Minute5)]
254    #[case("6MIN", OhlcvPeriod::Minute6)]
255    #[case("10MIN", OhlcvPeriod::Minute10)]
256    #[case("15MIN", OhlcvPeriod::Minute15)]
257    #[case("20MIN", OhlcvPeriod::Minute20)]
258    #[case("30MIN", OhlcvPeriod::Minute30)]
259    #[case("1HRS", OhlcvPeriod::Hour1)]
260    #[case("2HRS", OhlcvPeriod::Hour2)]
261    #[case("3HRS", OhlcvPeriod::Hour3)]
262    #[case("4HRS", OhlcvPeriod::Hour4)]
263    #[case("6HRS", OhlcvPeriod::Hour6)]
264    #[case("8HRS", OhlcvPeriod::Hour8)]
265    #[case("12HRS", OhlcvPeriod::Hour12)]
266    #[case("1DAY", OhlcvPeriod::Day1)]
267    #[case("2DAY", OhlcvPeriod::Day2)]
268    #[case("3DAY", OhlcvPeriod::Day3)]
269    #[case("5DAY", OhlcvPeriod::Day5)]
270    #[case("7DAY", OhlcvPeriod::Day7)]
271    #[case("10DAY", OhlcvPeriod::Day10)]
272    #[case("1MTH", OhlcvPeriod::Month1)]
273    #[case("2MTH", OhlcvPeriod::Month2)]
274    #[case("3MTH", OhlcvPeriod::Month3)]
275    #[case("4MTH", OhlcvPeriod::Month4)]
276    #[case("6MTH", OhlcvPeriod::Month6)]
277    #[case("1YRS", OhlcvPeriod::Year1)]
278    #[case("2YRS", OhlcvPeriod::Year2)]
279    #[case("3YRS", OhlcvPeriod::Year3)]
280    #[case("4YRS", OhlcvPeriod::Year4)]
281    #[case("5YRS", OhlcvPeriod::Year5)]
282    fn ohlcv_period_preserves_wire_value(#[case] wire: &str, #[case] expected: OhlcvPeriod) {
283        let encoded = serde_json::to_string(wire).unwrap();
284        let actual: OhlcvPeriod = serde_json::from_str(&encoded).unwrap();
285
286        assert_eq!(actual, expected);
287        assert_eq!(actual.as_ref(), wire);
288        assert_eq!(actual.to_string(), wire);
289        assert_eq!(wire.parse::<OhlcvPeriod>().unwrap(), expected);
290        assert_eq!(serde_json::to_string(&actual).unwrap(), encoded);
291    }
292
293    #[rstest]
294    #[case("BUY", TakerSide::Buy)]
295    #[case("SELL", TakerSide::Sell)]
296    #[case("BUY_ESTIMATED", TakerSide::BuyEstimated)]
297    #[case("SELL_ESTIMATED", TakerSide::SellEstimated)]
298    #[case("UNKNOWN", TakerSide::Unknown)]
299    fn taker_side_preserves_wire_value(#[case] wire: &str, #[case] expected: TakerSide) {
300        let encoded = serde_json::to_string(wire).unwrap();
301        let actual: TakerSide = serde_json::from_str(&encoded).unwrap();
302
303        assert_eq!(actual, expected);
304        assert_eq!(actual.as_ref(), wire);
305        assert_eq!(actual.to_string(), wire);
306        assert_eq!(wire.parse::<TakerSide>().unwrap(), expected);
307        assert_eq!(serde_json::to_string(&actual).unwrap(), encoded);
308    }
309
310    #[rstest]
311    #[case("SPOT", SymbolType::Spot)]
312    #[case("FUTURES", SymbolType::Futures)]
313    #[case("OPTION", SymbolType::Option)]
314    #[case("PERPETUAL", SymbolType::Perpetual)]
315    #[case("DEPLOYER_PERPETUAL", SymbolType::DeployerPerpetual)]
316    #[case("INDEX", SymbolType::Index)]
317    #[case("CREDIT", SymbolType::Credit)]
318    #[case("CONTRACT", SymbolType::Contract)]
319    #[case("OPTION_COMBO", SymbolType::OptionCombo)]
320    #[case("FUTURE_COMBO", SymbolType::FutureCombo)]
321    fn symbol_type_preserves_wire_value(#[case] wire: &str, #[case] expected: SymbolType) {
322        let encoded = serde_json::to_string(wire).unwrap();
323        let actual: SymbolType = serde_json::from_str(&encoded).unwrap();
324
325        assert_eq!(actual, expected);
326        assert_eq!(actual.as_ref(), wire);
327        assert_eq!(actual.to_string(), wire);
328        assert_eq!(wire.parse::<SymbolType>().unwrap(), expected);
329        assert_eq!(serde_json::to_string(&actual).unwrap(), encoded);
330    }
331
332    #[rstest]
333    #[case("FUTURE_VALUE")]
334    #[case("8SEC")]
335    #[case("")]
336    #[case("escaped\"value")]
337    fn unknown_classifications_keep_their_wire_value(#[case] wire: &str) {
338        let encoded = serde_json::to_string(wire).unwrap();
339        let period: OhlcvPeriod = serde_json::from_str(&encoded).unwrap();
340        let side: TakerSide = serde_json::from_str(&encoded).unwrap();
341        let symbol: SymbolType = serde_json::from_str(&encoded).unwrap();
342
343        assert_eq!(period, OhlcvPeriod::Other(wire.into()));
344        assert_eq!(side, TakerSide::Other(wire.into()));
345        assert_eq!(symbol, SymbolType::Other(wire.into()));
346        assert_eq!(serde_json::to_string(&period).unwrap(), encoded);
347        assert_eq!(serde_json::to_string(&side).unwrap(), encoded);
348        assert_eq!(serde_json::to_string(&symbol).unwrap(), encoded);
349    }
350}