jaytwo.TimeExpression 0.1.0-beta-20251102202452

jaytwo.TimeExpression

jaytwo.TimeExpression provides human-readable time formatting utilities.

View source on GitHub →

🧭 Overview

This library offers a few complementary formatting systems:

It’s tiny, dependency-free, and great for logs, metrics, or debugging output.

✨ Features

• ✅ Go-compatible duration syntax Output identical to Go’s time.Duration.String() — compact, human-readable (1h2m3.5s, 1.23ms, 500µs, 100ns).

• ⚙️ ASCII-safe output option Switch µs → us for compatibility with HTTP headers, log transport, or any ASCII-only system.

• 🧩 Adaptive sub-second precision Compact mode automatically trims noisy fractional digits for cleaner log output (e.g. 9.9999999s → 9.99s).

• ⏱ ExactSeconds formatting Provides culture-invariant decimal seconds, at full tick precision (7 decimal places), and never uses scientific notation. Ideal for metrics or structured logs where consistent machine-readable values matter.

• ⏱ ExactMilliseconds formatting Same idea as Exact Seconds, but in milliseconds (up to 4 decimals, still tick-precise).

• 💯 Deterministic and dependency-free No runtime dependencies, no culture surprises, no rounding errors — just consistent, predictable output on every platform.

• 🧪 Tiny and test-friendly Fast, allocation-light, and fully deterministic, perfect for loggers, middleware, benchmarks, or performance tracing.

📦 Installation

Add via NuGet:

PM> Install-Package jaytwo.TimeExpression

Or using the .NET CLI:

dotnet add package jaytwo.TimeExpression

🚀 Usage

Go-style duration formatting

using jaytwo.TimeExpression.Golang;

var sampleTime = TimeSpan.FromMinutes(1.5);
var microseconds = TimeSpan.FromTicks(11); // 1.1 µs

var oneTick = TimeSpan.FromTicks(1);
var almost10s = TimeSpan.FromSeconds(10) - oneTick;
var almost1m = TimeSpan.FromMinutes(1) - oneTick;
var almost1h = TimeSpan.FromHours(1) - oneTick;
var almost1d = TimeSpan.FromDays(1) - oneTick;
var almost1w = TimeSpan.FromDays(7) - oneTick;

// ToGoString (canonical Go behavior)
Console.WriteLine(GoDuration.ToGoString(TimeSpan.Zero));    // → 0s
Console.WriteLine(GoDuration.ToGoString(sampleTime));       // → 1m30s
Console.WriteLine(GoDuration.ToGoString(microseconds));     // → 1.1µs
Console.WriteLine(GoDuration.ToGoString(almost10s));        // → 9.9999999s
Console.WriteLine(GoDuration.ToGoString(almost1m));         // → 59.9999999s
Console.WriteLine(GoDuration.ToGoString(almost1h));         // → 59m59.9999999s
Console.WriteLine(GoDuration.ToGoString(almost1d));         // → 23h59m59.9999999s
Console.WriteLine(GoDuration.ToGoString(almost1w));         // → 167h59m59.9999999s

// ToAsciiString (only affects microseconds: µs → us)
Console.WriteLine(GoDuration.ToAsciiString(microseconds));  // → 1.1us

// ToCompactString (adaptive subsecond decimal precision)
Console.WriteLine(GoDuration.ToCompactString(almost10s));   // → 9.99s
Console.WriteLine(GoDuration.ToCompactString(almost1m));    // → 59.9s
Console.WriteLine(GoDuration.ToCompactString(almost1h));    // → 59m59s
Console.WriteLine(GoDuration.ToCompactString(almost1d));    // → 23h59m59s
Console.WriteLine(GoDuration.ToCompactString(almost1w));    // → 167h59m59s

Why does ASCII-safety matter? The first use of this package was adding human-readable response times to HTTP headers for easier debugging. Everything was working great until a sub-millisecond response time appeared, and suddenly the middleware crashed.

