1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
// Copyright 2025 Umberto Gotti <umberto.gotti@umbertogotti.dev>
// Licensed under the Apache License, Version 2.0
// http://www.apache.org/licenses/LICENSE-2.0
//! Pairing operator that combines each item with its predecessor.
//!
//! The [`combine_with_previous`](CombineWithPreviousExt::combine_with_previous) operator
//! emits `WithPrevious` items, containing the current value and the previous value (if any).
//!
//! # Behavior
//!
//! - First element: `WithPrevious { previous: None, current: first_value }`
//! - Subsequent elements: `WithPrevious { previous: Some(prev), current: curr }`
//! - Maintains state to track the previous value
//! - Preserves temporal ordering from the source stream
//!
//! # Returns
//!
//! A stream of `WithPrevious<T>` where each item contains the current
//! and previous values.
//!
//! # Errors
//!
//! This operator may produce `StreamItem::Error` in the following cases:
//!
//! - **Lock Errors**: When acquiring the previous value buffer lock fails (e.g., due to lock poisoning).
//! These are transient errors - the stream continues processing and may succeed on subsequent items.
//!
//! Lock errors are typically non-fatal and indicate temporary contention. The operator will continue
//! processing subsequent items. See the [Error Handling Guide](../docs/ERROR-HANDLING.md) for patterns
//! on handling these errors in your application.
//!
//! # See Also
//!
//! - [`combine_latest`](crate::CombineLatestExt::combine_latest) - Combines multiple streams
//! - Useful for change detection and delta calculations
//!
//! # Examples
//!
//! ```rust
//! use fluxion_stream::CombineWithPreviousExt;
//! use fluxion_test_utils::{Sequenced, helpers::unwrap_stream, unwrap_value, test_channel};
//! use fluxion_core::Timestamped as TimestampedTrait;
//!
//! # async fn example() {
//! // Create channel
//! let (tx, stream) = test_channel::<Sequenced<i32>>();
//!
//! // Combine with previous
//! let mut paired = stream.combine_with_previous();
//!
//! // Send values
//! tx.unbounded_send((1, 1).into()).unwrap();
//! tx.unbounded_send((2, 2).into()).unwrap();
//!
//! // Assert - first has no previous
//! let first = unwrap_value(Some(unwrap_stream(&mut paired, 500).await));
//! assert_eq!(first.previous, None);
//! assert_eq!(first.current.value, 1);
//!
//! // Assert - second has previous
//! let second = unwrap_value(Some(unwrap_stream(&mut paired, 500).await));
//! assert_eq!(second.previous.as_ref().unwrap().value, 1);
//! assert_eq!(second.current.value, 2);
//! # }
//! ```
//!
//! # Use Cases
//!
//! - Change detection (comparing consecutive values)
//! - Delta calculation (computing differences)
//! - State transitions (analyzing previous ? current)
//! - Duplicate filtering (skip if same as previous)
pub use CombineWithPreviousExt;
pub use CombineWithPreviousExt;