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

package/dist/Fx/combinators/race.js

@@ -0,0 +1,149 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import { dual } from "effect/Function";
+import * as Ref from "effect/Ref";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { empty } from "../constructors/empty.js";
+import { make } from "../constructors/make.js";
+/**
+ * Runs two streams concurrently until one emits, then mirrors the winner and
+ * interrupts the other.
+ *
+ * A failure or completion from one side before the other emits does **not**
+ * win unless every side ends without emitting. After a winner is chosen, that
+ * stream's later failures are propagated.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `race` selects a live producer by its first useful value rather than by setup,
+ * completion, or a fast failure. This is suitable for redundant sources where a
+ * producer that ends silently should not prevent another from becoming useful.
+ *
+ * ## Selection, ordering, and cardinality
+ *
+ * Both inputs start concurrently. The first emitted value atomically selects its
+ * producer; that value and all later values from the winner are forwarded in
+ * order. The loser emits nothing after selection and is interrupted. There is no
+ * buffering or replay.
+ *
+ * ## Ownership and lifetime
+ *
+ * Before a winner, a non-interruption failure is remembered but does not win; it
+ * is reported only if both inputs end without a value. After selection, winner
+ * failures are forwarded. Both environments remain required. The observing
+ * fiber owns both child fibers and interruption cancels the race and finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const response = Fx.race(
+ *   Fx.ensuring(Fx.at("slow", "50 millis"), Effect.log("slow closed")),
+ *   Fx.ensuring(Fx.at("fast", "5 millis"), Effect.log("fast closed"))
+ * )
+ * Effect.runPromise(Fx.collectAll(response)).then(console.log)
+ * // "slow closed" proves loser cleanup; the winning finalizer also runs
+ * // resolves ["fast"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const race = dual(2, (self, that) => raceAll(self, that));
+/**
+ * Races many streams: the first to emit wins and the rest are interrupted.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `raceAll` extends {@link race} to a runtime-sized set while preserving the
+ * first-value selection rule.
+ *
+ * ## Selection, ordering, and cardinality
+ *
+ * All inputs start concurrently. The first emitted value selects one input and
+ * only that input's values are forwarded afterward. Zero inputs produce the
+ * empty Fx; one input is returned unchanged. No result buffer is retained.
+ *
+ * ## Ownership and lifetime
+ *
+ * Before selection, the first non-interruption failure is retained and reported
+ * only if every input ends without emitting. After selection, winner failures
+ * are forwarded. All environments are required. Losers are interrupted and the
+ * observing fiber owns cleanup for every child.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const response = Fx.raceAll(
+ *   Fx.at("cache", "30 millis"),
+ *   Fx.at("primary", "5 millis"),
+ *   Fx.at("replica", "20 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(response)).then(console.log)
+ * // ["primary"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const raceAll = (...fxs) => {
+    if (fxs.length === 0) {
+        return empty;
+    }
+    if (fxs.length === 1) {
+        return fxs[0];
+    }
+    return make((sink) => Effect.gen(function* () {
+        const winner = yield* SynchronizedRef.make(null);
+        const ended = yield* Ref.make(0);
+        const firstFail = yield* Ref.make(null);
+        const fibersRef = yield* Ref.make([]);
+        const interruptOthers = (except) => Effect.flatMap(Ref.get(fibersRef), (fibers) => Effect.forEach(fibers, (fiber, i) => (i === except ? Effect.void : Fiber.interrupt(fiber)), { discard: true }));
+        const markEnded = Effect.gen(function* () {
+            const current = yield* SynchronizedRef.get(winner);
+            if (current !== null)
+                return;
+            const n = yield* Ref.updateAndGet(ended, (count) => count + 1);
+            if (n === fxs.length) {
+                const cause = yield* Ref.get(firstFail);
+                if (cause !== null) {
+                    yield* sink.onFailure(cause);
+                }
+            }
+        });
+        const fibers = [];
+        for (let i = 0; i < fxs.length; i++) {
+            const fx = fxs[i];
+            const fiber = yield* Effect.forkChild(Effect.flatMap(SynchronizedRef.get(winner), (already) => already !== null
+                ? Effect.void
+                : fx
+                    .run(makeSink((cause) => Effect.flatMap(SynchronizedRef.get(winner), (w) => {
+                    if (w === i)
+                        return sink.onFailure(cause);
+                    if (w === null && !Cause.hasInterruptsOnly(cause)) {
+                        return Ref.update(firstFail, (prev) => prev ?? cause);
+                    }
+                    return Effect.void;
+                }), (a) => SynchronizedRef.updateEffect(winner, (w) => {
+                    if (w === null) {
+                        return interruptOthers(i).pipe(Effect.andThen(sink.onSuccess(a)), Effect.as(i));
+                    }
+                    if (w === i) {
+                        return sink.onSuccess(a).pipe(Effect.as(w));
+                    }
+                    return Effect.succeed(w);
+                })))
+                    .pipe(Effect.ensuring(markEnded))), { startImmediately: true, uninterruptible: false });
+            fibers.push(fiber);
+        }
+        yield* Ref.set(fibersRef, fibers);
+        yield* Effect.forEach(fibers, (fiber) => Fiber.join(fiber).pipe(Effect.catchCause(() => Effect.void)), { concurrency: "unbounded", discard: true });
+    }));
+};

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

@@ -0,0 +1,41 @@
+import * as Schedule from "effect/Schedule";
+import type { Fx } from "../Fx.js";
+/**
+ * Repeats the entire stream according to `schedule` after each successful
+ * completion. Failures are not repeated.
+ *
+ * `Schedule.recurs(n)` runs the stream `n + 1` times (the original plus `n`
+ * repeats), matching Effect `Stream.repeat`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Repetition is a subscription-level decision: after one producer completes,
+ * a Schedule decides whether and when a fresh run should begin. Keeping that
+ * decision in Effect's Schedule preserves typed timing services and failures.
+ *
+ * ## Ownership and lifetime
+ *
+ * Runs are strictly sequential. Every source value is forwarded before the
+ * Schedule is stepped with `void`; a successful step sleeps as configured and
+ * starts a new source run. A source failure stops immediately and is never
+ * repeated. Schedule failure is forwarded; Schedule completion ends normally.
+ * Interruption cancels the active source or schedule sleep. No runs overlap.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { repeat } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const threeTicks = repeat(succeed("tick"), Schedule.recurs(2))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const repeat: {
+    <X, E2, R2>(schedule: Schedule.Schedule<X, void, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+    <A, E, R, X, E2, R2>(self: Fx<A, E, R>, schedule: Schedule.Schedule<X, void, E2, R2>): Fx<A, E | E2, R | R2>;
+};
+//# sourceMappingURL=repeat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repeat.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/repeat.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAG5C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAC3C,CAAC,CAAC,EAAE,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,CAAC,CAAC;IACzD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAC3C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAoC1B,CAAC"}

package/dist/Fx/combinators/repeat.js

@@ -0,0 +1,57 @@
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import * as Pull from "effect/Pull";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { make } from "../constructors/make.js";
+/**
+ * Repeats the entire stream according to `schedule` after each successful
+ * completion. Failures are not repeated.
+ *
+ * `Schedule.recurs(n)` runs the stream `n + 1` times (the original plus `n`
+ * repeats), matching Effect `Stream.repeat`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Repetition is a subscription-level decision: after one producer completes,
+ * a Schedule decides whether and when a fresh run should begin. Keeping that
+ * decision in Effect's Schedule preserves typed timing services and failures.
+ *
+ * ## Ownership and lifetime
+ *
+ * Runs are strictly sequential. Every source value is forwarded before the
+ * Schedule is stepped with `void`; a successful step sleeps as configured and
+ * starts a new source run. A source failure stops immediately and is never
+ * repeated. Schedule failure is forwarded; Schedule completion ends normally.
+ * Interruption cancels the active source or schedule sleep. No runs overlap.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { repeat } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const threeTicks = repeat(succeed("tick"), Schedule.recurs(2))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const repeat = dual(2, (self, schedule) => make((sink) => Effect.gen(function* () {
+    const step = yield* Schedule.toStepWithSleep(schedule);
+    const failed = yield* Ref.make(false);
+    const run = () => self
+        .run(makeSink((cause) => Ref.set(failed, true).pipe(Effect.andThen(sink.onFailure(cause))), sink.onSuccess))
+        .pipe(Effect.flatMap(() => Effect.flatMap(Ref.get(failed), (didFail) => {
+        if (didFail)
+            return Effect.void;
+        return Pull.matchEffect(step(undefined), {
+            onSuccess: run,
+            onFailure: sink.onFailure,
+            onDone: () => Effect.void,
+        });
+    })));
+    yield* run();
+})));

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

@@ -14,6 +14,28 @@ import type { Fx } from "../Fx.js";
  * `Result<A, Cause<E>>`. Consumers can use `Result.match` or `Result.isSuccess` /
  * `Result.isFailure` to handle success vs failure (including defect/interrupt).
  *
+ * @remarks
+ * ## Why
+ *
+ * `Result` is convenient when success and failure should travel through one
+ * data channel, while retaining the complete Cause rather than flattening it
+ * into the typed error alone.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each source value emits one successful Result in order. A terminal cause
+ * emits one failed Result and ends normally. The source is subscribed once;
+ * no resource is acquired and an interrupt reported by the source becomes
+ * data, although interrupting the outer running fiber still stops the run.
+ *
+ * @example
+ * ```ts
+ * import { result } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const outcomes = result(fail("offline"))
+ * ```
+ *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Result<A, Cause<E>>`.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CACL,CAAC"}
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAM5F,CAAC"}

package/dist/Fx/combinators/result.js

@@ -13,20 +13,34 @@ import { make } from "../constructors/make.js";
  * `Result<A, Cause<E>>`. Consumers can use `Result.match` or `Result.isSuccess` /
  * `Result.isFailure` to handle success vs failure (including defect/interrupt).
  *
+ * @remarks
+ * ## Why
+ *
+ * `Result` is convenient when success and failure should travel through one
+ * data channel, while retaining the complete Cause rather than flattening it
+ * into the typed error alone.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each source value emits one successful Result in order. A terminal cause
+ * emits one failed Result and ends normally. The source is subscribed once;
+ * no resource is acquired and an interrupt reported by the source becomes
+ * data, although interrupting the outer running fiber still stops the run.
+ *
+ * @example
+ * ```ts
+ * import { result } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const outcomes = result(fail("offline"))
+ * ```
+ *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Result<A, Cause<E>>`.
  * @since 1.0.0
  * @category combinators
  */
