@typed/fx 2.0.0-beta.3 → 2.0.0-beta.5

package/dist/Fx/combinators/catch.d.ts

@@ -3,9 +3,41 @@ import * as Cause from "effect/Cause";
 import type { ExcludeTag, ExtractTag, NoInfer, Tags } from "effect/Types";
 import type { Fx } from "../Fx.js";
 /**
- * Recovers from a typed failure of an Fx by switching to a fallback Fx.
+ * Recovers from the first typed failure of an Fx by running a fallback Fx.
  *
- * Mirrors `Effect.catch` / `Effect.catchAll` (catches `Cause.Fail` only).
+ * @remarks
+ * ## Why
+ *
+ * Typed failures are part of an Fx's public error channel, so callers often
+ * need to replace a failed producer based on its first typed failure. This is
+ * the push-stream counterpart of Effect's typed recovery.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source runs until it reports a Cause containing a `Fail`. The first typed
+ * failure starts exactly one fallback and the entire original Cause is replaced,
+ * including any defects or interrupts composed beside that Fail. A Cause with
+ * no Fail passes through unchanged. Source values already delivered remain
+ * delivered. The fallback's services become requirements of the returned Fx,
+ * and external interruption stops whichever run is active.
+ *
+ * @example
+ * ```ts
+ * import { catch as recover } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const resilient = recover(fail("offline"), (error) => succeed(error.length))
+ * ```
+ *
+ * @example Recovering a Fail discards its complete composite Cause
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catch as recover } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("socket defect"))
+ * const recovered = recover(failCause(composite), () => succeed("cached"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -16,7 +48,27 @@ export declare const catch_: {
 };
 export { catch_ as catch };
 /**
- * An alias for {@link catch}.
+ * Uses the Effect-style `catchAll` name for {@link catch}.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The alias lets Effect users apply the same typed-failure recovery vocabulary
+ * to Fx without introducing different runtime behavior.
+ *
+ * ## Ownership and lifetime
+ *
+ * It has exactly the source/fallback switching, failure, service, and
+ * interruption semantics of {@link catch}; it allocates no wrapper resource
+ * beyond that combinator.
+ *
+ * @example
+ * ```ts
+ * import { catchAll } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchAll(fail("missing"), () => succeed("default"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -26,10 +78,34 @@ export declare const catchAll: {
     <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, f: (e: E) => Fx<A2, E2, R2>): Fx<A | A2, E2, R | R2>;
 };
 /**
- * Recovers from *any* failure cause of an Fx (including defects and interrupts)
- * by switching to a fallback Fx.
+ * Recovers from any failure cause by running a fallback Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A full `Cause` retains typed failures, defects, interruption, and composed
+ * causes. Handling that structure explicitly is necessary at boundaries that
+ * must translate every termination mode rather than only expected errors.
  *
- * Mirrors `Effect.catchCause`.
+ * ## Ownership and lifetime
+ *
+ * The handler runs once after the source reports a cause and its returned Fx
+ * continues in the same subscription. It receives the cause unchanged. Values
+ * emitted before failure are not replayed, and the fallback's errors and
+ * services replace the recovered source error and join its requirements.
+ * Because interruption is catchable here, use this only when intentionally
+ * translating interruption rather than for ordinary typed recovery.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catchCause } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const reported = catchCause(failCause(Cause.die("boom")), (cause) =>
+ *   succeed(Cause.pretty(cause))
+ * )
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -39,9 +115,32 @@ export declare const catchCause: {
     <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, f: (cause: Cause.Cause<E>) => Fx<A2, E2, R2>): Fx<A | A2, E2, R | R2>;
 };
 /**
- * Recovers from a typed failure by matching on the `_tag` field of the error.
+ * Recovers selected tagged typed failures by running a fallback Fx.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchTag`.
+ * Tagged error unions are idiomatic Effect APIs. Selecting one or more tags
+ * narrows the handler input and removes only those variants from the returned
+ * error channel, preserving the rest for later composition.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source owns the subscription until its Cause contains a Fail whose tag
+ * matches. That first matching Fail starts one handler Fx and replaces the
+ * entire original Cause, including any defects or interrupts composed with it.
+ * A Cause with no Fail, or a first Fail with another tag, passes through intact.
+ * The fallback is lazy and contributes its errors and services to the result.
+ *
+ * @example
+ * ```ts
+ * import { catchTag } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * type Missing = { readonly _tag: "Missing"; readonly id: string }
+ * const source = fail<Missing>({ _tag: "Missing", id: "42" })
+ * const recovered = catchTag(source, "Missing", ({ id }) => succeed(`missing:${id}`))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -51,10 +150,30 @@ export declare const catchTag: {
     <A, E, R, const K extends Tags<E> | Arr.NonEmptyReadonlyArray<Tags<E>>, A2, E2, R2>(self: Fx<A, E, R>, k: K, f: (e: ExtractTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>) => Fx<A2, E2, R2>): Fx<A | A2, E2 | ExcludeTag<E, K extends Arr.NonEmptyReadonlyArray<string> ? K[number] : K>, R | R2>;
 };
 /**
- * Recovers from a typed failure when a predicate holds, by switching to a fallback Fx.
- * Only applies to `Cause.Fail`; defects and interrupts are not caught.
+ * Recovers a typed failure only when a predicate accepts it.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchIf`.
+ * Some typed errors are distinguished by values rather than tags. Predicate
+ * recovery handles that subset while retaining `E` in the result because a
+ * rejected error can still escape.
+ *
+ * ## Ownership and lifetime
+ *
+ * The predicate is evaluated on the first Fail found anywhere in the source
+ * Cause. A match starts one lazy fallback and replaces that entire Cause,
+ * including any defects or interrupts composed with the Fail. A rejection, or
+ * a Cause containing no Fail, forwards the original Cause unchanged. The
+ * fallback contributes its errors and services and shares the subscription.
+ *
+ * @example
+ * ```ts
+ * import { catchIf } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchIf(fail(404), (status) => status === 404, () => succeed("missing"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -64,10 +183,33 @@ export declare const catchIf: {
     <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, predicate: (e: E) => boolean, f: (e: E) => Fx<A2, E2, R2>): Fx<A | A2, E | E2, R | R2>;
 };
 /**
- * Recovers from a failure cause when a predicate on the cause holds,
- * by switching to a fallback Fx.
+ * Recovers a failure cause only when a predicate accepts the complete cause.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchCauseIf`.
+ * Cause-level predicates can distinguish defects, interruption, sequential or
+ * parallel cause structure that a typed-error predicate cannot observe.
+ *
+ * ## Ownership and lifetime
+ *
+ * The predicate receives the source cause unchanged. A match starts one lazy
+ * fallback in the same subscription; otherwise the original cause propagates.
+ * The fallback's requirements and errors are added, prior source values stay
+ * delivered, and interrupting the returned Fx interrupts its active run.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catchCauseIf } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchCauseIf(
+ *   failCause(Cause.die("bad decoder")),
+ *   Cause.hasDies,
+ *   () => succeed("reported")
+ * )
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -83,32 +225,63 @@ type TaggedCase<E> = {
         _tag: K;
     }>) => Fx<unknown, unknown, unknown>;
 };
+type CaseSuccess<T> = T extends (error: never) => Fx<infer A, infer _E, infer _R> ? A : never;
+type CaseError<T> = T extends (error: never) => Fx<infer _A, infer E, infer _R> ? E : never;
+type CaseServices<T> = T extends (error: never) => Fx<infer _A, infer _E, infer R> ? R : never;
 /**
- * Recovers from typed failures by matching on the `_tag` field with multiple handlers at once.
+ * Recovers several tagged typed-error variants with one handler table.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A handler table keeps multi-variant recovery exhaustive and preserves the
+ * precise success, error, and service unions produced by each selected case.
+ * Unlisted variants remain visible in the returned error channel.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first Fail found anywhere in the source Cause is inspected. A listed tag
+ * starts exactly one handler Fx and replaces the entire original Cause,
+ * including any defects or interrupts composed with that Fail. An untagged or
+ * unlisted first Fail, or a Cause with no Fail, propagates intact. Handlers are
+ * lazy and contribute their individual errors and service requirements.
+ *
+ * @example
+ * ```ts
+ * import { catchTags } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
  *
- * Mirrors `Effect.catchTags`.
+ * type Failure =
+ *   | { readonly _tag: "Missing"; readonly id: string }
+ *   | { readonly _tag: "Forbidden" }
+ * const source = fail<Failure>({ _tag: "Missing", id: "42" })
+ * const recovered = catchTags(source, {
+ *   Missing: ({ id }) => succeed(`missing:${id}`),
+ *   Forbidden: () => succeed("forbidden")
+ * })
+ * ```
  *
  * @since 1.0.0
  * @category combinators
  */
 export declare const catchTags: {
     <E, Cases extends TaggedCase<E>>(cases: Cases): <A, R>(self: Fx<A, E, R>) => Fx<A | {
-        [K in keyof Cases]: Cases[K] extends (e: unknown) => Fx<infer A2, unknown, unknown> ? A2 : never;
+        [K in keyof Cases]: CaseSuccess<Cases[K]>;
     }[keyof Cases], Exclude<E, {
         _tag: keyof Cases;
     }> | {
-        [K in keyof Cases]: Cases[K] extends (e: unknown) => Fx<unknown, infer E2, unknown> ? E2 : never;
+        [K in keyof Cases]: CaseError<Cases[K]>;
     }[keyof Cases], R | {
-        [K in keyof Cases]: Cases[K] extends (e: unknown) => Fx<unknown, unknown, infer R2> ? R2 : never;
+        [K in keyof Cases]: CaseServices<Cases[K]>;
     }[keyof Cases]>;
     <A, E, R, Cases extends TaggedCase<E>>(self: Fx<A, E, R>, cases: Cases): Fx<A | {
-        [K in keyof Cases]: Cases[K] extends (e: unknown) => Fx<infer A2, unknown, unknown> ? A2 : never;
+        [K in keyof Cases]: CaseSuccess<Cases[K]>;
     }[keyof Cases], Exclude<E, {
         _tag: keyof Cases;
     }> | {
-        [K in keyof Cases]: Cases[K] extends (e: unknown) => Fx<unknown, infer E2, unknown> ? E2 : never;
+        [K in keyof Cases]: CaseError<Cases[K]>;
     }[keyof Cases], R | {
-        [K in keyof Cases]: Cases[K] extends (e: unknown) => Fx<unknown, unknown, infer R2> ? R2 : never;
+        [K in keyof Cases]: CaseServices<Cases[K]>;
     }[keyof Cases]>;
 };
 //# sourceMappingURL=catch.d.ts.map

