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

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

@@ -1,23 +1,68 @@
 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
+ * @category Type contracts
  */
 export type FlatMapLike<Args extends ReadonlyArray<any> = []> = {
     <A, B, E2, R2>(f: (a: A) => Fx<B, E2, R2>, ...args: Args): <E, R>(self: Fx<A, E, R>) => Fx<B, E | E2, R | R2 | Scope.Scope>;
     <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.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export declare const flatMap: FlatMapLike;
 //# sourceMappingURL=flatMap.d.ts.map

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,14 +5,47 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export const flatMap = dual(2, (self, f) => make(Effect.fn(function* (sink) {
     const set = yield* FiberSet.make();

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
+ * @category Concurrent work
  */
-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
+ * @category Concurrent work
  */
 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
+ * @category Concurrent work
  */
-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,10 +4,48 @@ 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
+ * @category Concurrent work
  */
 export const flatMapConcurrentlyEffect = dual(3, (self, f, concurrency) => flatMapConcurrently(self, flow(f, fromEffect), concurrency));

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

@@ -2,9 +2,21 @@ 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
+ * @category Type contracts
  */
 export type FlatMapEffectLike<Args extends ReadonlyArray<any> = []> = {
     <A, B, E2, R2>(f: (a: A) => Effect.Effect<B, E2, R2>, ...args: Args): <E, R>(self: Fx<A, E, R>) => Fx<B, E | E2, R | R2 | Scope.Scope>;
@@ -13,12 +25,42 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export declare const flatMapEffect: FlatMapEffectLike;
 //# sourceMappingURL=flatMapEffect.d.ts.map

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,11 +4,41 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export const flatMapEffect = dual(2, (self, f) => flatMap(self, flow(f, fromEffect)));

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

@@ -1,11 +1,43 @@
 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.
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export declare const flip: <A, E, R>(fx: Fx<A, E, R>) => Fx<E, A, R>;
 //# sourceMappingURL=flip.d.ts.map

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,11 +1,43 @@
 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.
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const flip = (fx) => make((sink) => fx.run(sinkCore.flip(sink)));