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
105
106
107
108
109
110
111
112
113
114
115
116
117
// Copyright 2025 Umberto Gotti <umberto.gotti@umbertogotti.dev>
// Licensed under the Apache License, Version 2.0
// http://www.apache.org/licenses/LICENSE-2.0
use crateHasTimestamp;
/// A trait for types that have an intrinsic timestamp for stream ordering.
///
/// This trait extends [`HasTimestamp`] with the ability to construct and
/// deconstruct timestamped wrapper types. Use this for wrapper types like
/// `Sequenced<T>` that wrap an inner value with a timestamp.
///
/// For types that only need to provide a timestamp value without wrapping,
/// implement [`HasTimestamp`] instead.
///
/// This trait allows stream operators like `combine_latest` and `ordered_merge`
/// to work with any type that can provide a timestamp value and wraps an inner value.
///
/// The timestamp type is generic, allowing implementations to use different time
/// representations (monotonic counters, wall-clock time, etc.).
///
/// # Type Parameters
/// * `Inner` - The type of the value wrapped by this timestamped type
/// * `Timestamp` - The type representing the timestamp (must be `Ord + Copy`)
///
/// # Examples
///
/// ```
/// use fluxion_core::{Timestamped, HasTimestamp};
///
/// #[derive(Clone, Debug)]
/// struct TimestampedEvent<T> {
/// value: T,
/// timestamp: u64,
/// }
///
/// impl<T: Clone> HasTimestamp for TimestampedEvent<T> {
/// type Timestamp = u64;
///
/// fn timestamp(&self) -> Self::Timestamp {
/// self.timestamp
/// }
/// }
///
/// impl<T: Clone> Timestamped for TimestampedEvent<T> {
/// type Inner = T;
///
/// fn with_timestamp(value: T, timestamp: Self::Timestamp) -> Self {
/// TimestampedEvent { value, timestamp }
/// }
///
/// fn into_inner(self) -> Self::Inner {
/// self.value
/// }
/// }
/// ```
///
/// # Different Timestamp Types
///
/// The `Timestamp` type is generic and can represent various time sources:
///
/// **Monotonic counters** (u64, u128) - For test scenarios and event sourcing:
/// ```
/// use fluxion_core::{Timestamped, HasTimestamp};
///
/// #[derive(Clone, Debug)]
/// struct SequenceNumbered<T> {
/// value: T,
/// seq: u64,
/// }
///
/// impl<T: Clone> HasTimestamp for SequenceNumbered<T> {
/// type Timestamp = u64;
/// fn timestamp(&self) -> u64 { self.seq }
/// }
///
/// impl<T: Clone> Timestamped for SequenceNumbered<T> {
/// type Inner = T;
/// fn with_timestamp(value: T, seq: u64) -> Self { Self { value, seq } }
/// fn into_inner(self) -> T { self.value }
/// }
/// ```
///
/// **Wall-clock time** (Instant, SystemTime) - For real-time systems:
/// ```
/// use fluxion_core::{Timestamped, HasTimestamp};
/// use std::time::Instant;
///
/// #[derive(Clone, Debug)]
/// struct TimedEvent<T> {
/// value: T,
/// time: Instant,
/// }
///
/// impl<T: Clone> HasTimestamp for TimedEvent<T> {
/// type Timestamp = Instant;
/// fn timestamp(&self) -> Instant { self.time }
/// }
///
/// impl<T: Clone> Timestamped for TimedEvent<T> {
/// type Inner = T;
/// fn with_timestamp(value: T, time: Instant) -> Self { Self { value, time } }
/// fn into_inner(self) -> T { self.value }
/// }
/// ```