effect 4.0.5 → 4.0.6

package/dist/Stream.d.ts

@@ -1086,9 +1086,10 @@ export declare const fromPubSubTake: <A, E>(pubsub: PubSub.PubSub<Take.Take<A, E
  *
  * **Details**
  *
- * The stream reads from a `ReadableStreamDefaultReader`, maps read failures
- * with `onError`, and closes the reader when the stream finalizes. By default
- * the reader is canceled; set `releaseLockOnEnd` to release the lock instead.
+ * The stream reads from a `ReadableStreamDefaultReader` and maps read failures
+ * with `onError`. Finalization cancels the reader and releases its lock, or
+ * only releases the lock when `releaseLockOnEnd` is set. A rejected cancel
+ * hook becomes a defect.
  *
  * **Example** (Creating a stream from a ReadableStream)
  *
@@ -1235,6 +1236,11 @@ export interface EventListener<A = unknown> {
 /**
  * Creates a stream from an event listener.
  *
+ * **Gotchas**
+ *
+ * Event listeners cannot backpressure the source. When a bounded `bufferSize`
+ * is full, additional events are dropped rather than suspending the listener.
+ *
  * **Example** (Creating a stream from an event listener)
  *
  * ```ts import.meta.vitest
@@ -1593,6 +1599,11 @@ export declare const as: {
 /**
  * Maps both the failure and success channels of a stream.
  *
+ * **Details**
+ *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Mapping both the failure and success channels of a stream)
  *
  * ```ts import.meta.vitest
@@ -1629,6 +1640,11 @@ export declare const mapBoth: {
     /**
      * Maps both the failure and success channels of a stream.
      *
+     * **Details**
+     *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping both the failure and success channels of a stream)
      *
      * ```ts import.meta.vitest
@@ -1668,6 +1684,11 @@ export declare const mapBoth: {
     /**
      * Maps both the failure and success channels of a stream.
      *
+     * **Details**
+     *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping both the failure and success channels of a stream)
      *
      * ```ts import.meta.vitest
@@ -6333,6 +6354,12 @@ export declare const catchCause: {
  *
  * Typed failures and interruptions are not caught.
  *
+ * **Gotchas**
+ *
+ * `catchDefect` recovers any cause that contains a defect, including causes
+ * that also contain typed errors. Typed error handlers such as `catch` skip
+ * those causes, so defects always take precedence.
+ *
  * **Example** (Recovering from a defect)
  *
  * ```ts import.meta.vitest
@@ -6358,6 +6385,12 @@ export declare const catchDefect: {
      *
      * Typed failures and interruptions are not caught.
      *
+     * **Gotchas**
+     *
+     * `catchDefect` recovers any cause that contains a defect, including causes
+     * that also contain typed errors. Typed error handlers such as `catch` skip
+     * those causes, so defects always take precedence.
+     *
      * **Example** (Recovering from a defect)
      *
      * ```ts import.meta.vitest
@@ -6383,6 +6416,12 @@ export declare const catchDefect: {
      *
      * Typed failures and interruptions are not caught.
      *
+     * **Gotchas**
+     *
+     * `catchDefect` recovers any cause that contains a defect, including causes
+     * that also contain typed errors. Typed error handlers such as `catch` skip
+     * those causes, so defects always take precedence.
+     *
      * **Example** (Recovering from a defect)
      *
      * ```ts import.meta.vitest
@@ -6501,6 +6540,13 @@ export {
 /**
  * Switches over to the stream produced by the provided function if this one fails.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. If the cause also contains a
+ * defect, the handler does not run and the failure is propagated with every
+ * typed error converted to a defect. An interruption alongside a typed error
+ * does not prevent recovery.
+ *
  * **Example** (Catching stream failures)
  *
  * ```ts import.meta.vitest
@@ -6842,6 +6888,12 @@ export declare const tapDefect: {
  * stream. Non-matching failures propagate downstream, so the error type is
  * preserved unless the filter narrows it.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching matching failures)
  *
  * ```ts import.meta.vitest
@@ -6877,6 +6929,12 @@ export declare const catchIf: {
      * stream. Non-matching failures propagate downstream, so the error type is
      * preserved unless the filter narrows it.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching matching failures)
      *
      * ```ts import.meta.vitest
@@ -6912,6 +6970,12 @@ export declare const catchIf: {
      * stream. Non-matching failures propagate downstream, so the error type is
      * preserved unless the filter narrows it.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching matching failures)
      *
      * ```ts import.meta.vitest
@@ -6947,6 +7011,12 @@ export declare const catchIf: {
      * stream. Non-matching failures propagate downstream, so the error type is
      * preserved unless the filter narrows it.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching matching failures)
      *
      * ```ts import.meta.vitest
@@ -6972,7 +7042,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, refinement: Refinement<E, EB>, f: (e: EB) => Stream<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>;
+    <A, E, R, EB extends E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(self: Stream<A, E, R>, refinement: Refinement<NoInfer<E>, EB>, f: (e: EB) => Stream<A2, E2, R2>, orElse?: ((e: Exclude<E, EB>) => Stream<A3, E3, R3>) | undefined): Stream<A | A2 | Exclude<A3, unassigned>, E2 | E3 | (A3 extends unassigned ? Exclude<E, EB> : never), R | R2 | R3>;
     /**
      * Recovers from errors that match a predicate by switching to a recovery stream.
      *
@@ -6982,6 +7052,12 @@ export declare const catchIf: {
      * stream. Non-matching failures propagate downstream, so the error type is
      * preserved unless the filter narrows it.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching matching failures)
      *
      * ```ts import.meta.vitest
@@ -7023,6 +7099,12 @@ export declare const catchIf: {
  * Successful filter results are passed to `f`. Failed filter results go to
  * `orElse` when provided; otherwise the filter failure is re-failed.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * @see {@link catchIf} for predicate or refinement based recovery
  * @see {@link catchTag} for `_tag` based recovery from one tagged error
  * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
@@ -7047,6 +7129,12 @@ export declare const catchFilter: {
      * Successful filter results are passed to `f`. Failed filter results go to
      * `orElse` when provided; otherwise the filter failure is re-failed.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * @see {@link catchIf} for predicate or refinement based recovery
      * @see {@link catchTag} for `_tag` based recovery from one tagged error
      * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
@@ -7071,6 +7159,12 @@ export declare const catchFilter: {
      * Successful filter results are passed to `f`. Failed filter results go to
      * `orElse` when provided; otherwise the filter failure is re-failed.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * @see {@link catchIf} for predicate or refinement based recovery
      * @see {@link catchTag} for `_tag` based recovery from one tagged error
      * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
@@ -7091,6 +7185,12 @@ export declare const catchFilter: {
  * Use when you need to handle a specific error case from a stream whose error
  * type is a tagged union with a readonly `_tag` field.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching tagged failures)
  *
  * ```ts import.meta.vitest
@@ -7126,6 +7226,12 @@ export declare const catchTag: {
      * Use when you need to handle a specific error case from a stream whose error
      * type is a tagged union with a readonly `_tag` field.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching tagged failures)
      *
      * ```ts import.meta.vitest
@@ -7161,6 +7267,12 @@ export declare const catchTag: {
      * Use when you need to handle a specific error case from a stream whose error
      * type is a tagged union with a readonly `_tag` field.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching tagged failures)
      *
      * ```ts import.meta.vitest
@@ -7191,6 +7303,12 @@ export declare const catchTag: {
 /**
  * Switches to a recovery stream based on matching `_tag` handlers.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching tagged failures with handlers)
  *
  * ```ts import.meta.vitest
@@ -7230,6 +7348,12 @@ export declare const catchTags: {
     /**
      * Switches to a recovery stream based on matching `_tag` handlers.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching tagged failures with handlers)
      *
      * ```ts import.meta.vitest
@@ -7289,6 +7413,12 @@ export declare const catchTags: {
     /**
      * Switches to a recovery stream based on matching `_tag` handlers.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching tagged failures with handlers)
      *
      * ```ts import.meta.vitest
@@ -7358,6 +7488,12 @@ export declare const catchTags: {
  *
  * The handler receives the unwrapped reason.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching a tagged error reason)
  *
  * ```ts import.meta.vitest
@@ -7409,6 +7545,12 @@ export declare const catchReason: {
      *
      * The handler receives the unwrapped reason.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching a tagged error reason)
      *
      * ```ts import.meta.vitest
@@ -7460,6 +7602,12 @@ export declare const catchReason: {
      *
      * The handler receives the unwrapped reason.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching a tagged error reason)
      *
      * ```ts import.meta.vitest
@@ -7503,6 +7651,12 @@ export declare const catchReason: {
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching tagged error reasons)
  *
  * ```ts import.meta.vitest
@@ -7546,6 +7700,12 @@ export declare const catchReasons: {
     /**
      * Catches multiple reasons within a tagged error using an object of handlers.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching tagged error reasons)
      *
      * ```ts import.meta.vitest
@@ -7597,6 +7757,12 @@ export declare const catchReasons: {
     /**
      * Catches multiple reasons within a tagged error using an object of handlers.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Catching tagged error reasons)
      *
      * ```ts import.meta.vitest
@@ -7785,6 +7951,11 @@ export declare const unwrapReason: {
 /**
  * Transforms the errors emitted by this stream using `f`.
  *
+ * **Details**
+ *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Mapping stream errors)
  *
  * ```ts import.meta.vitest
@@ -7810,6 +7981,11 @@ export declare const mapError: {
     /**
      * Transforms the errors emitted by this stream using `f`.
      *
+     * **Details**
+     *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping stream errors)
      *
      * ```ts import.meta.vitest
@@ -7835,6 +8011,11 @@ export declare const mapError: {
     /**
      * Transforms the errors emitted by this stream using `f`.
      *
+     * **Details**
+     *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+     *
      * **Example** (Mapping stream errors)
      *
      * ```ts import.meta.vitest
@@ -8098,6 +8279,12 @@ export declare const orElseIfEmpty: {
 /**
  * Returns a stream that emits a fallback value when this stream fails.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Recovering with a fallback value)
  *
  * ```ts import.meta.vitest
@@ -8123,6 +8310,12 @@ export declare const orElseSucceed: {
     /**
      * Returns a stream that emits a fallback value when this stream fails.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Recovering with a fallback value)
      *
      * ```ts import.meta.vitest
@@ -8148,6 +8341,12 @@ export declare const orElseSucceed: {
     /**
      * Returns a stream that emits a fallback value when this stream fails.
      *
+     * **Gotchas**
+     *
+     * If the cause contains a defect, the handler is skipped and every typed error
+     * is converted to a defect, preserving reason order and interrupts. An
+     * interruption alongside a typed error does not prevent recovery.
+     *
      * **Example** (Recovering with a fallback value)
      *
      * ```ts import.meta.vitest
@@ -8209,6 +8408,13 @@ export declare const orDie: <A, E, R>(self: Stream<A, E, R>) => Stream<A, never,
  * The `log` option controls whether the failure is logged before the stream
  * terminates.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. If the cause also contains a
+ * defect, the failure is not ignored and is propagated with every typed error
+ * converted to a defect. An interruption alongside a typed error does not
+ * prevent the error from being ignored.
+ *
  * **Example** (Ignoring stream failures)
  *
  * ```ts import.meta.vitest
@@ -8298,6 +8504,12 @@ export declare const ignoreCause: <Arg extends Stream<any, any, any> | {
  * The schedule is reset as soon as the first element passes through the
  * stream again.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. A failure whose cause contains a
+ * defect is not retried and is propagated with every typed error converted to a
+ * defect. A typed error alongside an interruption is retried.
+ *
  * **Example** (Retrying stream failures)
  *
  * ```ts import.meta.vitest
@@ -8333,6 +8545,12 @@ export declare const retry: {
      * The schedule is reset as soon as the first element passes through the
      * stream again.
      *
+     * **Gotchas**
+     *
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
+     *
      * **Example** (Retrying stream failures)
      *
      * ```ts import.meta.vitest
@@ -8368,6 +8586,12 @@ export declare const retry: {
      * The schedule is reset as soon as the first element passes through the
      * stream again.
      *
+     * **Gotchas**
+     *
+     * Defects take precedence over typed errors. A failure whose cause contains a
+     * defect is not retried and is propagated with every typed error converted to a
+     * defect. A typed error alongside an interruption is retried.
+     *
      * **Example** (Retrying stream failures)
      *
      * ```ts import.meta.vitest
@@ -14371,7 +14595,8 @@ export declare const ensuring: {
 /**
  * Provides a layer or context to the stream, removing the corresponding
  * service requirements. Use `options.local` to build the layer every time; by
- * default, layers are shared between provide calls.
+ * default, a layer already built by an enclosing provide or runtime is reused;
+ * sibling provide calls build their own copies.
  *
  * **Example** (Providing stream requirements)
  *
@@ -14402,7 +14627,8 @@ export declare const provide: {
     /**
      * Provides a layer or context to the stream, removing the corresponding
      * service requirements. Use `options.local` to build the layer every time; by
-     * default, layers are shared between provide calls.
+     * default, a layer already built by an enclosing provide or runtime is reused;
+     * sibling provide calls build their own copies.
      *
      * **Example** (Providing stream requirements)
      *
@@ -14435,7 +14661,8 @@ export declare const provide: {
     /**
      * Provides a layer or context to the stream, removing the corresponding
      * service requirements. Use `options.local` to build the layer every time; by
-     * default, layers are shared between provide calls.
+     * default, a layer already built by an enclosing provide or runtime is reused;
+     * sibling provide calls build their own copies.
      *
      * **Example** (Providing stream requirements)
      *
@@ -16068,7 +16295,7 @@ export declare const mkArrayBuffer: <E, R>(self: Stream<Uint8Array, E, R>) => Ef
  * @category destructors
  * @since 4.0.0
  */
-export declare const mkUint8Array: <E, R>(self: Stream<Uint8Array, E, R>) => Effect.Effect<Uint8Array, E, R>;
+export declare const mkUint8Array: <E, R>(self: Stream<Uint8Array, E, R>) => Effect.Effect<Uint8Array<ArrayBuffer>, E, R>;
 /**
  * Converts the stream to a `ReadableStream` using the provided services.
  *