effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/internal/effect.ts

@@ -2643,28 +2643,40 @@ export const tapDefect: {
 
 /** @internal */
 export const catchIf: {
-  <E, EB extends E, A2, E2, R2, A3 = never, E3 = Exclude<E, EB>, R3 = never>(
+  <E, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     refinement: Predicate.Refinement<NoInfer<E>, EB>,
     f: (e: EB) => Effect.Effect<A2, E2, R2>,
     orElse?: ((e: Exclude<E, EB>) => Effect.Effect<A3, E3, R3>) | undefined
-  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
-  <E, A2, E2, R2, A3 = never, E3 = E, R3 = never>(
+  ): <A, R>(
+    self: Effect.Effect<A, E, R>
+  ) => Effect.Effect<
+    A | A2 | Exclude<A3, unassigned>,
+    E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never),
+    R | R2 | R3
+  >
+  <E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     predicate: Predicate.Predicate<NoInfer<E>>,
     f: (e: NoInfer<E>) => Effect.Effect<A2, E2, R2>,
     orElse?: ((e: NoInfer<E>) => Effect.Effect<A3, E3, R3>) | undefined
-  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
-  <A, E, R, EB extends E, A2, E2, R2, A3 = never, E3 = Exclude<E, EB>, R3 = never>(
+  ): <A, R>(
+    self: Effect.Effect<A, E, R>
+  ) => Effect.Effect<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? E : never), R | R2 | R3>
+  <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     self: Effect.Effect<A, E, R>,
     refinement: Predicate.Refinement<E, EB>,
     f: (e: EB) => Effect.Effect<A2, E2, R2>,
     orElse?: ((e: Exclude<E, EB>) => Effect.Effect<A3, E3, R3>) | undefined
-  ): Effect.Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
-  <A, E, R, A2, E2, R2, A3 = never, E3 = E, R3 = never>(
+  ): Effect.Effect<
+    A | A2 | Exclude<A3, unassigned>,
+    E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never),
+    R | R2 | R3
+  >
+  <A, E, R, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
     self: Effect.Effect<A, E, R>,
     predicate: Predicate.Predicate<E>,
     f: (e: E) => Effect.Effect<A2, E2, R2>,
     orElse?: ((e: E) => Effect.Effect<A3, E3, R3>) | undefined
-  ): Effect.Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
+  ): Effect.Effect<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? E : never), R | R2 | R3>
 } = dual(
   (args) => isEffect(args[0]),
   <A, E, R, A2, E2, R2, A3 = never, E3 = E, R3 = never>(
@@ -2685,17 +2697,19 @@ export const catchIf: {
 
 /** @internal */
 export const catchFilter: {
-  <E, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(
+  <E, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(
     filter: Filter.Filter<NoInfer<E>, EB, X>,
     f: (e: EB) => Effect.Effect<A2, E2, R2>,
     orElse?: ((e: X) => Effect.Effect<A3, E3, R3>) | undefined
-  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
-  <A, E, R, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(
+  ): <A, R>(
+    self: Effect.Effect<A, E, R>
+  ) => Effect.Effect<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? X : never), R | R2 | R3>
+  <A, E, R, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(
     self: Effect.Effect<A, E, R>,
     filter: Filter.Filter<NoInfer<E>, EB, X>,
     f: (e: EB) => Effect.Effect<A2, E2, R2>,
     orElse?: ((e: X) => Effect.Effect<A3, E3, R3>) | undefined
-  ): Effect.Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
+  ): Effect.Effect<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? X : never), R | R2 | R3>
 } = dual(
   (args) => isEffect(args[0]),
   <A, E, R, EB, A2, E2, R2, X, A3 = never, E3 = X, R3 = never>(
@@ -2723,8 +2737,8 @@ export const catchTag: {
     A1,
     E1,
     R1,
-    A2 = never,
-    E2 = ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     k: K,
@@ -2736,7 +2750,13 @@ export const catchTag: {
       | undefined
   ): <A, R>(
     self: Effect.Effect<A, E, R>
-  ) => Effect.Effect<A | A1 | A2, E1 | E2, R | R1 | R2>
+  ) => Effect.Effect<
+    A | A1 | Exclude<A2, unassigned>,
+    | E1
+    | E2
+    | (A2 extends unassigned ? ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never),
+    R | R1 | R2
+  >
   <
     A,
     E,
@@ -2745,8 +2765,8 @@ export const catchTag: {
     R1,
     E1,
     A1,
-    A2 = never,
-    E2 = ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     self: Effect.Effect<A, E, R>,
@@ -2755,7 +2775,13 @@ export const catchTag: {
     orElse?:
       | ((e: ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Effect.Effect<A2, E2, R2>)
       | undefined
-  ): Effect.Effect<A | A1 | A2, E1 | E2, R | R1 | R2>
+  ): Effect.Effect<
+    A | A1 | Exclude<A2, unassigned>,
+    | E1
+    | E2
+    | (A2 extends unassigned ? ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K> : never),
+    R | R1 | R2
+  >
 } = dual(
   (args) => isEffect(args[0]),
   <
@@ -2792,19 +2818,20 @@ export const catchTags: {
         [K in E["_tag"]]+?: (error: Extract<E, { _tag: K }>) => Effect.Effect<any, any, any>
       } :
       {}),
-    A2 = never,
-    E2 = Exclude<E, { _tag: keyof Cases }>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     cases: Cases,
     orElse?: ((e: Exclude<E, { _tag: keyof Cases }>) => Effect.Effect<A2, E2, R2>) | undefined
   ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<
     | A
-    | A2
+    | Exclude<A2, unassigned>
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Effect.Effect<infer A, any, any>) ? A : never
     }[keyof Cases],
     | E2
+    | (A2 extends unassigned ? Exclude<E, { _tag: keyof Cases }> : never)
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Effect.Effect<any, infer E, any>) ? E : never
     }[keyof Cases],
