effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/Clock.ts

@@ -1,8 +1,9 @@
 /**
  * Service and helpers for reading time and sleeping inside Effect programs.
- * The active `Clock` provides current time in milliseconds or nanoseconds and a
- * `sleep` operation for delaying work. Because time is accessed through a
- * service, tests can replace the clock with a controlled implementation.
+ * 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.
  *
  * @since 2.0.0
  */
@@ -22,56 +23,121 @@ import * as effect from "./internal/effect.ts"
  *
  * **Example** (Reading current time)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * 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
- *
- *   console.log(`Current time (ms): ${currentTime}`)
- *   console.log(`Current time (ns): ${currentTimeNanos}`)
+ *   return [currentTime, currentTimeNanos] as const
  * })
+ *
+ * await Effect.runPromise(Effect.provideService(clockOperations, Clock.Clock, testClock)) // => [1_000, 1_000_000_000n]
  * ```
  *
- * @category models
+ * @category services
  * @since 2.0.0
  */
 export interface Clock {
   /**
-   * Returns the current time in milliseconds unsafely.
+   * Returns the current Unix time in milliseconds unsafely.
    *
    * **When to use**
    *
-   * Use to read millisecond time synchronously when you already have a `Clock`
-   * service and can accept non-effectful access.
+   * Use to read a wall-clock timestamp synchronously when you already have a
+   * `Clock` service and can accept non-effectful access.
+   *
+   * **Gotchas**
+   *
+   * The value can move backward or forward when the system wall clock is
+   * corrected, so it is not suitable for measuring elapsed time.
    */
   currentTimeMillisUnsafe(): number
   /**
-   * Returns the current time in milliseconds.
+   * Returns the current Unix time in milliseconds.
    *
    * **When to use**
    *
-   * Use to read millisecond time through this `Clock` service in `Effect`.
+   * Use to read a wall-clock timestamp through this `Clock` service in
+   * `Effect`.
+   *
+   * **Gotchas**
+   *
+   * The value can move backward or forward when the system wall clock is
+   * corrected, so it is not suitable for measuring elapsed time.
    */
   readonly currentTimeMillis: Effect<number>
   /**
-   * Returns the current time in nanoseconds unsafely.
+   * Returns the current Unix time in nanoseconds unsafely.
    *
    * **When to use**
    *
-   * Use to read nanosecond time synchronously when you already have a `Clock`
-   * service and can accept non-effectful access.
+   * Use to read a wall-clock timestamp synchronously when you already have a
+   * `Clock` service and can accept non-effectful access.
+   *
+   * **Gotchas**
+   *
+   * The value can move backward or forward when the system wall clock is
+   * corrected, so it is not suitable for measuring elapsed time.
    */
   currentTimeNanosUnsafe(): bigint
   /**
-   * Returns the current time in nanoseconds.
+   * Returns the current Unix time in nanoseconds.
    *
    * **When to use**
    *
-   * Use to read nanosecond time through this `Clock` service in `Effect`.
+   * Use to read a wall-clock timestamp through this `Clock` service in
+   * `Effect`.
+   *
+   * **Gotchas**
+   *
+   * The value can move backward or forward when the system wall clock is
+   * corrected, so it is not suitable for measuring elapsed time.
    */
   readonly currentTimeNanos: Effect<bigint>
+  /**
+   * Returns the current monotonic time in nanoseconds unsafely.
+   *
+   * **When to use**
+   *
+   * Use to measure elapsed time synchronously when you already have a `Clock`
+   * service and can accept non-effectful access.
+   *
+   * **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.
+   *
+   * @since 4.0.0
+   */
+  monotonicTimeNanosUnsafe(): bigint
+  /**
+   * Returns the current monotonic time in nanoseconds.
+   *
+   * **When to use**
+   *
+   * Use to measure elapsed time through this `Clock` service in `Effect`.
+   *
+   * **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.
+   *
+   * @since 4.0.0
+   */
+  readonly monotonicTimeNanos: Effect<bigint>
   /**
    * Asynchronously sleeps for the specified duration.
    *
@@ -92,20 +158,32 @@ export interface Clock {
  *
  * **Example** (Accessing the Clock service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * 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
  * ```
  *
  * @see {@link clockWith} for using the current Clock service inside an effect
  * @see {@link currentTimeMillis} for reading the current time in milliseconds
  * @see {@link currentTimeNanos} for reading the current time in nanoseconds
  *
- * @category references
+ * @category services
  * @since 2.0.0
  */
 export const Clock: Context.Reference<Clock> = effect.ClockRef
@@ -120,75 +198,129 @@ export const Clock: Context.Reference<Clock> = effect.ClockRef
  *
  * **Example** (Accessing the current Clock service)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Clock, Effect } from "effect"
  *
- * const program = Clock.clockWith((clock) =>
- *   Effect.sync(() => {
- *     const currentTime = clock.currentTimeMillisUnsafe()
- *     console.log(`Current time: ${currentTime}`)
- *     return currentTime
- *   })
- * )
+ * 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
  * ```
  *
  * @see {@link Clock} for the service reference
  * @see {@link currentTimeMillis} for convenience accessor that returns milliseconds
  * @see {@link currentTimeNanos} for convenience accessor that returns nanoseconds
- * @category constructors
+ * @category accessors
  * @since 2.0.0
  */
 export const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effect<A, E, R> = effect.clockWith
 
 /**
- * Returns an Effect that succeeds with the current time in milliseconds.
+ * Returns an Effect that succeeds with the current Unix time in milliseconds.
  *
  * **When to use**
  *
- * Use to read wall-clock time from the active Clock service with millisecond
- * precision.
+ * 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.
  *
  * **Example** (Reading milliseconds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Clock, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const currentTime = yield* Clock.currentTimeMillis
- *   console.log(`Current time: ${currentTime}ms`)
- *   return currentTime
- * })
+ * 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
  * ```
  *
  * @see {@link currentTimeNanos} for nanosecond precision
