fin_primitives/lib.rs
1//! # fin-primitives
2//!
3//! A zero-panic, decimal-precise foundation for high-frequency trading and
4//! quantitative systems in Rust.
5//!
6//! ## Features
7//!
8//! | Module | What it provides | Key guarantee |
9//! |--------|-----------------|---------------|
10//! | [`types`] | `Price`, `Quantity`, `Symbol`, `NanoTimestamp`, `Side` newtypes | Validation at construction; no invalid value can exist at runtime |
11//! | [`tick`] | `Tick`, `TickFilter`, `TickReplayer` | Filter is pure; replayer yields ticks in ascending timestamp order |
12//! | [`orderbook`] | L2 `OrderBook` with `apply_delta`, spread, mid-price, VWAP, top-N levels | Sequence validation; inverted spreads are detected and rolled back |
13//! | [`ohlcv`] | `OhlcvBar`, `Timeframe`, `OhlcvAggregator`, `OhlcvSeries` | Bar invariants (`high >= low`, etc.) enforced on every push |
14//! | [`signals`] | `Signal` trait, `SignalPipeline`, `Sma`, `Ema`, `Rsi` | Returns `Unavailable` until warm-up period is satisfied; no silent NaN |
15//! | [`position`] | `Position`, `Fill`, `PositionLedger` | VWAP average cost; realized and unrealized P&L net of commissions |
16//! | [`risk`] | `DrawdownTracker`, `RiskRule` trait, `MaxDrawdownRule`, `MinEquityRule`, `RiskMonitor` | All breaches returned as a typed `Vec<RiskBreach>`; never silently swallowed |
17//!
18//! ## Design Principles
19//!
20//! - **Zero panics.** Every fallible operation returns `Result<_, FinError>`.
21//! No `unwrap` or `expect` in production code paths.
22//! - **Decimal precision.** All prices and quantities use [`rust_decimal::Decimal`].
23//! Floating-point drift is structurally impossible.
24//! - **Nanosecond timestamps.** [`types::NanoTimestamp`] is a newtype over `i64`
25//! nanoseconds since Unix epoch, suitable for microsecond-accurate event ordering.
26//! - **Composable by design.** [`risk::RiskRule`], [`signals::Signal`], and
27//! [`tick::TickFilter`] are traits; plug in your own implementations without forking.
28//!
29//! ## Errors
30//!
31//! All error variants live in [`FinError`] (re-exported at the crate root).
32//! Every public fallible function documents which variant it may return.
33//!
34//! All prices and quantities use [`rust_decimal::Decimal`]; never `f64`.
35
36#![forbid(unsafe_code)]
37#![deny(missing_docs)]
38
39pub mod error;
40pub mod ohlcv;
41pub mod orderbook;
42pub mod position;
43pub mod risk;
44pub mod signals;
45pub mod tick;
46pub mod types;
47
48pub use error::FinError;