effect 4.0.0-beta.66 → 4.0.0-beta.68

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,9 +19,10 @@
  * 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"
+ * import { FastCheck } from "effect/testing"
  *
  * // Property: reverse of reverse should equal original
  * const reverseProp = FastCheck.property(
@@ -37,9 +38,10 @@
  * FastCheck.assert(reverseProp)
  * ```
  *
- * @example
+ * **Example** (Checking string concatenation properties)
+ *
  * ```ts
- * import * as FastCheck from "effect/testing/FastCheck"
+ * import { FastCheck } from "effect/testing"
  *
  * // Test string concatenation properties
  * const concatProp = FastCheck.property(
@@ -56,9 +58,10 @@
  * FastCheck.assert(concatProp)
  * ```
  *
- * @example
+ * **Example** (Generating record data for properties)
+ *
  * ```ts
- * import * as FastCheck from "effect/testing/FastCheck"
+ * import { FastCheck } from "effect/testing"
  *
  * // Generate random data for testing
  * const personArbitrary = FastCheck.record({

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,16 @@ export interface TestClock extends Clock.Clock {
  * })
  * ```
  *
- * @since 4.0.0
- * @category models
+ * @since 2.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 +167,8 @@ export declare namespace TestClock {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface Options {
     /**
@@ -145,24 +179,12 @@ export declare namespace TestClock {
   }
 
   /**
-   * @example
-   * ```ts
-   * import { Effect } from "effect"
-   * import { TestClock } from "effect/testing"
+   * 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.
    *
-   * 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]> }
-   * })
-   * ```
-   *
-   * @since 4.0.0
    * @category models
+   * @since 4.0.0
    */
   export interface State {
     readonly timestamp: number
@@ -190,7 +212,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 +234,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 +368,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 +388,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 +400,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 +419,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 +431,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 +454,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 +464,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 +488,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 +498,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 +522,8 @@ export const setTime = (timestamp: number): Effect.Effect<void> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 4.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,10 +24,11 @@ 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"
+ * import { TestConsole } from "effect/testing"
  *
  * const program = Effect.gen(function*() {
  *   yield* Console.log("Hello, World!")
@@ -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,25 @@ 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
  */
 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 { TestConsole } from "effect/testing"
+   *
+   * 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 +88,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 { TestConsole } from "effect/testing"
+   *
+   * 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,10 +116,11 @@ 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"
+ * import { TestConsole } from "effect/testing"
  *
  * const program = Effect.gen(function*() {
  *   yield* Console.log("Debug message")
@@ -120,8 +134,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,10 +181,11 @@ 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"
+ * import { TestConsole } from "effect/testing"
  *
  * const program = TestConsole.testConsoleWith((testConsole) =>
  *   Effect.gen(function*() {
@@ -186,8 +201,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,10 +212,11 @@ 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"
+ * import { TestConsole } from "effect/testing"
  *
  * const program = Effect.gen(function*() {
  *   yield* Console.log("This will be captured")
@@ -214,8 +230,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,10 +239,11 @@ 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"
+ * import { TestConsole } from "effect/testing"
  *
  * const program = Effect.gen(function*() {
  *   yield* Console.log("First message")
@@ -244,8 +261,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,10 +272,11 @@ 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"
+ * import { TestConsole } from "effect/testing"
  *
  * const program = Effect.gen(function*() {
  *   yield* Console.error("Error message")
@@ -274,8 +292,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

@@ -106,6 +106,7 @@ import * as FastCheck from "../testing/FastCheck.ts"
  * @see {@link Decoding}
  * @see {@link Encoding}
  *
+ * @category testing
  * @since 4.0.0
  */
 export class Asserts<S extends Schema.Top> {
@@ -172,7 +173,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 +185,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 +222,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
           )
         )
@@ -345,6 +346,7 @@ export class Asserts<S extends Schema.Top> {
  * @see {@link Asserts}
  * @see {@link Encoding}
  *
+ * @category testing
  * @since 4.0.0
  */
 export class Decoding<S extends Schema.Top> {
@@ -394,7 +396,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 +424,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 +531,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 +559,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
       )
     )

package/src/testing/index.ts

@@ -18,11 +18,45 @@
 export * as FastCheck from "./FastCheck.ts"
 
 /**
+ * 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
  */
 export * as TestClock from "./TestClock.ts"
 
 /**
+ * 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
  */
 export * as TestConsole from "./TestConsole.ts"