TemporalCollections 1.0.0

TemporalCollections

TemporalCollections is a high-performance, thread-safe .NET library providing temporal data structures. Each structure associates items with precise insertion timestamps, enabling efficient time-based querying, filtering, and cleanup.

This project is ideal for scenarios where you need to store, query, and manage data with temporal semantics — such as event streams, time-windowed analytics, caching with expiry, or temporal state tracking.

Overview

TemporalCollections provides multiple thread-safe generic collections where each item is timestamped at insertion using a strictly monotonic clock. These collections expose interfaces for querying items based on their timestamps, removing old or expired entries efficiently, and preserving concurrency guarantees.

The key design goals are:

• Temporal semantics: Items are stored with precise insertion timestamps
• Thread safety: Suitable for concurrent multi-threaded environments
• Time-based querying: Fast retrieval of items within time ranges
• Efficient cleanup: Removing stale or expired data without locking entire collections for long

Core Concept: TemporalItem<T>

At the heart of all collections lies the TemporalItem<T> struct:

• Wraps an immutable value T with a timestamp (DateTime) indicating the moment of insertion
• Guarantees strictly increasing timestamps even under rapid or concurrent creation, using atomic operations
• Provides a timestamp comparer for sorting and searching

Available Collections

Usage Guidance

ITimeQueryable<T> Interface

All temporal collections implement the ITimeQueryable<T> interface, which provides a common set of methods to query and manage items based on their associated timestamps. This interface enables consistent time-based operations across different collection types.

Key Methods

• GetInRange(DateTime from, DateTime to)
  Returns an enumerable of temporal items whose timestamps fall within the inclusive range [from, to]. This allows filtering the collection by any desired time window.

• RemoveOlderThan(DateTime cutoff)
  Removes all items with timestamps strictly older than the specified cutoff time (Timestamp < cutoff). This method is useful for pruning outdated data and maintaining collection size.

• CountInRange(DateTime from, DateTime to)
  Returns the number of items with timestamps in the inclusive range [from, to]. Throws if to < from.

• GetTimeSpan()
  Returns latest.Timestamp - earliest.Timestamp. Returns TimeSpan.Zero if the collection is empty or has a single item.

• Clear()
  Removes all items from the collection.

• RemoveRange(DateTime from, DateTime to)
  Removes all items with timestamps in the inclusive range [from, to]. Throws if to < from.

• GetLatest()
  Returns the most recent item (max timestamp), or null if empty.

• GetEarliest()
  Returns the oldest item (min timestamp), or null if empty.

• GetBefore(DateTime time)
  Returns all items with Timestamp < time (strictly before), ordered by ascending timestamp.

• GetAfter(DateTime time)
  Returns all items with Timestamp > time (strictly after), ordered by ascending timestamp.

These methods collectively support efficient and thread-safe temporal queries and cleanups, allowing each collection to manage its items according to their timestamps while exposing a unified API.

Monotonic Timestamp Guarantee

A key feature of the temporal collections is the guarantee that timestamps assigned to items are strictly monotonically increasing, even when multiple items are created concurrently or in rapid succession.

This is achieved through the TemporalItem<T> record, which uses an atomic compare-and-swap operation on a static internal timestamp counter. When creating a new temporal item, the current UTC timestamp in ticks is retrieved and compared against the last assigned timestamp:

• If the current timestamp is greater than the last one, it is used as-is.
• If the current timestamp is less than or equal to the last assigned timestamp (e.g., due to rapid creation or clock precision limits), the timestamp is artificially incremented by one tick.

This approach ensures:

• Uniqueness: No two items share the exact same timestamp.
• Strict ordering: Timestamps always increase in time order.
• Thread safety: The mechanism works correctly across multiple threads without race conditions.

By enforcing this monotonic timestamp ordering, the temporal collections can rely on consistent time-based queries and maintain correct chronological order of items.

Notes

• Deterministic ordering: query results are returned in ascending timestamp order.
• Snapshot semantics: methods that return enumerables/lists provide a stable snapshot at call time.
• Thread-safety: all operations are designed to be thread-safe per collection.
• Intervals: for interval-based collections, the Timestamp used by this interface refers to the interval start.

Contributing

Thank you for considering to help out with the source code! If you'd like to contribute, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base.

Getting started with Git and GitHub

• Setting up Git
• Fork the repository
• Open an issue if you encounter a bug or have a suggestion for improvements/features

Licensee

TemporalCollections source code is available under MIT License, see license in the source.

Contact

Please contact at francesco.delre[at]protonmail.com for any details.