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

package/dist/Fx/combinators/filterMapLoopCauseEffect.js

@@ -4,6 +4,26 @@ import { make } from "../constructors/make.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/filterMapLoopEffect.d.ts

@@ -4,6 +4,26 @@ import type { Fx } from "../Fx.js";
 /**
  * Effectfully loops over an Fx with an accumulator, producing an optional new value.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoopEffect` makes the state transition Effectful while retaining zero-or-one output per
+ * input. It adds no serialization: overlapping producer callbacks can read the same seed, complete
+ * out of order, and overwrite one another's next state.
+ *
+ * ## Ownership and lifetime
+ * One mutable seed belongs to each run. Callback Causes are delivered to the Sink, services remain
+ * required, and interruption follows each delivery; callers need a serialized producer for atomic state.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const counted = Fx.fromIterable(["a", "b"]).pipe(
+ *   Fx.filterMapLoopEffect(0, (count, value) => Effect.succeed([Option.some(`${count}:${value}`), count + 1])),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function.
  * @returns An `Fx` emitting the transformed values.

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

@@ -1 +1 @@
-{"version":3,"file":"filterMapLoopEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoopEffect.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;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACzE,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,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACxE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CASrB,CAAC"}
+{"version":3,"file":"filterMapLoopEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/filterMapLoopEffect.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,CAAC,EACP,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACzE,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,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GACxE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CASrB,CAAC"}

package/dist/Fx/combinators/filterMapLoopEffect.js

@@ -4,6 +4,26 @@ import { make } from "../constructors/make.js";
 /**
  * Effectfully loops over an Fx with an accumulator, producing an optional new value.
  *
+ * @remarks
+ * ## Why
+ * `filterMapLoopEffect` makes the state transition Effectful while retaining zero-or-one output per
+ * input. It adds no serialization: overlapping producer callbacks can read the same seed, complete
+ * out of order, and overwrite one another's next state.
+ *
+ * ## Ownership and lifetime
+ * One mutable seed belongs to each run. Callback Causes are delivered to the Sink, services remain
+ * required, and interruption follows each delivery; callers need a serialized producer for atomic state.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const counted = Fx.fromIterable(["a", "b"]).pipe(
+ *   Fx.filterMapLoopEffect(0, (count, value) => Effect.succeed([Option.some(`${count}:${value}`), count + 1])),
+ * )
+ * ```
+ *
  * @param seed - The initial state.
  * @param f - The effectful loop function.
  * @returns An `Fx` emitting the transformed values.

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

@@ -1,7 +1,19 @@
 import type * as Scope from "effect/Scope";
 import type { Fx } from "../Fx.js";
 /**
- * Type definition for flatMap functions to support variable arguments.
+ * Describes a dual flattening operator whose callback returns an Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared type keeps data-first and data-last call styles consistent across
+ * merge, concat, switch, and exhaust policies while preserving the callback's
+ * success, error, and service channels.
+ *
+ * ## Ownership and lifetime
+ *
+ * The type acquires no resources. Implementations return an Fx requiring
+ * `Scope`; that Scope owns any admitted inner subscriptions and their cleanup.
  * @since 1.0.0
  * @category types
  */
