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

package/dist/Fx/combinators/tapEffect.js

@@ -5,10 +5,26 @@ import { make } from "../constructors/make.js";
 /**
  * Performs an effect for each element of the Fx, without changing the elements.
  *
+ * @remarks
+ * ## Why
+ * `tap` sequences an observation or side effect before forwarding each original value. It emits
+ * exactly once per successful callback, in source order; callback failure prevents that value.
+ *
+ * ## Ownership and lifetime
+ * Returned Effects run in the consumer path and are interrupted with it; a `void` callback is
+ * treated as `Effect.void`. Callback failures and services remain visible in the result type.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ * const logged = Fx.fromIterable([1, 2]).pipe(Fx.tap((n) => Effect.log(n)))
+ * ```
+ *
  * @param f - An effectful function to apply to each element.
  * @returns An `Fx` that emits the original elements.
  * @since 1.0.0
- * @category combinators
+ * @category Transforming values
  */
 export const tap = dual(2, (self, f) => make((sink) => self.run(sinkCore.tapEffect(sink, (a) => {
     const x = f(a);

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

@@ -0,0 +1,79 @@
+import { Duration, Scope } from "effect";
+import type { Fx } from "../Fx.js";
+/**
+ * Options for {@link throttle}. A duration-only call is leading-edge
+ * (`{ leading: true, trailing: false }`).
+ *
+ * @remarks
+ * ## Why
+ *
+ * Leading and trailing edges answer different interaction needs, so the
+ * window policy is explicit rather than hidden behind separate operators.
+ *
+ * ## Ownership and lifetime
+ *
+ * This immutable value owns no resource. `throttle` reads it when constructing
+ * the Fx; the resulting subscription owns the timer and pending value.
+ *
+ * @example
+ * ```ts
+ * import type { ThrottleOptions } from "@typed/fx/Fx"
+ *
+ * const options: ThrottleOptions = {
+ *   duration: "250 millis",
+ *   leading: true,
+ *   trailing: true
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Operator options
+ */
+export type ThrottleOptions = {
+    readonly duration: Duration.Input;
+    readonly leading?: boolean | undefined;
+    readonly trailing?: boolean | undefined;
+};
+/**
+ * Limits emissions to configured leading and trailing edges of fixed windows.
+ *
+ * Pass `{ duration, leading, trailing }` for trailing or both-edge behavior.
+ * A duration alone defaults to `{ leading: true, trailing: false }`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Throttling bounds push frequency while allowing immediate feedback, a final
+ * settled value, or both, without moving timing state outside the Fx graph.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first value opens a window. Leading mode emits it immediately. Values
+ * arriving while open replace one pending latest value; trailing mode emits
+ * that value when the timer closes, except that both-edge mode does not repeat
+ * the first value unless another arrived. Windows never overlap. Source errors
+ * propagate, source completion waits for the active window, and interruption
+ * stops the scoped timer and discards pending state.
+ *
+ * @example
+ * ```ts
+ * import { throttle } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const bounded = throttle(fromIterable([1, 2, 3]), {
+ *   duration: "250 millis",
+ *   leading: true,
+ *   trailing: true
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const throttle: {
+    (duration: Duration.Input): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, R | Scope.Scope>;
+    (options: ThrottleOptions): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, R | Scope.Scope>;
+    <A, E, R>(fx: Fx<A, E, R>, duration: Duration.Input): Fx<A, E, R | Scope.Scope>;
+    <A, E, R>(fx: Fx<A, E, R>, options: ThrottleOptions): Fx<A, E, R | Scope.Scope>;
+};
+//# sourceMappingURL=throttle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/throttle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAOjD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAKnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC,CAAC;AAsEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,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,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACpF,CAAC,OAAO,EAAE,eAAe,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,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACpF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,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;IAChF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CAoBjF,CAAC"}

package/dist/Fx/combinators/throttle.js

@@ -0,0 +1,99 @@
+import { Duration, Effect } from "effect";
+import * as FiberHandle from "effect/FiberHandle";
+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";
+import { isFx } from "../TypeId.js";
+import { exhaustMap } from "./exhaustMap.js";
+import { extendScope } from "../internal/scope.js";
+const isOptions = (u) => typeof u === "object" && u !== null && "duration" in u && !Duration.isDuration(u);
+const resolve = (durationOrOptions) => {
+    if (isOptions(durationOrOptions)) {
+        return {
+            duration: durationOrOptions.duration,
+            leading: durationOrOptions.leading ?? true,
+            trailing: durationOrOptions.trailing ?? false,
+        };
+    }
+    return { duration: durationOrOptions, leading: true, trailing: false };
+};
+const throttleWindow = (fx, duration, leading, trailing) => make(Effect.fn(function* (sink) {
+    const open = yield* Ref.make(false);
+    const pending = yield* Ref.make(Option.none());
+    const extra = yield* Ref.make(false);
+    const window = yield* FiberHandle.make();
+    const closeWindow = Effect.gen(function* () {
+        const hadExtra = yield* Ref.get(extra);
+        const shouldEmit = trailing && (!leading || hadExtra) ? yield* Ref.get(pending) : Option.none();
+        yield* Ref.set(open, false);
+        yield* Ref.set(pending, Option.none());
+        yield* Ref.set(extra, false);
+        if (Option.isSome(shouldEmit)) {
+            yield* sink.onSuccess(shouldEmit.value);
+        }
+    });
+    yield* fx.run(makeSink(sink.onFailure, (a) => Effect.gen(function* () {
+        const isOpen = yield* Ref.get(open);
+        if (!isOpen) {
+            yield* Ref.set(open, true);
+            yield* Ref.set(pending, Option.some(a));
+            yield* Ref.set(extra, false);
+            if (leading) {
+                yield* sink.onSuccess(a);
+            }
+            yield* FiberHandle.run(window, Effect.sleep(duration).pipe(Effect.andThen(closeWindow)));
+            return;
+        }
+        yield* Ref.set(pending, Option.some(a));
+        yield* Ref.set(extra, true);
+    })));
+    yield* FiberHandle.awaitEmpty(window);
+}, extendScope));
+/**
+ * Limits emissions to configured leading and trailing edges of fixed windows.
+ *
+ * Pass `{ duration, leading, trailing }` for trailing or both-edge behavior.
+ * A duration alone defaults to `{ leading: true, trailing: false }`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Throttling bounds push frequency while allowing immediate feedback, a final
+ * settled value, or both, without moving timing state outside the Fx graph.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first value opens a window. Leading mode emits it immediately. Values
+ * arriving while open replace one pending latest value; trailing mode emits
+ * that value when the timer closes, except that both-edge mode does not repeat
+ * the first value unless another arrived. Windows never overlap. Source errors
+ * propagate, source completion waits for the active window, and interruption
+ * stops the scoped timer and discards pending state.
+ *
+ * @example
+ * ```ts
+ * import { throttle } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const bounded = throttle(fromIterable([1, 2, 3]), {
+ *   duration: "250 millis",
+ *   leading: true,
+ *   trailing: true
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export const throttle = dual((args) => isFx(args[0]), (fx, durationOrOptions) => {
+    const { duration, leading, trailing } = resolve(durationOrOptions);
+    if (leading && !trailing) {
+        return exhaustMap(fx, (a) => make(Effect.fn(function* (sink) {
+            yield* sink.onSuccess(a);
+            yield* Effect.sleep(duration);
+        })));
+    }
+    return throttleWindow(fx, duration, leading, trailing);
+});

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