@@ -2822,8 +2849,8 @@ export const catchTags: {
         [K in E["_tag"]]+?: (error: Extract<E, { _tag: K }>) => Effect.Effect<any, any, any>
       } :
       {}),
-    A2 = never,
-    E2 = Exclude<E, { _tag: keyof Cases }>,
+    A2 = unassigned,
+    E2 = never,
     R2 = never
   >(
     self: Effect.Effect<A, E, R>,
@@ -2831,11 +2858,12 @@ export const catchTags: {
     orElse?: ((e: Exclude<E, { _tag: keyof Cases }>) => Effect.Effect<A2, E2, R2>) | undefined
   ): Effect.Effect<
     | A
-    | A2
+    | Exclude<A2, unassigned>
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Effect.Effect<infer A, any, any>) ? A : never
     }[keyof Cases],
     | E2
+    | (A2 extends unassigned ? Exclude<E, { _tag: keyof Cases }> : never)
     | {
       [K in keyof Cases]: Cases[K] extends ((...args: Array<any>) => Effect.Effect<any, infer E, any>) ? E : never
     }[keyof Cases],
@@ -2889,7 +2917,7 @@ export const catchReason: {
     self: Effect.Effect<A, E, R>
   ) => Effect.Effect<
     A | A2 | Exclude<A3, unassigned>,
-    (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3,
+    ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never),
     R | R2 | R3
   >
   <
@@ -2920,7 +2948,7 @@ export const catchReason: {
       | undefined
   ): Effect.Effect<
     A | A2 | Exclude<A3, unassigned>,
