effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/internal/option.ts

@@ -7,7 +7,8 @@ import * as Hash from "../Hash.ts"
 import { toJson } from "../Inspectable.ts"
 import type * as Option from "../Option.ts"
 import { hasProperty } from "../Predicate.ts"
-import { exitFail, exitSucceed, NoSuchElementError, PipeInspectableProto, YieldableProto } from "./core.ts"
+import { SingleShotGen } from "../Utils.ts"
+import { PipeInspectableProto } from "./core.ts"
 
 const TypeId = "~effect/data/Option"
 
@@ -16,7 +17,9 @@ const CommonProto = {
     _A: (_: never) => _
   },
   ...PipeInspectableProto,
-  ...YieldableProto
+  [Symbol.iterator]() {
+    return new SingleShotGen(this)
+  }
 }
 
 const SomeProto = Object.assign(Object.create(CommonProto), {
@@ -39,9 +42,6 @@ const SomeProto = Object.assign(Object.create(CommonProto), {
       _tag: this._tag,
       value: toJson(this.value)
     }
-  },
-  asEffect(this: Option.Some<unknown>) {
-    return exitSucceed(this.value)
   }
 })
 
@@ -70,9 +70,6 @@ const NoneProto = Object.assign(Object.create(CommonProto), {
       _id: "Option",
       _tag: this._tag
     }
-  },
-  asEffect<A>(this: Option.None<A>) {
-    return exitFail(new NoSuchElementError())
   }
 })
 

package/src/internal/result.ts

@@ -6,7 +6,8 @@ import { toJson } from "../Inspectable.ts"
 import type { Option } from "../Option.ts"
 import { hasProperty } from "../Predicate.ts"
 import type * as Result from "../Result.ts"
-import { exitFail, exitSucceed, PipeInspectableProto, YieldableProto } from "./core.ts"
+import { SingleShotGen } from "../Utils.ts"
+import { PipeInspectableProto } from "./core.ts"
 import * as option from "./option.ts"
 
 const TypeId = "~effect/data/Result"
@@ -18,7 +19,9 @@ const CommonProto = {
     _E: (_: never) => _
   },
   ...PipeInspectableProto,
-  ...YieldableProto
+  [Symbol.iterator]() {
+    return new SingleShotGen(this)
+  }
 }
 
 const SuccessProto = Object.assign(Object.create(CommonProto), {
@@ -41,9 +44,6 @@ const SuccessProto = Object.assign(Object.create(CommonProto), {
       _tag: this._tag,
       value: toJson(this.success)
     }
-  },
-  asEffect<L, R>(this: Result.Success<L, R>) {
-    return exitSucceed(this.success)
   }
 })
 
@@ -65,9 +65,6 @@ const FailureProto = Object.assign(Object.create(CommonProto), {
       _tag: this._tag,
       failure: toJson(this.failure)
     }
-  },
-  asEffect<A, E>(this: Result.Failure<A, E>) {
-    return exitFail(this.failure)
   }
 })
 

package/src/internal/schema/schema.ts

@@ -34,7 +34,7 @@ export function make<S extends Schema.Top>(ast: S["ast"], options?: object): S {
   self.ast = ast
   self.rebuild = (ast: AST.AST) => make(ast, options)
   self.makeEffect = flow(Parser.makeEffect(self), Effect.mapErrorEager((issue) => new SchemaError(issue)))
-  self.make = Parser.makeUnsafe(self)
+  self.make = Parser.make(self)
   self.makeOption = Parser.makeOption(self)
   return self
 }

package/src/testing/FastCheck.ts

@@ -19,7 +19,8 @@
  * true for your functions, rather than writing specific test cases. The library
  * then generates many random inputs to verify these properties.
  *
- * @example
+ * **Example** (Checking an array reversal property)
+ *
  * ```ts
  * import * as FastCheck from "effect/testing/FastCheck"
  *
@@ -37,7 +38,8 @@
  * FastCheck.assert(reverseProp)
  * ```
  *
- * @example
+ * **Example** (Checking string concatenation properties)
+ *
  * ```ts
  * import * as FastCheck from "effect/testing/FastCheck"
  *
@@ -56,7 +58,8 @@
  * FastCheck.assert(concatProp)
  * ```
  *
