Clock
Service and helpers for reading time and sleeping inside Effect programs. The active Clock provides Unix time, monotonic time for measuring elapsed durations, and a sleep operation for delaying work. Because time is accessed through a service, tests can replace the clock with a controlled implementation.
Accessors
Signature
declare const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effect<A, E, R>;currentTimeMillis
Returns an Effect that succeeds with the current Unix time in milliseconds.
When to use
Use to create wall-clock timestamps from the active Clock service with millisecond precision.
Gotchas
The value can move backward or forward when the system wall clock is corrected, so it is not suitable for measuring elapsed time.
See
currentTimeNanosfor nanosecond precisionmonotonicTimeNanosfor measuring elapsed timeclockWithfor accessing the full Clock service
Signature
declare const currentTimeMillis: Effect<number>;currentTimeNanos
Returns an Effect that succeeds with the current Unix time in nanoseconds.
When to use
Use to create wall-clock timestamps from the active Clock service with nanosecond precision.
Gotchas
The value can move backward or forward when the system wall clock is corrected, so it is not suitable for measuring elapsed time. The live clock allows up to one second of drift from Date.now() before re-anchoring.
See
monotonicTimeNanosfor measuring elapsed time
Signature
declare const currentTimeNanos: Effect<bigint>;monotonicTimeNanos
Returns an Effect that succeeds with the current monotonic time in nanoseconds.
When to use
Use to measure elapsed time by subtracting two readings.
Gotchas
The value has an arbitrary origin and is unsuitable for serialization. Use it only to subtract readings produced by the same clock. Whether it advances while the host is suspended depends on the runtime.
See
currentTimeNanosfor Unix wall-clock timestamps
Signature
declare const monotonicTimeNanos: Effect<bigint>;Services
Context reference for the active time service in the environment.
When to use
Use when you need to access or provide the full time service, including sleep operations, rather than a single timestamp accessor.
See
clockWithfor using the current Clock service inside an effectcurrentTimeMillisfor reading the current time in millisecondscurrentTimeNanosfor reading the current time in nanoseconds
Signature
declare const Clock: Reference<Clock>;Represents a time-based clock which provides functionality related to time and scheduling.
When to use
Use to define or provide a clock service for current-time and sleep operations.
Signature
interface Clock {
readonly currentTimeMillis: Effect<number>;
readonly currentTimeNanos: Effect<bigint>;
readonly monotonicTimeNanos: Effect<bigint>;
currentTimeMillisUnsafe(): number;
currentTimeNanosUnsafe(): bigint;
monotonicTimeNanosUnsafe(): bigint;
sleep(duration: Duration): Effect<void>;
}
Accesses the current Clock service and uses it to run the provided function.
When to use
Use when you need the full Clock service interface to perform multiple time operations or call unsafe variants within a single effect.
See
Clockfor the service referencecurrentTimeMillisfor convenience accessor that returns millisecondscurrentTimeNanosfor convenience accessor that returns nanoseconds