Turns out the µ in µs was the problem (HTTP headers require ASCII-only). Fix: enable GoDurationFormatOptions.AsciiMicroseconds to emit us.

Isn't Go's canonical implementation compact enough? While Go’s format is concise, the .NET TimeSpan representation includes full tick precision (7 decimal places).

Remember, my primary use case is human-readable logs and metrics. For humans, this level of detail often adds unnecessary noise. Even multi-minute operations end up displaying sub-microsecond-level fractions.

I might care that something took 1.02ms versus 1.92ms, but probably not that it took 12m23.59192s instead of 12m23.59102s.

Exact seconds

The ExactSeconds API provides culture-invariant decimal seconds, at full tick precision (7 decimal places), and never formats in scientific notation.

using jaytwo.TimeExpression.Seconds;

var twoMinutes = TimeSpan.FromMinutes(2);

var oneTick = TimeSpan.FromTicks(1);
var almost1m = TimeSpan.FromMinutes(1) - oneTick;
var almost1h = TimeSpan.FromHours(1) - oneTick;
var almost1d = TimeSpan.FromDays(1) - oneTick;
var almost1w = TimeSpan.FromDays(7) - oneTick;

// never scientific notation
Console.WriteLine(oneTick.TotalSeconds);                 // → 1E-7
Console.WriteLine(ExactSeconds.ToString(oneTick));       // → 0.0000001

// trims leading and trailing zeroes
Console.WriteLine(ExactSeconds.ToString(TimeSpan.Zero)); // → 0
Console.WriteLine(ExactSeconds.ToString(twoMinutes));    // → 120

// full tick precision
Console.WriteLine(ExactSeconds.ToString(almost1m));      // → 59.9999999
Console.WriteLine(ExactSeconds.ToString(almost1h));      // → 3599.9999999
Console.WriteLine(ExactSeconds.ToString(almost1d));      // → 86399.9999999
Console.WriteLine(ExactSeconds.ToString(almost1w));      // → 604799.9999999

This seems entirely unnecessary. And for most people, it probably is. But even in the machine-friendly parts of logs, I found it frustrating to track and/or validate full-precision values like 2.7E-4 at a glance.

Exact milliseconds

using jaytwo.TimeExpression.Milliseconds;

var twoMinutes = TimeSpan.FromMinutes(2);

var oneTick = TimeSpan.FromTicks(1);
var almost1m = TimeSpan.FromMinutes(1) - oneTick;
var almost1h = TimeSpan.FromHours(1) - oneTick;
var almost1d = TimeSpan.FromDays(1) - oneTick;
var almost1w = TimeSpan.FromDays(7) - oneTick;

// never scientific notation
Console.WriteLine(oneTick.TotalMilliseconds);                 // → 0.0001
Console.WriteLine(ExactMilliseconds.ToString(oneTick));       // → 0.0001

// trims leading and trailing zeroes
Console.WriteLine(ExactMilliseconds.ToString(TimeSpan.Zero)); // → 0
Console.WriteLine(ExactMilliseconds.ToString(twoMinutes));    // → 120000

// full tick precision
Console.WriteLine(ExactMilliseconds.ToString(almost1m));      // → 59999.9999
Console.WriteLine(ExactMilliseconds.ToString(almost1h));      // → 3599999.9999
Console.WriteLine(ExactMilliseconds.ToString(almost1d));      // → 86399999.9999
Console.WriteLine(ExactMilliseconds.ToString(almost1w));      // → 604799999.9999

Why Exact Milliseconds? Many latency and UI timings are reasoned about in milliseconds, not seconds. While scientific notation is less of an issue with only 4 decimal places, but this gives the same benefits as the other API's in this package: tick precision, culture-invariant formatting, and predictable output.

🧩 API Summary

Made with ❤️ by Jake — Licensed under the MIT License