effect 4.0.5 → 4.0.7

package/dist/Bytes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Joins and compares byte sequences stored in `Uint8Array` values.
+ *
+ * Byte-to-text conversions live in `TextEncoder` / `TextDecoder`, and hex or
+ * base64 conversions live in the `Encoding` modules.
+ *
+ * @stability unstable
+ * @since 4.0.6
+ */
+import * as Equ from "./Equivalence.ts";
+import * as order from "./Order.ts";
+/**
+ * Joins byte chunks into one new `Uint8Array`.
+ *
+ * **When to use**
+ *
+ * Use to combine frames, headers, or streamed chunks into a single buffer.
+ *
+ * **Gotchas**
+ *
+ * The result is always a new array, even when there is zero or one chunk, so
+ * it never aliases an input.
+ *
+ * **Example** (Joining byte chunks)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * const bytes = Bytes.concat([new Uint8Array([1, 2]), new Uint8Array([3])])
+ * Array.from(bytes) // => [1, 2, 3]
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.0.6
+ */
+export declare const concat: (chunks: ReadonlyArray<Uint8Array>) => Uint8Array<ArrayBuffer>;
+/**
+ * Compares byte sequences for equality, byte by byte.
+ *
+ * **Gotchas**
+ *
+ * This returns as soon as a byte differs, so it is not constant-time. Do not
+ * use it to compare secrets.
+ *
+ * **Example** (Comparing byte sequences)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * Bytes.Equivalence(new Uint8Array([1, 2]), new Uint8Array([1, 2])) // => true
+ * Bytes.Equivalence(new Uint8Array([1, 2]), new Uint8Array([1])) // => false
+ * ```
+ *
+ * @stability unstable
+ * @category instances
+ * @since 4.0.6
+ */
+export declare const Equivalence: Equ.Equivalence<Uint8Array>;
+/**
+ * Orders byte sequences lexicographically by unsigned byte value, placing a
+ * prefix before any longer sequence that starts with it.
+ *
+ * **Example** (Sorting byte sequences)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * Bytes.Order(new Uint8Array([1, 2]), new Uint8Array([1, 3])) // => -1
+ * Bytes.Order(new Uint8Array([2]), new Uint8Array([1, 9])) // => 1
+ * Bytes.Order(new Uint8Array([1]), new Uint8Array([1, 0])) // => -1
+ * ```
+ *
+ * @stability unstable
+ * @category instances
+ * @since 4.0.6
+ */
+export declare const Order: order.Order<Uint8Array>;
+//# sourceMappingURL=Bytes.d.ts.map

package/dist/Bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Bytes.d.ts","sourceRoot":"","sources":["../src/Bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,MAAM,WAAY,aAAa,CAAC,UAAU,CAAC,KAAG,UAAU,CAAC,WAAW,CAYhF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,UAAU,CAUlD,CAAA;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAQxC,CAAA"}

package/dist/Bytes.js

