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

package/dist/Fx/combinators/provide.js

@@ -3,18 +3,42 @@ import * as Exit from "effect/Exit";
 import { dual } from "effect/Function";
 import * as Layer from "effect/Layer";
 import * as Scope from "effect/Scope";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import { make } from "../constructors/make.js";
 /**
- * Provides context to an Fx from a Layer.
+ * Builds a Layer for each subscription and provides it to the entire Fx run.
  *
- * The context is provided to the entire Fx stream, including any effects run
- * during its execution. The context is scoped to the lifetime of the stream.
+ * @remarks
+ * ## Why
+ *
+ * Fx preserves Effect service requirements in `R`; providing a Layer closes
+ * those requirements while retaining acquisition failures and dependencies in
+ * the resulting type.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each subscription creates a private Scope and builds the Layer inside it
+ * before the source starts. A build failure is sent to the sink and the source
+ * never runs. Otherwise the built Context is available to every source Effect,
+ * and the Scope closes with the source's success, failure, defect, or
+ * interruption. Provided services are removed from `R`; Layer dependencies and
+ * errors are added.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect, Layer } from "effect"
+ * import { provide } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, ({ url }) => url))
+ * const runnable = provide(request, Layer.succeed(Config, { url: "/api" }))
+ * ```
  *
  * @param layer - The Layer to provide.
  * @returns An `Fx` with the required context provided.
  * @since 1.0.0
- * @category combinators
+ * @category Providing services
  */
 export const provide = dual(2, (fx, layer) => make(Effect.fnUntraced(function* (sink) {
     const scope = yield* Scope.make();
@@ -23,32 +47,129 @@ export const provide = dual(2, (fx, layer) => make(Effect.fnUntraced(function* (
         yield* Scope.close(scope, servicesExit);
         return yield* sink.onFailure(servicesExit.cause);
     }
-    return yield* fx.run(sink).pipe(Effect.provideServices(servicesExit.value), Effect.onExit((exit) => Scope.close(scope, exit)));
+    return yield* fx.run(sink).pipe(Effect.provideContext(servicesExit.value), Effect.onExit((exit) => Scope.close(scope, exit)));
 })));
-export const provideServices = dual(2, (fx, services) => provide(fx, Layer.succeedServices(services)));
 /**
- * Provides a single service to an Fx.
+ * Provides an already-built Effect Context to the entire Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Callers that already own service instances should not rebuild them through a
+ * resourceful Layer merely to satisfy an Fx's environment.
  *
- * Equivalent to `provideServices(fx, ServiceMap.make(tag, service))`. The service
- * is available for the entire Fx stream, scoped to the stream lifetime.
+ * ## Ownership and lifetime
+ *
+ * The Context is captured when this combinator is created and reused for each
+ * subscription. Its services are available to all source Effects and removed
+ * from `R`. This function does not acquire or release those service values;
+ * their owner must keep them valid for every subscription that uses the result.
+ * Source completion, failure, and interruption are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideContext } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const context = Context.make(Config, { url: "/api" })
+ * const runnable = provideContext(fromEffect(Effect.map(Config, (x) => x.url)), context)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Providing services
+ */
+export const provideContext = dual(2, (fx, services) => provide(fx, Layer.succeedContext(services)));
+/**
+ * Provides one existing service value to the entire Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the precise single-service form of {@link provideContext}, useful for
+ * tests and application edges where the instance is already owned.
+ *
+ * ## Ownership and lifetime
+ *
+ * The service value is captured and reused for every subscription. It is not
+ * acquired or finalized here; its caller owns its lifetime. The matching
+ * service identifier is removed from `R`, while values, errors, ordering, and
+ * interruption remain those of the source.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideService } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const runnable = provideService(
+ *   fromEffect(Effect.map(Config, (x) => x.url)),
+ *   Config,
+ *   { url: "/api" }
+ * )
+ * ```
  *
  * @param tag - The service tag (identifier).
  * @param service - The service implementation.
  * @returns An `Fx` with the required service provided.
  * @since 1.0.0
- * @category combinators
+ * @category Providing services
  */
-export const provideService = dual(3, (fx, tag, service) => provideServices(fx, ServiceMap.make(tag, service)));
+export const provideService = dual(3, (fx, tag, service) => provideContext(fx, Context.make(tag, service)));
 /**
- * Provides a single service to an Fx by running an effect that produces the service.
+ * Acquires one service with an Effect before running the Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Some service instances require effectful configuration but do not warrant a
+ * separately named Layer. This keeps acquisition failure and dependencies
+ * explicit in the returned Fx type.
+ *
+ * ## Ownership and lifetime
+ *
+ * The service Effect runs once per subscription while {@link provide} builds
+ * its Layer. A failure prevents the source from starting. On success, the
+ * service is available for the whole source run and its identifier is removed
+ * from `R`; acquisition errors and every requirement in `R2` are added. In
+ * particular, an `Effect.acquireRelease` service Effect still leaves
+ * `Scope.Scope` in the returned Fx requirements—the private Layer Scope does
+ * not erase that public requirement. The caller must provide that Scope.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideServiceEffect } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, (x) => x.url))
+ * const runnable = provideServiceEffect(request, Config, Effect.succeed({ url: "/api" }))
+ * ```
+ *
+ * @example Scoped acquisition keeps `Scope` in the returned Fx requirements
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideServiceEffect } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ * import { collectAll } from "@typed/fx/Fx"
  *
- * The effect is run when the Fx is run; the resulting service is provided to the
- * entire stream. Equivalent to `provide(fx, Layer.effect(tag, serviceEffect))`.
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, (x) => x.url))
+ * const acquired = Effect.acquireRelease(
+ *   Effect.succeed({ url: "/api" }),
+ *   () => Effect.void
+ * )
+ * const scopedFx = provideServiceEffect(request, Config, acquired)
+ * const program = Effect.scoped(collectAll(scopedFx))
+ * ```
  *
  * @param tag - The service tag (identifier).
  * @param serviceEffect - Effect that produces the service (may have its own requirements).
  * @returns An `Fx` with the required service provided.
  * @since 1.0.0
- * @category combinators
+ * @category Providing services
  */
 export const provideServiceEffect = dual(3, (fx, tag, serviceEffect) => provide(fx, Layer.effect(tag, serviceEffect)));

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

@@ -0,0 +1,92 @@
+import type { Fx } from "../Fx.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 Concurrent work
+ */
+export declare const race: {
+    <AR, ER, RR>(that: Fx<AR, ER, RR>): <AL, EL, RL>(self: Fx<AL, EL, RL>) => Fx<AL | AR, EL | ER, RL | RR>;
+    <AL, EL, RL, AR, ER, RR>(self: Fx<AL, EL, RL>, that: Fx<AR, ER, RR>): Fx<AL | AR, EL | ER, RL | RR>;
+};
+/**
+ * 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 Concurrent work
+ */
+export declare const raceAll: <FX extends ReadonlyArray<Fx<any, any, any>>>(...fxs: FX) => Fx<Fx.Success<FX[number]>, Fx.Error<FX[number]>, Fx.Services<FX[number]>>;
+//# sourceMappingURL=race.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"race.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/race.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACxG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EACrB,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACpB,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GACnB,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;CAOlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,OAAO,GAAI,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,UACzD,EAAE,KACT,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAwF1E,CAAC"}

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 Concurrent work
+ */
+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 Concurrent work
+ */
+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 Time and rate
+ */
+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 Time and rate
+ */
+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,10 +14,32 @@ 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
- * @category combinators
+ * @category Errors and recovery
  */
 export declare const result: <A, E, R>(fx: Fx<A, E, R>) => Fx<Result.Result<A, Cause.Cause<E>>, never, R>;
 //# sourceMappingURL=result.d.ts.map

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
+ * @category Errors and recovery
  */
-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)),
+}));