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

package/dist/Fx/combinators/map.js

@@ -4,9 +4,51 @@ import { make } from "../constructors/make.js";
 /**
  * Transforms the elements of an Fx using a provided function.
  *
+ * @remarks
+ * ## Why
+ * `map` changes each pushed value without changing when values arrive. It emits exactly once for
+ * every upstream success, in upstream order; the callback is synchronous and cannot add failures
+ * or services.
+ *
+ * ## Ownership and lifetime
+ * This operation acquires no resources and retains no state. Running the result runs the source in
+ * the same Scope, and interruption or failure is forwarded unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const labels = Fx.fromIterable([1, 2, 3]).pipe(Fx.map((n) => `item-${n}`))
+ * ```
+ *
  * @param f - A function that transforms values of type `A` to `B`.
  * @returns An `Fx` that emits values of type `B`.
  * @since 1.0.0
  * @category combinators
  */
 export const map = dual(2, (self, f) => make((sink) => self.run(sinkCore.map(sink, f))));
+/**
+ * Replaces all emitted values from the Fx with the provided value `b`.
+ *
+ * @remarks
+ * ## Why
+ * `as` preserves upstream timing and cardinality while intentionally discarding each value. It is
+ * useful when occurrence matters but payload does not.
+ *
+ * ## Ownership and lifetime
+ * This operation is a pure `map`; it acquires no resources, retains no state, and forwards source
+ * failure, completion, services, and interruption unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const refreshes = Fx.fromIterable(["click", "retry"]).pipe(Fx.as("refresh" as const))
+ * ```
+ *
+ * @param b - The value to emit instead.
+ * @returns An Fx that emits `b` for every element.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const as = dual(2, (self, b) => map(self, () => b));

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

@@ -5,6 +5,25 @@ import type { Fx } from "../Fx.js";
  * Mirrors `Effect.mapBoth`: `onSuccess` maps emitted values, `onFailure` maps the
  * typed failure (via `Cause.map`); defects and interrupts are preserved.
  *
+ * @remarks
+ * ## Why
+ * `mapBoth` transforms success values and typed failures together while preserving the rest of an
+ * Effect `Cause`. Every success still emits once in order; only typed failure values are mapped.
+ *
+ * ## Ownership and lifetime
+ * Both callbacks are synchronous and the operation acquires no resources. Defects, interruption,
+ * service requirements, and source lifetime pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const normalized = Fx.fail("offline").pipe(Fx.mapBoth({
+ *   onFailure: (message) => new Error(message),
+ *   onSuccess: (value) => String(value),
+ * }))
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */

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

@@ -1 +1 @@
-{"version":3,"file":"mapBoth.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mapBoth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE;QACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QACjC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;KAClC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAA;KAAE,GAC9E,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;CAelB,CAAC"}
+{"version":3,"file":"mapBoth.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mapBoth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE;QACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QACjC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;KAClC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAE5C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAA;KAAE,GAC9E,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;CAelB,CAAC"}

package/dist/Fx/combinators/mapBoth.js

@@ -8,6 +8,25 @@ import { make } from "../constructors/make.js";
  * Mirrors `Effect.mapBoth`: `onSuccess` maps emitted values, `onFailure` maps the
  * typed failure (via `Cause.map`); defects and interrupts are preserved.
  *
+ * @remarks
+ * ## Why
+ * `mapBoth` transforms success values and typed failures together while preserving the rest of an
+ * Effect `Cause`. Every success still emits once in order; only typed failure values are mapped.
+ *
+ * ## Ownership and lifetime
+ * Both callbacks are synchronous and the operation acquires no resources. Defects, interruption,
+ * service requirements, and source lifetime pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const normalized = Fx.fail("offline").pipe(Fx.mapBoth({
+ *   onFailure: (message) => new Error(message),
+ *   onSuccess: (value) => String(value),
+ * }))
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */

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