@@ -0,0 +1,109 @@
+/**
+ * Joins and compares byte sequences stored in `Uint8Array` values.
+ *
+ * Byte-to-text conversions live in `TextEncoder` / `TextDecoder`, and hex or
+ * base64 conversions live in the `Encoding` modules.
+ *
+ * @stability unstable
+ * @since 4.0.6
+ */
+import * as Equ from "./Equivalence.js";
+import * as order from "./Order.js";
+/**
+ * Joins byte chunks into one new `Uint8Array`.
+ *
+ * **When to use**
+ *
+ * Use to combine frames, headers, or streamed chunks into a single buffer.
+ *
+ * **Gotchas**
+ *
+ * The result is always a new array, even when there is zero or one chunk, so
+ * it never aliases an input.
+ *
+ * **Example** (Joining byte chunks)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * const bytes = Bytes.concat([new Uint8Array([1, 2]), new Uint8Array([3])])
+ * Array.from(bytes) // => [1, 2, 3]
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.0.6
+ */
+export const concat = chunks => {
+  let length = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    length += chunks[i].length;
+  }
+  const out = new Uint8Array(length);
+  let offset = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    out.set(chunks[i], offset);
+    offset += chunks[i].length;
+  }
+  return out;
+};
+/**
+ * Compares byte sequences for equality, byte by byte.
+ *
+ * **Gotchas**
+ *
+ * This returns as soon as a byte differs, so it is not constant-time. Do not
+ * use it to compare secrets.
+ *
+ * **Example** (Comparing byte sequences)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * Bytes.Equivalence(new Uint8Array([1, 2]), new Uint8Array([1, 2])) // => true
+ * Bytes.Equivalence(new Uint8Array([1, 2]), new Uint8Array([1])) // => false
+ * ```
+ *
+ * @stability unstable
+ * @category instances
+ * @since 4.0.6
+ */
+export const Equivalence = /*#__PURE__*/Equ.make((self, that) => {
+  if (self.length !== that.length) {
+    return false;
+  }
+  for (let i = 0; i < self.length; i++) {
+    if (self[i] !== that[i]) {
+      return false;
+    }
+  }
+  return true;
+});
+/**
+ * Orders byte sequences lexicographically by unsigned byte value, placing a
+ * prefix before any longer sequence that starts with it.
+ *
+ * **Example** (Sorting byte sequences)
+ *
+ * ```ts import.meta.vitest
+ * import { Bytes } from "effect"
+ *
+ * Bytes.Order(new Uint8Array([1, 2]), new Uint8Array([1, 3])) // => -1
+ * Bytes.Order(new Uint8Array([2]), new Uint8Array([1, 9])) // => 1
+ * Bytes.Order(new Uint8Array([1]), new Uint8Array([1, 0])) // => -1
+ * ```
+ *
+ * @stability unstable
+ * @category instances
+ * @since 4.0.6
+ */
+export const Order = /*#__PURE__*/order.make((self, that) => {
+  const length = Math.min(self.length, that.length);
+  for (let i = 0; i < length; i++) {
+    if (self[i] !== that[i]) {
+      return self[i] < that[i] ? -1 : 1;
+    }
+  }
+  return self.length < that.length ? -1 : self.length > that.length ? 1 : 0;
+});
+//# sourceMappingURL=Bytes.js.map

package/dist/Bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Bytes.js","names":[],"sources":["../src/Bytes.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;AASA,OAAO,KAAK,GAAG,MAAM,kBAAkB;AACvC,OAAO,KAAK,KAAK,MAAM,YAAY;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAM,MAAM,GAAI,MAAiC,IAA6B;EACnF,IAAI,MAAM,GAAG,CAAC;EACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;IACtC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM;EAC5B;EACA,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC;EAClC,IAAI,MAAM,GAAG,CAAC;EACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;IACtC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM;EAC5B;EACA,OAAO,GAAG;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAM,WAAW,gBAAgC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,KAAI;EAC9E,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE;IAC/B,OAAO,KAAK;EACd;EACA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;IACpC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE;MACvB,OAAO,KAAK;IACd;EACF;EACA,OAAO,IAAI;AACb,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAM,KAAK,gBAA4B,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,KAAI;EACtE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;EACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE;IAC/B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE;MACvB,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;IACnC;EACF;EACA,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC;AAC3E,CAAC,CAAC","ignoreList":[]}

package/dist/Channel.d.ts