-export const result = (fx) => make((sink) => fx.run(new ResultSink(sink)));
-class ResultSink {
-    sink;
-    onSuccess;
-    onFailure;
-    constructor(sink) {
-        this.sink = sink;
-        const s = sink;
-        this.onSuccess = (value) => s.onSuccess(Result.succeed(value));
-        this.onFailure = (cause) => s.onSuccess(Result.fail(cause));
-    }
-}
+export const result = (fx) => make((sink) => fx.run({
+    onSuccess: (value) => sink.onSuccess(Result.succeed(value)),
+    onFailure: (cause) => sink.onSuccess(Result.fail(cause)),
+}));

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

@@ -0,0 +1,53 @@
+import * as Schedule from "effect/Schedule";
+import type { Fx } from "../Fx.js";
+/**
+ * Retries the entire stream when its Cause contains a typed `Fail` accepted by
+ * `schedule`.
+ *
+ * The schedule is reset as soon as the first element of an attempt is emitted,
+ * matching Effect `Stream.retry`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Retrying the whole producer, rather than a single value callback, gives a
+ * Schedule the typed failure that ended an attempt and lets it control backoff.
+ *
+ * ## Ownership and lifetime
+ *
+ * Attempts are sequential and reuse the same downstream sink. The first Fail
+ * found anywhere in the Cause is offered to the Schedule, so a composite Cause
+ * containing that Fail can be retried even when it also contains defects or
+ * interrupts; starting a new attempt discards the whole prior Cause. A Cause
+ * without a Fail terminates immediately. Schedule completion re-emits the last
+ * source Cause, while Schedule failure terminates with its own cause. Emitting
+ * any value resets the Schedule. External interruption cancels the active
+ * attempt or backoff sleep.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { retry } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const retried = retry(fail("offline"), Schedule.recurs(2))
+ * ```
+ *
+ * @example A composite Cause is retryable when it contains a Fail
+ * ```ts
+ * import { Cause, Schedule } from "effect"
+ * import { retry } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("decoder defect"))
+ * const retried = retry(failCause(composite), Schedule.recurs(2))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const retry: {
+    <E, X, E2, R2>(schedule: Schedule.Schedule<X, E, E2, R2>): <A, R>(self: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+    <A, E, R, X, E2, R2>(self: Fx<A, E, R>, schedule: Schedule.Schedule<X, E, E2, R2>): Fx<A, E | E2, R | R2>;
+};
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/retry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAG5C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACxC,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,CAAC,CAAC;IACtD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACxC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAwC1B,CAAC"}

package/dist/Fx/combinators/retry.js

@@ -0,0 +1,71 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import * as Pull from "effect/Pull";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schedule from "effect/Schedule";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { make } from "../constructors/make.js";
+/**
+ * Retries the entire stream when its Cause contains a typed `Fail` accepted by
+ * `schedule`.
+ *
+ * The schedule is reset as soon as the first element of an attempt is emitted,
+ * matching Effect `Stream.retry`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Retrying the whole producer, rather than a single value callback, gives a
+ * Schedule the typed failure that ended an attempt and lets it control backoff.
+ *
+ * ## Ownership and lifetime
+ *
+ * Attempts are sequential and reuse the same downstream sink. The first Fail
+ * found anywhere in the Cause is offered to the Schedule, so a composite Cause
+ * containing that Fail can be retried even when it also contains defects or
+ * interrupts; starting a new attempt discards the whole prior Cause. A Cause
+ * without a Fail terminates immediately. Schedule completion re-emits the last
+ * source Cause, while Schedule failure terminates with its own cause. Emitting
+ * any value resets the Schedule. External interruption cancels the active
+ * attempt or backoff sleep.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { retry } from "@typed/fx/Fx"
+ * import { fail } from "@typed/fx/Fx"
+ *
+ * const retried = retry(fail("offline"), Schedule.recurs(2))
+ * ```
+ *
+ * @example A composite Cause is retryable when it contains a Fail
+ * ```ts
+ * import { Cause, Schedule } from "effect"
+ * import { retry } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("decoder defect"))
+ * const retried = retry(failCause(composite), Schedule.recurs(2))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const retry = dual(2, (self, schedule) => make((sink) => Effect.gen(function* () {
+    const stepRef = yield* Ref.make(yield* Schedule.toStepWithSleep(schedule));
+    const reset = Effect.flatMap(Schedule.toStepWithSleep(schedule), (step) => Ref.set(stepRef, step));
+    const attempt = () => self.run(makeSink((cause) => {
+        const found = Cause.findFail(cause);
+        if (Result.isFailure(found)) {
+            return sink.onFailure(cause);
+        }
+        return Effect.flatMap(Ref.get(stepRef), (step) => Pull.matchEffect(step(found.success.error), {
+            onSuccess: () => attempt(),
+            onFailure: (stepCause) => sink.onFailure(stepCause),
+            onDone: () => sink.onFailure(cause),
+        }));
+    }, (a) => reset.pipe(Effect.andThen(sink.onSuccess(a)))));
+    yield* attempt();
+})));

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

@@ -0,0 +1,31 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Emits the latest source value whenever `sampler` emits. Source values that
+ * arrive between sampler ticks are not forwarded until the next tick.
+ *
+ * **Completion:** Completes when the source completes.
+ * **Errors:** The first failure from either stream fails the result.
+ *
+ * @remarks
+ * ## Why
+ * `sample` separates value production from observation cadence. A sampler tick emits the latest
+ * source value once, or nothing before the source's first value; repeated ticks may repeat a value.
+ *
+ * ## Ownership and lifetime
+ * One latest-value cell and a child sampler fiber belong to each run. Source completion interrupts
+ * the sampler; any failure or consumer interruption stops both and releases the retained value.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const snapshots = Fx.sample(Fx.fromIterable([10, 20]), Fx.fromIterable(["tick"]))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const sample: {
+    <S, E2, R2>(sampler: Fx<S, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+    <A, E, R, S, E2, R2>(self: Fx<A, E, R>, sampler: Fx<S, E2, R2>): Fx<A, E | E2, R | R2>;
+};
+//# sourceMappingURL=sample.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sample.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/sample.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,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,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3F,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAyBxF,CAAC"}

package/dist/Fx/combinators/sample.js

@@ -0,0 +1,42 @@
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import { dual } from "effect/Function";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { make } from "../constructors/make.js";
+/**
+ * Emits the latest source value whenever `sampler` emits. Source values that
+ * arrive between sampler ticks are not forwarded until the next tick.
+ *
+ * **Completion:** Completes when the source completes.
+ * **Errors:** The first failure from either stream fails the result.
+ *
+ * @remarks
+ * ## Why
+ * `sample` separates value production from observation cadence. A sampler tick emits the latest
+ * source value once, or nothing before the source's first value; repeated ticks may repeat a value.
+ *
+ * ## Ownership and lifetime
+ * One latest-value cell and a child sampler fiber belong to each run. Source completion interrupts
+ * the sampler; any failure or consumer interruption stops both and releases the retained value.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const snapshots = Fx.sample(Fx.fromIterable([10, 20]), Fx.fromIterable(["tick"]))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const sample = dual(2, (self, sampler) => make(Effect.fn(function* (sink) {
+    const latest = yield* Ref.make(Option.none());
+    const samplerFiber = yield* Effect.forkChild(sampler.run(makeSink(sink.onFailure, () => Effect.flatMap(Ref.get(latest), (opt) => Option.match(opt, {
+        onNone: () => Effect.void,
+        onSome: (a) => sink.onSuccess(a),
+    })))));
+    yield* self
+        .run(makeSink(sink.onFailure, (a) => Ref.set(latest, Option.some(a))))
+        .pipe(Effect.ensuring(Fiber.interrupt(samplerFiber)));
+})));

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

@@ -6,6 +6,22 @@ import type { Fx } from "../Fx.js";
  *
  * Semantics align with Effect Stream's `scan`: output is `initial`, `f(initial, a1)`, `f(..., a2)`, ...
  *
+ * @remarks
+ * ## Why
+ * `scan` exposes every accumulated state, including `initial` before the source is run. For `n`
+ * inputs it emits `n + 1` states in order, making incremental reduction observable.
+ *
+ * ## Ownership and lifetime
+ * Each run owns an independent accumulator and releases it when the run ends. The pure reducer
+ * acquires no resources and preserves source failures, services, and interruption.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const totals = Fx.fromIterable([1, 2, 3]).pipe(Fx.scan(0, (sum, n) => sum + n))
+ * ```
+ *
  * @param initial - Initial state (first value emitted).
  * @param f - Reducer `(state, value) => nextState`.
  * @returns An `Fx` that emits the accumulated state at each step.
@@ -20,6 +36,29 @@ export declare const scan: {
  * Scans the stream with an effectful function, emitting the accumulated state after each element.
  * Emits the initial value first, then for each input `a` runs `f(state, a)` and emits the resulting state.
  *
+ * @remarks
+ * ## Why
+ * `scanEffect` permits a failing or service-backed accumulated transition and emits `initial`
+ * before subscribing. It does not serialize later producer callbacks: overlapping reductions can
+ * read the same state, finish out of order, and overwrite one another's next state.
+ *
+ * ## Ownership and lifetime
+ * One mutable accumulator is owned per run. Reducer Effects inherit producer concurrency and use
+ * the captured services. Failure is delivered to the Sink without committing that transition;
+ * interruption follows the invoking callback rather than locking the entire run.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const concurrent = Fx.make<number>((sink) =>
+ *   Effect.all([sink.onSuccess(1), sink.onSuccess(2)], { concurrency: "unbounded", discard: true })
+ * )
+ * const program = Fx.collectAll(concurrent.pipe(Fx.scanEffect(0, (sum, n) => Effect.succeed(sum + n))))
+ * // Both overlapping reductions may observe sum === 0; serialize the producer for atomic totals.
+ * ```
+ *
  * @param initial - Initial state (first value emitted).
  * @param f - Effectful reducer `(state, value) => Effect<nextState>`.
  * @returns An `Fx` that emits the accumulated state at each step.

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

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/scan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,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;IACjF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAe9E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,OAAO,EAAE,CAAC,EACV,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,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,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,OAAO,EAAE,CAAC,EACV,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAwB1B,CAAC"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/scan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,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;IACjF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAa9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACX,OAAO,EAAE,CAAC,EACV,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,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,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,OAAO,EAAE,CAAC,EACV,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAC1C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAwB1B,CAAC"}

package/dist/Fx/combinators/scan.js

@@ -8,6 +8,22 @@ import { make } from "../constructors/make.js";
  *
  * Semantics align with Effect Stream's `scan`: output is `initial`, `f(initial, a1)`, `f(..., a2)`, ...
  *
+ * @remarks
+ * ## Why
+ * `scan` exposes every accumulated state, including `initial` before the source is run. For `n`
+ * inputs it emits `n + 1` states in order, making incremental reduction observable.
+ *
+ * ## Ownership and lifetime
+ * Each run owns an independent accumulator and releases it when the run ends. The pure reducer
+ * acquires no resources and preserves source failures, services, and interruption.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const totals = Fx.fromIterable([1, 2, 3]).pipe(Fx.scan(0, (sum, n) => sum + n))
+ * ```
+ *
  * @param initial - Initial state (first value emitted).
  * @param f - Reducer `(state, value) => nextState`.
  * @returns An `Fx` that emits the accumulated state at each step.
@@ -25,6 +41,29 @@ export const scan = dual(3, (fx, initial, f) => make((sink) => Effect.gen(functi
  * Scans the stream with an effectful function, emitting the accumulated state after each element.
  * Emits the initial value first, then for each input `a` runs `f(state, a)` and emits the resulting state.
  *
+ * @remarks
+ * ## Why
+ * `scanEffect` permits a failing or service-backed accumulated transition and emits `initial`
+ * before subscribing. It does not serialize later producer callbacks: overlapping reductions can
+ * read the same state, finish out of order, and overwrite one another's next state.
+ *
+ * ## Ownership and lifetime
+ * One mutable accumulator is owned per run. Reducer Effects inherit producer concurrency and use
+ * the captured services. Failure is delivered to the Sink without committing that transition;
+ * interruption follows the invoking callback rather than locking the entire run.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const concurrent = Fx.make<number>((sink) =>
+ *   Effect.all([sink.onSuccess(1), sink.onSuccess(2)], { concurrency: "unbounded", discard: true })
+ * )
+ * const program = Fx.collectAll(concurrent.pipe(Fx.scanEffect(0, (sum, n) => Effect.succeed(sum + n))))
+ * // Both overlapping reductions may observe sum === 0; serialize the producer for atomic totals.
+ * ```
+ *
  * @param initial - Initial state (first value emitted).
  * @param f - Effectful reducer `(state, value) => Effect<nextState>`.
  * @returns An `Fx` that emits the accumulated state at each step.