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

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

@@ -0,0 +1,34 @@
+import { Fx } from "../Fx.js";
+import { Duration } from "effect";
+/**
+ * Delays every source value by `duration` while preserving its value and order.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Per-value delay is useful when pacing downstream work without changing the
+ * stream's error type or replacing the producer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each delivered value runs an Effect sleep before reaching the sink. Because
+ * this uses sequential effectful mapping, later values wait behind earlier
+ * sleeps and arrival order is preserved. Source failures propagate; interrupting
+ * the subscription interrupts the active sleep. No external resource is retained.
+ *
+ * @example
+ * ```ts
+ * import { delay } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const paced = delay(fromIterable([1, 2, 3]), "100 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const delay: {
+    (duration: Duration.Input): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E, R>;
+    <A, E, R>(self: Fx<A, E, R>, duration: Duration.Input): Fx<A, E, R>;
+};
+//# sourceMappingURL=delay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/delay.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAU,MAAM,QAAQ,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAGrE,CAAC"}

package/dist/Fx/combinators/delay.js

@@ -0,0 +1,31 @@
+import { dual } from "effect/Function";
+import { Effect } from "effect";
+import { mapEffect } from "./mapEffect.js";
+/**
+ * Delays every source value by `duration` while preserving its value and order.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Per-value delay is useful when pacing downstream work without changing the
+ * stream's error type or replacing the producer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each delivered value runs an Effect sleep before reaching the sink. Because
+ * this uses sequential effectful mapping, later values wait behind earlier
+ * sleeps and arrival order is preserved. Source failures propagate; interrupting
+ * the subscription interrupts the active sleep. No external resource is retained.
+ *
+ * @example
+ * ```ts
+ * import { delay } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const paced = delay(fromIterable([1, 2, 3]), "100 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const delay = dual(2, (self, duration) => mapEffect(self, (a) => Effect.as(Effect.sleep(duration), a)));

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

@@ -4,6 +4,22 @@ import type { Fx } from "../Fx.js";
  * Drops elements from an Fx until a predicate returns true.
  * Emits from the first element for which the predicate returns true (including that element) and all following elements.
  *
+ * @remarks
+ * ## Why
+ * `dropUntil` opens a one-way gate at the first matching value. The match and every later value emit
+ * once in source order; after opening, the predicate is no longer consulted.
+ *
+ * ## Ownership and lifetime
+ * The gate is local to one run and discarded on completion or interruption. No resources are
+ * acquired and the source's errors and services pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const ready = Fx.fromIterable([1, 2, 3]).pipe(Fx.dropUntil((n) => n >= 2))
+ * ```
+ *
  * @param predicate - The predicate function.
  * @returns An `Fx` that emits once the predicate first matches.
  * @since 1.0.0
@@ -17,6 +33,32 @@ export declare const dropUntil: {
  * Drops elements from an Fx until an effectful predicate returns true.
  * Emits from the first element for which the predicate effect succeeds with true (including that element) and all following elements.
  *
+ * @remarks
+ * ## Why
+ * `dropUntilEffect` makes the gate decision Effectful. The first `true` opens the gate and is
+ * forwarded, but its `skipWhileEffect` implementation eagerly evaluates the predicate for every
+ * later value as well; those later boolean results no longer affect forwarding.
+ *
+ * ## Ownership and lifetime
+ * The gate is per run. Predicate effects inherit producer ordering and concurrency, are interrupted
+ * with their invoking delivery, and expose `E2`/`R2`. Failures remain observable after the gate opens.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const checks = yield* Ref.make(0)
+ *   const values = yield* Fx.collectAll(
+ *     Fx.fromIterable([2, 3]).pipe(
+ *       Fx.dropUntilEffect((n) => Ref.update(checks, (count) => count + 1).pipe(Effect.as(n === 2)))
+ *     )
+ *   )
+ *   return { values, checks: yield* Ref.get(checks) } // { values: [2, 3], checks: 2 }
+ * })
+ * ```
+ *
  * @param predicate - Effectful predicate function.
  * @returns An `Fx` that emits once the predicate first matches.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"dropUntil.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/dropUntil.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAKvE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAClD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAClD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAO1B,CAAC"}
+{"version":3,"file":"dropUntil.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/dropUntil.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAGvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAClD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAClD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAO1B,CAAC"}

package/dist/Fx/combinators/dropUntil.js

@@ -5,6 +5,22 @@ import { skipWhile, skipWhileEffect } from "./skipWhile.js";
  * Drops elements from an Fx until a predicate returns true.
  * Emits from the first element for which the predicate returns true (including that element) and all following elements.
  *
+ * @remarks
+ * ## Why
+ * `dropUntil` opens a one-way gate at the first matching value. The match and every later value emit
+ * once in source order; after opening, the predicate is no longer consulted.
+ *
+ * ## Ownership and lifetime
+ * The gate is local to one run and discarded on completion or interruption. No resources are
+ * acquired and the source's errors and services pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const ready = Fx.fromIterable([1, 2, 3]).pipe(Fx.dropUntil((n) => n >= 2))
+ * ```
+ *
  * @param predicate - The predicate function.
  * @returns An `Fx` that emits once the predicate first matches.
  * @since 1.0.0
@@ -15,6 +31,32 @@ export const dropUntil = dual(2, (fx, predicate) => skipWhile(fx, (a) => !predic
  * Drops elements from an Fx until an effectful predicate returns true.
  * Emits from the first element for which the predicate effect succeeds with true (including that element) and all following elements.
  *
+ * @remarks
+ * ## Why
+ * `dropUntilEffect` makes the gate decision Effectful. The first `true` opens the gate and is
+ * forwarded, but its `skipWhileEffect` implementation eagerly evaluates the predicate for every
+ * later value as well; those later boolean results no longer affect forwarding.
+ *
+ * ## Ownership and lifetime
+ * The gate is per run. Predicate effects inherit producer ordering and concurrency, are interrupted
+ * with their invoking delivery, and expose `E2`/`R2`. Failures remain observable after the gate opens.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const checks = yield* Ref.make(0)
+ *   const values = yield* Fx.collectAll(
+ *     Fx.fromIterable([2, 3]).pipe(
+ *       Fx.dropUntilEffect((n) => Ref.update(checks, (count) => count + 1).pipe(Effect.as(n === 2)))
+ *     )
+ *   )
+ *   return { values, checks: yield* Ref.get(checks) } // { values: [2, 3], checks: 2 }
+ * })
+ * ```
+ *
  * @param predicate - Effectful predicate function.
  * @returns An `Fx` that emits once the predicate first matches.
  * @since 1.0.0

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

@@ -0,0 +1,38 @@
+import * as Scope from "effect/Scope";
+import type { Fx } from "../Fx.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 combinators
+ */
+export declare function during<A, E, R, Start extends Fx.Any, E2, R2>(events: Fx<A, E, R>, signals: Fx<Start, E2, R2>): Fx<A, E | E2 | Fx.Error<Start>, R | R2 | Fx.Services<Start> | Scope.Scope>;
+//# sourceMappingURL=during.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"during.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/during.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAKnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EAC1D,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACnB,OAAO,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,GACzB,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAoF5E"}

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 combinators
+ */
+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,10 +1,40 @@
 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

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,10 +2,40 @@ 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

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

@@ -1,10 +1,46 @@
 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.

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,11 +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, 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.

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

@@ -1,8 +1,44 @@
 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.

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,9 +2,45 @@ 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.