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

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

@@ -0,0 +1,76 @@
+import * as Duration from "effect/Duration";
+import type * as Scope from "effect/Scope";
+import type { Fx } from "../Fx.js";
+/**
+ * Completes the stream if it does not produce a value (or complete) within
+ * `duration` of the previous event. Matches Effect `Stream.timeout`.
+ *
+ * The timeout is reset after each emission. An infinite duration is a no-op;
+ * a zero duration completes immediately.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Silence is meaningful in push systems. This operator turns an idle period
+ * into normal completion without inventing an error type.
+ *
+ * ## Ownership and lifetime
+ *
+ * Subscription starts the source and one scoped timer. Each delivered value
+ * forwards immediately and rearms the timer. If the timer wins, it interrupts
+ * the source and the result completes; the interrupt caused by that timeout is
+ * not forwarded. Source failure before the deadline propagates. Interruption
+ * clears both source fiber and timer. Infinite duration returns the source;
+ * zero duration never starts it.
+ *
+ * @example
+ * ```ts
+ * import { timeout } from "@typed/fx/Fx"
+ * import { periodic } from "@typed/fx/Fx"
+ *
+ * const bounded = timeout(periodic("1 second"), "250 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const timeout: {
+    (duration: Duration.Input): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E, R | Scope.Scope>;
+    <A, E, R>(self: Fx<A, E, R>, duration: Duration.Input): Fx<A, E, R | Scope.Scope>;
+};
+/**
+ * Switches to `fallback` if the source does not produce a value within
+ * `duration` of the previous event. Matches Effect `Stream.timeoutOrElse`
+ * and RxJS `timeoutTo`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A fallback lets an idle producer hand ownership to another push source while
+ * preserving both sources' precise values, failures, and services.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source and resettable timer start first. On timeout the source is
+ * interrupted, then one fallback subscription starts; the two producers never
+ * overlap. A source failure before timeout propagates and does not start the
+ * fallback. Interruption stops the active producer and timer. Infinite duration
+ * returns the source unchanged; zero duration returns the fallback without
+ * starting the source.
+ *
+ * @example
+ * ```ts
+ * import { timeoutTo } from "@typed/fx/Fx"
+ * import { periodic, succeed } from "@typed/fx/Fx"
+ *
+ * const available = timeoutTo(periodic("1 second"), "250 millis", succeed("offline"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const timeoutTo: {
+    <B, E2, R2>(duration: Duration.Input, fallback: Fx<B, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A | B, E | E2, R | R2 | Scope.Scope>;
+    <A, E, R, B, E2, R2>(self: Fx<A, E, R>, duration: Duration.Input, fallback: Fx<B, E2, R2>): Fx<A | B, E | E2, R | R2 | Scope.Scope>;
+};
+//# sourceMappingURL=timeout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAM5C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAI3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AA6CnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACtF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CAMlF,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,QAAQ,EAAE,QAAQ,CAAC,KAAK,EACxB,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACtB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3E,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,KAAK,EACxB,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GACtB,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CAa5C,CAAC"}

package/dist/Fx/combinators/timeout.js

@@ -0,0 +1,110 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as FiberHandle from "effect/FiberHandle";
+import { dual } from "effect/Function";
+import * as Ref from "effect/Ref";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { empty } from "../constructors/empty.js";
+import { make } from "../constructors/make.js";
+import { extendScope } from "../internal/scope.js";
+const runTimed = (self, duration, fallback) => make(Effect.fn(function* (sink) {
+    const timedOut = yield* Ref.make(false);
+    const sourceFiber = yield* Ref.make(null);
+    const timer = yield* FiberHandle.make();
+    const onTimeout = Effect.gen(function* () {
+        yield* Ref.set(timedOut, true);
+        const fiber = yield* Ref.get(sourceFiber);
+        if (fiber)
+            yield* Fiber.interrupt(fiber);
+    });
+    const arm = FiberHandle.run(timer, Effect.sleep(duration).pipe(Effect.andThen(onTimeout)));
+    const fiber = yield* Effect.forkChild(self.run(makeSink((cause) => Effect.flatMap(Ref.get(timedOut), (didTimeout) => didTimeout ? Effect.void : sink.onFailure(cause)), (a) => sink.onSuccess(a).pipe(Effect.andThen(arm)))));
+    yield* Ref.set(sourceFiber, fiber);
+    yield* arm;
+    yield* Fiber.join(fiber).pipe(Effect.catchCause(() => Effect.void));
+    yield* FiberHandle.clear(timer);
+    if ((yield* Ref.get(timedOut)) && fallback !== undefined) {
+        yield* fallback.run(sink);
+    }
+}, extendScope));
+/**
+ * Completes the stream if it does not produce a value (or complete) within
+ * `duration` of the previous event. Matches Effect `Stream.timeout`.
+ *
+ * The timeout is reset after each emission. An infinite duration is a no-op;
+ * a zero duration completes immediately.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Silence is meaningful in push systems. This operator turns an idle period
+ * into normal completion without inventing an error type.
+ *
+ * ## Ownership and lifetime
+ *
+ * Subscription starts the source and one scoped timer. Each delivered value
+ * forwards immediately and rearms the timer. If the timer wins, it interrupts
+ * the source and the result completes; the interrupt caused by that timeout is
+ * not forwarded. Source failure before the deadline propagates. Interruption
+ * clears both source fiber and timer. Infinite duration returns the source;
+ * zero duration never starts it.
+ *
+ * @example
+ * ```ts
+ * import { timeout } from "@typed/fx/Fx"
+ * import { periodic } from "@typed/fx/Fx"
+ *
+ * const bounded = timeout(periodic("1 second"), "250 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export const timeout = dual(2, (self, duration) => {
+    const d = Duration.fromInputUnsafe(duration);
+    if (!Duration.isFinite(d))
+        return self;
+    if (Duration.isZero(d))
+        return empty;
+    return runTimed(self, d, undefined);
+});
+/**
+ * Switches to `fallback` if the source does not produce a value within
+ * `duration` of the previous event. Matches Effect `Stream.timeoutOrElse`
+ * and RxJS `timeoutTo`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A fallback lets an idle producer hand ownership to another push source while
+ * preserving both sources' precise values, failures, and services.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source and resettable timer start first. On timeout the source is
+ * interrupted, then one fallback subscription starts; the two producers never
+ * overlap. A source failure before timeout propagates and does not start the
+ * fallback. Interruption stops the active producer and timer. Infinite duration
+ * returns the source unchanged; zero duration returns the fallback without
+ * starting the source.
+ *
+ * @example
+ * ```ts
+ * import { timeoutTo } from "@typed/fx/Fx"
+ * import { periodic, succeed } from "@typed/fx/Fx"
+ *
+ * const available = timeoutTo(periodic("1 second"), "250 millis", succeed("offline"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export const timeoutTo = dual(3, (self, duration, fallback) => {
+    const d = Duration.fromInputUnsafe(duration);
+    if (!Duration.isFinite(d))
+        return self;
+    if (Duration.isZero(d))
+        return fallback;
+    return runTimed(self, d, fallback);
+});

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

@@ -4,10 +4,25 @@ import type { Fx } from "../Fx.js";
  * The resulting Fx waits for all input streams to emit at least once before emitting the first tuple.
  * Afterwards, it emits a new tuple whenever any input stream emits a new value.
  *
+ * @remarks
+ * ## Why
+ * `tuple` combines independent push sources by latest value while retaining their positional types.
+ * It emits nothing until every source has produced once, then emits a snapshot after any update.
+ *
+ * ## Ownership and lifetime
+ * All inputs run concurrently as children of the consumer and one latest value per input is retained
+ * for that run. Failure/interruption stops the group; normal completion waits for every input.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const point = Fx.tuple(Fx.succeed(10), Fx.succeed(20))
+ * ```
+ *
  * @param fxs - The Fx streams to combine.
  * @returns An `Fx` emitting tuples of values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare function tuple<FX extends ReadonlyArray<Fx<any, any, any>>>(...fxs: FX): Fx<{
     readonly [K in keyof FX]: Fx.Success<FX[K]>;
@@ -16,10 +31,25 @@ export declare function tuple<FX extends ReadonlyArray<Fx<any, any, any>>>(...fx
  * Combines a record of Fx streams into a single Fx that emits a record of the latest values.
  * Similar to `tuple`, but for objects.
  *
+ * @remarks
+ * ## Why
+ * `struct` gives latest-value combination stable field names. It waits for every field once and
+ * then emits a new immutable record when any field source updates.
+ *
+ * ## Ownership and lifetime
+ * It delegates concurrent ownership and retained latest values to `tuple`. Input failures and
+ * services are unioned, and all runs end with the consuming Fx.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const user = Fx.struct({ name: Fx.succeed("Ada"), online: Fx.succeed(true) })
+ * ```
+ *
  * @param fxs - A record of Fx streams.
  * @returns An `Fx` emitting records of values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare function struct<FXS extends Readonly<Record<string, Fx<any, any, any>>>>(fxs: FXS): Fx<{
     readonly [K in keyof FXS]: Fx.Success<FXS[K]>;

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

@@ -1 +1 @@
-{"version":3,"file":"tuple.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/tuple.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAC/D,GAAG,GAAG,EAAE,EAAE,GACT,EAAE,CACH;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CAAE,EAC/C,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EACpB,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CACxB,CA+BA;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,GAAG,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAC5E,GAAG,EAAE,GAAG,GACP,EAAE,CACH;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,EACjD,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,EACxB,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAC5B,CAOA"}
+{"version":3,"file":"tuple.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/tuple.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CAAC,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAC/D,GAAG,GAAG,EAAE,EAAE,GACT,EAAE,CACH;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CAAE,EAC/C,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EACpB,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CACxB,CAiCA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,MAAM,CAAC,GAAG,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAC5E,GAAG,EAAE,GAAG,GACP,EAAE,CACH;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,EACjD,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,EACxB,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAC5B,CAOA"}

package/dist/Fx/combinators/tuple.js

@@ -8,16 +8,32 @@ import { map } from "./map.js";
  * The resulting Fx waits for all input streams to emit at least once before emitting the first tuple.
  * Afterwards, it emits a new tuple whenever any input stream emits a new value.
  *
+ * @remarks
+ * ## Why
+ * `tuple` combines independent push sources by latest value while retaining their positional types.
+ * It emits nothing until every source has produced once, then emits a snapshot after any update.
+ *
+ * ## Ownership and lifetime
+ * All inputs run concurrently as children of the consumer and one latest value per input is retained
+ * for that run. Failure/interruption stops the group; normal completion waits for every input.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const point = Fx.tuple(Fx.succeed(10), Fx.succeed(20))
+ * ```
+ *
  * @param fxs - The Fx streams to combine.
  * @returns An `Fx` emitting tuples of values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export function tuple(...fxs) {
     if (fxs.length === 0)
         return succeed([]);
-    if (fxs.length === 1)
-        return fxs[0];
+    if (fxs.length === 1) {
+        return map(fxs[0], (value) => [value]);
+    }
     return make(Effect.fn(function* (sink) {
         const len = fxs.length;
         // oxlint-disable-next-line unicorn/no-new-array
@@ -27,7 +43,7 @@ export function tuple(...fxs) {
             result[i] = value;
             filled.add(i);
             if (filled.size === len) {
-                yield* sink.onSuccess(result);
+                yield* sink.onSuccess(result.slice(0));
             }
         }))), { concurrency: "unbounded", discard: true });
     }));
@@ -36,10 +52,25 @@ export function tuple(...fxs) {
  * Combines a record of Fx streams into a single Fx that emits a record of the latest values.
  * Similar to `tuple`, but for objects.
  *
+ * @remarks
+ * ## Why
+ * `struct` gives latest-value combination stable field names. It waits for every field once and
+ * then emits a new immutable record when any field source updates.
+ *
+ * ## Ownership and lifetime
+ * It delegates concurrent ownership and retained latest values to `tuple`. Input failures and
+ * services are unioned, and all runs end with the consuming Fx.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const user = Fx.struct({ name: Fx.succeed("Ada"), online: Fx.succeed(true) })
+ * ```
+ *
  * @param fxs - A record of Fx streams.
  * @returns An `Fx` emitting records of values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export function struct(fxs) {
     return map(tuple(...Object.entries(fxs).map(([key, fx]) => map(fx, (value) => [key, value]))), Object.fromEntries);

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

@@ -0,0 +1,27 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Forwards `events` until `signal` emits, then interrupts `events`.
+ *
+ * @remarks
+ * ## Why
+ * `until` gives an event source an external stop boundary. Event values retain their order until
+ * the first signal; the signal itself is not emitted and the event run then completes by interruption.
+ *
+ * ## Ownership and lifetime
+ * Both sources start behind one gate in a private Scope. Event completion cancels the signal;
+ * signaling cancels events; failures are forwarded unless they are the expected cancellation.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const bounded = Fx.until(Fx.fromIterable([1, 2, 3]), Fx.succeed("stop"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const until: {
+    <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=until.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"until.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/until.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;GAoBG;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;CAmEzF,CAAC"}

package/dist/Fx/combinators/until.js

@@ -0,0 +1,56 @@
+import { Cause, Deferred, Effect, Exit, Fiber, Ref, Scope } from "effect";
+import { dual } from "effect/Function";
+import { make } from "../constructors/make.js";
+import { observe } from "../run/observe.js";
+import { take } from "./take.js";
+/**
+ * Forwards `events` until `signal` emits, then interrupts `events`.
+ *
+ * @remarks
+ * ## Why
+ * `until` gives an event source an external stop boundary. Event values retain their order until
+ * the first signal; the signal itself is not emitted and the event run then completes by interruption.
+ *
+ * ## Ownership and lifetime
+ * Both sources start behind one gate in a private Scope. Event completion cancels the signal;
+ * signaling cancels events; failures are forwarded unless they are the expected cancellation.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const bounded = Fx.until(Fx.fromIterable([1, 2, 3]), Fx.succeed("stop"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export const until = dual(2, (events, signal) => make(Effect.fn(function* (sink) {
+    const scope = yield* Scope.make();
+    const cancellingSignal = yield* Ref.make(false);
+    yield* Effect.gen(function* () {
+        const startupGate = yield* Deferred.make();
+        const eventsFiberRef = yield* Ref.make(null);
+        const signaled = yield* Ref.make(false);
+        const stopEvents = Effect.uninterruptible(Effect.gen(function* () {
+            yield* Ref.set(signaled, true);
+            const eventsFiber = yield* Ref.get(eventsFiberRef);
+            if (eventsFiber !== null)
+                yield* Fiber.interrupt(eventsFiber);
+        }));
+        const signalFiber = yield* Effect.forkIn(Deferred.await(startupGate).pipe(Effect.andThen(signal.pipe(take(1), observe(() => stopEvents))), Effect.catchCause((cause) => Effect.flatMap(Ref.get(cancellingSignal), (didCancelSignal) => didCancelSignal
+            ? Effect.failCause(cause)
+            : Effect.uninterruptible(sink.onFailure(cause).pipe(Effect.andThen(stopEvents)))))), scope);
+        const eventsFiber = yield* Effect.forkIn(Deferred.await(startupGate).pipe(Effect.andThen(events.run(sink))), scope);
+        yield* Ref.set(eventsFiberRef, eventsFiber);
+        yield* Deferred.succeed(startupGate, undefined);
+        const eventsExit = yield* Fiber.await(eventsFiber);
+        yield* Ref.set(cancellingSignal, true);
+        yield* Fiber.interrupt(signalFiber);
+        if (Exit.isFailure(eventsExit)) {
+            const didSignal = yield* Ref.get(signaled);
+            if (!(didSignal && Cause.hasInterruptsOnly(eventsExit.cause))) {
+                return yield* Effect.failCause(eventsExit.cause);
+            }
+        }
+    }).pipe(Effect.onExit((exit) => Ref.set(cancellingSignal, true).pipe(Effect.andThen(Scope.close(scope, exit)))));
+})));

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

@@ -3,10 +3,39 @@ import type { Fx } from "../Fx.js";
 /**
  * Unwraps an Effect that produces an Fx into a single Fx.
  *
+ * @remarks
+ * ## Why
+ *
+ * `unwrap` defers choosing or acquiring a producer until observation, while
+ * keeping the Effect and the selected Fx in one typed push pipeline.
+ *
+ * ## Execution and cardinality
+ *
+ * Each observation runs `effect` once. On success, the produced Fx is observed
+ * and all of its values are forwarded in order. The acquisition Effect itself
+ * emits no value, and the inner is never started if acquisition fails.
+ *
+ * ## Ownership and lifetime
+ *
+ * Acquisition and inner failures are forwarded and both environments remain in
+ * the returned type. `unwrap` does not create a Scope or hide one: interruption
+ * stops whichever phase is active, and any resourceful Effect or inner Fx must
+ * expose and receive its own `Scope` requirement.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const selected = Fx.unwrap(
+ *   Effect.succeed(Fx.fromIterable(["ready", "running"]))
+ * )
+ * ```
+ *
  * @param effect - An `Effect` that produces an `Fx`.
  * @returns An `Fx` that runs the effect and then the produced Fx.
  * @since 1.0.0
- * @category combinators
+ * @category Generator composition
  */
