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

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

@@ -2,6 +2,43 @@ import type { FlatMapLike } from "./flatMap.js";
 /**
  * Maps each element of an Fx to a new Fx, ignoring new elements until the current inner Fx completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * `exhaustMap` is an admission policy for work that must never overlap and does
+ * not need a backlog, such as ignoring repeated submit events while one submit
+ * is running.
+ *
+ * ## Admission, ordering, and cardinality
+ *
+ * The first source value observed while idle admits one inner Fx. For values
+ * arriving while it runs, `f` is still evaluated to construct an inner, but that
+ * inner is not run and no value is queued. Every admitted inner may emit any
+ * number of values in its own order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted-inner failures are forwarded and their services remain
+ * typed. A `FiberHandle` in the required `Scope` owns the active inner. Source
+ * completion waits for that inner; interruption closes the handle and the
+ * inner's child Scope, running its finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const submits = Fx.mergeAll(
+ *   Fx.at("first", "0 millis"),
+ *   Fx.at("ignored while busy", "5 millis"),
+ *   Fx.at("later", "30 millis")
+ * )
+ * const accepted = Fx.exhaustMap(submits, (command) => Fx.at(command, "20 millis"))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["first", "later"]
+ * ```
+ *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from the active inner stream.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"exhaustMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMap.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,WAiBxB,CAAC"}
+{"version":3,"file":"exhaustMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMap.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,UAAU,EAAE,WAiBxB,CAAC"}

package/dist/Fx/combinators/exhaustMap.js

@@ -7,6 +7,43 @@ import { extendScope } from "../internal/scope.js";
 /**
  * Maps each element of an Fx to a new Fx, ignoring new elements until the current inner Fx completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * `exhaustMap` is an admission policy for work that must never overlap and does
+ * not need a backlog, such as ignoring repeated submit events while one submit
+ * is running.
+ *
+ * ## Admission, ordering, and cardinality
+ *
+ * The first source value observed while idle admits one inner Fx. For values
+ * arriving while it runs, `f` is still evaluated to construct an inner, but that
+ * inner is not run and no value is queued. Every admitted inner may emit any
+ * number of values in its own order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted-inner failures are forwarded and their services remain
+ * typed. A `FiberHandle` in the required `Scope` owns the active inner. Source
+ * completion waits for that inner; interruption closes the handle and the
+ * inner's child Scope, running its finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const submits = Fx.mergeAll(
+ *   Fx.at("first", "0 millis"),
+ *   Fx.at("ignored while busy", "5 millis"),
+ *   Fx.at("later", "30 millis")
+ * )
+ * const accepted = Fx.exhaustMap(submits, (command) => Fx.at(command, "20 millis"))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["first", "later"]
+ * ```
+ *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from the active inner stream.
  * @since 1.0.0

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

@@ -2,6 +2,38 @@ import type { FlatMapEffectLike } from "./flatMapEffect.js";
 /**
  * Maps each element of an Fx to an Effect, ignoring new elements until the current effect completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * This Effect-producing form of {@link exhaustMap} prevents overlapping command
+ * Effects while deliberately applying no queue or latest-value replay policy.
+ *
+ * ## Admission and cardinality
+ *
+ * The first value while idle starts one Effect and emits its one successful
+ * result. For values received while it runs, `f` is still evaluated to construct
+ * an Effect, but that Effect is not run or queued.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and callback Effect failures remain typed and callback services are
+ * added to the output requirements. The active Effect is owned by the returned
+ * Fx's required `Scope`; completion waits for it and interruption runs its
+ * finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const accepted = Fx.exhaustMapEffect(Fx.fromIterable([1, 2]), (id) =>
+ *   Effect.as(Effect.sleep("20 millis"), `saved:${id}`)
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["saved:1"]: the second Effect is constructed but not admitted
+ * ```
+ *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
  * @returns An `Fx` that emits the results of the active effect.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"exhaustMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMapEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAM9B,CAAC"}
+{"version":3,"file":"exhaustMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMapEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAM9B,CAAC"}

package/dist/Fx/combinators/exhaustMapEffect.js

@@ -4,6 +4,38 @@ import { exhaustMap } from "./exhaustMap.js";
 /**
  * Maps each element of an Fx to an Effect, ignoring new elements until the current effect completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * This Effect-producing form of {@link exhaustMap} prevents overlapping command
+ * Effects while deliberately applying no queue or latest-value replay policy.
+ *
+ * ## Admission and cardinality
+ *
+ * The first value while idle starts one Effect and emits its one successful
+ * result. For values received while it runs, `f` is still evaluated to construct
+ * an Effect, but that Effect is not run or queued.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and callback Effect failures remain typed and callback services are
+ * added to the output requirements. The active Effect is owned by the returned
+ * Fx's required `Scope`; completion waits for it and interruption runs its
+ * finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const accepted = Fx.exhaustMapEffect(Fx.fromIterable([1, 2]), (id) =>
+ *   Effect.as(Effect.sleep("20 millis"), `saved:${id}`)
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["saved:1"]: the second Effect is constructed but not admitted
+ * ```
+ *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
  * @returns An `Fx` that emits the results of the active effect.
  * @since 1.0.0

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

@@ -1,7 +1,28 @@
 import type * as Exit from "effect/Exit";
 import type { Fx } from "../Fx.js";
 /**
- * Materializes the success and failure of an Fx into `Exit` values.
+ * Materializes every success and the terminal failure as infallible `Exit` values.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Turning both channels into data lets downstream Fx composition inspect
+ * complete Effect causes without terminating the pipeline.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each source value becomes `Exit.succeed` in arrival order. A source failure,
+ * including a defect or interrupt, becomes one `Exit.failCause`, after which
+ * the returned Fx completes with error type `never`. It acquires no resource
+ * beyond the single source subscription.
+ *
+ * @example
+ * ```ts
+ * import { exit } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const outcomes = exit(fail("offline"))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Exit<A, E>`.

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

@@ -1 +1 @@
-{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CACJ,CAAC"}
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CACJ,CAAC"}

package/dist/Fx/combinators/exit.js

@@ -1,7 +1,28 @@
 import * as sinkCore from "../../Sink/combinators.js";
 import { make } from "../constructors/make.js";
 /**
- * Materializes the success and failure of an Fx into `Exit` values.
+ * Materializes every success and the terminal failure as infallible `Exit` values.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Turning both channels into data lets downstream Fx composition inspect
+ * complete Effect causes without terminating the pipeline.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each source value becomes `Exit.succeed` in arrival order. A source failure,
+ * including a defect or interrupt, becomes one `Exit.failCause`, after which
+ * the returned Fx completes with error type `never`. It acquires no resource
+ * beyond the single source subscription.
+ *
+ * @example
+ * ```ts
+ * import { exit } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const outcomes = exit(fail("offline"))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Exit<A, E>`.

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

@@ -2,6 +2,22 @@ import type { Fx } from "../Fx.js";
 /**
  * Filters elements of an Fx using a predicate function.
  *
+ * @remarks
+ * ## Why
+ * `filter` keeps the source's push timing and order while allowing zero or one output for each
+ * input. The predicate is synchronous, so it adds neither failures nor service requirements.
+ *
+ * ## Ownership and lifetime
+ * No resource or buffer is acquired. The predicate runs while the source invokes the downstream
+ * sink; source failure, completion, and interruption are forwarded unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const even = Fx.fromIterable([1, 2, 3, 4]).pipe(Fx.filter((n) => n % 2 === 0))
+ * ```
+ *
  * @param f - A predicate function.
  * @returns An `Fx` that emits only the elements for which `f` returns `true`.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAKjE,CAAC"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAGjE,CAAC"}

package/dist/Fx/combinators/filter.js

@@ -4,6 +4,22 @@ import { make } from "../constructors/make.js";
 /**
  * Filters elements of an Fx using a predicate function.
  *
+ * @remarks
+ * ## Why
+ * `filter` keeps the source's push timing and order while allowing zero or one output for each
+ * input. The predicate is synchronous, so it adds neither failures nor service requirements.
+ *
+ * ## Ownership and lifetime
+ * No resource or buffer is acquired. The predicate runs while the source invokes the downstream
+ * sink; source failure, completion, and interruption are forwarded unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const even = Fx.fromIterable([1, 2, 3, 4]).pipe(Fx.filter((n) => n % 2 === 0))
+ * ```
+ *
  * @param f - A predicate function.
  * @returns An `Fx` that emits only the elements for which `f` returns `true`.
  * @since 1.0.0

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

@@ -3,6 +3,27 @@ import type { Fx } from "../Fx.js";
 /**
  * Filters elements of an Fx using an effectful predicate function.
  *
+ * @remarks
+ * ## Why
+ * `filterEffect` supports service-backed or failing decisions without flattening a second Fx. Each
+ * input runs one predicate Effect; `true` emits once and `false` emits nothing. The adapter does not
+ * serialize concurrent producer deliveries, so accepted values may arrive out of input order.
+ *
+ * ## Ownership and lifetime
+ * A predicate Effect belongs to the producer callback that invoked it. Its Cause is sent to the
+ * Sink, `R2` stays required, and interruption follows that delivery. No lock or queue is added.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const concurrent = Fx.make<number>((sink) =>
+ *   Effect.all([sink.onSuccess(1), sink.onSuccess(2)], { concurrency: "unbounded", discard: true })
+ * )
+ * const positive = concurrent.pipe(Fx.filterEffect((n) => Effect.succeed(n > 0)))
+ * ```
+ *
  * @param f - An effectful predicate function.
  * @returns An `Fx` that emits only the elements for which `f` returns `true`.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"filterEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE;IACzB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACtB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}
+{"version":3,"file":"filterEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAI7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,EAAE;IACzB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACtB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}

package/dist/Fx/combinators/filterEffect.js

@@ -4,6 +4,27 @@ import { make } from "../constructors/make.js";
 /**
  * Filters elements of an Fx using an effectful predicate function.
  *
+ * @remarks
+ * ## Why
+ * `filterEffect` supports service-backed or failing decisions without flattening a second Fx. Each
+ * input runs one predicate Effect; `true` emits once and `false` emits nothing. The adapter does not
+ * serialize concurrent producer deliveries, so accepted values may arrive out of input order.
+ *
+ * ## Ownership and lifetime
+ * A predicate Effect belongs to the producer callback that invoked it. Its Cause is sent to the
+ * Sink, `R2` stays required, and interruption follows that delivery. No lock or queue is added.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const concurrent = Fx.make<number>((sink) =>
+ *   Effect.all([sink.onSuccess(1), sink.onSuccess(2)], { concurrency: "unbounded", discard: true })
+ * )
+ * const positive = concurrent.pipe(Fx.filterEffect((n) => Effect.succeed(n > 0)))
+ * ```
+ *
  * @param f - An effectful predicate function.
  * @returns An `Fx` that emits only the elements for which `f` returns `true`.
  * @since 1.0.0

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

@@ -3,6 +3,25 @@ import type { Fx } from "../Fx.js";
 /**
  * Maps and filters elements of an Fx in a single operation.
  *
+ * @remarks
+ * ## Why
+ * `filterMap` represents a partial synchronous transformation explicitly with `Option`. Each input
+ * produces at most one output: `Some` is unwrapped and `None` is omitted, with source order intact.
+ *
+ * ## Ownership and lifetime
+ * This operation is stateless and acquires no resources. It preserves the source's error and
+ * service channels and stops whenever the source or consuming fiber stops.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Option } from "effect"
+ *
+ * const numbers = Fx.fromIterable(["1", "x", "2"]).pipe(
+ *   Fx.filterMap((text) => Number.isNaN(Number(text)) ? Option.none() : Option.some(Number(text))),
+ * )
+ * ```
+ *
  * @param f - A function that returns an `Option` for each element.
  * @returns An `Fx` that emits values for which `f` returns `Some`.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"filterMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEhF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAK7E,CAAC"}
+{"version":3,"file":"filterMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEhF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAG7E,CAAC"}

package/dist/Fx/combinators/filterMap.js

@@ -4,6 +4,25 @@ import { make } from "../constructors/make.js";
 /**
  * Maps and filters elements of an Fx in a single operation.
  *
+ * @remarks
+ * ## Why
+ * `filterMap` represents a partial synchronous transformation explicitly with `Option`. Each input
+ * produces at most one output: `Some` is unwrapped and `None` is omitted, with source order intact.
+ *
+ * ## Ownership and lifetime
+ * This operation is stateless and acquires no resources. It preserves the source's error and
+ * service channels and stops whenever the source or consuming fiber stops.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Option } from "effect"
+ *
+ * const numbers = Fx.fromIterable(["1", "x", "2"]).pipe(
+ *   Fx.filterMap((text) => Number.isNaN(Number(text)) ? Option.none() : Option.some(Number(text))),
+ * )
+ * ```
+ *
  * @param f - A function that returns an `Option` for each element.
  * @returns An `Fx` that emits values for which `f` returns `Some`.
  * @since 1.0.0

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

@@ -4,6 +4,26 @@ import type { Fx } from "../Fx.js";
 /**
  * Maps and filters elements of an Fx using an effectful function.
  *
+ * @remarks
+ * ## Why
+ * `filterMapEffect` combines an Effectful decision and transformation without introducing nested
+ * streams. `Some` emits once and `None` emits nothing. Producer callbacks are not serialized, so
+ * overlapping Effects can complete and emit in a different order than their inputs.
+ *
+ * ## Ownership and lifetime
+ * Each callback Effect follows its invoking producer delivery. Its failure Cause is sent to the
+ * Sink, services remain exposed as `R2`, and no semaphore, queue, or resource is added.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const accepted = Fx.fromIterable([1, 2]).pipe(
+ *   Fx.filterMapEffect((n) => Effect.succeed(n > 1 ? Option.some(n * 10) : Option.none()))
+ * )
+ * ```
+ *
  * @param f - An effectful function that returns an `Option` for each element.
  * @returns An `Fx` that emits values for which `f` returns `Some`.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"filterMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACnD,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACtB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACnD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}
+{"version":3,"file":"filterMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACnD,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACtB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACnD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}

package/dist/Fx/combinators/filterMapEffect.js

@@ -4,6 +4,26 @@ import { make } from "../constructors/make.js";
 /**
  * Maps and filters elements of an Fx using an effectful function.
  *
+ * @remarks
+ * ## Why
+ * `filterMapEffect` combines an Effectful decision and transformation without introducing nested
+ * streams. `Some` emits once and `None` emits nothing. Producer callbacks are not serialized, so
+ * overlapping Effects can complete and emit in a different order than their inputs.
+ *
+ * ## Ownership and lifetime
+ * Each callback Effect follows its invoking producer delivery. Its failure Cause is sent to the
+ * Sink, services remain exposed as `R2`, and no semaphore, queue, or resource is added.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const accepted = Fx.fromIterable([1, 2]).pipe(
+ *   Fx.filterMapEffect((n) => Effect.succeed(n > 1 ? Option.some(n * 10) : Option.none()))
+ * )
+ * ```
+ *
  * @param f - An effectful function that returns an `Option` for each element.
  * @returns An `Fx` that emits values for which `f` returns `Some`.
  * @since 1.0.0

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

@@ -4,6 +4,25 @@ import type { Fx } from "../Fx.js";
  * Loops over an Fx with an accumulator, producing an optional new value for each element.
  * If the function returns `None`, the element is filtered out.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoop` combines per-run state, mapping, and filtering in one ordered step. Every input
+ * updates the accumulator and may emit one `Some`; `None` still commits the returned next state.
+ *
+ * ## Ownership and lifetime
+ * The seed is copied into each run and retained only until that run ends. The callback is pure, and
+ * source failure, services, completion, and interruption are preserved.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const everyOther = Fx.fromIterable([1, 2, 3]).pipe(
+ *   Fx.filterMapLoop(0, (index, value) => [index % 2 === 0 ? Option.some(value) : Option.none(), index + 1]),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The loop function returning `Option<C>` and the new state.
  * @returns An `Fx` emitting the transformed values.

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

@@ -1 +1 @@
-{"version":3,"file":"filterMapLoop.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE;IAC1B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAClD,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAClD,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}
+{"version":3,"file":"filterMapLoop.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,aAAa,EAAE;IAC1B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAClD,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAClD,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}

package/dist/Fx/combinators/filterMapLoop.js

@@ -5,6 +5,25 @@ import { make } from "../constructors/make.js";
  * Loops over an Fx with an accumulator, producing an optional new value for each element.
  * If the function returns `None`, the element is filtered out.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoop` combines per-run state, mapping, and filtering in one ordered step. Every input
+ * updates the accumulator and may emit one `Some`; `None` still commits the returned next state.
+ *
+ * ## Ownership and lifetime
+ * The seed is copied into each run and retained only until that run ends. The callback is pure, and
+ * source failure, services, completion, and interruption are preserved.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const everyOther = Fx.fromIterable([1, 2, 3]).pipe(
+ *   Fx.filterMapLoop(0, (index, value) => [index % 2 === 0 ? Option.some(value) : Option.none(), index + 1]),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The loop function returning `Option<C>` and the new state.
  * @returns An `Fx` emitting the transformed values.

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

@@ -5,6 +5,26 @@ import type { Fx } from "../Fx.js";
  * Loops over the failure causes of an Fx with an accumulator, potentially transforming or filtering them.
  * This allows for complex error handling logic that maintains state across failures.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoopCause` transforms, suppresses, or reclassifies successive failure causes with
+ * explicit state. Successful values pass through; each observed cause advances the accumulator and
+ * `None` suppresses forwarding that cause.
+ *
+ * ## Ownership and lifetime
+ * Failure state is isolated to one run and discarded afterward. The pure callback acquires no
+ * resources; defects and interrupts are visible inside the full `Cause` supplied to it.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const firstFailureOnly = Fx.fail("offline").pipe(
+ *   Fx.filterMapLoopCause(false, (seen, cause) => [seen ? Option.none() : Option.some(Cause.map(cause, String)), true]),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The loop function for causes.
  * @returns An `Fx` with transformed errors.

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

@@ -1 +1 @@
-{"version":3,"file":"filterMapLoopCause.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoopCause.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5E,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5E,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}
+{"version":3,"file":"filterMapLoopCause.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoopCause.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5E,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACZ,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5E,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAQhB,CAAC"}

package/dist/Fx/combinators/filterMapLoopCause.js

@@ -5,6 +5,26 @@ import { make } from "../constructors/make.js";
  * Loops over the failure causes of an Fx with an accumulator, potentially transforming or filtering them.
  * This allows for complex error handling logic that maintains state across failures.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoopCause` transforms, suppresses, or reclassifies successive failure causes with
+ * explicit state. Successful values pass through; each observed cause advances the accumulator and
+ * `None` suppresses forwarding that cause.
+ *
+ * ## Ownership and lifetime
+ * Failure state is isolated to one run and discarded afterward. The pure callback acquires no
+ * resources; defects and interrupts are visible inside the full `Cause` supplied to it.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const firstFailureOnly = Fx.fail("offline").pipe(
+ *   Fx.filterMapLoopCause(false, (seen, cause) => [seen ? Option.none() : Option.some(Cause.map(cause, String)), true]),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The loop function for causes.
  * @returns An `Fx` with transformed errors.

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

@@ -5,6 +5,26 @@ import type { Fx } from "../Fx.js";
 /**
  * Effectfully loops over the failure causes of an Fx with an accumulator.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoopCauseEffect` supports Effectful, stateful cause policy. Each Cause produces `Some`
+ * to forward or `None` to suppress, but concurrent failure deliveries are not serialized and can
+ * read the same seed or commit next states out of order.
+ *
+ * ## Ownership and lifetime
+ * Cause state and callback Effects belong to the consuming run. Services remain required, callback
+ * failure is sent to the Sink, and interruption follows each delivery; no semaphore is introduced.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const handled = Fx.fail("offline").pipe(
+ *   Fx.filterMapLoopCauseEffect(0, (count, cause) => Effect.succeed([Option.some(cause), count + 1])),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function for causes.
  * @returns An `Fx` with transformed errors.

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

@@ -1 +1 @@
-{"version":3,"file":"filterMapLoopCauseEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoopCauseEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE;IACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CACD,GAAG,EAAE,CAAC,EACN,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACtE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAChB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CACD,GAAG,EAAE,CAAC,EACN,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACrE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAYrB,CAAC"}
+{"version":3,"file":"filterMapLoopCauseEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoopCauseEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB,EAAE;IACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CACD,GAAG,EAAE,CAAC,EACN,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACtE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAChB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CACD,GAAG,EAAE,CAAC,EACN,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACrE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAYrB,CAAC"}