- * @example
+ * **Example** (Generating record data for properties)
+ *
  * ```ts
  * import * as FastCheck from "effect/testing/FastCheck"
  *

package/src/testing/TestClock.ts

@@ -1,4 +1,28 @@
 /**
+ * The `TestClock` module provides a controllable implementation of the Effect
+ * `Clock` service for tests. Instead of waiting for real time to pass, effects
+ * that use `Effect.sleep`, timeouts, schedules, retries, and other time-based
+ * operators can be driven deterministically by advancing the test clock.
+ *
+ * **Common use cases**
+ *
+ * - Testing sleeps, delays, timeouts, debouncing, retries, and schedules without
+ *   slowing the test suite down
+ * - Advancing time with {@link adjust} or jumping to an exact timestamp with
+ *   {@link setTime}
+ * - Running a specific effect against the live clock with {@link withLive}
+ *   while the rest of the test remains under test-clock control
+ *
+ * **Testing gotchas**
+ *
+ * - Effects that sleep semantically block until the clock is advanced far
+ *   enough, so tests usually fork the time-dependent effect before calling
+ *   {@link adjust} or {@link setTime}
+ * - Scheduled sleeps are resumed in clock-time order as the test clock moves
+ *   forward
+ * - If a test uses time but never advances the `TestClock`, the module starts a
+ *   delayed warning to help identify a hanging test
+ *
  * @since 2.0.0
  */
 import * as Arr from "../Array.ts"
@@ -25,6 +49,8 @@ import * as Semaphore from "../Semaphore.ts"
  *
  * For example, here is how we can test `Effect.timeout` using `TestClock`:
  *
+ * **Example** (Testing timeouts deterministically)
+ *
  * ```ts
  * import { Effect, Fiber, Option, pipe } from "effect"
  * import { TestClock } from "effect/testing"
@@ -50,7 +76,8 @@ import * as Semaphore from "../Semaphore.ts"
  * being tested, then adjust the clock time, and finally verify that the
  * expected effects have been performed.
  *
