Optima.Net.Chronology 1.0.2

Optima.Net.Chronology

Optima.Net.Chronology provides a small set of clear, deterministic primitives for reasoning about time in software systems.

Many systems struggle with time because typical APIs mix together concepts such as time zones, calendars, and absolute time. This library separates those concerns and focuses only on the global timeline.

The core idea is simple:

Chronon → a single point on the global timeline
LOT → Length Of Time between two points
WOT → Window Of Time between two Chronons

Supporting utilities help developers work with time safely and predictably.

These primitives are useful in real systems such as:

• Financial systems
• Event processing pipelines
• Distributed worker systems
• Scheduling systems
• Monitoring and analytics systems

Core Concepts

Chronon

Represents a single moment on the global timeline.

Chronons are always UTC based and represent absolute time.

LOT

LOT stands for Length Of Time.

A LOT represents the distance between two Chronons.

WOT

WOT stands for Window Of Time.

A WOT represents a positioned span between two Chronons.

The window rule is:

Start ⇐ t < End

The start is inclusive and the end is exclusive.

Chronon Features

Chronon provides deterministic operations for:

• Creating moments in time
• Converting between timestamps
• Performing timeline arithmetic
• Comparing moments
• Measuring distance between events

Example:

Chronon now = Chronon.Now();

Console.WriteLine("Current moment: " + now);

Unix timestamps are commonly used in distributed systems.

Chronon c = Chronon.FromUnixTimeSeconds(1700000000);

long seconds = c.ToUnixTimeSeconds();

Working with milliseconds:

Chronon c = Chronon.FromUnixTimeMilliseconds(1700000000000);

long ms = c.ToUnixTimeMilliseconds();

Distance between two events:

Chronon start = Chronon.FromUnixTimeSeconds(10);
Chronon end = Chronon.FromUnixTimeSeconds(20);

LOT distance = start.DistanceTo(end);

Special values:

Chronon epoch = Chronon.UnixEpoch;
Chronon min = Chronon.MinValue;
Chronon max = Chronon.MaxValue;

LOT: Length Of Time

LOT represents a duration independent of any position on the timeline.

Common creation helpers:

LOT seconds = LOT.FromSeconds(30);
LOT minutes = LOT.FromMinutes(5);
LOT hours = LOT.FromHours(2);
LOT days = LOT.FromDays(1);

Arithmetic:

LOT a = LOT.FromSeconds(10);
LOT b = LOT.FromSeconds(5);

LOT sum = a + b;
LOT difference = a - b;
LOT negated = -a;

Scalar operations:

LOT interval = LOT.FromMinutes(5);

LOT triple = interval * 3;
LOT half = interval / 2;

Conversion:

TimeSpan span = interval.ToTimeSpan();

State checks:

bool positive = interval.IsPositive;
bool negative = interval.IsNegative;
bool zero = interval.IsZero;

WOT: Window Of Time

A WOT represents a positioned span on the timeline.

Chronon start = Chronon.Now();
Chronon end = start + LOT.FromHours(2);

WOT window = new WOT(start, end);

Containment:

Chronon moment = Chronon.Now();

bool inside = window.Contains(moment);

Window length:

LOT duration = window.Length;

Shifting a window:

WOT shifted = window.Shift(LOT.FromMinutes(30));

Splitting windows:

foreach (var segment in window.Split(LOT.FromMinutes(15)))
{
    Console.WriteLine(segment.Start + " -> " + segment.End);
}

Intersection:

WOT a = new WOT(start, start + LOT.FromHours(2));
WOT b = new WOT(start + LOT.FromHours(1), start + LOT.FromHours(3));

WOT? overlap = a.Intersect(b);

Union:

WOT merged = a.Union(b);

Subtracting windows:

foreach (var remaining in a.Subtract(b))
{
    Console.WriteLine(remaining.Start + " -> " + remaining.End);
}

Scenario 1: Processing an Online Payment

In a payment system, each transaction must be timestamped when it enters the system.

Chronon provides a clear representation of that moment.

Chronon receivedAt = Chronon.Now();

Console.WriteLine("Payment received at: " + receivedAt);

Using Chronon instead of DateTime avoids ambiguity about time zones and ensures the system always works with UTC time.

Scenario 2: Payment Expiry Window

Many payment systems allow customers a limited time to complete a payment.

Chronon created = Chronon.Now();

LOT expiryDuration = LOT.FromMinutes(15);

Chronon expiryTime = created + expiryDuration;

Console.WriteLine("Payment expires at: " + expiryTime);

Scenario 3: Creating a Validity Window

Example: a discount code valid between two times.

Chronon start = Chronon.Now();
LOT duration = LOT.FromHours(2);

Chronon end = start + duration;

WOT discountWindow = new WOT(start, end);

Chronon purchaseTime = Chronon.Now();

bool valid = discountWindow.Contains(purchaseTime);

Scenario 4: Worker Processing Windows

Distributed systems often divide work into time windows.

Chronon start = Chronon.Now();
Chronon end = start + LOT.FromHours(1);

WOT hourWindow = new WOT(start, end);

foreach (var segment in hourWindow.Split(LOT.FromMinutes(15)))
{
    Console.WriteLine(segment.Start + " -> " + segment.End);
}

Scenario 5: Window Algebra

Window algebra allows complex scheduling logic.

Example: removing maintenance time from a processing window.

WOT processing = new WOT(start, start + LOT.FromHours(4));

WOT maintenance = new WOT(start + LOT.FromHours(1),
                           start + LOT.FromHours(2));

foreach (var active in processing.Subtract(maintenance))
{
    Console.WriteLine("Active window:");
    Console.WriteLine(active.Start + " -> " + active.End);
}

Why This Library Exists

Many time APIs mix multiple concerns:

• Time zones
• Local calendars
• Absolute time
• Durations

Optima.Net.Chronology separates these concerns.

It focuses purely on the global timeline and provides deterministic operations for:

• measuring time
• comparing time
• creating time windows
• generating time sequences

Typical Usage Pattern

Applications typically use the library as follows:

1. Obtain the current moment using Chronon.Now().
2. Use LOT to represent durations.
3. Use WOT to represent windows.
4. Combine these primitives to build scheduling or time logic.

License

MIT License