@typed/fx 2.0.0-beta.1 → 2.0.0-beta.10

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

@@ -2,13 +2,58 @@ import type { Fx } from "../Fx.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
+ * @category Transforming values
  */
 export declare const map: {
     <A, B>(f: (a: A) => B): <E, R>(self: Fx<A, E, R>) => Fx<B, E, R>;
     <A, E, R, B>(self: Fx<A, E, R>, f: (a: A) => B): Fx<B, E, R>;
 };
+/**
+ * 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 Transforming values
+ */
+export declare const as: {
+    <B>(b: B): <A, E, R>(self: Fx<A, E, R>) => Fx<B, E, R>;
+    <A, E, R, B>(self: Fx<A, E, R>, b: B): Fx<B, E, R>;
+};
 //# sourceMappingURL=map.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/map.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,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;IAEjE,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,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAK9D,CAAC"}
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/map.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,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;IAEjE,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,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAG9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,EAAE,EAAE;IACf,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACgC,CAAC"}

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
+ * @category Transforming values
  */
 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 Transforming values
+ */
+export const as = dual(2, (self, b) => map(self, () => b));

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

@@ -5,8 +5,27 @@ 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
+ * @category Errors and recovery
  */
 export declare const mapBoth: {
     <E, E2, A, A2>(options: {

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,7 +8,26 @@ 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
+ * @category Errors and recovery
  */
 export const mapBoth = dual(2, (self, options) => make((sink) => self.run(makeSink((cause) => sink.onFailure(Cause.map(cause, options.onFailure)), (a) => sink.onSuccess(options.onSuccess(a))))));

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

@@ -3,10 +3,34 @@ 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
- * @category combinators
+ * @category Transforming values
  */
 export declare const mapEffect: {
     <A, B, E2, R2>(f: (a: A) => Effect.Effect<B, E2, R2>): <E, R>(fx: Fx<A, E | E2, R>) => Fx<B, E | E2, R | R2>;

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,9 +4,33 @@ 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
- * @category combinators
+ * @category Transforming values
  */
 export const mapEffect = dual(2, (self, f) => make((sink) => self.run(sinkCore.mapEffect(sink, f))));

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

@@ -1,14 +1,30 @@
 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
+ * @category Errors and recovery
  */
 export declare const mapError: {
     <E, E2>(f: (e: E) => E2): <A, R>(self: Fx<A, E, R>) => Fx<A, E2, R>;

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,14 +3,30 @@ 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
+ * @category Errors and recovery
  */
 export const mapError = dual(2, (self, f) => make((sink) => self.run(makeSink((cause) => sink.onFailure(Cause.map(cause, f)), sink.onSuccess))));

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

@@ -2,10 +2,44 @@ 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
- * @category combinators
+ * @category Combining sources
  */
 export declare const mergeAll: <FX extends ReadonlyArray<Fx<any, any, any>>>(...fx: FX) => Fx<Fx.Success<FX[number]>, Fx.Error<FX[number]>, Fx.Services<FX[number]>>;
 //# sourceMappingURL=mergeAll.d.ts.map

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,10 +4,44 @@ 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
- * @category combinators
+ * @category Combining sources
  */
 export const mergeAll = (...fx) => make((sink) => Effect.forEach(fx, (fx) => fx.run(skipInterrupt(sink)), {
     concurrency: fx.length,

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

@@ -1,14 +1,46 @@
 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.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare function mergeOrdered<FX extends ReadonlyArray<Fx<any, any, any>>>(...fx: FX): Fx<Fx.Success<FX[number]>, Fx.Error<FX[number]>, Fx.Services<FX[number]>>;
 //# sourceMappingURL=mergeOrdered.d.ts.map

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":"AAOA,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,CAoB3E"}

package/dist/Fx/combinators/mergeOrdered.js

@@ -2,36 +2,75 @@ import * as Cause from "effect/Cause";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
 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.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export function mergeOrdered(...fx) {
     return make(Effect.fn(function* (sink) {
-        const { makeSink, onEnd } = withBuffers(fx.length, sink);
-        yield* Effect.forEach(fx, (fx, i) => Effect.onExit(fx.run(makeSink(i)), () => onEnd(i)), {
+        const { makeSink, onEnd, discard } = withBuffers(fx.length, sink);
+        const run = Effect.forEach(fx, (fx, i) => Effect.onExit(fx.run(makeSink(i)), () => onEnd(i)), {
             concurrency: "unbounded",
             discard: true,
         });
+        yield* Effect.acquireUseRelease(run.pipe(Effect.forkChild({ startImmediately: true })), Fiber.join, (fiber) => discard.pipe(Effect.andThen(Fiber.interrupt(fiber))));
     }));
 }
 function withBuffers(size, sink) {
     const buffers = indexedBuffers(size, sink);
     const onSuccess = (index, value) => buffers.get(index).onSuccess(value);
     const onEnd = (index) => buffers.get(index).onEnd;
+    const discard = Effect.sync(() => {
+        for (const buffer of buffers.values())
+            buffer.discard();
+    });
     const makeSink = (index) => Sink.make((cause) => (Cause.hasInterruptsOnly(cause) ? onEnd(index) : sink.onFailure(cause)), (value) => onSuccess(index, value));
     return {
         onSuccess,
         onEnd,
+        discard,
         makeSink,
     };
 }
@@ -60,12 +99,16 @@ function indexedBuffers(size, sink) {
 }
 function IndexedBuffer(state, sink, onDone) {
     let buffer = [];
+    let active = true;
+    const forward = (value) => Effect.suspend(() => (active ? sink.onSuccess(value) : Effect.void));
     const onSuccess = (value) => {
+        if (!active)
+            return Effect.void;
         if (state.ready) {
             if (buffer.length === 0)
-                return sink.onSuccess(value);
+                return forward(value);
             buffer.push(value);
-            const effect = Effect.forEach(buffer, sink.onSuccess);
+            const effect = Effect.forEach(buffer, forward);
             buffer = [];
             return effect;
         }
@@ -74,16 +117,27 @@ function IndexedBuffer(state, sink, onDone) {
             return Effect.void;
         }
     };
-    const onEnd = Effect.flatMap(Deferred.await(state.deferred), () => {
-        if (buffer.length === 0)
-            return onDone;
-        const effect = Effect.forEach(buffer, sink.onSuccess);
-        buffer = [];
-        return Effect.ensuring(effect, onDone);
+    const onEnd = Effect.suspend(() => {
+        if (!active)
+            return Effect.void;
+        return Effect.flatMap(Deferred.await(state.deferred), () => {
+            if (!active)
+                return Effect.void;
+            if (buffer.length === 0)
+                return onDone;
+            const effect = Effect.forEach(buffer, forward);
+            buffer = [];
+            return Effect.ensuring(effect, onDone);
+        });
     });
     return {
         state,
         onSuccess,
         onEnd,
+        discard: () => {
+            active = false;
+            buffer = [];
+            Deferred.doneUnsafe(state.deferred, Exit.void);
+        },
     };
 }