- * @example
+ * **Example** (Advancing time deterministically)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -72,8 +99,8 @@ import * as Semaphore from "../Semaphore.ts"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface TestClock extends Clock.Clock {
   /**
@@ -95,7 +122,10 @@ export interface TestClock extends Clock.Clock {
 }
 
 /**
- * @example
+ * Namespace containing `TestClock` configuration and state types.
+ *
+ * **Example** (Configuring a test clock)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -112,12 +142,17 @@ export interface TestClock extends Clock.Clock {
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare namespace TestClock {
   /**
-   * @example
+   * Options used when constructing a `TestClock`. `warningDelay` controls how
+   * long the live clock waits before logging a warning when a test uses time
+   * without advancing the test clock.
+   *
+   * **Example** (Configuring the warning delay)
+   *
    * ```ts
    * import { Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -133,8 +168,8 @@ export declare namespace TestClock {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Options {
     /**
@@ -145,24 +180,12 @@ export declare namespace TestClock {
   }
 
   /**
-   * @example
-   * ```ts
-   * import { Effect } from "effect"
-   * import { TestClock } from "effect/testing"
-   *
-   * const program = Effect.gen(function*() {
-   *   const testClock = yield* TestClock.make()
-   *
-   *   // The state represents the current timestamp and scheduled sleeps
-   *   const timestamp = testClock.currentTimeMillisUnsafe()
-   *   console.log(timestamp) // Current test time
-   *
-   *   // Internal state structure: { timestamp: number, sleeps: Array<[number, Latch.Latch]> }
-   * })
-   * ```
+   * Represents the state tracked by a `TestClock`, including the current
+   * millisecond timestamp and the sleeps scheduled to resume when the clock
+   * reaches their target time.
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface State {
     readonly timestamp: number
@@ -190,7 +213,8 @@ const SleepOrder = Order.flip(Order.Struct({
 /**
  * Creates a `TestClock` with optional configuration.
  *
- * @example
+ * **Example** (Creating a test clock)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -211,8 +235,8 @@ const SleepOrder = Order.flip(Order.Struct({
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*(
   options?: TestClock.Options
@@ -345,7 +369,8 @@ export const make = Effect.fnUntraced(function*(
 /**
  * Creates a `Layer` which constructs a `TestClock`.
  *
- * @example
+ * **Example** (Providing a test clock layer)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -364,8 +389,8 @@ export const make = Effect.fnUntraced(function*(
  * }).pipe(Effect.provide(testClockLayer))
  * ```
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer: (options?: TestClock.Options) => Layer.Layer<TestClock> = flow(
   make,
@@ -376,7 +401,8 @@ export const layer: (options?: TestClock.Options) => Layer.Layer<TestClock> = fl
  * Retrieves the `TestClock` service for this test and uses it to run the
  * specified workflow.
  *
- * @example
+ * **Example** (Accessing the test clock)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -394,8 +420,8 @@ export const layer: (options?: TestClock.Options) => Layer.Layer<TestClock> = fl
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const testClockWith = <A, E, R>(
   f: (testClock: TestClock) => Effect.Effect<A, E, R>
@@ -406,7 +432,8 @@ export const testClockWith = <A, E, R>(
  * by the specified duration, running any actions scheduled for on or before
  * the new time in order.
  *
- * @example
+ * **Example** (Advancing the test clock)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -428,8 +455,8 @@ export const testClockWith = <A, E, R>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const adjust = (duration: Duration.Input): Effect.Effect<void> =>
   testClockWith((testClock) => testClock.adjust(duration))
@@ -438,7 +465,8 @@ export const adjust = (duration: Duration.Input): Effect.Effect<void> =>
  * Sets the current clock time to the specified `timestamp`. Any effects that
  * were scheduled to occur on or before the new time will be run in order.
  *
- * @example
+ * **Example** (Setting the test clock time)
+ *
  * ```ts
  * import { Duration, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -461,8 +489,8 @@ export const adjust = (duration: Duration.Input): Effect.Effect<void> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const setTime = (timestamp: number): Effect.Effect<void> =>
   testClockWith((testClock) => testClock.setTime(timestamp))
@@ -471,7 +499,8 @@ export const setTime = (timestamp: number): Effect.Effect<void> =>
  * Executes the specified effect with the live `Clock` instead of the
  * `TestClock`.
  *
- * @example
+ * **Example** (Running with the live clock)
+ *
  * ```ts
  * import { Clock, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -494,8 +523,8 @@ export const setTime = (timestamp: number): Effect.Effect<void> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const withLive = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
   testClockWith((testClock) => testClock.withLive(effect))

package/src/testing/TestConsole.ts

@@ -1,4 +1,14 @@
 /**
+ * The `TestConsole` module provides a test implementation of the `Console`
+ * service that records console calls instead of writing them to the host
+ * environment. It is useful when testing workflows that use `Console.log` or
+ * `Console.error` and need to assert on the produced output.
+ *
+ * Use {@link layer} to provide the test console to an effect, then inspect
+ * captured output with {@link logLines} and {@link errorLines}. Because console
+ * operations are service-based effects, programs under test must be run with
+ * this layer for their output to be captured.
+ *
  * @since 4.0.0
  */
 import * as Array from "../Array.ts"
@@ -14,7 +24,8 @@ import * as Layer from "../Layer.ts"
  * This interface extends the standard Console interface and adds methods to
  * retrieve logged messages for verification in tests.
  *
- * @example
+ * **Example** (Capturing console output in tests)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import * as TestConsole from "effect/testing/TestConsole"
@@ -31,8 +42,8 @@ import * as Layer from "../Layer.ts"
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TestConsole extends Console.Console {
   /**
@@ -51,30 +62,26 @@ export interface TestConsole extends Console.Console {
  * The `TestConsole` namespace provides types and utilities for working with
  * test console implementations.
  *
- * @example
- * ```ts
- * // The TestConsole namespace provides types for testing
- * // Use TestConsole.make to create a test console instance
- * // Use TestConsole.layer to provide the service in tests
- * ```
- *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare namespace TestConsole {
   /**
    * Represents a console method name that can be invoked on the TestConsole.
    * This type includes all methods available on the Console interface.
    *
-   * @example
+   * **Example** (Typing captured console methods)
+   *
    * ```ts
-   * // Method represents console method names like:
-   * // "log", "error", "warn", "debug", "info", etc.
-   * // All methods from the Console interface are supported
+   * import type * as TestConsole from "effect/testing/TestConsole"
+   *
+   * const method: TestConsole.TestConsole.Method = "log"
+   *
+   * console.log(method) // "log"
    * ```
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export type Method = keyof Console.Console
 
@@ -82,15 +89,22 @@ export declare namespace TestConsole {
    * Represents a single console method invocation captured by the TestConsole.
    * Each entry contains the method name and the parameters passed to it.
    *
-   * @example
+   * **Example** (Typing captured console entries)
+   *
    * ```ts
-   * // Entry represents captured console calls with their method and parameters
-   * // Each entry contains: { method: string, parameters: ReadonlyArray<unknown> }
-   * // Used internally by TestConsole to track all console operations
+   * import type * as TestConsole from "effect/testing/TestConsole"
+   *
+   * const entry: TestConsole.TestConsole.Entry = {
+   *   method: "error",
+   *   parameters: ["not found"]
+   * }
+   *
+   * console.log(entry.method) // "error"
+   * console.log(entry.parameters) // ["not found"]
    * ```
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Entry {
     readonly method: Method
@@ -103,7 +117,8 @@ export declare namespace TestConsole {
  * The returned TestConsole implements the Console interface and provides
  * additional methods to retrieve logged messages.
  *
- * @example
+ * **Example** (Creating a test console)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import * as TestConsole from "effect/testing/TestConsole"
@@ -120,8 +135,8 @@ export declare namespace TestConsole {
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.gen(function*() {
   const entries: Array<TestConsole.Entry> = []
@@ -167,7 +182,8 @@ export const make = Effect.gen(function*() {
  * Retrieves the `TestConsole` service for this test and uses it to run the
  * specified workflow.
  *
- * @example
+ * **Example** (Accessing the test console service)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as TestConsole from "effect/testing/TestConsole"
@@ -186,8 +202,8 @@ export const make = Effect.gen(function*() {
  * ).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const testConsoleWith = <A, E, R>(f: (console: TestConsole) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
   Console.consoleWith((console) => f(console as TestConsole))
@@ -197,7 +213,8 @@ export const testConsoleWith = <A, E, R>(f: (console: TestConsole) => Effect.Eff
  * This layer can be used to provide a TestConsole implementation
  * for testing purposes.
  *
- * @example
+ * **Example** (Providing a test console layer)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import * as TestConsole from "effect/testing/TestConsole"
@@ -214,8 +231,8 @@ export const testConsoleWith = <A, E, R>(f: (console: TestConsole) => Effect.Eff
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<TestConsole> = Layer.effect(Console.Console)(make) as any
 
@@ -223,7 +240,8 @@ export const layer: Layer.Layer<TestConsole> = Layer.effect(Console.Console)(mak
  * Returns an array of all items that have been logged by the program using
  * `Console.log` thus far.
  *
- * @example
+ * **Example** (Reading captured log lines)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import * as TestConsole from "effect/testing/TestConsole"
@@ -244,8 +262,8 @@ export const layer: Layer.Layer<TestConsole> = Layer.effect(Console.Console)(mak
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = testConsoleWith(
   (console) => console.logLines
@@ -255,7 +273,8 @@ export const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = tes
  * Returns an array of all items that have been logged by the program using
  * `Console.error` thus far.
  *
- * @example
+ * **Example** (Reading captured error lines)
+ *
  * ```ts
  * import { Console, Effect } from "effect"
  * import * as TestConsole from "effect/testing/TestConsole"
@@ -274,8 +293,8 @@ export const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = tes
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const errorLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = testConsoleWith(
   (console) => console.errorLines

package/src/testing/TestSchema.ts

@@ -172,7 +172,7 @@ export class Asserts<S extends Schema.Top> {
     async function succeed(input: S["~type.make.in"], expected?: S["Type"]) {
       const r = await Effect.runPromise(
         makeEffect(input, options).pipe(
-          Effect.mapError((issue) => issue.toString()),
+          Effect.mapErrorEager((issue) => issue.toString()),
           Effect.result
         )
       )
@@ -184,7 +184,7 @@ export class Asserts<S extends Schema.Top> {
       async fail(input: unknown, message: string) {
         const r = await Effect.runPromise(
           makeEffect(input, options).pipe(
-            Effect.mapError((issue) => issue.toString()),
+            Effect.mapErrorEager((issue) => issue.toString()),
             Effect.result
           )
         )
@@ -221,8 +221,8 @@ export class Asserts<S extends Schema.Top> {
       FastCheck.asyncProperty(arbitrary, async (t) => {
         const r = await Effect.runPromise(
           encodeEffect(t).pipe(
-            Effect.flatMap((e) => decodeUnknownEffect(e)),
-            Effect.mapError((issue) => issue.toString()),
+            Effect.flatMapEager((e) => decodeUnknownEffect(e)),
+            Effect.mapErrorEager((issue) => issue.toString()),
             Effect.result
           )
         )
@@ -394,7 +394,7 @@ export class Decoding<S extends Schema.Top> {
   ) {
     const r = await Effect.runPromise(
       this.decodeUnknownEffect(input, this.options?.parseOptions).pipe(
-        Effect.mapError((issue) => issue.toString()),
+        Effect.mapErrorEager((issue) => issue.toString()),
         Effect.result
       )
     )
@@ -422,7 +422,7 @@ export class Decoding<S extends Schema.Top> {
   ) {
     const r = await Effect.runPromise(
       this.decodeUnknownEffect(input, this.options?.parseOptions).pipe(
-        Effect.mapError((issue) => issue.toString()),
+        Effect.mapErrorEager((issue) => issue.toString()),
         Effect.result
       )
     )
@@ -529,7 +529,7 @@ class Encoding<S extends Schema.Top> {
   ) {
     const r = await Effect.runPromise(
       this.encodeUnknownEffect(input, this.options?.parseOptions).pipe(
-        Effect.mapError((issue) => issue.toString()),
+        Effect.mapErrorEager((issue) => issue.toString()),
         Effect.result
       )
     )
@@ -557,7 +557,7 @@ class Encoding<S extends Schema.Top> {
   ) {
     const r = await Effect.runPromise(
       this.encodeUnknownEffect(input, this.options?.parseOptions).pipe(
-        Effect.mapError((issue) => issue.toString()),
+        Effect.mapErrorEager((issue) => issue.toString()),
         Effect.result
       )
     )