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

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 Errors and recovery
+ */
+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 Errors and recovery
+ */
+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 Time and rate
+ */
+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 Time and rate
+ */
+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,11 +6,27 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const scan: {
     <S, A>(initial: S, f: (s: S, a: A) => S): <E, R>(fx: Fx<A, E, R>) => Fx<S, E, R>;
@@ -20,11 +36,34 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export declare const scanEffect: {
     <S, A, E2, R2>(initial: S, f: (s: S, a: A) => Effect.Effect<S, E2, R2>): <E, R>(fx: Fx<A, E, R>) => Fx<S, E | E2, R | R2>;

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,11 +8,27 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const scan = dual(3, (fx, initial, f) => make((sink) => Effect.gen(function* () {
     yield* sink.onSuccess(initial);
@@ -25,14 +41,37 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Stateful transforms
  */
 export const scanEffect = dual(3, (fx, initial, f) => make((sink) => Effect.gen(function* () {
-    const services = yield* Effect.services();
+    const services = yield* Effect.context();
     yield* sink.onSuccess(initial);
-    yield* fx.run(sinkLoopEffect(sink, initial, (s, a) => pipe(f(s, a), Effect.catchCause((cause) => sink.onFailure(cause).pipe(Effect.as(s))), Effect.map((next) => [next, next]), Effect.provideServices(services))));
+    yield* fx.run(sinkLoopEffect(sink, initial, (s, a) => pipe(f(s, a), Effect.catchCause((cause) => sink.onFailure(cause).pipe(Effect.as(s))), Effect.map((next) => [next, next]), Effect.provideContext(services))));
 })));

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

@@ -0,0 +1,30 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Drops `events` until `signal` emits, then forwards the rest.
+ *
+ * @remarks
+ * ## Why
+ * `since` uses one Fx as a start boundary for another. Events before the first signal are dropped;
+ * after it arrives, remaining events emit in their original order. Signal values are not emitted.
+ *
+ * ## Ownership and lifetime
+ * Event and signal runs share a child Scope. The signal observer fiber is forked but never joined:
+ * a signal failure ends that fiber and is discarded rather than delivered to the event Sink, so it
+ * does not stop events. Event completion closes the Scope; consumer interruption stops both runs.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * // This Effect succeeds with []; the failed signal neither opens the gate nor fails collection.
+ * const program = Fx.collectAll(Fx.since(Fx.fromIterable([1, 2]), Fx.fail("signal failed")))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const since: {
+    <B, E2, R2>(signal: Fx<B, E2, R2>): <A, E, R>(events: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+    <A, E, R, B, E2, R2>(events: Fx<A, E, R>, signal: Fx<B, E2, R2>): Fx<A, E | E2, R | R2>;
+};
+//# sourceMappingURL=since.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"since.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/since.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5F,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAsBzF,CAAC"}

package/dist/Fx/combinators/since.js

@@ -0,0 +1,39 @@
+import { Effect, Fiber, Scope } from "effect";
+import { dual } from "effect/Function";
+import { make } from "../constructors/make.js";
+import { observe } from "../run/observe.js";
+import { filter } from "./filter.js";
+/**
+ * Drops `events` until `signal` emits, then forwards the rest.
+ *
+ * @remarks
+ * ## Why
+ * `since` uses one Fx as a start boundary for another. Events before the first signal are dropped;
+ * after it arrives, remaining events emit in their original order. Signal values are not emitted.
+ *
+ * ## Ownership and lifetime
+ * Event and signal runs share a child Scope. The signal observer fiber is forked but never joined:
+ * a signal failure ends that fiber and is discarded rather than delivered to the event Sink, so it
+ * does not stop events. Event completion closes the Scope; consumer interruption stops both runs.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * // This Effect succeeds with []; the failed signal neither opens the gate nor fails collection.
+ * const program = Fx.collectAll(Fx.since(Fx.fromIterable([1, 2]), Fx.fail("signal failed")))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export const since = dual(2, (events, signal) => make(Effect.fn(function* (sink) {
+    let ready = false;
+    const scope = yield* Scope.make();
+    const eventsFiber = yield* Effect.forkIn(events.pipe(filter(() => ready)).run(sink), scope);
+    yield* signal.pipe(observe(() => {
+        ready = true;
+        return Effect.interrupt;
+    }), Effect.forkIn(scope));
+    yield* Fiber.join(eventsFiber).pipe(Effect.onExit((exit) => Scope.close(scope, exit)));
+})));

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

@@ -3,10 +3,25 @@ import type { Fx } from "../Fx.js";
 /**
  * Skips the first `n` elements of an Fx.
  *
+ * @remarks
+ * ## Why
+ * `skip` discards only the first `n` pushes, then forwards every later value in source order.
+ *
+ * ## Ownership and lifetime
+ * A counter is local to each run and no resource is acquired. Completion, failure, services, and
+ * interruption otherwise follow the source.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const tail = Fx.fromIterable([1, 2, 3]).pipe(Fx.skip(1))
+ * ```
+ *
  * @param n - The number of elements to skip.
  * @returns An `Fx` that emits values after the first `n` elements.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export declare const skip: {
     (n: number): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, R>;
@@ -15,10 +30,26 @@ export declare const skip: {
 /**
  * Skips the first `n` elements where `n` is produced by an Effect.
  *
+ * @remarks
+ * ## Why
+ * `skipEffect` obtains the prefix length at consumption time before subscribing to the source.
+ *
+ * ## Ownership and lifetime
+ * The count Effect runs once per run and can fail, require services, or be interrupted. The source
+ * is acquired only after the count succeeds.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const tail = Fx.fromIterable([1, 2]).pipe(Fx.skipEffect(Effect.succeed(1)))
+ * ```
+ *
  * @param count - Effect that produces the number of elements to skip.
  * @returns An `Fx` that emits values after the first `n` elements.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export declare const skipEffect: {
     <E2, R2>(count: Effect.Effect<number, E2, R2>): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;

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

@@ -1 +1 @@
-{"version":3,"file":"skip.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/skip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAIpD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,EAAE,EAAE,EAAE,EACL,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,GACnC,CAAC,CAAC,EAAE,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;IACvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAKjG,CAAC"}
+{"version":3,"file":"skip.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/skip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAGpD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,EAAE,EAAE,EAAE,EACL,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,GACnC,CAAC,CAAC,EAAE,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;IACvD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAKjG,CAAC"}

package/dist/Fx/combinators/skip.js

@@ -5,18 +5,49 @@ import { unwrap } from "./unwrap.js";
 /**
  * Skips the first `n` elements of an Fx.
  *
+ * @remarks
+ * ## Why
+ * `skip` discards only the first `n` pushes, then forwards every later value in source order.
+ *
+ * ## Ownership and lifetime
+ * A counter is local to each run and no resource is acquired. Completion, failure, services, and
+ * interruption otherwise follow the source.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const tail = Fx.fromIterable([1, 2, 3]).pipe(Fx.skip(1))
+ * ```
+ *
  * @param n - The number of elements to skip.
  * @returns An `Fx` that emits values after the first `n` elements.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export const skip = dual(2, (fx, n) => slice(fx, { skip: n, take: Infinity }));
 /**
  * Skips the first `n` elements where `n` is produced by an Effect.
  *
+ * @remarks
+ * ## Why
+ * `skipEffect` obtains the prefix length at consumption time before subscribing to the source.
+ *
+ * ## Ownership and lifetime
+ * The count Effect runs once per run and can fail, require services, or be interrupted. The source
+ * is acquired only after the count succeeds.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const tail = Fx.fromIterable([1, 2]).pipe(Fx.skipEffect(Effect.succeed(1)))
+ * ```
+ *
  * @param count - Effect that produces the number of elements to skip.
  * @returns An `Fx` that emits values after the first `n` elements.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export const skipEffect = dual(2, (fx, count) => unwrap(Effect.map(count, (n) => skip(fx, n))));

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

@@ -2,10 +2,26 @@ import type { Fx } from "../Fx.js";
 /**
  * Drops elements that are equal to the previous element using standard equality.
  *
+ * @remarks
+ * ## Why
+ * `skipRepeats` removes only consecutive duplicates using Effect's structural equality. The first
+ * value always emits; distinct values remain ordered, and a value may emit again after a change.
+ *
+ * ## Ownership and lifetime
+ * One previous value is retained for each run and released when it ends. The operation owns no
+ * external resource and preserves source errors, services, and interruption.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const distinctRuns = Fx.fromIterable([1, 1, 2, 1]).pipe(Fx.skipRepeats)
+ * ```
+ *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` with consecutive duplicates removed.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export declare const skipRepeats: <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, R>;
 //# sourceMappingURL=skipRepeats.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"skipRepeats.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/skipRepeats.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAKnC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAgB,CAAC"}
+{"version":3,"file":"skipRepeats.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/skipRepeats.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAKnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAgB,CAAC"}

package/dist/Fx/combinators/skipRepeats.js

@@ -4,9 +4,25 @@ const skipRepeats_ = skipRepeatsWith(equals);
 /**
  * Drops elements that are equal to the previous element using standard equality.
  *
+ * @remarks
+ * ## Why
+ * `skipRepeats` removes only consecutive duplicates using Effect's structural equality. The first
+ * value always emits; distinct values remain ordered, and a value may emit again after a change.
+ *
+ * ## Ownership and lifetime
+ * One previous value is retained for each run and released when it ends. The operation owns no
+ * external resource and preserves source errors, services, and interruption.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const distinctRuns = Fx.fromIterable([1, 1, 2, 1]).pipe(Fx.skipRepeats)
+ * ```
+ *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` with consecutive duplicates removed.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export const skipRepeats = skipRepeats_;

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

@@ -3,10 +3,27 @@ import type { Fx } from "../Fx.js";
 /**
  * Drops elements that are equal to the previous element using a custom equivalence function.
  *
+ * @remarks
+ * ## Why
+ * `skipRepeatsWith` defines consecutive equality for values that need domain-specific comparison.
+ * It compares against the last emitted value, emits the first value, and otherwise preserves order.
+ *
+ * ## Ownership and lifetime
+ * The per-run previous-value state is updated atomically and released when observation ends. The
+ * pure equivalence adds no failures or services and acquires no resource.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const byId = Fx.skipRepeatsWith<{ id: number }>((a, b) => a.id === b.id)
+ * const changes = Fx.fromIterable([{ id: 1 }, { id: 1 }, { id: 2 }]).pipe(byId)
+ * ```
+ *
  * @param Eq - The equivalence function to use.
  * @returns An `Fx` with consecutive duplicates removed.
  * @since 1.0.0
- * @category combinators
+ * @category Selecting values
  */
 export declare const skipRepeatsWith: <A>(Eq: Equivalence.Equivalence<A>) => <E, R>(fx: Fx<A, E, R>) => Fx<A, E, R>;
 //# sourceMappingURL=skipRepeatsWith.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"skipRepeatsWith.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/skipRepeatsWith.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,WAAW,MAAM,oBAAoB,CAAC;AAMvD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GACzB,CAAC,EAAE,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,MACjC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAoBhC,CAAC"}
+{"version":3,"file":"skipRepeatsWith.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/skipRepeatsWith.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,WAAW,MAAM,oBAAoB,CAAC;AAMvD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,eAAe,GACzB,CAAC,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,MACjC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAoBhC,CAAC"}