@@ -10,9 +22,42 @@ export type FlatMapLike<Args extends ReadonlyArray<any> = []> = {
     <A, E, R, B, E2, R2>(self: Fx<A, E, R>, f: (a: A) => Fx<B, E2, R2>, ...args: Args): Fx<B, E | E2, R | R2 | Scope.Scope>;
 };
 /**
- * Maps each element of an Fx to a new Fx, and merges the results.
+ * Maps each source value to an inner Fx and merges every inner concurrently.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `flatMap` is the unconstrained merge policy for independent pushed work. It
+ * preserves push-based production instead of collecting an inner Fx before the
+ * next source value can be handled.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * Every source value creates exactly one inner Fx with no concurrency limit.
+ * Each inner retains its own emission order, but values from different inners
+ * interleave according to arrival time. There is no output buffer or global
+ * ordering guarantee.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and inner failures are forwarded; their required services are unioned.
+ * A `FiberSet` in the required `Scope` owns all inner fibers. Source completion
+ * waits for the set to empty. Interrupting observation closes the Scope and
+ * interrupts every active inner, running each inner Scope's finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const rows = Fx.flatMap(Fx.fromIterable([
+ *   { id: "slow", wait: "20 millis" as const },
+ *   { id: "fast", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Fx.at(id, wait))
  *
- * The inner Fx streams are run concurrently. This is equivalent to `mergeMap` in RxJS.
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(rows))).then(console.log)
+ * // ["fast", "slow"]: inners overlap and results arrive by production time
+ * ```
  *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from all inner streams.

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

@@ -1 +1 @@
-{"version":3,"file":"flatMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMap.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;IAC9D,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAC1B,GAAG,IAAI,EAAE,IAAI,GACZ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAC1B,GAAG,IAAI,EAAE,IAAI,GACZ,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,EAAE,WAarB,CAAC"}
+{"version":3,"file":"flatMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMap.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;IAC9D,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAC1B,GAAG,IAAI,EAAE,IAAI,GACZ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAC1B,GAAG,IAAI,EAAE,IAAI,GACZ,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,OAAO,EAAE,WAarB,CAAC"}

package/dist/Fx/combinators/flatMap.js

@@ -5,9 +5,42 @@ import { make as makeSink } from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
 import { extendScope } from "../internal/scope.js";
 /**
- * Maps each element of an Fx to a new Fx, and merges the results.
+ * Maps each source value to an inner Fx and merges every inner concurrently.
  *
- * The inner Fx streams are run concurrently. This is equivalent to `mergeMap` in RxJS.
+ * @remarks
+ * ## Why
+ *
+ * `flatMap` is the unconstrained merge policy for independent pushed work. It
+ * preserves push-based production instead of collecting an inner Fx before the
+ * next source value can be handled.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * Every source value creates exactly one inner Fx with no concurrency limit.
+ * Each inner retains its own emission order, but values from different inners
+ * interleave according to arrival time. There is no output buffer or global
+ * ordering guarantee.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and inner failures are forwarded; their required services are unioned.
+ * A `FiberSet` in the required `Scope` owns all inner fibers. Source completion
+ * waits for the set to empty. Interrupting observation closes the Scope and
+ * interrupts every active inner, running each inner Scope's finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const rows = Fx.flatMap(Fx.fromIterable([
+ *   { id: "slow", wait: "20 millis" as const },
+ *   { id: "fast", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Fx.at(id, wait))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(rows))).then(console.log)
+ * // ["fast", "slow"]: inners overlap and results arrive by production time
+ * ```
  *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from all inner streams.

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

@@ -1,12 +1,59 @@
-import type { FlatMapLike } from "./flatMap.js";
+import * as Cause from "effect/Cause";
+import type * as Scope from "effect/Scope";
+import type { Fx } from "../Fx.js";
 /**
  * Maps each element of an Fx to a new Fx, running them concurrently with a limit.
  *
+ * @remarks
+ * ## Why
+ *
+ * This is the admission-controlled form of {@link flatMap}. It bounds active
+ * work while retaining every source value, which is appropriate when a remote
+ * service or local resource has a known concurrency budget.
+ *
+ * ## Concurrency, ordering, and buffering
+ *
+ * Each source value creates one child fiber. A semaphore admits at most
+ * `concurrency` inners into execution; excess fibers wait for a permit rather
+ * than being dropped. Values from each inner retain local order, but admitted
+ * inners may interleave and output is not reordered into source order.
+ *
+ * ## Ownership and lifetime
+ *
+ * A non-positive, fractional, infinite, or unsafe-integer limit fails through
+ * the Sink with `Cause.IllegalArgumentError`. Source and inner failures and
+ * services remain typed. The required `Scope` owns waiting and active fibers;
+ * source completion waits for all of them, and interruption cancels both groups
+ * and runs active inner finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const jobs = Fx.fromIterable([
+ *   { id: "one", wait: "20 millis" as const },
+ *   { id: "two", wait: "20 millis" as const },
+ *   { id: "three", wait: "1 millis" as const }
+ * ])
+ * const bounded = Fx.flatMapConcurrently(
+ *   jobs,
+ *   ({ id, wait }) => Fx.at(id, wait),
+ *   2
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(bounded))).then(console.log)
+ * // "three" waits for one of the first two permits despite its shorter delay
+ * ```
+ *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
- * @param concurrency - The maximum number of concurrent inner streams.
+ * @param concurrency - A positive safe-integer limit for concurrent inner streams. Invalid limits fail with `Cause.IllegalArgumentError`.
  * @returns An `Fx` that emits values from the inner streams.
  * @since 1.0.0
  * @category combinators
  */
-export declare const flatMapConcurrently: FlatMapLike<[concurrency: number]>;
+export declare const flatMapConcurrently: {
+    <A, B, E2, R2>(f: (a: A) => Fx<B, E2, R2>, concurrency: number): <E, R>(self: Fx<A, E, R>) => Fx<B, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
+    <A, E, R, B, E2, R2>(self: Fx<A, E, R>, f: (a: A) => Fx<B, E2, R2>, concurrency: number): Fx<B, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
+};
 //# sourceMappingURL=flatMapConcurrently.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"flatMapConcurrently.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMapConcurrently.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAkBlE,CAAC"}
