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

package/dist/Fx/combinators/filterMapLoopCauseEffect.js

@@ -4,10 +4,30 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const filterMapLoopCauseEffect = dual(3, (self, seed, f) => make((sink) => self.run(sinkCore.filterMapLoopCauseEffect(sink, seed, f))));

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

@@ -4,11 +4,31 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const filterMapLoopEffect: {
     <B, A, E2, R2, C>(seed: B, f: (acc: B, a: A) => Effect.Effect<readonly [Option.Option<C>, B], E2, R2>): <E, R>(self: Fx<A, E | E2, R>) => Fx<C, E | E2, R | R2>;

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,10 +4,30 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const filterMapLoopEffect = dual(3, (self, seed, f) => make((sink) => self.run(sinkCore.filterMapLoopEffect(sink, seed, f))));

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":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAgBlE,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,5 +1,7 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as FiberSet from "effect/FiberSet";
+import * as Semaphore from "effect/Semaphore";
 import { dual } from "effect/Function";
 import { make as makeSink } from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
@@ -7,16 +9,61 @@ 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) {
-    const semaphore = yield* Effect.makeSemaphore(concurrency);
+    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();
-    yield* self.run(makeSink(sink.onFailure, (a) => FiberSet.run(set, lock(f(a).run(sink)))));
+    yield* self.run(makeSink(sink.onFailure, (a) => FiberSet.run(set, lock(Effect.asVoid(f(a).run(sink))))));
     yield* FiberSet.awaitEmpty(set);
 }, extendScope)));

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)));