package/dist/Fx/combinators/catch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catch.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/catch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catch.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/catch.ts"],"names":[],"mappings":"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"}

package/dist/Fx/combinators/catch.js

@@ -15,9 +15,41 @@ const matchesTag = (tag, error) => {
     return tag.some((t) => t === error._tag);
 };
 /**
- * Recovers from a typed failure of an Fx by switching to a fallback Fx.
+ * Recovers from the first typed failure of an Fx by running a fallback Fx.
  *
- * Mirrors `Effect.catch` / `Effect.catchAll` (catches `Cause.Fail` only).
+ * @remarks
+ * ## Why
+ *
+ * Typed failures are part of an Fx's public error channel, so callers often
+ * need to replace a failed producer based on its first typed failure. This is
+ * the push-stream counterpart of Effect's typed recovery.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source runs until it reports a Cause containing a `Fail`. The first typed
+ * failure starts exactly one fallback and the entire original Cause is replaced,
+ * including any defects or interrupts composed beside that Fail. A Cause with
+ * no Fail passes through unchanged. Source values already delivered remain
+ * delivered. The fallback's services become requirements of the returned Fx,
+ * and external interruption stops whichever run is active.
+ *
+ * @example
+ * ```ts
+ * import { catch as recover } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const resilient = recover(fail("offline"), (error) => succeed(error.length))
+ * ```
+ *
+ * @example Recovering a Fail discards its complete composite Cause
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catch as recover } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("socket defect"))
+ * const recovered = recover(failCause(composite), () => succeed("cached"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -31,26 +63,93 @@ export const catch_ = dual(2, (self, f) => make((sink) => self.run(makeSink((cau
 }, sink.onSuccess))));
 export { catch_ as catch };
 /**
- * An alias for {@link catch}.
+ * Uses the Effect-style `catchAll` name for {@link catch}.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The alias lets Effect users apply the same typed-failure recovery vocabulary
+ * to Fx without introducing different runtime behavior.
+ *
+ * ## Ownership and lifetime
+ *
+ * It has exactly the source/fallback switching, failure, service, and
+ * interruption semantics of {@link catch}; it allocates no wrapper resource
+ * beyond that combinator.
+ *
+ * @example
+ * ```ts
+ * import { catchAll } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchAll(fail("missing"), () => succeed("default"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
  */
 export const catchAll = catch_;
 /**
- * Recovers from *any* failure cause of an Fx (including defects and interrupts)
- * by switching to a fallback Fx.
+ * Recovers from any failure cause by running a fallback Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A full `Cause` retains typed failures, defects, interruption, and composed
+ * causes. Handling that structure explicitly is necessary at boundaries that
+ * must translate every termination mode rather than only expected errors.
  *
- * Mirrors `Effect.catchCause`.
+ * ## Ownership and lifetime
+ *
+ * The handler runs once after the source reports a cause and its returned Fx
+ * continues in the same subscription. It receives the cause unchanged. Values
+ * emitted before failure are not replayed, and the fallback's errors and
+ * services replace the recovered source error and join its requirements.
+ * Because interruption is catchable here, use this only when intentionally
+ * translating interruption rather than for ordinary typed recovery.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catchCause } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const reported = catchCause(failCause(Cause.die("boom")), (cause) =>
+ *   succeed(Cause.pretty(cause))
+ * )
+ * ```
  *
  * @since 1.0.0
  * @category combinators
  */
 export const catchCause = dual(2, (self, f) => make((sink) => self.run(makeSink((cause) => f(cause).run(sink), sink.onSuccess))));
 /**
- * Recovers from a typed failure by matching on the `_tag` field of the error.
+ * Recovers selected tagged typed failures by running a fallback Fx.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchTag`.
+ * Tagged error unions are idiomatic Effect APIs. Selecting one or more tags
+ * narrows the handler input and removes only those variants from the returned
+ * error channel, preserving the rest for later composition.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source owns the subscription until its Cause contains a Fail whose tag
+ * matches. That first matching Fail starts one handler Fx and replaces the
+ * entire original Cause, including any defects or interrupts composed with it.
+ * A Cause with no Fail, or a first Fail with another tag, passes through intact.
+ * The fallback is lazy and contributes its errors and services to the result.
+ *
+ * @example
+ * ```ts
+ * import { catchTag } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * type Missing = { readonly _tag: "Missing"; readonly id: string }
+ * const source = fail<Missing>({ _tag: "Missing", id: "42" })
+ * const recovered = catchTag(source, "Missing", ({ id }) => succeed(`missing:${id}`))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -68,10 +167,30 @@ export const catchTag = dual(3, (self, k, f) => make((sink) => self.run(makeSink
     }
 }, sink.onSuccess))));
 /**
- * Recovers from a typed failure when a predicate holds, by switching to a fallback Fx.
- * Only applies to `Cause.Fail`; defects and interrupts are not caught.
+ * Recovers a typed failure only when a predicate accepts it.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchIf`.
+ * Some typed errors are distinguished by values rather than tags. Predicate
+ * recovery handles that subset while retaining `E` in the result because a
+ * rejected error can still escape.
+ *
+ * ## Ownership and lifetime
+ *
+ * The predicate is evaluated on the first Fail found anywhere in the source
+ * Cause. A match starts one lazy fallback and replaces that entire Cause,
+ * including any defects or interrupts composed with the Fail. A rejection, or
+ * a Cause containing no Fail, forwards the original Cause unchanged. The
+ * fallback contributes its errors and services and shares the subscription.
+ *
+ * @example
+ * ```ts
+ * import { catchIf } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchIf(fail(404), (status) => status === 404, () => succeed("missing"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators
@@ -88,19 +207,70 @@ export const catchIf = dual(3, (self, predicate, f) => make((sink) => self.run(m
     return sink.onFailure(cause);
 }, sink.onSuccess))));
 /**
- * Recovers from a failure cause when a predicate on the cause holds,
- * by switching to a fallback Fx.
+ * Recovers a failure cause only when a predicate accepts the complete cause.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchCauseIf`.
+ * Cause-level predicates can distinguish defects, interruption, sequential or
+ * parallel cause structure that a typed-error predicate cannot observe.
+ *
+ * ## Ownership and lifetime
+ *
+ * The predicate receives the source cause unchanged. A match starts one lazy
+ * fallback in the same subscription; otherwise the original cause propagates.
+ * The fallback's requirements and errors are added, prior source values stay
+ * delivered, and interrupting the returned Fx interrupts its active run.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catchCauseIf } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchCauseIf(
+ *   failCause(Cause.die("bad decoder")),
+ *   Cause.hasDies,
+ *   () => succeed("reported")
+ * )
+ * ```
  *
  * @since 1.0.0
  * @category combinators
  */
 export const catchCauseIf = dual(3, (self, predicate, f) => make((sink) => self.run(makeSink((cause) => (predicate(cause) ? f(cause).run(sink) : sink.onFailure(cause)), sink.onSuccess))));
 /**
- * Recovers from typed failures by matching on the `_tag` field with multiple handlers at once.
+ * Recovers several tagged typed-error variants with one handler table.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A handler table keeps multi-variant recovery exhaustive and preserves the
+ * precise success, error, and service unions produced by each selected case.
+ * Unlisted variants remain visible in the returned error channel.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first Fail found anywhere in the source Cause is inspected. A listed tag
+ * starts exactly one handler Fx and replaces the entire original Cause,
+ * including any defects or interrupts composed with that Fail. An untagged or
+ * unlisted first Fail, or a Cause with no Fail, propagates intact. Handlers are
+ * lazy and contribute their individual errors and service requirements.
+ *
+ * @example
+ * ```ts
+ * import { catchTags } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
  *
- * Mirrors `Effect.catchTags`.
+ * type Failure =
+ *   | { readonly _tag: "Missing"; readonly id: string }
+ *   | { readonly _tag: "Forbidden" }
+ * const source = fail<Failure>({ _tag: "Missing", id: "42" })
+ * const recovered = catchTags(source, {
+ *   Missing: ({ id }) => succeed(`missing:${id}`),
+ *   Forbidden: () => succeed("forbidden")
+ * })
+ * ```
  *
  * @since 1.0.0
  * @category combinators

package/dist/Fx/combinators/causes.d.ts

@@ -1,7 +1,30 @@
 import type * as Cause from "effect/Cause";
 import type { Fx } from "../Fx.js";
 /**
- * Emits only the failure causes from an Fx, discarding successful values.
+ * Emits the source's terminal failure cause and discards every successful value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Failure telemetry and supervision often need the complete Effect `Cause`
+ * without treating that cause as another failure. Materializing only the
+ * failure side makes those pipelines ordinary, infallible Fx values.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source is subscribed once. Success values are dropped in arrival order;
+ * a terminal cause is emitted once and the returned Fx completes without a
+ * typed error. Defects and interruption are retained inside the emitted cause.
+ * No resource is acquired beyond the source subscription.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { causes } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const failures = causes(failCause(Cause.fail("offline")))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Cause<E>`.

package/dist/Fx/combinators/causes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"causes.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/causes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAO1E,CAAC"}
+{"version":3,"file":"causes.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/causes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAO1E,CAAC"}

package/dist/Fx/combinators/causes.js

@@ -3,7 +3,30 @@ import * as Option from "effect/Option";
 import { exit } from "./exit.js";
 import { filterMap } from "./filterMap.js";
 /**
- * Emits only the failure causes from an Fx, discarding successful values.
+ * Emits the source's terminal failure cause and discards every successful value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Failure telemetry and supervision often need the complete Effect `Cause`
+ * without treating that cause as another failure. Materializing only the
+ * failure side makes those pipelines ordinary, infallible Fx values.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source is subscribed once. Success values are dropped in arrival order;
+ * a terminal cause is emitted once and the returned Fx completes without a
+ * typed error. Defects and interruption are retained inside the emitted cause.
+ * No resource is acquired beyond the source subscription.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { causes } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const failures = causes(failCause(Cause.fail("offline")))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Cause<E>`.