effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Unify.ts

@@ -20,6 +20,8 @@ import { identity } from "./Function.ts"
 /**
  * A unique symbol used to identify unification behavior in Effect types.
  *
+ * **Details**
+ *
  * This symbol is used internally by the Effect type system to enable automatic
  * unification of Effect types in unions and complex type operations.
  *
@@ -31,6 +33,8 @@ export declare const unifySymbol: unique symbol
 /**
  * The type of the unifySymbol.
  *
+ * **Details**
+ *
  * This type represents the unique symbol used for identifying unification
  * behavior in Effect types. It's typically used in type-level operations
  * to enable automatic type unification.
@@ -43,6 +47,8 @@ export type unifySymbol = typeof unifySymbol
 /**
  * A unique symbol used to identify the type information for unification.
  *
+ * **Details**
+ *
  * This symbol is used internally by the Effect type system to store type
  * information that can be used during type unification operations.
  *
@@ -54,6 +60,8 @@ export declare const typeSymbol: unique symbol
 /**
  * The type of the typeSymbol.
  *
+ * **Details**
+ *
  * This type represents the unique symbol used for storing type information
  * in types that support unification. It's used in type-level operations
  * to access and manipulate type information.
@@ -66,6 +74,8 @@ export type typeSymbol = typeof typeSymbol
 /**
  * A unique symbol used to specify types that should be ignored during unification.
  *
+ * **Details**
+ *
  * This symbol is used internally by the Effect type system to mark types
  * that should be excluded from the unification process, allowing for more
  * precise type handling in complex scenarios.
@@ -78,6 +88,8 @@ export declare const ignoreSymbol: unique symbol
 /**
  * The type of the ignoreSymbol.
  *
+ * **Details**
+ *
  * This type represents the unique symbol used for marking types that should
  * be ignored during unification operations. It's used in type-level operations
  * to exclude specific types from the unification process.
@@ -121,6 +133,8 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
 /**
  * Unifies types that implement the unification protocol.
  *
+ * **Details**
+ *
  * This type performs automatic type unification for types that contain
  * the unification symbols (`unifySymbol`, `typeSymbol`, `ignoreSymbol`).
  * It's primarily used internally by the Effect type system to handle
@@ -178,6 +192,8 @@ export type Unify<A> = Values<
 /**
  * Applies `Unify` to a value or function return type at compile time.
  *
+ * **Details**
+ *
  * This is an identity function at runtime. For functions, the returned function
  * has the same runtime behavior while its return type is normalized with the
  * Effect unification protocol.
@@ -214,6 +230,8 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **Details**
+   *
    * This is an identity function at runtime. For functions, the returned function
    * has the same runtime behavior while its return type is normalized with the
    * Effect unification protocol.
@@ -259,6 +277,8 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **Details**
+   *
    * This is an identity function at runtime. For functions, the returned function
    * has the same runtime behavior while its return type is normalized with the
    * Effect unification protocol.
@@ -303,6 +323,8 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **Details**
+   *
    * This is an identity function at runtime. For functions, the returned function
    * has the same runtime behavior while its return type is normalized with the
    * Effect unification protocol.
@@ -344,6 +366,8 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **Details**
+   *
    * This is an identity function at runtime. For functions, the returned function
    * has the same runtime behavior while its return type is normalized with the
    * Effect unification protocol.
@@ -384,6 +408,8 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **Details**
+   *
    * This is an identity function at runtime. For functions, the returned function
    * has the same runtime behavior while its return type is normalized with the
    * Effect unification protocol.
@@ -423,6 +449,8 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **Details**
+   *
    * This is an identity function at runtime. For functions, the returned function
    * has the same runtime behavior while its return type is normalized with the
    * Effect unification protocol.

package/src/Utils.ts

@@ -63,21 +63,20 @@ import type * as Types from "./Types.ts"
 /**
  * An `IterableIterator` that yields its wrapped value exactly once.
  *
- * When to use:
+ * **When to use**
  *
- * - Implement `[Symbol.iterator]()` on Effect-like types so they can be
- *   `yield*`-ed inside generator functions (e.g. `Effect.gen`, `Option.gen`).
- * - You almost never construct this directly — it is created internally by
- *   yieldable types.
+ * Implement `[Symbol.iterator]()` on Effect-like types so they can be
+ * `yield*`-ed inside generator functions, such as `Effect.gen` and
+ * `Option.gen`. You almost never construct this directly — it is created
+ * internally by yieldable types.
  *
- * Behavior:
+ * **Details**
  *
- * - The first call to `next()` returns `{ value: self, done: false }`.
- * - Every subsequent call returns `{ value: a, done: true }` where `a` is
- *   the argument passed to `next()`.
- * - `[Symbol.iterator]()` returns a **new** `SingleShotGen` wrapping the same
- *   value, so the outer type can be iterated multiple times.
- * - Does not mutate the wrapped value.
+ * The first call to `next()` returns `{ value: self, done: false }`. Every
+ * subsequent call returns `{ value: a, done: true }` where `a` is the argument
+ * passed to `next()`. `[Symbol.iterator]()` returns a **new** `SingleShotGen`
+ * wrapping the same value, so the outer type can be iterated multiple times.
+ * It does not mutate the wrapped value.
  *
  * **Example** (Yielding a wrapped value in a generator)
  *
@@ -96,7 +95,6 @@ import type * as Types from "./Types.ts"
  * ```
  *
  * @see {@link Gen} — the type-level signature that relies on `SingleShotGen`
- *
  * @category constructors
  * @since 2.0.0
  */
