fluxion_rx/
lib.rs

1// Copyright 2025 Umberto Gotti <umberto.gotti@umbertogotti.dev>
2// Licensed under the Apache License, Version 2.0
3// http://www.apache.org/licenses/LICENSE-2.0
4
5//! # Fluxion
6//!
7//! A reactive stream processing library with ordered semantics, friendly interface, and bullet-proof, state-of-the art test coverage and examples.
8//!
9//! ## Overview
10//!
11//! Fluxion provides a high-level API for working with ordered, reactive streams.
12//! It builds on top of the Rust async ecosystem (tokio, futures) and adds
13//! ordering guarantees and powerful stream composition operators.
14//!
15//! ## Design Philosophy
16//!
17//! Fluxion maintains a clean separation of concerns:
18//!
19//! - **Production code**: Use `FluxionStream` for composable, immutable stream transformations
20//! - **Test code**: Use `async_channel` for imperative test setup
21//!
22//! This architecture solves the fundamental conflict between:
23//! - Consuming operations (stream extensions that take `self`)
24//! - Mutation operations (sending values via channels)
25//!
26//! ## Quick Start
27//!
28//! ```rust
29//! use fluxion_rx::prelude::*;
30//! use futures::StreamExt;
31//!
32//! #[tokio::main]
33//! async fn main() {
34//!     // Create a stream from an async channel
35//!     let (tx, rx) = async_channel::unbounded::<i32>();
36//!     let stream = rx.into_fluxion_stream();
37//!
38//!     // Send some values
39//!     tx.try_send(1).unwrap();
40//!     tx.try_send(2).unwrap();
41//!     tx.try_send(3).unwrap();
42//!     drop(tx);
43//!
44//!     // Process the stream (unwrap StreamItem values)
45//!     let sum: i32 = stream.fold(0, |acc, x| async move {
46//!         acc + x.unwrap()
47//!     }).await;
48//!     println!("Sum: {}", sum);  // Prints: Sum: 6
49//! }
50//! ```
51//!
52//! ## Core Concepts
53//!
54//! ### Timestamped Trait
55//!
56//! All stream operators work with types implementing the [`Timestamped`] trait, which
57//! provides temporal ordering:
58//!
59//! ```rust
60//! use fluxion_rx::Timestamped;
61//!
62//! // Items must provide a timestamp
63//! fn process_timestamped<T: Timestamped>(item: T) {
64//!     let ts = item.timestamp();     // Get timestamp for ordering
65//!     let value = item.into_inner();  // Extract inner value
66//! }
67//! ```
68//!
69//! ### Stream Operators
70//!
71//! Fluxion provides powerful stream composition operators:
72//!
73//! - **combine_latest** - Combine multiple streams, emitting when any emits
74//! - **with_latest_from** - Sample one stream using another as trigger
75//! - **ordered_merge** - Merge streams preserving temporal order
76//! - **take_latest_when** - Sample on filter condition
77//! - **emit_when** - Gate stream emissions based on conditions
78//!
79//! See [`fluxion_stream`] for the complete list.
80//!
81//! ## Workspace Structure
82//!
83//! - [`fluxion`](crate) - Main crate (this crate), re-exports core types
84//! - [`fluxion_core`] - Core traits and utilities
85//! - [`fluxion_stream`] - Stream operators and combinators
86//! - `fluxion_exec` - Async execution and subscription utilities
87// fluxion_error - Error types and handling
88
89// Re-export core types
90pub use fluxion_core::into_stream::IntoStream;
91pub use fluxion_core::{HasTimestamp, Timestamped};
92
93// Re-export commonly used types
94pub use fluxion_stream::{CombinedState, WithPrevious};
95
96// Re-export exec utilities
97pub use fluxion_exec;
98
99/// Prelude module for convenient imports.
100///
101/// Import this module to bring the most commonly used Fluxion types into scope:
102///
103/// ```rust
104/// use fluxion_rx::prelude::*;
105///
106/// // Now you have access to:
107/// // - Extension traits via fluxion_stream::prelude
108/// // - Timestamped trait
109/// // - IntoStream trait
110/// // - CombinedState, WithPrevious
111/// ```
112///
113/// This is the recommended way to use Fluxion in most applications.
114pub mod prelude {
115    pub use fluxion_core::into_stream::IntoStream;
116    pub use fluxion_core::{HasTimestamp, Timestamped};
117    pub use fluxion_stream::prelude::*;
118    pub use fluxion_stream::{CombinedState, WithPrevious};
119}
fluxion_rx/lib.rs

fluxion_rx/
lib.rs