@@ -1426,6 +1426,12 @@ export declare const fromSchedule: <O, E, R>(schedule: Schedule.Schedule<O, unkn
 /**
  * Creates a channel from a lazily supplied Web `ReadableStream`.
  *
+ * **Details**
+ *
+ * Read failures are mapped 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** (Reading from a Web stream)
  *
  * ```ts import.meta.vitest
@@ -3808,6 +3814,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
@@ -3832,6 +3844,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
@@ -3856,6 +3874,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
@@ -4086,6 +4110,13 @@ export {
 /**
  * Recovers from typed channel errors by running a fallback channel.
  *
+ * **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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -4148,6 +4179,12 @@ export declare const tapError: {
  * are handled by `orElse` when provided. Without `orElse`, non-matching errors
  * are 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 catch_ catch} for recovering from every typed channel error
  * @see {@link catchFilter} for selecting typed errors with a `Filter`
  * @see {@link catchTag} for selecting tagged typed errors
@@ -4172,6 +4209,12 @@ export declare const catchIf: {
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are 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 catch_ catch} for recovering from every typed channel error
      * @see {@link catchFilter} for selecting typed errors with a `Filter`
      * @see {@link catchTag} for selecting tagged typed errors
@@ -4181,7 +4224,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <OutErr, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Exclude<OutErr, EB> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutErr, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(refinement: Predicate.Refinement<NoInfer<OutErr>, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Exclude<OutErr, EB> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from typed channel errors that match a predicate or refinement.
      *
@@ -4196,6 +4239,12 @@ export declare const catchIf: {
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are 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 catch_ catch} for recovering from every typed channel error
      * @see {@link catchFilter} for selecting typed errors with a `Filter`
      * @see {@link catchTag} for selecting tagged typed errors
@@ -4220,6 +4269,12 @@ export declare const catchIf: {
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are 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 catch_ catch} for recovering from every typed channel error
      * @see {@link catchFilter} for selecting typed errors with a `Filter`
      * @see {@link catchTag} for selecting tagged typed errors
@@ -4229,7 +4284,7 @@ export declare const catchIf: {
      * @category error handling
      * @since 4.0.0
      */
-    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<OutErr, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Exclude<OutErr, EB> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
+    <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, EB extends OutErr, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1, OutElem2 = Types.unassigned, OutErr2 = never, OutDone2 = never, InElem2 = unknown, InErr2 = unknown, InDone2 = unknown, Env2 = never>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, refinement: Predicate.Refinement<NoInfer<OutErr>, EB>, f: (failure: EB) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>, orElse?: ((failure: Exclude<OutErr, EB>) => Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>) | undefined): Channel<OutElem | OutElem1 | Exclude<OutElem2, Types.unassigned>, OutErr1 | OutErr2 | (OutElem2 extends Types.unassigned ? Exclude<OutErr, EB> : never), OutDone | OutDone1 | OutDone2, InElem & InElem1 & InElem2, InErr & InErr1 & InErr2, InDone & InDone1 & InDone2, Env | Env1 | Env2>;
     /**
      * Recovers from typed channel errors that match a predicate or refinement.
      *
@@ -4244,6 +4299,12 @@ export declare const catchIf: {
      * are handled by `orElse` when provided. Without `orElse`, non-matching errors
      * are 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 catch_ catch} for recovering from every typed channel error
      * @see {@link catchFilter} for selecting typed errors with a `Filter`
      * @see {@link catchTag} for selecting tagged typed errors
@@ -4269,6 +4330,12 @@ export declare const catchIf: {
  * filter results are handled by `orElse` when provided. Without `orElse`,
  * failed filter results are 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 selecting typed errors with a predicate
  * @see {@link catchTag} for selecting tagged typed errors
  * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
@@ -4292,6 +4359,12 @@ export declare const catchFilter: {
      * filter results are handled by `orElse` when provided. Without `orElse`,
      * failed filter results are 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 selecting typed errors with a predicate
      * @see {@link catchTag} for selecting tagged typed errors
      * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
@@ -4315,6 +4388,12 @@ export declare const catchFilter: {
      * filter results are handled by `orElse` when provided. Without `orElse`,
      * failed filter results are 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 selecting typed errors with a predicate
      * @see {@link catchTag} for selecting tagged typed errors
      * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
@@ -4334,6 +4413,12 @@ export declare const catchFilter: {
  * errors are handled by `orElse` when provided. Without `orElse`,
  * non-matching errors are 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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -4348,6 +4433,12 @@ export declare const catchTag: {
      * errors are handled by `orElse` when provided. Without `orElse`,
      * non-matching errors are 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.
+     *
      * @stability stable
      * @category error handling
      * @since 4.0.0
@@ -4362,6 +4453,12 @@ export declare const catchTag: {
      * errors are handled by `orElse` when provided. Without `orElse`,
      * non-matching errors are 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.
+     *
      * @stability stable
      * @category error handling
      * @since 4.0.0
@@ -4371,6 +4468,12 @@ export declare const catchTag: {
 /**
  * Catches a specific reason within a tagged error.
  *
+ * **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 from nested reasons)
  *
  * ```ts import.meta.vitest
@@ -4407,6 +4510,12 @@ export declare const catchReason: {
     /**
      * Catches a specific reason within a tagged error.
      *
+     * **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 from nested reasons)
      *
      * ```ts import.meta.vitest
@@ -4443,6 +4552,12 @@ export declare const catchReason: {
     /**
      * Catches a specific reason within a tagged error.
      *
+     * **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 from nested reasons)
      *
      * ```ts import.meta.vitest
@@ -4480,6 +4595,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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -4488,6 +4609,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.
+     *
      * @stability stable
      * @category error handling
      * @since 4.0.0
@@ -4512,6 +4639,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.
+     *
      * @stability stable
      * @category error handling
      * @since 4.0.0
@@ -4632,9 +4765,12 @@ export declare const unwrapReason: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, K extends TagsWithReason<OutErr>>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, errorTag: K): Channel<OutElem, Types.ExcludeTag<OutErr, K> | Types.ReasonOf<Types.ExtractTag<OutErr, K>>, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Returns a new channel, which is the same as this one, except the failure
- * value of the returned channel is created by applying the specified function
- * to the failure value of this channel.
+ * Transforms the typed errors of a channel using the specified function.
+ *
+ * **Details**
+ *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
  *
  * @stability stable
  * @category error handling
@@ -4642,9 +4778,12 @@ export declare const unwrapReason: {
  */
 export declare const mapError: {
     /**
-     * Returns a new channel, which is the same as this one, except the failure
-     * value of the returned channel is created by applying the specified function
-     * to the failure value of this channel.
+     * Transforms the typed errors of a channel using the specified function.
+     *
+     * **Details**
+     *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
      *
      * @stability stable
      * @category error handling
@@ -4652,9 +4791,12 @@ export declare const mapError: {
      */
     <OutErr, OutErr2>(f: (err: OutErr) => OutErr2): <OutElem, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr2, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Returns a new channel, which is the same as this one, except the failure
-     * value of the returned channel is created by applying the specified function
-     * to the failure value of this channel.
+     * Transforms the typed errors of a channel using the specified function.
+     *
+     * **Details**
+     *
+     * Maps every typed error in the cause, preserving defects, interrupts and
+     * reason order. Unlike typed recovery, mapping does not convert errors to defects.
      *
      * @stability stable
      * @category error handling
@@ -4697,6 +4839,13 @@ export declare const orDie: <OutElem, OutErr, OutDone, InElem, InErr, InDone, En
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
+ * **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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -4739,6 +4888,12 @@ export declare const ignoreCause: <Arg extends Channel<any, any, any, any, any,
  * Returns a new channel that retries this channel according to the specified
  * schedule whenever it fails.
  *
+ * **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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -4748,6 +4903,12 @@ export declare const retry: {
      * Returns a new channel that retries this channel according to the specified
      * schedule whenever it fails.
      *
+     * **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.
+     *
      * @stability stable
      * @category error handling
      * @since 4.0.0
@@ -4757,6 +4918,12 @@ export declare const retry: {
      * Returns a new channel that retries this channel according to the specified
      * schedule whenever it fails.
      *
+     * **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.
+     *
      * @stability stable
      * @category error handling
      * @since 4.0.0
@@ -5190,8 +5357,9 @@ export declare const splitLines: <Err, Done>() => Channel<Arr.NonEmptyReadonlyAr
  * **Details**
  *
  * Input chunks are decoded with streaming enabled so multi-byte characters may
- * span `Uint8Array` boundaries. The optional `encoding` and `options` are
- * passed to `TextDecoder`.
+ * span `Uint8Array` boundaries. On normal completion, incomplete trailing
+ * characters become U+FFFD or, with `fatal: true`, a defect. The optional
+ * `encoding` and `options` are passed to `TextDecoder`.
  *
  * @stability stable
  * @category decoding