@@ -140,19 +138,18 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  * Type-level marker encoding the variance of a `TypeLambda`'s type
  * parameters.
  *
- * When to use:
+ * **When to use**
  *
- * - Define variance constraints for a higher-kinded type so that
- *   {@link Gen} can correctly infer `R`, `O`, and `E` from yielded values.
- * - You typically don't construct values of this type — it exists purely for
- *   type inference.
+ * Define variance constraints for a higher-kinded type so that {@link Gen}
+ * can correctly infer `R`, `O`, and `E` from yielded values. You typically
+ * don't construct values of this type — it exists purely for type inference.
  *
- * Behavior:
+ * **Details**
  *
- * - `F` is invariant (must match exactly).
- * - `R` is contravariant (input / environment position).
- * - `O` and `E` are covariant (output / error position).
- * - Pure type-level construct — no runtime representation.
+ * `F` is invariant and must match exactly. `R` is contravariant in the input
+ * or environment position. `O` and `E` are covariant in the output and error
+ * positions. This is a pure type-level construct with no runtime
+ * representation.
  *
  * **Example** (Declaring variance for a TypeLambda)
  *
@@ -168,7 +165,6 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  * ```
  *
  * @see {@link Gen} — uses `Variance` for type parameter inference
- *
  * @category models
  * @since 2.0.0
  */
@@ -183,19 +179,18 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  * Type-level signature for generator-based monadic composition over any
  * `TypeLambda`.
  *
- * When to use:
+ * **When to use**
  *
- * - Type the `gen` function of a module that supports generator syntax
- *   (e.g. `Option.gen`, `Result.gen`, `Effect.gen`).
- * - Accepts either `(body)` or `(self, body)` where `body` is a generator
- *   function. The `self` overload binds `this` inside the generator.
+ * Type the `gen` function of a module that supports generator syntax, such as
+ * `Option.gen`, `Result.gen`, and `Effect.gen`. It accepts either `(body)` or
+ * `(self, body)` where `body` is a generator function. The `self` overload
+ * binds `this` inside the generator.
  *
- * Behavior:
+ * **Details**
  *
- * - Pure type alias — no runtime behavior.
- * - Infers `R`, `O`, `E` from the yielded values via {@link Variance} or
- *   `Kind` constraints.
- * - The generator's return type `A` becomes the output's `A` parameter.
+ * This is a pure type alias with no runtime behavior. It infers `R`, `O`, and
+ * `E` from the yielded values via {@link Variance} or `Kind` constraints. The
+ * generator's return type `A` becomes the output's `A` parameter.
  *
  * **Example** (Typing a gen function for Option)
  *
@@ -207,7 +202,6 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  *
  * @see {@link Variance} — encodes the variance used for inference
  * @see {@link SingleShotGen} — the iterator protocol that makes yielding work
- *
  * @category models
  * @since 2.0.0
  */

package/src/index.ts

@@ -2595,17 +2595,28 @@ export * as Latch from "./Latch.ts"
  * application. Services can be injected into effects via
  * `Effect.provideService`. Effects can require services via `Effect.service`.
  *
- * Layer can be thought of as recipes for producing bundles of services, given
- * their dependencies (other services).
+ * A layer is a recipe for producing services from their dependencies:
  *
- * Construction of services can be effectful and utilize resources that must be
- * acquired and safely released when the services are done being utilized.
+ * - `ROut` is what the layer provides.
+ * - `E` is what can fail while building the layer.
+ * - `RIn` is what the layer needs in order to build.
  *
- * By default layers are shared, meaning that if the same layer is used twice
- * the layer will only be allocated a single time.
+ * Normal application code should ask for services. Layer code should create
+ * services. The application entry point should provide the final layer once.
+ * Keeping this boundary clear makes programs easier to reuse with production,
+ * test, or mock implementations.
+ *
+ * Construction of services can be effectful and can acquire resources that must
+ * be safely released when the services are no longer used. For example, a layer
+ * can open a database pool during acquisition and close it in a finalizer.
+ *
+ * Layers are lazy: they do not build anything until they are provided to a
+ * program or explicitly built. By default layers are shared, meaning that if the
+ * same layer value is used twice, it is allocated only once and both users share
+ * the same service instance.
  *
  * Because of their excellent composition properties, layers are the idiomatic
- * way in Effect-TS to create services that depend on other services.
+ * way in Effect to create services that depend on other services.
  *
  * @since 2.0.0
  */

package/src/testing/TestClock.ts

@@ -38,19 +38,27 @@ import * as Order from "../Order.ts"
 import * as Semaphore from "../Semaphore.ts"
 
 /**
- * A `TestClock` simplifies deterministically and efficiently testing effects
- * which involve the passage of time.
+ * A `TestClock` simplifies deterministic and efficient testing of effects that
+ * involve the passage of time.
+ *
+ * **Details**
  *
  * Instead of waiting for actual time to pass, `sleep` and methods implemented
- * in terms of it schedule effects to take place at a given clock time. Users
- * can adjust the clock time using the `adjust` and `setTime` methods, and all
- * effects scheduled to take place on or before that time will automatically be
- * run in order.
+ * in terms of it schedule effects to take place at a given clock time. Use
+ * `adjust` and `setTime` to move clock time, and all effects scheduled to take
+ * place on or before that time will automatically run in order.
+ *
+ * **Gotchas**
  *
- * For example, here is how we can test `Effect.timeout` using `TestClock`:
+ * Calls to `sleep` and methods derived from it will semantically block until
+ * the time is set to on or after the time they are scheduled to run. Fork the
+ * effect being tested, then adjust the clock time, and finally verify that the
+ * expected effects have been performed.
  *
  * **Example** (Testing timeouts deterministically)
  *
+ * Tests `Effect.timeout` using `TestClock`.
+ *
  * ```ts
  * import { Effect, Fiber, Option, pipe } from "effect"
  * import { TestClock } from "effect/testing"
