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
// 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 Debug;
/// A minimal trait for types that have an intrinsic timestamp for stream ordering.
///
/// This trait provides read-only access to a timestamp value,
/// allowing stream operators to order and compare items based on their temporal position.
///
/// # Relationship with `Timestamped`
///
/// `HasTimestamp` is a minimal trait for reading timestamps,
/// while `Timestamped` extends it with an `Inner` type and construction methods
/// (`with_timestamp`, `into_inner`).
///
/// Use `HasTimestamp` when you only need to read timestamps (e.g., ordering, comparison).
/// Use `Timestamped` when you need to construct new timestamped values or access inner values.
///
/// # Type Parameters
/// * `Timestamp` - The type representing the timestamp (must be `Ord + Copy`)
///
/// # Examples
///
/// ```
/// use fluxion_core::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
/// }
/// }
/// ```
///
/// # Different Timestamp Types
///
/// The `Timestamp` type is generic and can represent various time sources:
///
/// **Monotonic counters** (u64, u128) - For test scenarios and event sourcing:
/// ```rust
/// use fluxion_core::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 }
/// }
/// ```
///
/// **Wall-clock time** (Instant, SystemTime) - For real-time systems:
/// ```rust
/// use fluxion_core::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 }
/// }
/// ```