@@ -3,6 +3,30 @@ import type { Fx } from "../Fx.js";
 /**
  * Transforms the elements of an Fx using a provided Effectful function.
  *
+ * @remarks
+ * ## Why
+ * `mapEffect` performs one Effectful transformation for every input and emits once for each
+ * successful callback. It does not serialize sink invocations: ordering and concurrency are owned
+ * by the producer, so overlapping callbacks may complete and emit out of input order.
+ *
+ * ## Ownership and lifetime
+ * Each callback Effect belongs to the producer delivery that invoked it. Failure is routed to the
+ * Sink, services remain required, and interruption is local to that delivery. The combinator adds
+ * no queue, semaphore, result retention, or independent fiber.
+ *
+ * @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 program = Fx.collectAll(
+ *   concurrent.pipe(Fx.mapEffect((n) => Effect.sleep(n === 1 ? "10 millis" : "0 millis").pipe(Effect.as(n))))
+ * ) // producer concurrency permits [2, 1]
+ * ```
+ *
  * @param f - A function that transforms values of type `A` to an Effect of `B`.
  * @returns An `Fx` that emits values of type `B`.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"mapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mapEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAK7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACpC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,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;IAEzD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACpB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACpC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}
+{"version":3,"file":"mapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mapEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAK7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACpC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,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;IAEzD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACpB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACpC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}

package/dist/Fx/combinators/mapEffect.js

@@ -4,6 +4,30 @@ import { make } from "../constructors/make.js";
 /**
  * Transforms the elements of an Fx using a provided Effectful function.
  *
+ * @remarks
+ * ## Why
+ * `mapEffect` performs one Effectful transformation for every input and emits once for each
+ * successful callback. It does not serialize sink invocations: ordering and concurrency are owned
+ * by the producer, so overlapping callbacks may complete and emit out of input order.
+ *
+ * ## Ownership and lifetime
+ * Each callback Effect belongs to the producer delivery that invoked it. Failure is routed to the
+ * Sink, services remain required, and interruption is local to that delivery. The combinator adds
+ * no queue, semaphore, result retention, or independent fiber.
+ *
+ * @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 program = Fx.collectAll(
+ *   concurrent.pipe(Fx.mapEffect((n) => Effect.sleep(n === 1 ? "10 millis" : "0 millis").pipe(Effect.as(n))))
+ * ) // producer concurrency permits [2, 1]
+ * ```
+ *
  * @param f - A function that transforms values of type `A` to an Effect of `B`.
  * @returns An `Fx` that emits values of type `B`.
  * @since 1.0.0

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

@@ -1,11 +1,27 @@
 import type { Fx } from "../Fx.js";
 /**
- * Transforms the error channel of an Fx using the provided function.
+ * Transforms typed failures while preserving defects and interruption.
  *
- * Failures (Cause) are mapped via `Cause.map`, so only the typed failure (`Fail`)
- * is transformed; defects and interrupts are preserved unchanged.
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.mapError`.
+ * Libraries can expose a domain error without losing the richer Cause that
+ * Effect uses for defects, interruption, and composed failures.
+ *
+ * ## Ownership and lifetime
+ *
+ * The mapping function runs synchronously for each `Cause.Fail` reported by
+ * the source. It does not run for defects or interrupts, which pass through
+ * unchanged. Values retain order and cardinality. No resource is acquired and
+ * the returned Fx has the same subscription lifetime and services as its source.
+ *
+ * @example
+ * ```ts
+ * import { mapError } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const domainFailure = mapError(fail(404), (status) => ({ _tag: "HttpError", status }))
+ * ```
  *
  * @since 1.0.0
  * @category combinators

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

@@ -1 +1 @@
-{"version":3,"file":"mapError.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mapError.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;CAOjE,CAAC"}
+{"version":3,"file":"mapError.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mapError.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;CAKjE,CAAC"}

package/dist/Fx/combinators/mapError.js

@@ -3,12 +3,28 @@ import { dual } from "effect/Function";
 import { make as makeSink } from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
 /**
- * Transforms the error channel of an Fx using the provided function.
+ * Transforms typed failures while preserving defects and interruption.
  *
- * Failures (Cause) are mapped via `Cause.map`, so only the typed failure (`Fail`)
- * is transformed; defects and interrupts are preserved unchanged.
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.mapError`.
+ * Libraries can expose a domain error without losing the richer Cause that
+ * Effect uses for defects, interruption, and composed failures.
+ *
+ * ## Ownership and lifetime
+ *
+ * The mapping function runs synchronously for each `Cause.Fail` reported by
+ * the source. It does not run for defects or interrupts, which pass through
+ * unchanged. Values retain order and cardinality. No resource is acquired and
+ * the returned Fx has the same subscription lifetime and services as its source.
+ *
+ * @example
+ * ```ts
+ * import { mapError } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const domainFailure = mapError(fail(404), (status) => ({ _tag: "HttpError", status }))
+ * ```
  *
  * @since 1.0.0
  * @category combinators

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

@@ -2,6 +2,40 @@ import type { Fx } from "../Fx.js";
 /**
  * Merges multiple Fx streams into a single Fx that emits values from all input streams concurrently.
  *
+ * @remarks
+ * ## Why
+ *
+ * `mergeAll` combines a known set of independent push producers without adding
+ * a source-of-sources or choosing a winner.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * All inputs start concurrently. Every non-interruption value from every input
+ * is forwarded once. Each input preserves its own order, while values across
+ * inputs interleave by arrival; there is no buffering to restore argument order.
+ * An empty argument list completes without emitting.
+ *
+ * ## Ownership and lifetime
+ *
+ * Typed failures from any input are forwarded and every input environment is
+ * required. Interrupt-only causes from sibling cancellation are suppressed at
+ * the Sink boundary. The observing fiber owns all concurrent runs: completion
+ * waits for all inputs, and interruption cancels the remaining runs and their
+ * resource lifetimes.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const events = Fx.mergeAll(
+ *   Fx.at("slow", "20 millis"),
+ *   Fx.at("fast", "1 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(events)).then(console.log)
+ * // ["fast", "slow"]
+ * ```
+ *
  * @param fx - The Fx streams to merge.
  * @returns An `Fx` that emits values from all input streams.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"mergeAll.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mergeAll.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAClE,GAAG,IAAI,EAAE,KACR,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAMxE,CAAC"}
+{"version":3,"file":"mergeAll.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mergeAll.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,SAC3D,EAAE,KACR,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAMxE,CAAC"}

package/dist/Fx/combinators/mergeAll.js

@@ -4,6 +4,40 @@ import { make } from "../constructors/make.js";
 /**
  * Merges multiple Fx streams into a single Fx that emits values from all input streams concurrently.
  *
+ * @remarks
+ * ## Why
+ *
+ * `mergeAll` combines a known set of independent push producers without adding
+ * a source-of-sources or choosing a winner.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * All inputs start concurrently. Every non-interruption value from every input
+ * is forwarded once. Each input preserves its own order, while values across
+ * inputs interleave by arrival; there is no buffering to restore argument order.
+ * An empty argument list completes without emitting.
+ *
+ * ## Ownership and lifetime
+ *
+ * Typed failures from any input are forwarded and every input environment is
+ * required. Interrupt-only causes from sibling cancellation are suppressed at
+ * the Sink boundary. The observing fiber owns all concurrent runs: completion
+ * waits for all inputs, and interruption cancels the remaining runs and their
+ * resource lifetimes.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const events = Fx.mergeAll(
+ *   Fx.at("slow", "20 millis"),
+ *   Fx.at("fast", "1 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(events)).then(console.log)
+ * // ["fast", "slow"]
+ * ```
+ *
  * @param fx - The Fx streams to merge.
  * @returns An `Fx` that emits values from all input streams.
  * @since 1.0.0

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

@@ -1,9 +1,41 @@
 import type { Fx } from "../Fx.js";
 /**
- * Merges multiple Fx streams concurrently but emits values in the order of the input streams.
+ * Runs multiple Fx streams concurrently while draining their values in argument order.
  *
- * This ensures that values from the first Fx are emitted before values from the second Fx, and so on.
- * Values from later streams are buffered until earlier streams complete or emit their values (depending on semantics, but usually this means strictly ordered emission).
+ * @remarks
+ * ## Why
+ *
+ * `mergeOrdered` overlaps production latency while preserving the same output
+ * grouping as sequential concatenation. It is useful only when that ordering is
+ * worth retaining later results in memory.
+ *
+ * ## Concurrency, ordering, and buffering
+ *
+ * Every input starts immediately. Input zero forwards as it produces. Values
+ * from each later input are buffered until every earlier input ends, then drained
+ * in that input's emission order before the next buffer is released. Buffering
+ * is unbounded: a fast or infinite later input can retain arbitrary values while
+ * an earlier input remains open.
+ *
+ * ## Ownership and lifetime
+ *
+ * Non-interruption failures are forwarded. Interrupt-only causes mark that input
+ * ended so they cannot deadlock later buffers. All input services remain typed.
+ * The observing fiber owns all runs and buffers; completion waits for all inputs,
+ * while interruption discards buffers and interrupts remaining resource scopes.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const ordered = Fx.mergeOrdered(
+ *   Fx.at("slow first", "20 millis"),
+ *   Fx.at("fast second", "1 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(ordered)).then(console.log)
+ * // ["slow first", "fast second"]: the second value waits in its buffer
+ * ```
  *
  * @param fx - The Fx streams to merge.
  * @returns An `Fx` that emits values in order.

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

@@ -1 +1 @@
-{"version":3,"file":"mergeOrdered.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mergeOrdered.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EACtE,GAAG,EAAE,EAAE,EAAE,GACR,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAW3E"}
+{"version":3,"file":"mergeOrdered.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/mergeOrdered.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EACtE,GAAG,EAAE,EAAE,EAAE,GACR,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAW3E"}

package/dist/Fx/combinators/mergeOrdered.js

@@ -5,10 +5,42 @@ import * as Exit from "effect/Exit";
 import * as Sink from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
 /**
- * Merges multiple Fx streams concurrently but emits values in the order of the input streams.
+ * Runs multiple Fx streams concurrently while draining their values in argument order.
  *
- * This ensures that values from the first Fx are emitted before values from the second Fx, and so on.
- * Values from later streams are buffered until earlier streams complete or emit their values (depending on semantics, but usually this means strictly ordered emission).
+ * @remarks
+ * ## Why
+ *
+ * `mergeOrdered` overlaps production latency while preserving the same output
+ * grouping as sequential concatenation. It is useful only when that ordering is
+ * worth retaining later results in memory.
+ *
+ * ## Concurrency, ordering, and buffering
+ *
+ * Every input starts immediately. Input zero forwards as it produces. Values
+ * from each later input are buffered until every earlier input ends, then drained
+ * in that input's emission order before the next buffer is released. Buffering
+ * is unbounded: a fast or infinite later input can retain arbitrary values while
+ * an earlier input remains open.
+ *
+ * ## Ownership and lifetime
+ *
+ * Non-interruption failures are forwarded. Interrupt-only causes mark that input
+ * ended so they cannot deadlock later buffers. All input services remain typed.
+ * The observing fiber owns all runs and buffers; completion waits for all inputs,
+ * while interruption discards buffers and interrupts remaining resource scopes.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const ordered = Fx.mergeOrdered(
+ *   Fx.at("slow first", "20 millis"),
+ *   Fx.at("fast second", "1 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(ordered)).then(console.log)
+ * // ["slow first", "fast second"]: the second value waits in its buffer
+ * ```
  *
  * @param fx - The Fx streams to merge.
  * @returns An `Fx` that emits values in order.

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

@@ -2,10 +2,40 @@ import type * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import type { Fx } from "../Fx.js";
 /**
- * Adds an `Effect.onError`-style finalizer to an `Fx`.
+ * Runs cleanup after the source reports a failure cause.
  *
- * The cleanup is run only if the stream fails (including defects / interrupts
- * carried in the `Cause`).
+ * @remarks
+ * ## Why
+ *
+ * Failure-only observation belongs at the stream boundary when cleanup needs
+ * the complete Cause rather than merely the typed error.
+ *
+ * ## Ownership and lifetime
+ *
+ * The original cause is delivered downstream first. Cleanup runs only if that
+ * downstream `onFailure` Effect succeeds; if the sink itself fails or interrupts,
+ * `flatMap` never reaches cleanup. Typed cleanup failure is impossible by
+ * signature, but `Effect.ignore` does not suppress defects or interruption:
+ * either can fail or interrupt the run after the source Cause was handled. Its
+ * services are required for the subscription, and it does not run after success.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { onError } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const logged = onError(fail("offline"), (cause) => Effect.logError(cause))
+ * ```
+ *
+ * @example A cleanup defect is not a typed failure
+ * ```ts
+ * import { Effect } from "effect"
+ * import { onError } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const defectiveCleanup = onError(fail("offline"), () => Effect.die("logger defect"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators

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

@@ -1 +1 @@
-{"version":3,"file":"onError.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/onError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAC9D,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEjD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EACb,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAC9D,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAerB,CAAC"}
+{"version":3,"file":"onError.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/onError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAC9D,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEjD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EACb,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAC9D,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAerB,CAAC"}

package/dist/Fx/combinators/onError.js

@@ -3,10 +3,40 @@ import { dual } from "effect/Function";
 import { make as makeSink } from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
 /**
- * Adds an `Effect.onError`-style finalizer to an `Fx`.
+ * Runs cleanup after the source reports a failure cause.
  *
- * The cleanup is run only if the stream fails (including defects / interrupts
- * carried in the `Cause`).
+ * @remarks
+ * ## Why
+ *
+ * Failure-only observation belongs at the stream boundary when cleanup needs
+ * the complete Cause rather than merely the typed error.
+ *
+ * ## Ownership and lifetime
+ *
+ * The original cause is delivered downstream first. Cleanup runs only if that
+ * downstream `onFailure` Effect succeeds; if the sink itself fails or interrupts,
+ * `flatMap` never reaches cleanup. Typed cleanup failure is impossible by
+ * signature, but `Effect.ignore` does not suppress defects or interruption:
+ * either can fail or interrupt the run after the source Cause was handled. Its
+ * services are required for the subscription, and it does not run after success.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { onError } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const logged = onError(fail("offline"), (cause) => Effect.logError(cause))
+ * ```
+ *
+ * @example A cleanup defect is not a typed failure
+ * ```ts
+ * import { Effect } from "effect"
+ * import { onError } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const defectiveCleanup = onError(fail("offline"), () => Effect.die("logger defect"))
+ * ```
  *
  * @since 1.0.0
  * @category combinators

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

@@ -2,9 +2,35 @@ import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import type { Fx } from "../Fx.js";
 /**
- * Adds an `Effect.onExit`-style finalizer to an `Fx`.
+ * Observes the Fx's final success or failure with an Effect finalizer.
  *
- * The finalizer is run when the `Fx` terminates (success, failure, or interruption).
+ * @remarks
+ * ## Why
+ *
+ * Teardown and audit work sometimes depends on how the complete subscription
+ * ended. An `Exit` preserves that distinction without materializing it as a
+ * stream value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The finalizer runs once after successful completion, a reported source cause,
+ * or interruption of the running fiber. The success Exit carries `void`
+ * because an Fx may emit many values and has no single terminal success value.
+ * A finalizer failure after normal completion is reported in the returned error
+ * channel. After a source failure or interruption it is suppressed so the
+ * already-observed termination remains authoritative. Finalizer services live
+ * for the subscription only.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Exit } from "effect"
+ * import { onExit } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const audited = onExit(succeed("ready"), (exit) =>
+ *   Effect.log(Exit.isSuccess(exit) ? "complete" : "failed")
+ * )
+ * ```
  *
  * @since 1.0.0
  * @category combinators

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

@@ -1 +1 @@
-{"version":3,"file":"onExit.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/onExit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAMpC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AASnC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC3B,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAClE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEnD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC9B,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAClE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAiD1B,CAAC"}
+{"version":3,"file":"onExit.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/onExit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAMpC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC3B,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAClE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEnD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC9B,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAClE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAiD1B,CAAC"}

package/dist/Fx/combinators/onExit.js

@@ -10,9 +10,35 @@ const toFinalizer = (f) => (exit) => {
     return Effect.isEffect(x) ? x : Effect.void;
 };
 /**
- * Adds an `Effect.onExit`-style finalizer to an `Fx`.
+ * Observes the Fx's final success or failure with an Effect finalizer.
  *
- * The finalizer is run when the `Fx` terminates (success, failure, or interruption).
+ * @remarks
+ * ## Why
+ *
+ * Teardown and audit work sometimes depends on how the complete subscription
+ * ended. An `Exit` preserves that distinction without materializing it as a
+ * stream value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The finalizer runs once after successful completion, a reported source cause,
+ * or interruption of the running fiber. The success Exit carries `void`
+ * because an Fx may emit many values and has no single terminal success value.
+ * A finalizer failure after normal completion is reported in the returned error
+ * channel. After a source failure or interruption it is suppressed so the
+ * already-observed termination remains authoritative. Finalizer services live
+ * for the subscription only.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Exit } from "effect"
+ * import { onExit } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const audited = onExit(succeed("ready"), (exit) =>
+ *   Effect.log(Exit.isSuccess(exit) ? "complete" : "failed")
+ * )
+ * ```
  *
  * @since 1.0.0
  * @category combinators