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 Added in v2.0.0 Source

Accessors

clockWith

Added in v2.0.0 Source

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

Clock for the service reference
currentTimeMillis for convenience accessor that returns milliseconds
currentTimeNanos for convenience accessor that returns nanoseconds

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

Added in v2.0.0 Source

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

currentTimeNanos for nanosecond precision
monotonicTimeNanos for measuring elapsed time
clockWith for accessing the full Clock service

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

Added in v2.0.0 Source

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

monotonicTimeNanos for measuring elapsed time

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

Added in v4.0.0 Source

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

currentTimeNanos for Unix wall-clock timestamps

Signature

declare const monotonicTimeNanos: Effect<bigint>

Services

Clock

Added in v2.0.0 Source

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

clockWith for using the current Clock service inside an effect
currentTimeMillis for reading the current time in milliseconds
currentTimeNanos for reading the current time in nanoseconds

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

Added in v2.0.0 Source

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]