@@ -68,14 +76,6 @@ import * as Semaphore from "../Semaphore.ts"
  * })
  * ```
  *
- * Note how we forked the fiber that `sleep` was invoked on. Calls to `sleep`
- * and methods derived from it will semantically block until the time is set to
- * on or after the time they are scheduled to run. If we didn't fork the fiber
- * on which we called sleep we would never get to set the time on the line
- * below. Thus, a useful pattern when using `TestClock` is to fork the effect
- * being tested, then adjust the clock time, and finally verify that the
- * expected effects have been performed.
- *
  * **Example** (Advancing time deterministically)
  *
  * ```ts
@@ -330,7 +330,7 @@ export const make = Effect.fnUntraced(function*(
 
   const runSemaphore = yield* Semaphore.make(1)
   const run = Effect.fnUntraced(function*(step: (currentTimestamp: number) => number) {
-    yield* Fiber.await(yield* Effect.forkScoped(Effect.yieldNow))
+    yield* Fiber.await(yield* Effect.forkChild(Effect.yieldNow))
     const endTimestamp = step(currentTimestamp)
     while (Arr.isArrayNonEmpty(sleeps)) {
       if (Arr.lastNonEmpty(sleeps).timestamp > endTimestamp) break

package/src/testing/TestConsole.ts

@@ -21,6 +21,8 @@ import * as Layer from "../Layer.ts"
  * It captures all console output for testing purposes while maintaining full
  * compatibility with the standard Console API.
  *
+ * **Details**
+ *
  * This interface extends the standard Console interface and adds methods to
  * retrieve logged messages for verification in tests.
  *

package/src/testing/TestSchema.ts

@@ -78,14 +78,11 @@ import * as Parser from "../SchemaParser.ts"
 import * as FastCheck from "../testing/FastCheck.ts"
 
 /**
- * Entry point for schema test assertions. Wraps a schema and exposes
- * operation-specific helpers: {@link Decoding}, {@link Encoding}, make,
- * arbitrary generation, and round-trip verification.
+ * Entry point for schema test assertions. Wraps a schema and exposes operation-specific helpers for decoding, encoding, make, arbitrary generation, and round-trip verification.
  *
- * When to use:
- * - You are writing unit tests for a schema's decoding, encoding, or
- *   construction behavior.
- * - You want property-based round-trip or generation checks.
+ * **When to use**
+ *
+ * Use `Asserts` when writing schema unit tests for decoding, encoding, construction, property-based round-trip, or generation behavior.
  *
  * **Example** (Decoding and encoding a struct)
  *
@@ -105,19 +102,16 @@ 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> {
   /**
-   * Static helpers for comparing schema AST structures. Useful when you need
-   * to assert that two field or element definitions produce the same AST.
+   * Static helpers for comparing schema AST structures.
    *
-   * - `ast.fields.equals(a, b)` – compares struct field ASTs via
-   *   `assert.deepStrictEqual`.
-   * - `ast.elements.equals(a, b)` – compares tuple element ASTs via
-   *   `assert.deepStrictEqual`.
+   * **Details**
+   *
+   * `ast.fields.equals(a, b)` compares struct field ASTs via `assert.deepStrictEqual`. `ast.elements.equals(a, b)` compares tuple element ASTs via `assert.deepStrictEqual`.
    *
    * **Example** (Comparing struct fields)
    *
@@ -148,12 +142,11 @@ export class Asserts<S extends Schema.Top> {
     this.schema = schema
   }
   /**
-   * Returns an object with `succeed` and `fail` helpers for testing the
-   * schema's `make` operation.
+   * Returns an object with `succeed` and `fail` helpers for testing the schema's `make` operation.
+   *
+   * **Details**
    *
-   * - `succeed(input)` – asserts make returns the input unchanged.
-   * - `succeed(input, expected)` – asserts make returns `expected`.
-   * - `fail(input, message)` – asserts make fails with `message`.
+   * `succeed(input)` asserts make returns the input unchanged. `succeed(input, expected)` asserts make returns `expected`. `fail(input, message)` asserts make fails with `message`.
    *
    * **Example** (Testing make)
    *
@@ -194,13 +187,11 @@ export class Asserts<S extends Schema.Top> {
     }
   }
   /**
-   * Runs a property-based test that encodes arbitrary values and then decodes
-   * them, asserting the decoded value equals the original. Useful for verifying
-   * that a codec is lossless (encode followed by decode is identity).
+   * Runs a property-based test that encodes arbitrary values and then decodes them, asserting the decoded value equals the original.
+   *
+   * **Details**
    *
-   * - Uses FastCheck to generate arbitrary values matching the schema's Type.
-   * - Fails the test if any generated value does not round-trip.
-   * - Pass `options.params` to control FastCheck parameters (e.g. `numRuns`).
+   * FastCheck generates arbitrary values matching the schema's `Type`. The assertion fails if any generated value does not round-trip. Pass `options.params` to control FastCheck parameters such as `numRuns`.
    *
    * **Example** (Round-trip verification)
    *
@@ -233,10 +224,11 @@ export class Asserts<S extends Schema.Top> {
     )
   }
   /**
-   * Returns a {@link Decoding} instance for this schema, providing `succeed`
-   * and `fail` helpers to test decoding behavior.
+   * Returns a {@link Decoding} instance for this schema with helpers for decoding assertions.
    *
-   * - Pass `parseOptions` to control error reporting (e.g. `{ errors: "all" }`).
+   * **Details**
+   *
+   * Pass `parseOptions` to control error reporting, for example `{ errors: "all" }`.
    *
    * **Example** (Decoding assertions)
    *
@@ -258,10 +250,11 @@ export class Asserts<S extends Schema.Top> {
     return new Decoding(this.schema, options)
   }
   /**
-   * Returns an {@link Encoding} instance for this schema, providing `succeed`
-   * and `fail` helpers to test encoding behavior.
+   * Returns an {@link Encoding} instance for this schema with helpers for encoding assertions.
+   *
+   * **Details**
    *
-   * - Pass `parseOptions` to control error reporting (e.g. `{ errors: "all" }`).
+   * Pass `parseOptions` to control error reporting, for example `{ errors: "all" }`.
    *
    * **Example** (Encoding assertions)
    *
@@ -282,12 +275,11 @@ export class Asserts<S extends Schema.Top> {
     return new Encoding(this.schema, options)
   }
   /**
-   * Returns an object with property-based testing helpers for the schema's
-   * arbitrary generator.
+   * Returns an object with property-based testing helpers for the schema's arbitrary generator.
+   *
+   * **Details**
    *
-   * - `verifyGeneration()` – generates arbitrary values and asserts each
-   *   satisfies the schema's `is` predicate. Defaults to 20 runs.
-   * - Pass `options.params` to override FastCheck parameters.
+   * `verifyGeneration()` generates arbitrary values and asserts each value satisfies the schema's `is` predicate. It defaults to 20 runs. Pass `options.params` to override FastCheck parameters.
    *
    * **Example** (Verifying arbitrary generation)
    *
@@ -315,22 +307,15 @@ export class Asserts<S extends Schema.Top> {
 }
 
 /**
- * Decoding test helper. Wraps a schema and exposes `succeed` and `fail`
- * methods that run the schema's decoder and compare the result.
+ * Decoding test helper that wraps a schema and exposes `succeed` and `fail` methods that run the schema's decoder and compare the result.
  *
- * When to use:
- * - You want to assert that specific inputs decode to expected values.
- * - You want to assert that invalid inputs produce specific error messages.
- * - You need to provide services required by the schema's decoding pipeline.
+ * **When to use**
  *
- * Behavior:
- * - All assertions are async and use `assert.deepStrictEqual` internally.
- * - `succeed(input)` asserts the decoded output equals `input` (identity).
- * - `succeed(input, expected)` asserts the decoded output equals `expected`.
- * - `fail(input, message)` asserts decoding fails and the stringified issue
- *   equals `message`.
- * - `provide(key, impl)` returns a new `Decoding` with the service injected
- *   into the decoding context.
+ * Use `Decoding` when you want to assert that specific inputs decode to expected values, invalid inputs produce specific error messages, or schemas receive required decoding services.
+ *
+ * **Details**
+ *
+ * All assertions are async and use `assert.deepStrictEqual` internally. `succeed(input)` asserts the decoded output equals `input`; `succeed(input, expected)` asserts it equals `expected`; `fail(input, message)` asserts decoding fails and the stringified issue equals `message`. `provide(key, impl)` returns a new `Decoding` with the service injected into the decoding context.
  *
  * **Example** (Decoding with service provision)
  *
@@ -345,7 +330,6 @@ export class Asserts<S extends Schema.Top> {
  *
  * @see {@link Asserts}
  * @see {@link Encoding}
- *
  * @category testing
  * @since 4.0.0
  */
@@ -431,11 +415,15 @@ export class Decoding<S extends Schema.Top> {
     assert.deepStrictEqual(r, Result.fail(message))
   }
   /**
-   * Returns a new {@link Decoding} instance with the given service injected
-   * into the decoding effect context. Use this when the schema's decoder
-   * requires a service dependency.
+   * Returns a new {@link Decoding} instance with the given service injected into the decoding effect context.
    *
-   * - Does not mutate the current instance; returns a new one.
+   * **When to use**
+   *
+   * Use this when the schema's decoder requires a service dependency.
+   *
+   * **Details**
+   *
+   * This method does not mutate the current instance.
    *
    * @see {@link Encoding.provide}
    */