Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

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.

6 exports Since v2.0.0 Source

Accessors

clockWith

Since v2.0.0

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

Signature

declare const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effect<A, E, R>

Example Accessing the current Clock service 

import { Clock, Effect } from "effect"


const testClock: Clock.Clock = {
  currentTimeMillisUnsafe: () => 1_000,
  currentTimeMillis: Effect.succeed(1_000),
  monotonicTimeNanosUnsafe: () => 1_000_000_000n,
  monotonicTimeNanos: Effect.succeed(1_000_000_000n),
  currentTimeNanosUnsafe: () => 1_000_000_000n,
  currentTimeNanos: Effect.succeed(1_000_000_000n),
  sleep: () => Effect.void
}


const program = Clock.clockWith((clock) => Effect.sync(() => clock.currentTimeMillisUnsafe()))


await Effect.runPromise(Effect.provideService(program, Clock.Clock, testClock)) // => 1_000

currentTimeMillis

Since v2.0.0

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

Signature

declare const currentTimeMillis: Effect<number>

Example Reading milliseconds 

import { Clock, Effect } from "effect"


const testClock: Clock.Clock = {
  currentTimeMillisUnsafe: () => 1_000,
  currentTimeMillis: Effect.succeed(1_000),
  monotonicTimeNanosUnsafe: () => 1_000_000_000n,
  monotonicTimeNanos: Effect.succeed(1_000_000_000n),
  currentTimeNanosUnsafe: () => 1_000_000_000n,
  currentTimeNanos: Effect.succeed(1_000_000_000n),
  sleep: () => Effect.void
}


await Effect.runPromise(Effect.provideService(Clock.currentTimeMillis, Clock.Clock, testClock)) // => 1_000

currentTimeNanos

Since v2.0.0

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

Signature

declare const currentTimeNanos: Effect<bigint>

Example Reading nanoseconds 

import { Clock, Effect } from "effect"


const testClock: Clock.Clock = {
  currentTimeMillisUnsafe: () => 1_000,
  currentTimeMillis: Effect.succeed(1_000),
  monotonicTimeNanosUnsafe: () => 1_000_000_000n,
  monotonicTimeNanos: Effect.succeed(1_000_000_000n),
  currentTimeNanosUnsafe: () => 1_000_000_000n,
  currentTimeNanos: Effect.succeed(1_000_000_000n),
  sleep: () => Effect.void
}


await Effect.runPromise(Effect.provideService(Clock.currentTimeNanos, Clock.Clock, testClock)) // => 1_000_000_000n

monotonicTimeNanos

Since v4.0.0

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

Signature

declare const monotonicTimeNanos: Effect<bigint>

Services

Clock

Since v2.0.0

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

Signature

declare const Clock: Reference<Clock>

Example Accessing the Clock service 

import { Clock, Effect } from "effect"


const testClock: Clock.Clock = {
  currentTimeMillisUnsafe: () => 1_000,
  currentTimeMillis: Effect.succeed(1_000),
  monotonicTimeNanosUnsafe: () => 1_000_000_000n,
  monotonicTimeNanos: Effect.succeed(1_000_000_000n),
  currentTimeNanosUnsafe: () => 1_000_000_000n,
  currentTimeNanos: Effect.succeed(1_000_000_000n),
  sleep: () => Effect.void
}


const program = Effect.gen(function*() {
  const clock = yield* Clock.Clock
  return clock.currentTimeMillisUnsafe()
})


await Effect.runPromise(Effect.provideService(program, Clock.Clock, testClock)) // => 1_000

Clock

interface
Since v2.0.0

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>;
}

Example Reading current time 

import { Clock, Effect } from "effect"


const testClock: Clock.Clock = {
  currentTimeMillisUnsafe: () => 1_000,
  currentTimeMillis: Effect.succeed(1_000),
  monotonicTimeNanosUnsafe: () => 1_000_000_000n,
  monotonicTimeNanos: Effect.succeed(1_000_000_000n),
  currentTimeNanosUnsafe: () => 1_000_000_000n,
  currentTimeNanos: Effect.succeed(1_000_000_000n),
  sleep: () => Effect.void
}


const clockOperations = Effect.gen(function*() {
  const currentTime = yield* Clock.currentTimeMillis
  const currentTimeNanos = yield* Clock.currentTimeNanos
  return [currentTime, currentTimeNanos] as const
})


await Effect.runPromise(Effect.provideService(clockOperations, Clock.Clock, testClock)) // => [1_000, 1_000_000_000n]