+{"version":3,"file":"flatMapConcurrently.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMapConcurrently.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAKtC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAC1B,WAAW,EAAE,MAAM,GAClB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAEjG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAC1B,WAAW,EAAE,MAAM,GAClB,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CA4BrE,CAAC"}

package/dist/Fx/combinators/flatMapConcurrently.js

@@ -1,3 +1,4 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as FiberSet from "effect/FiberSet";
 import * as Semaphore from "effect/Semaphore";
@@ -8,13 +9,58 @@ import { extendScope } from "../internal/scope.js";
 /**
  * Maps each element of an Fx to a new Fx, running them concurrently with a limit.
  *
+ * @remarks
+ * ## Why
+ *
+ * This is the admission-controlled form of {@link flatMap}. It bounds active
+ * work while retaining every source value, which is appropriate when a remote
+ * service or local resource has a known concurrency budget.
+ *
+ * ## Concurrency, ordering, and buffering
+ *
+ * Each source value creates one child fiber. A semaphore admits at most
+ * `concurrency` inners into execution; excess fibers wait for a permit rather
+ * than being dropped. Values from each inner retain local order, but admitted
+ * inners may interleave and output is not reordered into source order.
+ *
+ * ## Ownership and lifetime
+ *
+ * A non-positive, fractional, infinite, or unsafe-integer limit fails through
+ * the Sink with `Cause.IllegalArgumentError`. Source and inner failures and
+ * services remain typed. The required `Scope` owns waiting and active fibers;
+ * source completion waits for all of them, and interruption cancels both groups
+ * and runs active inner finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const jobs = Fx.fromIterable([
+ *   { id: "one", wait: "20 millis" as const },
+ *   { id: "two", wait: "20 millis" as const },
+ *   { id: "three", wait: "1 millis" as const }
+ * ])
+ * const bounded = Fx.flatMapConcurrently(
+ *   jobs,
+ *   ({ id, wait }) => Fx.at(id, wait),
+ *   2
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(bounded))).then(console.log)
+ * // "three" waits for one of the first two permits despite its shorter delay
+ * ```
+ *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
- * @param concurrency - The maximum number of concurrent inner streams.
+ * @param concurrency - A positive safe-integer limit for concurrent inner streams. Invalid limits fail with `Cause.IllegalArgumentError`.
  * @returns An `Fx` that emits values from the inner streams.
  * @since 1.0.0
  * @category combinators
  */
 export const flatMapConcurrently = dual(3, (self, f, concurrency) => make(Effect.fn(function* (sink) {
+    if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {
+        return yield* sink.onFailure(Cause.fail(new Cause.IllegalArgumentError(`concurrency must be a positive safe integer, received ${concurrency}`)));
+    }
     const semaphore = yield* Semaphore.make(concurrency);
     const lock = semaphore.withPermits(1);
     const set = yield* FiberSet.make();

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

@@ -1,12 +1,56 @@
-import type { FlatMapEffectLike } from "./flatMapEffect.js";
+import type * as Cause from "effect/Cause";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import type { Fx } from "../Fx.js";
 /**
  * Maps each element of an Fx to an Effect, running them concurrently with a limit.
  *
+ * @remarks
+ * ## Why
+ *
+ * This Effect-producing bounded merge avoids manual `Fx.fromEffect` conversion
+ * while making the callback's concurrency budget part of the operation.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * Every source value eventually starts one callback Effect, with no more than
+ * `concurrency` active at once. Each success emits exactly one value. Waiting
+ * work is retained, and results arrive by completion rather than source order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Invalid limits fail with `Cause.IllegalArgumentError`; source and callback
+ * failures remain typed and callback services are added to requirements. The
+ * required `Scope` owns waiting and active Effects. Completion drains them;
+ * interruption cancels them and runs their finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const loaded = Fx.flatMapConcurrentlyEffect(
+ *   Fx.fromIterable([
+ *     { id: "one", wait: "20 millis" as const },
+ *     { id: "two", wait: "20 millis" as const },
+ *     { id: "three", wait: "1 millis" as const }
+ *   ]),
+ *   ({ id, wait }) => Effect.as(Effect.sleep(wait), id),
+ *   2
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(loaded))).then(console.log)
+ * // "three" remains queued until a permit is released
+ * ```
+ *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
- * @param concurrency - The maximum number of concurrent effects.
+ * @param concurrency - A positive safe-integer limit for concurrent effects. Invalid limits fail with `Cause.IllegalArgumentError`.
  * @returns An `Fx` that emits the results of the effects.
  * @since 1.0.0
  * @category combinators
  */
-export declare const flatMapConcurrentlyEffect: FlatMapEffectLike<[concurrency: number]>;
+export declare const flatMapConcurrentlyEffect: {
+    <A, B, E2, R2>(f: (a: A) => Effect.Effect<B, E2, R2>, concurrency: number): <E, R>(self: Fx<A, E, R>) => Fx<B, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
+    <A, E, R, B, E2, R2>(self: Fx<A, E, R>, f: (a: A) => Effect.Effect<B, E2, R2>, concurrency: number): Fx<B, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
+};
 //# sourceMappingURL=flatMapConcurrentlyEffect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"flatMapConcurrentlyEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMapConcurrentlyEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAiB,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAQ9E,CAAC"}
+{"version":3,"file":"flatMapConcurrentlyEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMapConcurrentlyEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,yBAAyB,EAAE;IACtC,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,EACrC,WAAW,EAAE,MAAM,GAClB,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAEjG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EACrC,WAAW,EAAE,MAAM,GAClB,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CASrE,CAAC"}

package/dist/Fx/combinators/flatMapConcurrentlyEffect.js

@@ -4,8 +4,46 @@ import { flatMapConcurrently } from "./flatMapConcurrently.js";
 /**
  * Maps each element of an Fx to an Effect, running them concurrently with a limit.
  *
+ * @remarks
+ * ## Why
+ *
+ * This Effect-producing bounded merge avoids manual `Fx.fromEffect` conversion
+ * while making the callback's concurrency budget part of the operation.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * Every source value eventually starts one callback Effect, with no more than
+ * `concurrency` active at once. Each success emits exactly one value. Waiting
+ * work is retained, and results arrive by completion rather than source order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Invalid limits fail with `Cause.IllegalArgumentError`; source and callback
+ * failures remain typed and callback services are added to requirements. The
+ * required `Scope` owns waiting and active Effects. Completion drains them;
+ * interruption cancels them and runs their finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const loaded = Fx.flatMapConcurrentlyEffect(
+ *   Fx.fromIterable([
+ *     { id: "one", wait: "20 millis" as const },
+ *     { id: "two", wait: "20 millis" as const },
+ *     { id: "three", wait: "1 millis" as const }
+ *   ]),
+ *   ({ id, wait }) => Effect.as(Effect.sleep(wait), id),
+ *   2
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(loaded))).then(console.log)
+ * // "three" remains queued until a permit is released
+ * ```
+ *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
- * @param concurrency - The maximum number of concurrent effects.
+ * @param concurrency - A positive safe-integer limit for concurrent effects. Invalid limits fail with `Cause.IllegalArgumentError`.
  * @returns An `Fx` that emits the results of the effects.
  * @since 1.0.0
  * @category combinators

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

@@ -2,7 +2,19 @@ import type * as Effect from "effect/Effect";
 import type * as Scope from "effect/Scope";
 import type { Fx } from "../Fx.js";
 /**
- * Type definition for flatMapEffect functions to support variable arguments.
+ * Describes a dual flattening operator whose callback returns an Effect.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared type gives Effect-producing merge, concat, switch, and exhaust
+ * operators the same data-first and data-last surface while retaining callback
+ * errors and services in the returned Fx.
+ *
+ * ## Ownership and lifetime
+ *
+ * The type acquires no resources. Implementations adapt each Effect to a
+ * one-value Fx whose execution is owned by the returned Fx's required `Scope`.
  * @since 1.0.0
  * @category types
  */
@@ -13,7 +25,37 @@ export type FlatMapEffectLike<Args extends ReadonlyArray<any> = []> = {
 /**
  * Maps each element of an Fx to an Effect, and merges the results.
  *
- * The effects are run concurrently.
+ * @remarks
+ * ## Why
+ *
+ * This is the Effect-producing form of {@link flatMap}. It admits independent
+ * Effects directly without callers manually applying `Fx.fromEffect`.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * Every source value starts one Effect with unbounded concurrency. Each
+ * successful Effect emits exactly one value. Results appear in completion order,
+ * not source order, and no output buffer restores ordering.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and callback failures remain typed and callback services are unioned
+ * with source services. The required `Scope` owns all running Effects; source
+ * completion waits for them, and interruption runs every Effect finalizer.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const loaded = Fx.flatMapEffect(Fx.fromIterable([
+ *   { id: "slow", wait: "20 millis" as const },
+ *   { id: "fast", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Effect.as(Effect.sleep(wait), id))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(loaded))).then(console.log)
+ * // ["fast", "slow"]
+ * ```
  *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
  * @returns An `Fx` that emits the results of the effects.

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

@@ -1 +1 @@
-{"version":3,"file":"flatMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMapEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;IACpE,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,EACrC,GAAG,IAAI,EAAE,IAAI,GACZ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EACrC,GAAG,IAAI,EAAE,IAAI,GACZ,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,iBAM3B,CAAC"}
+{"version":3,"file":"flatMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flatMapEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;IACpE,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,EACrC,GAAG,IAAI,EAAE,IAAI,GACZ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EACrC,GAAG,IAAI,EAAE,IAAI,GACZ,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,aAAa,EAAE,iBAM3B,CAAC"}

package/dist/Fx/combinators/flatMapEffect.js

@@ -4,7 +4,37 @@ import { flatMap } from "./flatMap.js";
 /**
  * Maps each element of an Fx to an Effect, and merges the results.
  *
- * The effects are run concurrently.
+ * @remarks
+ * ## Why
+ *
+ * This is the Effect-producing form of {@link flatMap}. It admits independent
+ * Effects directly without callers manually applying `Fx.fromEffect`.
+ *
+ * ## Concurrency, ordering, and cardinality
+ *
+ * Every source value starts one Effect with unbounded concurrency. Each
+ * successful Effect emits exactly one value. Results appear in completion order,
+ * not source order, and no output buffer restores ordering.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and callback failures remain typed and callback services are unioned
+ * with source services. The required `Scope` owns all running Effects; source
+ * completion waits for them, and interruption runs every Effect finalizer.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const loaded = Fx.flatMapEffect(Fx.fromIterable([
+ *   { id: "slow", wait: "20 millis" as const },
+ *   { id: "fast", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Effect.as(Effect.sleep(wait), id))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(loaded))).then(console.log)
+ * // ["fast", "slow"]
+ * ```
  *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
  * @returns An `Fx` that emits the results of the effects.

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

@@ -1,6 +1,38 @@
 import type { Fx } from "../Fx.js";
 /**
- * Flips the error and success channels of an Fx.
+ * Emits typed failures as values and fails with the first successful value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Channel inversion makes an error-producing computation composable through
+ * success operators, mirroring Effect's `flip` without erasing either type.
+ *
+ * ## Ownership and lifetime
+ *
+ * If a source Cause contains any Fail, the first typed error `e` is delivered
+ * as success and the entire Cause is discarded, including defects or interrupts
+ * composed beside that Fail. A Cause with no Fail propagates unchanged. A source
+ * success `a` terminates the returned Fx with typed failure `a`. The source
+ * subscription is the only lifetime and external interruption still stops it.
+ *
+ * @example
+ * ```ts
+ * import { flip } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const errorsAsValues = flip(fail("offline"))
+ * ```
+ *
+ * @example The first Fail wins over the rest of a composite Cause
+ * ```ts
+ * import { Cause } from "effect"
+ * import { flip } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("decoder defect"))
+ * const errorValue = flip(failCause(composite))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` where errors are successes and successes are errors.

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

@@ -1 +1 @@
-{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flip.ts"],"names":[],"mappings":"AAEA,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,CAAC,EAAE,CAAC,EAAE,CAAC,CACJ,CAAC"}
+{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/flip.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACJ,CAAC"}

package/dist/Fx/combinators/flip.js

@@ -1,7 +1,39 @@
 import * as sinkCore from "../../Sink/combinators.js";
 import { make } from "../constructors/make.js";
 /**
- * Flips the error and success channels of an Fx.
+ * Emits typed failures as values and fails with the first successful value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Channel inversion makes an error-producing computation composable through
+ * success operators, mirroring Effect's `flip` without erasing either type.
+ *
+ * ## Ownership and lifetime
+ *
+ * If a source Cause contains any Fail, the first typed error `e` is delivered
+ * as success and the entire Cause is discarded, including defects or interrupts
+ * composed beside that Fail. A Cause with no Fail propagates unchanged. A source
+ * success `a` terminates the returned Fx with typed failure `a`. The source
+ * subscription is the only lifetime and external interruption still stops it.
+ *
+ * @example
+ * ```ts
+ * import { flip } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const errorsAsValues = flip(fail("offline"))
+ * ```
+ *
+ * @example The first Fail wins over the rest of a composite Cause
+ * ```ts
+ * import { Cause } from "effect"
+ * import { flip } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("decoder defect"))
+ * const errorValue = flip(failCause(composite))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` where errors are successes and successes are errors.