-export declare const unwrap: <A, E, R, E2, R2>(effect: Effect.Effect<Fx<A, E, R>, E2, R2>) => Fx<A, E | E2, R | R2>;
+export declare const unwrap: <A = never, E = never, R = never, E2 = never, R2 = never>(effect: Effect.Effect<Fx<A, E, R>, E2, R2>) => Fx<A, E | E2, R | R2>;
 //# sourceMappingURL=unwrap.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"unwrap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/unwrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACpC,QAAQ,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,KACzC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAMpB,CAAC"}
+{"version":3,"file":"unwrap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/unwrap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,UACpE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,KACzC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAMpB,CAAC"}

package/dist/Fx/combinators/unwrap.js

@@ -3,10 +3,39 @@ import { make } from "../constructors/make.js";
 /**
  * Unwraps an Effect that produces an Fx into a single Fx.
  *
+ * @remarks
+ * ## Why
+ *
+ * `unwrap` defers choosing or acquiring a producer until observation, while
+ * keeping the Effect and the selected Fx in one typed push pipeline.
+ *
+ * ## Execution and cardinality
+ *
+ * Each observation runs `effect` once. On success, the produced Fx is observed
+ * and all of its values are forwarded in order. The acquisition Effect itself
+ * emits no value, and the inner is never started if acquisition fails.
+ *
+ * ## Ownership and lifetime
+ *
+ * Acquisition and inner failures are forwarded and both environments remain in
+ * the returned type. `unwrap` does not create a Scope or hide one: interruption
+ * stops whichever phase is active, and any resourceful Effect or inner Fx must
+ * expose and receive its own `Scope` requirement.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const selected = Fx.unwrap(
+ *   Effect.succeed(Fx.fromIterable(["ready", "running"]))
+ * )
+ * ```
+ *
  * @param effect - An `Effect` that produces an `Fx`.
  * @returns An `Fx` that runs the effect and then the produced Fx.
  * @since 1.0.0
- * @category combinators
+ * @category Generator composition
  */
 export const unwrap = (effect) => make((sink) => Effect.matchCauseEffect(effect, {
     onFailure: (cause) => sink.onFailure(cause),

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

@@ -6,10 +6,43 @@ import type { Fx } from "../Fx.js";
  *
  * The scope of the effect is closed when the Fx completes or is interrupted.
  *
+ * @remarks
+ * ## Why
+ *
+ * `unwrapScoped` is the safe boundary for an Effect that acquires resources
+ * while choosing an Fx. It discharges the inner `Scope` requirement instead of
+ * leaking acquisition lifetime to every consumer.
+ *
+ * ## Execution and cardinality
+ *
+ * Each observation opens one Scope, runs `effect` once, then forwards every
+ * value from the produced Fx in order. The inner never starts if acquisition
+ * fails, and the acquisition Effect adds no output value.
+ *
+ * ## Ownership and lifetime
+ *
+ * Acquisition and inner failures are forwarded. Non-Scope services from both
+ * phases remain required. The opened Scope owns resources acquired by both the
+ * Effect and produced Fx; it closes after normal completion, failure, or
+ * interruption, running finalizers exactly at the observation boundary.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const scoped = Fx.unwrapScoped(
+ *   Effect.acquireRelease(
+ *     Effect.succeed(Fx.succeed("connected")),
+ *     () => Effect.void
+ *   )
+ * )
+ * ```
+ *
  * @param effect - An `Effect` that produces an `Fx`.
  * @returns An `Fx` that runs the effect and then the produced Fx.
  * @since 1.0.0
- * @category combinators
+ * @category Generator composition
  */
 export declare const unwrapScoped: <A, E, R, E2, R2>(effect: Effect.Effect<Fx<A, E, R>, E2, R2 | Scope.Scope>) => Fx<A, E | E2, Exclude<R | R2, Scope.Scope>>;
 //# sourceMappingURL=unwrapScoped.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"unwrapScoped.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/unwrapScoped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAC1C,QAAQ,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,KACvD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAQ1C,CAAC"}
+{"version":3,"file":"unwrapScoped.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/unwrapScoped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,UAClC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,KACvD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAQ1C,CAAC"}

package/dist/Fx/combinators/unwrapScoped.js

@@ -5,10 +5,43 @@ import { make } from "../constructors/make.js";
  *
  * The scope of the effect is closed when the Fx completes or is interrupted.
  *
+ * @remarks
+ * ## Why
+ *
+ * `unwrapScoped` is the safe boundary for an Effect that acquires resources
+ * while choosing an Fx. It discharges the inner `Scope` requirement instead of
+ * leaking acquisition lifetime to every consumer.
+ *
+ * ## Execution and cardinality
+ *
+ * Each observation opens one Scope, runs `effect` once, then forwards every
+ * value from the produced Fx in order. The inner never starts if acquisition
+ * fails, and the acquisition Effect adds no output value.
+ *
+ * ## Ownership and lifetime
+ *
+ * Acquisition and inner failures are forwarded. Non-Scope services from both
+ * phases remain required. The opened Scope owns resources acquired by both the
+ * Effect and produced Fx; it closes after normal completion, failure, or
+ * interruption, running finalizers exactly at the observation boundary.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const scoped = Fx.unwrapScoped(
+ *   Effect.acquireRelease(
+ *     Effect.succeed(Fx.succeed("connected")),
+ *     () => Effect.void
+ *   )
+ * )
+ * ```
+ *
  * @param effect - An `Effect` that produces an `Fx`.
  * @returns An `Fx` that runs the effect and then the produced Fx.
  * @since 1.0.0
- * @category combinators
+ * @category Generator composition
  */
 export const unwrapScoped = (effect) => make((sink) => Effect.scoped(Effect.matchCauseEffect(effect, {
     onFailure: (cause) => sink.onFailure(cause),

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

@@ -3,11 +3,27 @@ import type { Fx } from "../Fx.js";
 /**
  * Conditionally runs one of two Fx streams based on the boolean value emitted by the condition stream.
  *
+ * @remarks
+ * ## Why
+ * `if` turns boolean pushes into a switchable branch. Each condition value selects one branch,
+ * interrupts the previous branch, and forwards only values from the currently selected Fx.
+ *
+ * ## Ownership and lifetime
+ * The required Scope owns the active branch. Replacement interrupts and awaits the previous branch;
+ * consumer interruption closes the active work. Failures are delivered to the Sink and only become
+ * terminal when the chosen Sink policy interrupts observation.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const status = Fx.if(Fx.fromIterable([true, false]), { onTrue: Fx.succeed("on"), onFalse: Fx.succeed("off") })
+ * ```
+ *
  * @param condition - An `Fx` emitting booleans.
  * @param matchers - An object containing `onTrue` and `onFalse` Fx streams.
  * @returns An `Fx` that switches between `onTrue` and `onFalse` based on the condition.
  * @since 1.0.0
- * @category combinators
+ * @category Conditional sources
  */
 declare const if_: {
     <B, E2, R2, C, E3, R3>(matchers: {
@@ -23,11 +39,30 @@ export { if_ as if };
 /**
  * Conditionally emits one of two values based on the boolean value emitted by the condition stream.
  *
+ * @remarks
+ * ## Why
+ * `when` is the value-only form of `if`, implemented with `switchMap`. Each condition push selects a
+ * constant inner Fx, but a newer condition can interrupt that inner before it emits; output
+ * cardinality can therefore be lower than the number of condition values.
+ *
+ * ## Ownership and lifetime
+ * It delegates branch switching to `if`; its constant branches acquire no resources. The Scope owns
+ * scheduled branch fibers, replacement awaits their interruption, and source completion waits for
+ * the latest selected branch.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const program = Fx.collectAll(
+ *   Fx.when(Fx.fromIterable([true, false]), { onTrue: "yes", onFalse: "no" })
+ * ) // the later `false` may replace `true` before "yes" is emitted
+ * ```
+ *
  * @param condition - An `Fx` emitting booleans.
  * @param matchers - An object containing `onTrue` and `onFalse` values.
  * @returns An `Fx` that emits the matched value.
  * @since 1.0.0
- * @category combinators
+ * @category Conditional sources
  */
 export declare const when: <E, R, B, C>(condition: Fx<boolean, E, R>, matchers: {
     onTrue: B;