+ * @see {@link monotonicTimeNanos} for measuring elapsed time
  * @see {@link clockWith} for accessing the full Clock service
  *
- * @category constructors
+ * @category accessors
  * @since 2.0.0
  */
 export const currentTimeMillis: Effect<number> = effect.currentTimeMillis
 
 /**
- * Returns an Effect that succeeds with the current time in nanoseconds.
+ * Returns an Effect that succeeds with the current Unix time in nanoseconds.
  *
  * **When to use**
  *
- * Use to read wall-clock time from the active `Clock` service with nanosecond
- * precision.
+ * 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.
  *
  * **Example** (Reading nanoseconds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Clock, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const currentTime = yield* Clock.currentTimeNanos
- *   console.log(`Current time: ${currentTime}ns`)
- *   return currentTime
- * })
+ * 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
  * ```
  *
- * @category constructors
+ * @see {@link monotonicTimeNanos} for measuring elapsed time
+ *
+ * @category accessors
  * @since 2.0.0
  */
 export const currentTimeNanos: Effect<bigint> = effect.currentTimeNanos
+
+/**
+ * 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 {@link currentTimeNanos} for Unix wall-clock timestamps
+ *
+ * @category accessors
+ * @since 4.0.0
+ */
+export const monotonicTimeNanos: Effect<bigint> = effect.monotonicTimeNanos

package/src/Combiner.ts

@@ -26,13 +26,12 @@ import type * as Order from "./Order.ts"
  *
  * **Example** (Combining numbers with addition)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner } from "effect"
  *
  * const Sum = Combiner.make<number>((self, that) => self + that)
  *
- * console.log(Sum.combine(3, 4))
- * // Output: 7
+ * Sum.combine(3, 4) // => 7
  * ```
  *
  * @see {@link make} – create a `Combiner` from a function
@@ -65,13 +64,12 @@ export interface Combiner<A> {
  *
  * **Example** (Multiplying numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner } from "effect"
  *
  * const Product = Combiner.make<number>((self, that) => self * that)
  *
- * console.log(Product.combine(3, 5))
- * // Output: 15
+ * Product.combine(3, 5) // => 15
  * ```
  *
  * @see {@link Combiner} – the interface this creates
@@ -97,13 +95,12 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  *
  * **Example** (Reversing string concatenation)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner, String } from "effect"
  *
  * const Prepend = Combiner.flip(String.ReducerConcat)
  *
- * console.log(Prepend.combine("a", "b"))
- * // Output: "ba"
+ * Prepend.combine("a", "b") // => "ba"
  * ```
  *
  * @see {@link make}
@@ -130,16 +127,13 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  *
  * **Example** (Selecting the minimum of two numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner, Number } from "effect"
  *
  * const Min = Combiner.min(Number.Order)
  *
- * console.log(Min.combine(3, 1))
- * // Output: 1
- *
- * console.log(Min.combine(1, 3))
- * // Output: 1
+ * Min.combine(3, 1) // => 1
+ * Min.combine(1, 3) // => 1
  * ```
  *
  * @see {@link max}
@@ -166,16 +160,13 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **Example** (Selecting the maximum of two numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner, Number } from "effect"
  *
  * const Max = Combiner.max(Number.Order)
  *
- * console.log(Max.combine(3, 1))
- * // Output: 3
- *
- * console.log(Max.combine(1, 3))
- * // Output: 3
+ * Max.combine(3, 1) // => 3
+ * Max.combine(1, 3) // => 3
  * ```
  *
  * @see {@link min}
@@ -199,13 +190,12 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **Example** (Keeping the first value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner } from "effect"
  *
  * const First = Combiner.first<number>()
  *
- * console.log(First.combine(1, 2))
- * // Output: 1
+ * First.combine(1, 2) // => 1
  * ```
  *
  * @see {@link last}
@@ -229,13 +219,12 @@ export function first<A>(): Combiner<A> {
  *
  * **Example** (Keeping the last value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner } from "effect"
  *
  * const Last = Combiner.last<number>()
  *
- * console.log(Last.combine(1, 2))
- * // Output: 2
+ * Last.combine(1, 2) // => 2
  * ```
  *
  * @see {@link first}
@@ -261,13 +250,12 @@ export function last<A>(): Combiner<A> {
  *
  * **Example** (Always returning zero)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner } from "effect"
  *
  * const Zero = Combiner.constant(0)
  *
- * console.log(Zero.combine(42, 99))
- * // Output: 0
+ * Zero.combine(42, 99) // => 0
  * ```
  *
  * @see {@link first}
@@ -297,13 +285,12 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * **Example** (Joining strings with a separator)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner, String } from "effect"
  *
  * const commaSep = Combiner.intercalate(",")(String.ReducerConcat)
  *
- * console.log(commaSep.combine("a", "b"))
- * // Output: "a,b"
+ * commaSep.combine("a", "b") // => "a,b"
  * ```
  *
  * @see {@link make}