-    (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3,
+    ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never),
     R | R2 | R3
   >
 } = dual(
@@ -2950,7 +2978,7 @@ export const catchReason: {
       | undefined
   ): Effect.Effect<
     A | A2 | Exclude<A3, unassigned>,
-    (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3,
+    ExcludeTag<E, K> | E2 | E3 | (A3 extends unassigned ? ExtractTag<E, K> : never),
     R | R2 | R3
   > =>
     catchIf(
@@ -2993,8 +3021,9 @@ export const catchReasons: {
     | { [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Effect.Effect<infer A, any, any> ? A : never }[
       keyof Cases
     ],
-    | (A2 extends unassigned ? E : ExcludeTag<E, K>)
+    | ExcludeTag<E, K>
     | E2
+    | (A2 extends unassigned ? ExtractTag<E, K> : never)
     | { [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Effect.Effect<any, infer E, any> ? E : never }[
       keyof Cases
     ],
@@ -3034,8 +3063,9 @@ export const catchReasons: {
     | { [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Effect.Effect<infer A, any, any> ? A : never }[
       keyof Cases
     ],
-    | (A2 extends unassigned ? E : ExcludeTag<E, K>)
+    | ExcludeTag<E, K>
     | E2
+    | (A2 extends unassigned ? ExtractTag<E, K> : never)
     | { [RK in keyof Cases]: Cases[RK] extends (...args: Array<any>) => Effect.Effect<any, infer E, any> ? E : never }[
       keyof Cases
     ],

package/src/internal/request.ts

@@ -79,7 +79,7 @@ interface Batch {
 }
 
 const batchPool: Array<Batch> = []
-const pendingBatches = new Map<RequestResolver<any>, Map<unknown, Batch>>()
+const pendingBatches = new WeakMap<RequestResolver<any>, Map<unknown, Batch>>()
 
 const addEntry = <A extends Request.Any>(
   resolver: RequestResolver<A>,
@@ -150,6 +150,8 @@ const addEntry = <A extends Request.Any>(
               newBatch.entrySet.clear()
               newBatch.key = undefined
               newBatch.fiber = undefined
+              newBatch.resolver = undefined as any
+              newBatch.map = undefined as any
               batchPool.push(newBatch)
             }
             return effect.void

package/src/internal/schema/arbitrary.ts

@@ -122,6 +122,19 @@ function resetContext(ctx: Schema.Annotations.ToArbitrary.Context): Schema.Annot
   return { ...ctx, constraints: undefined }
 }
 
+function toIntegerConstraints(
+  constraint: Schema.Annotations.ToArbitrary.NumberConstraints
+): FastCheck.IntegerConstraints {
+  const out: FastCheck.IntegerConstraints = {}
+  if (constraint.min !== undefined) {
+    out.min = constraint.minExcluded ? Math.floor(constraint.min) + 1 : Math.ceil(constraint.min)
+  }
+  if (constraint.max !== undefined) {
+    out.max = constraint.maxExcluded ? Math.ceil(constraint.max) - 1 : Math.floor(constraint.max)
+  }
+  return out
+}
+
 interface LazyArbitraryWithContext<T> {
   (fc: typeof FastCheck, ctx: Schema.Annotations.ToArbitrary.Context): FastCheck.Arbitrary<T>
 }
@@ -199,7 +212,7 @@ function base(ast: AST.AST, path: ReadonlyArray<PropertyKey>): LazyArbitraryWith
       return (fc, ctx) => {
         const constraint = ctx.constraints?.number
         if (constraint?.isInteger) {
-          return fc.integer(constraint)
+          return fc.integer(toIntegerConstraints(constraint))
         }
         return fc.float(constraint)
       }

package/src/internal/schema/representation.ts

@@ -286,6 +286,19 @@ export const fromASTBlacklist: Set<string> = new Set([
   AST.ClassTypeId
 ])
 
+const standardJsonSchemaAnnotationKeys: ReadonlySet<string> = new Set([
+  "title",
+  "description",
+  "default",
+  "examples",
+  "readOnly",
+  "writeOnly",
+  "format",
+  "contentEncoding",
+  "contentMediaType",
+  "contentSchema"
+])
+
 function fromASTAnnotations(
   annotations: Schema.Annotations.Annotations | undefined
 ): { annotations: Schema.Annotations.Annotations } | undefined {
@@ -318,6 +331,7 @@ export function toJsonSchemaMultiDocument(
 ): JsonSchema.MultiDocument<"draft-2020-12"> {
   const generateDescriptions = options?.generateDescriptions ?? false
   const additionalProperties = options?.additionalProperties ?? false
+  const includeAnnotationKey = options?.includeAnnotationKey
 
   const definitions = Rec.map(multiDocument.references, (d) => recur(d))
 
@@ -569,21 +583,30 @@ export function toJsonSchemaMultiDocument(
   function collectJsonSchemaAnnotations(
     annotations: Schema.Annotations.Annotations | undefined
   ): JsonSchema.JsonSchema | undefined {
-    if (annotations) {
-      const out: JsonSchema.JsonSchema = {}
-      if (typeof annotations.title === "string") out.title = annotations.title
-      if (typeof annotations.description === "string") out.description = annotations.description
-      else if (generateDescriptions && typeof annotations.expected === "string") out.description = annotations.expected
-      if (annotations.default !== undefined) out.default = annotations.default
-      if (Array.isArray(annotations.examples)) out.examples = annotations.examples
-      if (typeof annotations.readOnly === "boolean") out.readOnly = annotations.readOnly
-      if (typeof annotations.writeOnly === "boolean") out.writeOnly = annotations.writeOnly
-      if (typeof annotations.format === "string") out.format = annotations.format
-      if (typeof annotations.contentEncoding === "string") out.contentEncoding = annotations.contentEncoding
-      if (typeof annotations.contentMediaType === "string") out.contentMediaType = annotations.contentMediaType
-
-      if (Object.keys(out).length > 0) return out
+    if (annotations === undefined) return undefined
+
+    const out: JsonSchema.JsonSchema = {}
+    if (typeof annotations.title === "string") out.title = annotations.title
+    if (typeof annotations.description === "string") out.description = annotations.description
+    else if (generateDescriptions && typeof annotations.expected === "string") out.description = annotations.expected
+    if (annotations.default !== undefined) out.default = annotations.default
+    if (Array.isArray(annotations.examples)) out.examples = annotations.examples
+    if (typeof annotations.readOnly === "boolean") out.readOnly = annotations.readOnly
+    if (typeof annotations.writeOnly === "boolean") out.writeOnly = annotations.writeOnly
+    if (typeof annotations.format === "string") out.format = annotations.format
+    if (typeof annotations.contentEncoding === "string") out.contentEncoding = annotations.contentEncoding
+    if (typeof annotations.contentMediaType === "string") out.contentMediaType = annotations.contentMediaType
+
+    if (includeAnnotationKey) {
+      for (const [key, value] of Object.entries(annotations)) {
+        if (value === undefined) continue
+        if (standardJsonSchemaAnnotationKeys.has(key)) continue
+        if (!includeAnnotationKey(key)) continue
+        out[key] = value
+      }
     }
+
+    if (Object.keys(out).length > 0) return out
   }
 
   function collectJsonSchemaChecks<M>(

package/src/testing/TestConsole.ts

@@ -1,13 +1,40 @@
 /**
- * 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.
+ * The `TestConsole` module provides a test implementation of the Effect
+ * `Console` service. When {@link layer} is provided, calls made through the
+ * Effect console APIs are captured in memory instead of being written to the
+ * host console, so tests can assert on logged values deterministically.
+ *
+ * This module is intentionally small: it gives tests a console layer, helpers
+ * for reading captured `Console.log` and `Console.error` arguments, and a way
+ * to access the provided test console service directly.
+ *
+ * **Mental model**
+ *
+ * - {@link layer} replaces the current `Console` service with a fresh
+ *   in-memory test console for the effect it is provided to
+ * - Code under test must call Effect's `Console` APIs; direct calls to
+ *   `globalThis.console` are outside the service and are not captured
+ * - {@link logLines} returns the values passed to `Console.log` in call order
+ * - {@link errorLines} returns the values passed to `Console.error` in call
+ *   order
+ * - {@link testConsoleWith} gives direct access to the current `TestConsole`
+ *   service when a test needs to inspect or call it manually
+ *
+ * **Common tasks**
+ *
+ * - Capture console output by providing {@link layer}
+ * - Assert on logged values with {@link logLines}
+ * - Assert on error output with {@link errorLines}
+ * - Construct a standalone test console service with {@link make}
+ * - Access the provided service with {@link testConsoleWith}
+ *
+ * **Gotchas**
+ *
+ * - Captured log and error values are the original arguments, not formatted
+ *   strings
+ * - `logLines` and `errorLines` expose `Console.log` and `Console.error`
+ *   output; other console methods are implemented for compatibility but do not
+ *   have dedicated accessor effects in this module
  *
  * @since 4.0.0
  */
@@ -21,6 +48,11 @@ import * as Layer from "../Layer.ts"
  * It captures all console output for testing purposes while maintaining full
  * compatibility with the standard Console API.
  *
+ * **When to use**
+ *
+ * Use to provide a console implementation that records calls for assertions in
+ * tests.
+ *
  * **Details**
  *
  * This interface extends the standard Console interface and adds methods to
@@ -44,6 +76,10 @@ import * as Layer from "../Layer.ts"
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link layer} for providing `TestConsole` to an effect
+ * @see {@link logLines} for reading captured `Console.log` calls
+ * @see {@link errorLines} for reading captured `Console.error` calls
+ *
  * @category models
  * @since 4.0.0
  */
@@ -51,11 +87,21 @@ export interface TestConsole extends Console.Console {
   /**
    * Returns an array of all items that have been logged by the program using
    * `Console.log` thus far.
+   *
+   * **When to use**
+   *
+   * Use to inspect captured `Console.log` calls through a `TestConsole`
+   * instance.
    */
   readonly logLines: Effect.Effect<ReadonlyArray<unknown>>
   /**
    * Returns an array of all items that have been logged by the program using
    * `Console.error` thus far.
+   *
+   * **When to use**
+   *
+   * Use to inspect captured `Console.error` calls through a `TestConsole`
+   * instance.
    */
   readonly errorLines: Effect.Effect<ReadonlyArray<unknown>>
 }
@@ -64,6 +110,10 @@ export interface TestConsole extends Console.Console {
  * The `TestConsole` namespace provides types and utilities for working with
  * test console implementations.
  *
+ * **When to use**
+ *
+ * Use when referring to types nested under the `TestConsole` namespace.
+ *
  * @since 4.0.0
  */
 export declare namespace TestConsole {
@@ -71,6 +121,11 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to type the console method name recorded in a captured test console
+   * entry.
+   *
    * **Example** (Typing captured console methods)
    *
    * ```ts
@@ -90,6 +145,10 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to inspect or type one captured console invocation.
+   *
    * **Example** (Typing captured console entries)
    *
    * ```ts
@@ -118,6 +177,10 @@ export declare namespace TestConsole {
  * The returned TestConsole implements the Console interface and provides
  * additional methods to retrieve logged messages.
  *
+ * **When to use**
+ *
+ * Use to construct a test console service value directly.
+ *
  * **Example** (Creating a test console)
  *
  * ```ts
@@ -136,6 +199,8 @@ export declare namespace TestConsole {
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link layer} for providing a `TestConsole` as a `Layer`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -183,6 +248,10 @@ export const make = Effect.gen(function*() {
  * Retrieves the `TestConsole` service for this test and uses it to run the
  * specified workflow.
  *
+ * **When to use**
+ *
+ * Use to access the provided test console service inside an effect.
+ *
  * **Example** (Accessing the test console service)
  *
  * ```ts
@@ -203,6 +272,10 @@ export const make = Effect.gen(function*() {
  * ).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link layer} for providing the test console service
+ * @see {@link logLines} for reading captured `Console.log` calls directly
+ * @see {@link errorLines} for reading captured `Console.error` calls directly
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -214,6 +287,10 @@ export const testConsoleWith = <A, E, R>(f: (console: TestConsole) => Effect.Eff
  * This layer can be used to provide a TestConsole implementation
  * for testing purposes.
  *
+ * **When to use**
+ *
+ * Use to run an effect with console calls captured by `TestConsole`.
+ *
  * **Example** (Providing a test console layer)
  *
  * ```ts
@@ -232,6 +309,9 @@ export const testConsoleWith = <A, E, R>(f: (console: TestConsole) => Effect.Eff
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link make} for constructing the service value directly
+ * @see {@link testConsoleWith} for accessing the provided test console service
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -241,6 +321,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.
  *
+ * **When to use**
+ *
+ * Use to assert on captured `Console.log` output from a program provided with
+ * `TestConsole.layer`.
+ *
  * **Example** (Reading captured log lines)
  *
  * ```ts
@@ -263,6 +348,9 @@ export const layer: Layer.Layer<TestConsole> = Layer.effect(Console.Console)(mak
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link errorLines} for reading captured `Console.error` output
+ * @see {@link layer} for capturing console calls during a test
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -274,6 +362,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.
  *
+ * **When to use**
+ *
+ * Use to assert on captured `Console.error` output from a program provided
+ * with `TestConsole.layer`.
+ *
  * **Example** (Reading captured error lines)
  *
  * ```ts
@@ -294,6 +387,9 @@ export const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = tes
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link logLines} for reading captured `Console.log` output
+ * @see {@link layer} for capturing console calls during a test
+ *
  * @category utils
  * @since 4.0.0
  */