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

package/dist/Fx/combinators/during.js

@@ -0,0 +1,85 @@
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Scope from "effect/Scope";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { make } from "../constructors/make.js";
+import { take } from "./take.js";
+/**
+ * Forwards `events` only between a start signal and that signal's first stop event.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Push lifetimes are often controlled by other push lifetimes: a pointer move
+ * matters between pointer-down and pointer-up, for example. `during` models
+ * that gate without converting either side into polling state.
+ *
+ * ## Ownership and lifetime
+ *
+ * `events` and the outer `signals` Fx start concurrently in one child Scope.
+ * Only the first outer value is used; that value must itself be an Fx, whose
+ * first value closes the gate. Event values before the start signal and after
+ * the stop signal are discarded. Completion of `events` completes the result.
+ * A failure from events, signals, or the selected stop Fx terminates everything;
+ * closing or interrupting the returned Fx interrupts all remaining fibers and
+ * closes the private Scope.
+ *
+ * @example
+ * ```ts
+ * import { during } from "@typed/fx/Fx"
+ * import { delay } from "@typed/fx/Fx"
+ * import { periodic, succeed } from "@typed/fx/Fx"
+ *
+ * const pointerMoves = periodic("16 millis")
+ * const pointerDown = succeed(delay(succeed(undefined), "1 second"))
+ * const activeMoves = during(pointerMoves, pointerDown)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export function during(events, signals) {
+    return make(Effect.fn(function* (sink) {
+        const scope = yield* Scope.make();
+        yield* Effect.gen(function* () {
+            const eventsGate = yield* Deferred.make();
+            let phase = "waiting";
+            let stoppedEvents = false;
+            const eventsFiber = yield* Effect.forkIn(Deferred.await(eventsGate).pipe(Effect.andThen(events.run(makeSink((cause) => Effect.suspend(() => {
+                if (phase === "stopped")
+                    return Effect.void;
+                phase = "stopped";
+                return sink.onFailure(cause);
+            }), (value) => Effect.suspend(() => phase === "active" ? sink.onSuccess(value) : Effect.void))))), scope, { startImmediately: true, uninterruptible: false });
+            const stopEvents = Effect.uninterruptible(Effect.suspend(() => {
+                if (phase !== "active")
+                    return Effect.void;
+                phase = "stopped";
+                stoppedEvents = true;
+                return Fiber.interrupt(eventsFiber);
+            }));
+            const failAndStopEvents = (cause) => Effect.uninterruptible(Effect.suspend(() => {
+                if (phase === "stopped")
+                    return Effect.void;
+                phase = "stopped";
+                stoppedEvents = true;
+                return sink.onFailure(cause).pipe(Effect.andThen(Fiber.interrupt(eventsFiber)));
+            }));
+            yield* Effect.forkIn(take(signals, 1).run(makeSink(failAndStopEvents, (stopSignal) => Effect.suspend(() => {
+                if (phase !== "waiting")
+                    return Effect.void;
+                phase = "active";
+                return Effect.asVoid(Effect.forkIn(take(stopSignal, 1).run(makeSink(failAndStopEvents, () => stopEvents)), scope, { startImmediately: true, uninterruptible: false }));
+            }))), scope, { startImmediately: true, uninterruptible: false });
+            yield* Deferred.succeed(eventsGate, undefined);
+            const eventsExit = yield* Fiber.await(eventsFiber);
+            if (Exit.isFailure(eventsExit) &&
+                !(stoppedEvents && Cause.hasInterruptsOnly(eventsExit.cause))) {
+                return yield* Effect.failCause(eventsExit.cause);
+            }
+        }).pipe(Effect.onExit((exit) => Scope.close(scope, exit)));
+    }));
+}

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

@@ -1,13 +1,43 @@
 import * as Effect from "effect/Effect";
 import type { Fx } from "../Fx.js";
 /**
- * Adds an `Effect.ensuring`-style finalizer to an `Fx`.
+ * Runs a finalizer with no typed error after the Fx run ends for any reason.
  *
- * The finalizer is guaranteed to run when the stream terminates (success,
- * failure, or interruption).
+ * @remarks
+ * ## Why
+ *
+ * Resources sometimes belong to the subscription as a whole rather than to
+ * individual values. `ensuring` attaches unconditional teardown without
+ * changing the source's success or typed-error channels.
+ *
+ * ## Ownership and lifetime
+ *
+ * The finalizer runs exactly once after normal completion, failure, defect, or
+ * interruption of the source run and follows Effect's `ensuring` finalization
+ * semantics. Its `never` typed-error channel does not make it incapable of
+ * defecting or being interrupted: a finalizer defect can fail a successful run
+ * or combine with the source Cause. Its services are required for the subscription.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { ensuring } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const observed = ensuring(succeed("ready"), Effect.log("subscription closed"))
+ * ```
+ *
+ * @example A `never` typed-error channel can still contain a defect
+ * ```ts
+ * import { Effect } from "effect"
+ * import { ensuring } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const defectiveFinalizer = ensuring(succeed("ready"), Effect.die("close failed"))
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Resource lifetime
  */
 export declare const ensuring: {
     <R2>(finalizer: Effect.Effect<void, never, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E, R | R2>;

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

@@ -1 +1 @@
-{"version":3,"file":"ensuring.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/ensuring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAElG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAK/F,CAAC"}
+{"version":3,"file":"ensuring.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/ensuring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAElG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAK/F,CAAC"}

package/dist/Fx/combinators/ensuring.js

@@ -2,12 +2,42 @@ import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
 import { make } from "../constructors/make.js";
 /**
- * Adds an `Effect.ensuring`-style finalizer to an `Fx`.
+ * Runs a finalizer with no typed error after the Fx run ends for any reason.
  *
- * The finalizer is guaranteed to run when the stream terminates (success,
- * failure, or interruption).
+ * @remarks
+ * ## Why
+ *
+ * Resources sometimes belong to the subscription as a whole rather than to
+ * individual values. `ensuring` attaches unconditional teardown without
+ * changing the source's success or typed-error channels.
+ *
+ * ## Ownership and lifetime
+ *
+ * The finalizer runs exactly once after normal completion, failure, defect, or
+ * interruption of the source run and follows Effect's `ensuring` finalization
+ * semantics. Its `never` typed-error channel does not make it incapable of
+ * defecting or being interrupted: a finalizer defect can fail a successful run
+ * or combine with the source Cause. Its services are required for the subscription.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { ensuring } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const observed = ensuring(succeed("ready"), Effect.log("subscription closed"))
+ * ```
+ *
+ * @example A `never` typed-error channel can still contain a defect
+ * ```ts
+ * import { Effect } from "effect"
+ * import { ensuring } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const defectiveFinalizer = ensuring(succeed("ready"), Effect.die("close failed"))
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Resource lifetime
  */
 export const ensuring = dual(2, (self, finalizer) => make((sink) => self.run(sink).pipe(Effect.ensuring(finalizer))));

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

@@ -1,15 +1,51 @@
 import type { FlatMapLike } from "./flatMap.js";
 /**
- * Maps each element of an Fx to a new Fx, but only runs one inner Fx at a time.
- * If a new element arrives while an inner Fx is running, the new element is buffered (overwriting any previously buffered value).
- * When the current inner Fx completes, the latest buffered Fx is run.
+ * Maps each element to an inner Fx, running one now and retaining only the latest waiting value.
  *
- * This is useful for scenarios where you want to ignore intermediate values but ensure the latest value is eventually processed.
+ * @remarks
+ * ## Why
+ *
+ * `exhaustLatestMap` fits work that cannot overlap but must eventually reflect
+ * the newest request. Unlike {@link exhaustMap}, it remembers one pending value;
+ * unlike {@link concatMap}, it does not let a backlog grow.
+ *
+ * ## Admission, buffering, and cardinality
+ *
+ * The first value while idle starts immediately. While that inner runs, each new
+ * value replaces the single pending inner Effect; replaced values never run.
+ * When the active inner completes, the latest pending inner starts. An admitted
+ * inner may emit any number of values, in that inner's order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted-inner failures are forwarded and both environments remain
+ * typed. The required `Scope` owns every active inner fiber. Source completion
+ * waits until the active and final pending inner finish; interruption closes the
+ * Scope and runs inner finalizers. The one-slot pending buffer retains work, not
+ * emitted output.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const refreshes = Fx.mergeAll(
+ *   Fx.at("v1", "0 millis"),
+ *   Fx.at("v2", "5 millis"),
+ *   Fx.at("v3", "10 millis")
+ * )
+ * const latestEventually = Fx.exhaustLatestMap(refreshes, (version) =>
+ *   Fx.at(`indexed:${version}`, "20 millis")
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(latestEventually))).then(console.log)
+ * // ["indexed:v1", "indexed:v3"]
+ * ```
  *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from the inner streams.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export declare const exhaustLatestMap: FlatMapLike;
 //# sourceMappingURL=exhaustLatestMap.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"exhaustLatestMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustLatestMap.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAmD9B,CAAC"}
+{"version":3,"file":"exhaustLatestMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustLatestMap.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAmD9B,CAAC"}

package/dist/Fx/combinators/exhaustLatestMap.js

@@ -5,16 +5,52 @@ 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, but only runs one inner Fx at a time.
- * If a new element arrives while an inner Fx is running, the new element is buffered (overwriting any previously buffered value).
- * When the current inner Fx completes, the latest buffered Fx is run.
+ * Maps each element to an inner Fx, running one now and retaining only the latest waiting value.
  *
- * This is useful for scenarios where you want to ignore intermediate values but ensure the latest value is eventually processed.
+ * @remarks
+ * ## Why
+ *
+ * `exhaustLatestMap` fits work that cannot overlap but must eventually reflect
+ * the newest request. Unlike {@link exhaustMap}, it remembers one pending value;
+ * unlike {@link concatMap}, it does not let a backlog grow.
+ *
+ * ## Admission, buffering, and cardinality
+ *
+ * The first value while idle starts immediately. While that inner runs, each new
+ * value replaces the single pending inner Effect; replaced values never run.
+ * When the active inner completes, the latest pending inner starts. An admitted
+ * inner may emit any number of values, in that inner's order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted-inner failures are forwarded and both environments remain
+ * typed. The required `Scope` owns every active inner fiber. Source completion
+ * waits until the active and final pending inner finish; interruption closes the
+ * Scope and runs inner finalizers. The one-slot pending buffer retains work, not
+ * emitted output.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const refreshes = Fx.mergeAll(
+ *   Fx.at("v1", "0 millis"),
+ *   Fx.at("v2", "5 millis"),
+ *   Fx.at("v3", "10 millis")
+ * )
+ * const latestEventually = Fx.exhaustLatestMap(refreshes, (version) =>
+ *   Fx.at(`indexed:${version}`, "20 millis")
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(latestEventually))).then(console.log)
+ * // ["indexed:v1", "indexed:v3"]
+ * ```
  *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from the inner streams.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export const exhaustLatestMap = dual(2, (self, f) => {
     return make(Effect.fn(function* (sink) {

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

@@ -1,13 +1,49 @@
 import type { FlatMapEffectLike } from "./flatMapEffect.js";
 /**
- * Maps each element of an Fx to an Effect, but only runs one effect at a time.
- * If a new element arrives while an effect is running, the new element is buffered (overwriting any previously buffered value).
- * When the current effect completes, the latest buffered effect is run.
+ * Maps each element to an Effect, running one now and retaining only the latest waiting value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the Effect-producing form of {@link exhaustLatestMap}: it serializes
+ * Effects while bounding pending work to one replaceable latest request.
+ *
+ * ## Admission, buffering, and cardinality
+ *
+ * The first value while idle starts one Effect. While it runs, each callback is
+ * evaluated and the constructed Effect replaces the single pending Effect. Each
+ * admitted Effect emits exactly one successful result; superseded pending
+ * Effects never run and emit nothing.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted Effect failures remain typed, as do callback service
+ * requirements. The required `Scope` owns the active Effect; source completion
+ * drains the final pending value, while interruption discards pending work and
+ * runs active finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const refreshes = Fx.mergeAll(
+ *   Fx.at("v1", "0 millis"),
+ *   Fx.at("v2", "5 millis"),
+ *   Fx.at("v3", "10 millis")
+ * )
+ * const indexed = Fx.exhaustLatestMapEffect(refreshes, (version) =>
+ *   Effect.as(Effect.sleep("20 millis"), `indexed:${version}`)
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(indexed))).then(console.log)
+ * // ["indexed:v1", "indexed:v3"]
+ * ```
  *
  * @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 exhaustLatestMapEffect: FlatMapEffectLike;
 //# sourceMappingURL=exhaustLatestMapEffect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"exhaustLatestMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustLatestMapEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAMpC,CAAC"}
+{"version":3,"file":"exhaustLatestMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustLatestMapEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAMpC,CAAC"}

package/dist/Fx/combinators/exhaustLatestMapEffect.js

@@ -2,13 +2,49 @@ import { dual, flow } from "effect/Function";
 import { fromEffect } from "../constructors/fromEffect.js";
 import { exhaustLatestMap } from "./exhaustLatestMap.js";
 /**
- * Maps each element of an Fx to an Effect, but only runs one effect at a time.
- * If a new element arrives while an effect is running, the new element is buffered (overwriting any previously buffered value).
- * When the current effect completes, the latest buffered effect is run.
+ * Maps each element to an Effect, running one now and retaining only the latest waiting value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the Effect-producing form of {@link exhaustLatestMap}: it serializes
+ * Effects while bounding pending work to one replaceable latest request.
+ *
+ * ## Admission, buffering, and cardinality
+ *
+ * The first value while idle starts one Effect. While it runs, each callback is
+ * evaluated and the constructed Effect replaces the single pending Effect. Each
+ * admitted Effect emits exactly one successful result; superseded pending
+ * Effects never run and emit nothing.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted Effect failures remain typed, as do callback service
+ * requirements. The required `Scope` owns the active Effect; source completion
+ * drains the final pending value, while interruption discards pending work and
+ * runs active finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const refreshes = Fx.mergeAll(
+ *   Fx.at("v1", "0 millis"),
+ *   Fx.at("v2", "5 millis"),
+ *   Fx.at("v3", "10 millis")
+ * )
+ * const indexed = Fx.exhaustLatestMapEffect(refreshes, (version) =>
+ *   Effect.as(Effect.sleep("20 millis"), `indexed:${version}`)
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(indexed))).then(console.log)
+ * // ["indexed:v1", "indexed:v3"]
+ * ```
  *
  * @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 exhaustLatestMapEffect = dual(2, (self, f) => exhaustLatestMap(self, flow(f, fromEffect)));

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

@@ -2,10 +2,47 @@ import type { FlatMapLike } from "./flatMap.js";
 /**
  * Maps each element of an Fx to a new Fx, ignoring new elements until the current inner Fx completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * `exhaustMap` is an admission policy for work that must never overlap and does
+ * not need a backlog, such as ignoring repeated submit events while one submit
+ * is running.
+ *
+ * ## Admission, ordering, and cardinality
+ *
+ * The first source value observed while idle admits one inner Fx. For values
+ * arriving while it runs, `f` is still evaluated to construct an inner, but that
+ * inner is not run and no value is queued. Every admitted inner may emit any
+ * number of values in its own order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted-inner failures are forwarded and their services remain
+ * typed. A `FiberHandle` in the required `Scope` owns the active inner. Source
+ * completion waits for that inner; interruption closes the handle and the
+ * inner's child Scope, running its finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const submits = Fx.mergeAll(
+ *   Fx.at("first", "0 millis"),
+ *   Fx.at("ignored while busy", "5 millis"),
+ *   Fx.at("later", "30 millis")
+ * )
+ * const accepted = Fx.exhaustMap(submits, (command) => Fx.at(command, "20 millis"))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["first", "later"]
+ * ```
+ *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from the active inner stream.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export declare const exhaustMap: FlatMapLike;
 //# sourceMappingURL=exhaustMap.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"exhaustMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMap.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,WAiBxB,CAAC"}
+{"version":3,"file":"exhaustMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMap.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,UAAU,EAAE,WAiBxB,CAAC"}

package/dist/Fx/combinators/exhaustMap.js

@@ -7,10 +7,47 @@ import { extendScope } from "../internal/scope.js";
 /**
  * Maps each element of an Fx to a new Fx, ignoring new elements until the current inner Fx completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * `exhaustMap` is an admission policy for work that must never overlap and does
+ * not need a backlog, such as ignoring repeated submit events while one submit
+ * is running.
+ *
+ * ## Admission, ordering, and cardinality
+ *
+ * The first source value observed while idle admits one inner Fx. For values
+ * arriving while it runs, `f` is still evaluated to construct an inner, but that
+ * inner is not run and no value is queued. Every admitted inner may emit any
+ * number of values in its own order.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and admitted-inner failures are forwarded and their services remain
+ * typed. A `FiberHandle` in the required `Scope` owns the active inner. Source
+ * completion waits for that inner; interruption closes the handle and the
+ * inner's child Scope, running its finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const submits = Fx.mergeAll(
+ *   Fx.at("first", "0 millis"),
+ *   Fx.at("ignored while busy", "5 millis"),
+ *   Fx.at("later", "30 millis")
+ * )
+ * const accepted = Fx.exhaustMap(submits, (command) => Fx.at(command, "20 millis"))
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["first", "later"]
+ * ```
+ *
  * @param f - A function that maps an element `A` to a new `Fx<B>`.
  * @returns An `Fx` that emits values from the active inner stream.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export const exhaustMap = dual(2, (self, f) => make(Effect.fn(function* (sink) {
     const handle = yield* FiberHandle.make();

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

@@ -2,10 +2,42 @@ import type { FlatMapEffectLike } from "./flatMapEffect.js";
 /**
  * Maps each element of an Fx to an Effect, ignoring new elements until the current effect completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * This Effect-producing form of {@link exhaustMap} prevents overlapping command
+ * Effects while deliberately applying no queue or latest-value replay policy.
+ *
+ * ## Admission and cardinality
+ *
+ * The first value while idle starts one Effect and emits its one successful
+ * result. For values received while it runs, `f` is still evaluated to construct
+ * an Effect, but that Effect is not run or queued.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and callback Effect failures remain typed and callback services are
+ * added to the output requirements. The active Effect is owned by the returned
+ * Fx's required `Scope`; completion waits for it and interruption runs its
+ * finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const accepted = Fx.exhaustMapEffect(Fx.fromIterable([1, 2]), (id) =>
+ *   Effect.as(Effect.sleep("20 millis"), `saved:${id}`)
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["saved:1"]: the second Effect is constructed but not admitted
+ * ```
+ *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
  * @returns An `Fx` that emits the results of the active effect.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export declare const exhaustMapEffect: FlatMapEffectLike;
 //# sourceMappingURL=exhaustMapEffect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"exhaustMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMapEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAM9B,CAAC"}
+{"version":3,"file":"exhaustMapEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/exhaustMapEffect.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAM9B,CAAC"}

package/dist/Fx/combinators/exhaustMapEffect.js

@@ -4,9 +4,41 @@ import { exhaustMap } from "./exhaustMap.js";
 /**
  * Maps each element of an Fx to an Effect, ignoring new elements until the current effect completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * This Effect-producing form of {@link exhaustMap} prevents overlapping command
+ * Effects while deliberately applying no queue or latest-value replay policy.
+ *
+ * ## Admission and cardinality
+ *
+ * The first value while idle starts one Effect and emits its one successful
+ * result. For values received while it runs, `f` is still evaluated to construct
+ * an Effect, but that Effect is not run or queued.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and callback Effect failures remain typed and callback services are
+ * added to the output requirements. The active Effect is owned by the returned
+ * Fx's required `Scope`; completion waits for it and interruption runs its
+ * finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const accepted = Fx.exhaustMapEffect(Fx.fromIterable([1, 2]), (id) =>
+ *   Effect.as(Effect.sleep("20 millis"), `saved:${id}`)
+ * )
+ *
+ * Effect.runPromise(Effect.scoped(Fx.collectAll(accepted))).then(console.log)
+ * // ["saved:1"]: the second Effect is constructed but not admitted
+ * ```
+ *
  * @param f - A function that maps an element `A` to an `Effect<B>`.
  * @returns An `Fx` that emits the results of the active effect.
  * @since 1.0.0
- * @category combinators
+ * @category Concurrent work
  */
 export const exhaustMapEffect = dual(2, (self, f) => exhaustMap(self, flow(f, fromEffect)));

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

@@ -1,12 +1,33 @@
 import type * as Exit from "effect/Exit";
 import type { Fx } from "../Fx.js";
 /**
- * Materializes the success and failure of an Fx into `Exit` values.
+ * Materializes every success and the terminal failure as infallible `Exit` values.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Turning both channels into data lets downstream Fx composition inspect
+ * complete Effect causes without terminating the pipeline.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each source value becomes `Exit.succeed` in arrival order. A source failure,
+ * including a defect or interrupt, becomes one `Exit.failCause`, after which
+ * the returned Fx completes with error type `never`. It acquires no resource
+ * beyond the single source subscription.
+ *
+ * @example
+ * ```ts
+ * import { exit } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const outcomes = exit(fail("offline"))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Exit<A, E>`.
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export declare const exit: <A, E, R>(fx: Fx<A, E, R>) => Fx<Exit.Exit<A, E>, never, R>;
 //# sourceMappingURL=exit.d.ts.map

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

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