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

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

@@ -1 +1 @@
-{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/when.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,QAAA,MAAM,GAAG,EAAE;IACT,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE;QAC/B,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;KACxB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;IAExF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACzB,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAC5B,QAAQ,EAAE;QACR,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;KACxB,GACA,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;CAehD,CAAC;AAEF,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;AAErB;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAC7B,WAAW,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAC5B,UAAU;IACR,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,EAAE,CAAC,CAAC;CACZ,KACA,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAExB,CAAC"}
+{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/when.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,QAAA,MAAM,GAAG,EAAE;IACT,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE;QAC/B,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;KACxB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;IAExF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACzB,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAC5B,QAAQ,EAAE;QACR,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;KACxB,GACA,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;CAchD,CAAC;AAEF,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,aAClB,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,YAClB;IACR,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,EAAE,CAAC,CAAC;CACZ,KACA,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAExB,CAAC"}

package/dist/Fx/combinators/when.js

@@ -4,24 +4,59 @@ import { switchMap } from "./switchMap.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
  */
 const if_ = dual(2, (condition, matchers) => {
-    return switchMap(condition, (pass) => (pass ? matchers.onTrue : matchers.onFalse));
+    return switchMap(condition, (pass) => pass ? matchers.onTrue : matchers.onFalse);
 });
 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 const when = (condition, matchers) => {
     return if_(condition, { onTrue: succeed(matchers.onTrue), onFalse: succeed(matchers.onFalse) });

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

@@ -0,0 +1,58 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Emits `[source, latest]` whenever the source emits, using the latest value
+ * from `that`. Source values are dropped until `that` has emitted at least once.
+ *
+ * Unlike {@link zipLatest}, this does **not** emit when `that` updates.
+ *
+ * **Completion:** Completes when the source completes.
+ * **Errors:** The first failure from either stream fails the result.
+ *
+ * @remarks
+ * ## Why
+ * `withLatestFrom` makes the left source the sole emission trigger while enriching it with right-side
+ * state. Left values before the right's first value are dropped; right updates never emit alone.
+ *
+ * ## Ownership and lifetime
+ * The right source runs in a child fiber and one latest value is retained. Left completion or
+ * consumer interruption interrupts that fiber; failure from either side is forwarded.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const labeled = Fx.withLatestFrom(Fx.fromIterable([1, 2]), Fx.succeed("ready"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combining sources
+ */
+export declare const withLatestFrom: {
+    <B, E2, R2>(that: Fx<B, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<readonly [A, B], E | E2, R | R2>;
+    <A, E, R, B, E2, R2>(self: Fx<A, E, R>, that: Fx<B, E2, R2>): Fx<readonly [A, B], E | E2, R | R2>;
+};
+/**
+ * Like {@link withLatestFrom}, but combines the pair with `f`.
+ *
+ * @remarks
+ * ## Why
+ * `withLatestFromWith` applies a synchronous projection at each eligible left emission without
+ * allocating a public tuple stage. Cardinality and triggering remain those of `withLatestFrom`.
+ *
+ * ## Ownership and lifetime
+ * It inherits the child right-hand fiber and latest-value lifetime from `withLatestFrom`; the pure
+ * projection adds no failures, services, or resources.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const labels = Fx.withLatestFromWith(Fx.fromIterable([1]), Fx.succeed("item"), (n, kind) => `${kind}-${n}`)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combining sources
+ */
+export declare const withLatestFromWith: {
+    <A, B, E2, R2, C>(that: Fx<B, E2, R2>, f: (a: A, b: B) => C): <E, R>(self: Fx<A, E, R>) => Fx<C, E | E2, R | R2>;
+    <A, E, R, B, E2, R2, C>(self: Fx<A, E, R>, that: Fx<B, E2, R2>, f: (a: A, b: B) => C): Fx<C, E | E2, R | R2>;
+};
+//# sourceMappingURL=withLatestFrom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"withLatestFrom.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/withLatestFrom.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,cAAc,EAAE;IAC3B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAClB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IACvE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CA8BnG,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,EAAE;IAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACd,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EACnB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GACnB,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,EAAE,CAAC,EACpB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EACnB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GACnB,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAQ1B,CAAC"}

package/dist/Fx/combinators/withLatestFrom.js

@@ -0,0 +1,68 @@
+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";
+import { map } from "./map.js";
+/**
+ * Emits `[source, latest]` whenever the source emits, using the latest value
+ * from `that`. Source values are dropped until `that` has emitted at least once.
+ *
+ * Unlike {@link zipLatest}, this does **not** emit when `that` updates.
+ *
+ * **Completion:** Completes when the source completes.
+ * **Errors:** The first failure from either stream fails the result.
+ *
+ * @remarks
+ * ## Why
+ * `withLatestFrom` makes the left source the sole emission trigger while enriching it with right-side
+ * state. Left values before the right's first value are dropped; right updates never emit alone.
+ *
+ * ## Ownership and lifetime
+ * The right source runs in a child fiber and one latest value is retained. Left completion or
+ * consumer interruption interrupts that fiber; failure from either side is forwarded.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const labeled = Fx.withLatestFrom(Fx.fromIterable([1, 2]), Fx.succeed("ready"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combining sources
+ */
+export const withLatestFrom = dual(2, (self, that) => make((sink) => Effect.gen(function* () {
+    const latest = yield* Ref.make(Option.none());
+    const other = yield* Effect.forkChild(that.run(makeSink(sink.onFailure, (b) => Ref.set(latest, Option.some(b)))), { startImmediately: true, uninterruptible: false });
+    yield* Effect.yieldNow;
+    yield* self
+        .run(makeSink(sink.onFailure, (a) => Effect.flatMap(Ref.get(latest), (opt) => Option.match(opt, {
+        onNone: () => Effect.void,
+        onSome: (b) => sink.onSuccess([a, b]),
+    }))))
+        .pipe(Effect.ensuring(Fiber.interrupt(other)));
+})));
+/**
+ * Like {@link withLatestFrom}, but combines the pair with `f`.
+ *
+ * @remarks
+ * ## Why
+ * `withLatestFromWith` applies a synchronous projection at each eligible left emission without
+ * allocating a public tuple stage. Cardinality and triggering remain those of `withLatestFrom`.
+ *
+ * ## Ownership and lifetime
+ * It inherits the child right-hand fiber and latest-value lifetime from `withLatestFrom`; the pure
+ * projection adds no failures, services, or resources.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const labels = Fx.withLatestFromWith(Fx.fromIterable([1]), Fx.succeed("item"), (n, kind) => `${kind}-${n}`)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Combining sources
+ */
+export const withLatestFromWith = dual(3, (self, that, f) => map(withLatestFrom(self, that), (pair) => f(pair[0], pair[1])));

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

@@ -1,4 +1,38 @@
 import type { SpanOptionsNoTrace } from "effect/Tracer";
 import type { Fx } from "../Fx.js";
-export declare const withSpan: <A, E, R>(fx: Fx<A, E, R>, name: string, options?: SpanOptionsNoTrace) => Fx<A, E, R>;
+/**
+ * Traces the whole subscription and each success or failure delivery.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A single Effect span around subscription setup cannot show time spent in
+ * downstream sink callbacks. Nested delivery spans make the push boundary
+ * visible while keeping the source's values and types unchanged.
+ *
+ * ## Ownership and lifetime
+ *
+ * Every run creates an `Fx(name)` span covering the source subscription. Each
+ * `onSuccess` and `onFailure` callback executes in its own child span. Span
+ * lifetime follows the Effects exactly; interruption closes active spans.
+ * Options are forwarded to all three span kinds, and no service requirement or
+ * failure is added beyond the configured Effect tracer.
+ *
+ * @example
+ * ```ts
+ * import { withSpan } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const traced = withSpan(succeed("ready"), "load-settings", {
+ *   attributes: { component: "settings" }
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Observing failures
+ */
+export declare const withSpan: {
+    (name: string, options?: SpanOptionsNoTrace): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, R>;
+    <A, E, R>(fx: Fx<A, E, R>, name: string, options?: SpanOptionsNoTrace): Fx<A, E, R>;
+};
 //# sourceMappingURL=withSpan.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"withSpan.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/withSpan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9B,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,MAAM,MAAM,EACZ,UAAU,kBAAkB,KAC3B,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAaZ,CAAC"}
+{"version":3,"file":"withSpan.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/withSpan.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,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;IACxF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAgBrF,CAAC"}

package/dist/Fx/combinators/withSpan.js

@@ -1,6 +1,37 @@
 import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
 import { make as makeSink } from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
-export const withSpan = (fx, name, options) => {
-    return make((sink) => Effect.withSpan(fx.run(makeSink((cause) => Effect.withSpan(sink.onFailure(cause), `onFailure(${name})`, options), (value) => Effect.withSpan(sink.onSuccess(value), `onSuccess(${name})`, options))), `Fx(${name})`, options));
-};
+import { isFx } from "../TypeId.js";
+/**
+ * Traces the whole subscription and each success or failure delivery.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A single Effect span around subscription setup cannot show time spent in
+ * downstream sink callbacks. Nested delivery spans make the push boundary
+ * visible while keeping the source's values and types unchanged.
+ *
+ * ## Ownership and lifetime
+ *
+ * Every run creates an `Fx(name)` span covering the source subscription. Each
+ * `onSuccess` and `onFailure` callback executes in its own child span. Span
+ * lifetime follows the Effects exactly; interruption closes active spans.
+ * Options are forwarded to all three span kinds, and no service requirement or
+ * failure is added beyond the configured Effect tracer.
+ *
+ * @example
+ * ```ts
+ * import { withSpan } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const traced = withSpan(succeed("ready"), "load-settings", {
+ *   attributes: { component: "settings" }
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Observing failures
+ */
+export const withSpan = dual((args) => isFx(args[0]), (fx, name, options) => make((sink) => Effect.withSpan(fx.run(makeSink((cause) => Effect.withSpan(sink.onFailure(cause), `onFailure(${name})`, options), (value) => Effect.withSpan(sink.onSuccess(value), `onSuccess(${name})`, options))), `Fx(${name})`, options)));

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

@@ -10,10 +10,25 @@ import type { Fx } from "../Fx.js";
  *
  * **Errors:** The first failure from either stream fails the zipped stream.
  *
+ * @remarks
+ * ## Why
+ * `zip` preserves one-to-one positional correspondence between two producers. Values wait in
+ * unbounded queues until their counterpart arrives, and pairs emit in each source's order.
+ *
+ * ## Ownership and lifetime
+ * Both child runs and queues belong to the consumer. The first completion, any failure, or
+ * interruption stops both fibers and discards unmatched queued values.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const pairs = Fx.zip(Fx.fromIterable([1, 2]), Fx.fromIterable(["a", "b"]))
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits pairs `[A, B]`.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare const zip: {
     <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<readonly [A, A2], E | E2, R | R2>;
@@ -26,11 +41,26 @@ export declare const zip: {
  * **Completion:** Completes when the **first** of the two streams completes.
  * **Errors:** The first failure from either stream fails the result.
  *
+ * @remarks
+ * ## Why
+ * `zipWith` combines each strict pair immediately, preserving `zip`'s lockstep cardinality and
+ * ordering while avoiding a separate tuple mapping step.
+ *
+ * ## Ownership and lifetime
+ * It inherits `zip`'s two child runs and unbounded unmatched-value queues. The pure combiner adds no
+ * resource, error, or service requirement.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const sums = Fx.zipWith(Fx.fromIterable([1]), Fx.fromIterable([2]), (a, b) => a + b)
+ * ```
+ *
  * @param that - The second Fx stream.
  * @param f - Function to combine the pair `(a, b)` into a single value.
  * @returns An Fx that emits combined values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare const zipWith: {
     <A, A2, E2, R2, B>(that: Fx<A2, E2, R2>, f: (a: A, b: A2) => B): <E, R>(self: Fx<A, E, R>) => Fx<B, E | E2, R | R2>;
@@ -45,10 +75,25 @@ export declare const zipWith: {
  * **Completion:** Completes when **both** streams have completed.
  * **Errors:** The first failure from either stream fails the result.
  *
+ * @remarks
+ * ## Why
+ * `zipLatest` combines independent sources as state: after both initialize, either update emits one
+ * pair containing both latest values. It does not enforce one-to-one pairing.
+ *
+ * ## Ownership and lifetime
+ * It delegates to `tuple`: both sources run concurrently and retain one latest value each until
+ * both complete or the consumer is interrupted.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const latest = Fx.zipLatest(Fx.succeed(1), Fx.succeed("ready"))
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits `[AL, AR]` on every update from either stream.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare const zipLatest: {
     <AR, ER, RR>(that: Fx<AR, ER, RR>): <AL, EL, RL>(self: Fx<AL, EL, RL>) => Fx<readonly [AL, AR], EL | ER, RL | RR>;
@@ -62,11 +107,26 @@ export declare const zipLatest: {
  * **Completion:** Completes when **both** streams have completed.
  * **Errors:** The first failure from either stream fails the result.
  *
+ * @remarks
+ * ## Why
+ * `zipLatestWith` projects latest-value pairs whenever either initialized source updates. The
+ * synchronous callback changes payloads without changing `zipLatest` cardinality.
+ *
+ * ## Ownership and lifetime
+ * Both concurrent sources and their retained latest values are owned by the consumer. The combiner
+ * is pure; failure, services, completion, and interruption come from the inputs.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const label = Fx.zipLatestWith(Fx.succeed(1), Fx.succeed("item"), (n, kind) => `${kind}-${n}`)
+ * ```
+ *
  * @param that - The second Fx stream.
  * @param f - Function to combine the latest `(left, right)` into a single value.
  * @returns An Fx that emits combined values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare const zipLatestWith: {
     <AL, AR, ER, RR, B>(that: Fx<AR, ER, RR>, f: (left: AL, right: AR) => B): <EL, RL>(self: Fx<AL, EL, RL>) => Fx<B, EL | ER, RL | RR>;

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

@@ -1 +1 @@
-{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/zip.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/zip.ts"],"names":[],"mappings":"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"}

package/dist/Fx/combinators/zip.js

@@ -19,10 +19,25 @@ import { tuple } from "./tuple.js";
  *
  * **Errors:** The first failure from either stream fails the zipped stream.
  *
+ * @remarks
+ * ## Why
+ * `zip` preserves one-to-one positional correspondence between two producers. Values wait in
+ * unbounded queues until their counterpart arrives, and pairs emit in each source's order.
+ *
+ * ## Ownership and lifetime
+ * Both child runs and queues belong to the consumer. The first completion, any failure, or
+ * interruption stops both fibers and discards unmatched queued values.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const pairs = Fx.zip(Fx.fromIterable([1, 2]), Fx.fromIterable(["a", "b"]))
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits pairs `[A, B]`.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export const zip = dual(2, (self, that) => make((sink) => Effect.gen(function* () {
     const leftQueue = yield* Queue.unbounded();
@@ -61,11 +76,26 @@ export const zip = dual(2, (self, that) => make((sink) => Effect.gen(function* (
  * **Completion:** Completes when the **first** of the two streams completes.
  * **Errors:** The first failure from either stream fails the result.
  *
+ * @remarks
+ * ## Why
+ * `zipWith` combines each strict pair immediately, preserving `zip`'s lockstep cardinality and
+ * ordering while avoiding a separate tuple mapping step.
+ *
+ * ## Ownership and lifetime
+ * It inherits `zip`'s two child runs and unbounded unmatched-value queues. The pure combiner adds no
+ * resource, error, or service requirement.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const sums = Fx.zipWith(Fx.fromIterable([1]), Fx.fromIterable([2]), (a, b) => a + b)
+ * ```
+ *
  * @param that - The second Fx stream.
  * @param f - Function to combine the pair `(a, b)` into a single value.
  * @returns An Fx that emits combined values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export const zipWith = dual(3, (self, that, f) => map(zip(self, that), (pair) => f(pair[0], pair[1])));
 /**
@@ -77,10 +107,25 @@ export const zipWith = dual(3, (self, that, f) => map(zip(self, that), (pair) =>
  * **Completion:** Completes when **both** streams have completed.
  * **Errors:** The first failure from either stream fails the result.
  *
+ * @remarks
+ * ## Why
+ * `zipLatest` combines independent sources as state: after both initialize, either update emits one
+ * pair containing both latest values. It does not enforce one-to-one pairing.
+ *
+ * ## Ownership and lifetime
+ * It delegates to `tuple`: both sources run concurrently and retain one latest value each until
+ * both complete or the consumer is interrupted.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const latest = Fx.zipLatest(Fx.succeed(1), Fx.succeed("ready"))
+ * ```
+ *
  * @param that - The second Fx stream.
  * @returns An Fx that emits `[AL, AR]` on every update from either stream.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export const zipLatest = dual(2, (self, that) => tuple(self, that));
 /**
@@ -91,10 +136,25 @@ export const zipLatest = dual(2, (self, that) => tuple(self, that));
  * **Completion:** Completes when **both** streams have completed.
  * **Errors:** The first failure from either stream fails the result.
  *
+ * @remarks
+ * ## Why
+ * `zipLatestWith` projects latest-value pairs whenever either initialized source updates. The
+ * synchronous callback changes payloads without changing `zipLatest` cardinality.
+ *
+ * ## Ownership and lifetime
+ * Both concurrent sources and their retained latest values are owned by the consumer. The combiner
+ * is pure; failure, services, completion, and interruption come from the inputs.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * const label = Fx.zipLatestWith(Fx.succeed(1), Fx.succeed("item"), (n, kind) => `${kind}-${n}`)
+ * ```
+ *
  * @param that - The second Fx stream.
  * @param f - Function to combine the latest `(left, right)` into a single value.
  * @returns An Fx that emits combined values.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export const zipLatestWith = dual(3, (self, that, f) => map(zipLatest(self, that), (pair) => f(pair[0], pair[1])));

package/dist/Fx/constructors/at.d.ts

@@ -3,11 +3,31 @@ import type { Fx } from "../Fx.js";
 /**
  * Creates an Fx that emits a single value after a specified delay.
  *
+ * @remarks
+ * ## Why
+ *
+ * `at` models a one-shot producer while keeping the delay inside Effect's
+ * interruptible scheduling rather than an unmanaged timer callback.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no timer. Running the `Fx` sleeps, emits exactly once, and
+ * completes after the sink handles the value. Interrupting the run cancels the sleep.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { at, first } from "@typed/fx/Fx"
+ *
+ * const delayed = at("ready", "10 millis")
+ * const program = Effect.map(first(delayed), (value) => value)
+ * ```
+ *
  * @param value - The value to emit.
  * @param delay - The duration to wait before emitting.
  * @returns An `Fx` that emits the value after the delay.
  * @since 1.0.0
- * @category constructors
+ * @category Time and rate
  */
 export declare const at: {
     (delay: Duration.Input): <A>(value: A) => Fx<A>;

package/dist/Fx/constructors/at.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"at.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/at.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAGjD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,eAAO,MAAM,EAAE,EAAE;IACf,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;CAK7C,CAAC"}
+{"version":3,"file":"at.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/at.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAGjD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,EAAE,EAAE;IACf,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;CAK7C,CAAC"}

package/dist/Fx/constructors/at.js

@@ -4,10 +4,30 @@ import { make } from "./make.js";
 /**
  * Creates an Fx that emits a single value after a specified delay.
  *
+ * @remarks
+ * ## Why
+ *
+ * `at` models a one-shot producer while keeping the delay inside Effect's
+ * interruptible scheduling rather than an unmanaged timer callback.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no timer. Running the `Fx` sleeps, emits exactly once, and
+ * completes after the sink handles the value. Interrupting the run cancels the sleep.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { at, first } from "@typed/fx/Fx"
+ *
+ * const delayed = at("ready", "10 millis")
+ * const program = Effect.map(first(delayed), (value) => value)
+ * ```
+ *
  * @param value - The value to emit.
  * @param delay - The duration to wait before emitting.
  * @returns An `Fx` that emits the value after the delay.
  * @since 1.0.0
- * @category constructors
+ * @category Time and rate
  */
 export const at = dual(2, (value, delay) => make((sink) => flatMap(sleep(delay), () => sink.onSuccess(value))));

package/dist/Fx/constructors/die.d.ts

@@ -2,10 +2,31 @@ import type { Fx } from "../Fx.js";
 /**
  * Creates an Fx that immediately terminates with a defect (unexpected error).
  *
+ * @remarks
+ * ## Why
+ *
+ * Defects represent unexpected, non-recoverable failures and remain distinct from
+ * the typed `E` channel.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction is inert. Each run delivers one defect cause to the sink and emits
+ * no values; it acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import { die, observe } from "@typed/fx/Fx"
+ *
+ * const program = observe(die(new Error("broken")), () => Effect.void).pipe(
+ *   Effect.catchCause((cause) => Effect.succeed(Cause.hasDies(cause)))
+ * )
+ * ```
+ *
  * @param defect - The defect value.
  * @returns An `Fx` that dies immediately.
  * @since 1.0.0
- * @category constructors
+ * @category Failure sources
  */
 export declare const die: (defect: unknown) => Fx<never, never, never>;
 //# sourceMappingURL=die.d.ts.map

package/dist/Fx/constructors/die.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"die.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/die.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAG5D,CAAC"}
+{"version":3,"file":"die.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/die.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,GAAG,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAG5D,CAAC"}