Axial
Repository F# setup
open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Layers
open Axial.Console
open Axial.FileSystem
open Axial.Hosting
open Axial.Hosting.Browser
open Axial.Hosting.Node
open Axial.PlatformService
open Axial.State
open Axial.Telemetry
open Axial.Telemetry.JavaScript

IClock provides UtcNow() for timestamps, Elapsed() for monotonic durations, and Sleep() for cancellable delays. Timed flows require IHasClock in their environment, so a host or test supplies one source for all three operations.

Show page setup
// Setup for the checked examples on this page.
open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Layers
open Axial.Console
open Axial.FileSystem
open Axial.Hosting
open Axial.Hosting.Browser
open Axial.Hosting.Node
open Axial.PlatformService
open Axial.State
open Axial.Telemetry
open Axial.Telemetry.JavaScript
/// Fails the docs test when an example's result differs from the value shown.
let shouldEqual expected actual =
    if actual <> expected then failwithf "Expected %A but got %A" expected actual
Verified
open System
open Axial
open Axial.PlatformService
Verified
let expiresWithin (window: TimeSpan) (expiry: DateTimeOffset) : Flow<#IHasClock, Never, bool> =
    Clock.now |> Flow.map (fun now -> expiry - now <= window)

Clock.now returns a DateTimeOffset. The other readers derive from it. Here they run against the base runtime with its clock fixed at noon UTC on 1 January 2026:

Verified
> open System;;
> open Axial.PlatformService;;
> let runtime () = { BaseRuntime.liveValue with Clock = Clock.fromValue (DateTimeOffset(2026, 1, 1, 12, 0, 0, TimeSpan.Zero)) };;
> (Clock.now : Flow<BaseRuntime, Never, DateTimeOffset>) |> Flow.map _.Hour |> Flow.run (runtime ());;
> (Clock.utcDateTime : Flow<BaseRuntime, Never, DateTime>) |> Flow.map _.Kind |> Flow.run (runtime ());;
> (Clock.unixTimeSeconds : Flow<BaseRuntime, Never, int64>) |> Flow.run (runtime ());;
> (Clock.unixTimeMilliseconds : Flow<BaseRuntime, Never, int64>) |> Flow.run (runtime ());;
val it: Exit<int,Never> = Success 12
val it: Exit<DateTimeKind,Never> = Success Utc
val it: Exit<int64,Never> = Success 1767268800L
val it: Exit<int64,Never> = Success 1767268800000L

None of them produce a typed failure, so the error channel stays free for the workflow's own errors.

Measuring durations

Wall-clock time can jump when the system clock is adjusted, so do not use it to measure durations. IClock.Elapsed is a monotonic reading for that job, and Clock.timed wraps a flow with it:

Verified
let buildReport : Flow<BaseRuntime, Never, string> = Flow.ok "report"

let timedReport : Flow<BaseRuntime, Never, string> =
    flow {
        let! report, took = buildReport |> Clock.timed
        do! Log.info $"report built in {took.TotalMilliseconds:F0} ms"
        return report
    }

Clock.elapsed reads the timer directly; only the difference between two readings is meaningful. Measuring through the clock instead of Stopwatch keeps durations deterministic in tests: under Clock.fromValue every duration is zero:

Verified
let gate = obj()
let mutable logged = []

let testRuntime =
    { BaseRuntime.liveValue with
        Clock = Clock.fromValue (DateTimeOffset(2026, 1, 1, 12, 0, 0, TimeSpan.Zero))
        Log = Log.fromSink (fun _ message -> lock gate (fun () -> logged <- message :: logged)) }

timedReport |> Flow.run testRuntime |> shouldEqual (Exit.Success "report")
lock gate (fun () -> List.rev logged) |> shouldEqual [ "report built in 0 ms" ]

Supplying the service

Clock.live reads DateTimeOffset.UtcNow and a monotonic process timer. Clock.layer is the same value as a Layer<unit, Never, IClock>. Most applications get the clock as part of the base runtime rather than wiring it alone.

Testing

Clock.fromValue pins the instant for read-only tests. It deliberately rejects Sleep; use ManualClock for a workflow that sleeps, times out, retries, or forks fibers. Advance it after the expected sleeper has registered:

Verified
let clock = ManualClock(DateTimeOffset.Parse "2026-01-01T00:00:00Z")
let env = ClockEnvironment(clock :> IClock)
let sleeping : Flow<ClockEnvironment, Never, unit> = Flow.sleep (TimeSpan.FromSeconds 5.0)
let pending = sleeping |> Flow.toAsync env |> Async.StartAsTask
// The workflow registers its sleep asynchronously, so wait for it before advancing.
while clock.Sleepers = 0 do
    System.Threading.Thread.SpinWait 20
clock.AdvanceBy(TimeSpan.FromSeconds 5.0)
pending.Wait()

ManualClock is currently available on .NET. Clock.live supports .NET and Fable. A fixed clock is enough for a time-read assertion:

On Fable, an F# record may use a field named Clock and implement IHasClock.Clock. Axial marks the interface for Fable name mangling so the generated JavaScript does not confuse the record field with the interface getter. If handwritten JavaScript supplies an environment, construct an Axial environment in F# (or use the generated ClockEnvironment constructor) rather than passing a plain { Clock: clock } object. The latter lacks the interface method the compiled Flow calls. This rule also applies to the other IHas* service interfaces.

Verified
type ClockEnv =
    { Clock: IClock }
    interface IHasClock with
        member this.Clock = this.Clock

let atNoon = { Clock = Clock.fromValue (DateTimeOffset(2026, 1, 1, 12, 0, 0, TimeSpan.Zero)) }
Verified
expiresWithin (TimeSpan.FromHours 1.0) (DateTimeOffset(2026, 1, 1, 12, 30, 0, TimeSpan.Zero))
|> Flow.run atNoon
|> shouldEqual (Exit.Success true)

expiresWithin (TimeSpan.FromHours 1.0) (DateTimeOffset(2026, 1, 1, 15, 0, 0, TimeSpan.Zero))
|> Flow.run atNoon
|> shouldEqual (Exit.Success false)

A fixed clock does not advance. When a test needs time to move, use ManualClock and advance it explicitly, so the test controls how time moves instead of depending on wall-clock timing.

IClock reports the time; it does not schedule. Delays, timeouts, and retry policies are Flow runtime concerns; see scheduling and retries.