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

package/dist/Fx/run/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/observe.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAe5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE9D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC9B,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAuBpC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAA6B,CAAC;AAEhG;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAClD,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE;IACzB,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IAE3E,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC9B,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;CAOjD,CAAC"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/observe.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAiB5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE9D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC9B,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAmCpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAA6B,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CACjD,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,YAAY,EAAE;IACzB,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IAE3E,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAC9B,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAC9C,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;CAOjD,CAAC"}

package/dist/Fx/run/observe.js

@@ -1,4 +1,4 @@
-import { callback, catchCause, failCause, forkChild, isEffect, matchCauseEffect, runForkWith, servicesWith, sync, void as void_, } from "effect/Effect";
+import { callback, catchCause, ensuring, failCause, forkScoped, isEffect, matchCauseEffect, runForkWith, contextWith, sync, suspend, void as void_, } from "effect/Effect";
 import { interrupt } from "effect/Fiber";
 import { dual } from "effect/Function";
 import { effectDiscard } from "effect/Layer";
@@ -7,49 +7,170 @@ import { make } from "../../Sink/Sink.js";
  * Observes the values of an `Fx` stream using a callback function.
  * The callback can return `void` or an `Effect` which will be executed for each value.
  *
+ * @remarks
+ * ## Why
+ *
+ * `observe` is the primary Effect boundary for performing work for each pushed value.
+ * A plain callback is lifted to Effect, while an Effect callback contributes its own
+ * typed failures and services to the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Observation starts only when the returned Effect runs. That Effect owns the source
+ * run and completes when the source completes. Interruption interrupts the internal
+ * fiber and source cleanup. Callback invocation follows the producer's delivery
+ * behavior; `observe` adds no buffer or concurrency of its own. A source cause or a
+ * callback failure fails the returned Effect as `E | E2` and stops further
+ * deliveries. The producer fiber finishes cleanup before observation settles;
+ * resources acquired in the caller's Scope retain that Scope's lifetime.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { fromIterable, observe } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const total = yield* Ref.make(0)
+ *   yield* observe(fromIterable([1, 2, 3]), (value) => Ref.update(total, (n) => n + value))
+ *   return yield* Ref.get(total)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` stream to observe.
  * @param f - The function to call for each emitted value.
  * @returns An `Effect` that completes when the stream ends.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
-export const observe = dual(2, (fx, f) => servicesWith((services) => callback((resume) => {
-    const onFailure = (cause) => sync(() => resume(failCause(cause)));
-    const onSuccess = (value) => {
-        const result = f(value);
-        return isEffect(result) ? catchCause(result, onFailure) : void_;
-    };
-    const onDone = () => sync(() => resume(void_));
-    return fx.run(make(onFailure, onSuccess)).pipe(matchCauseEffect(make(onFailure, onDone)), runForkWith(services), interrupt);
-})));
+export const observe = dual(2, (fx, f) => contextWith((services) => {
+    let fiber;
+    return callback((resume) => {
+        let done = false;
+        const complete = (result) => sync(() => {
+            if (done)
+                return;
+            done = true;
+            resume(result);
+        });
+        const onFailure = (cause) => complete(failCause(cause));
+        const onSuccess = (value) => suspend(() => {
+            if (done)
+                return void_;
+            const result = f(value);
+            return isEffect(result) ? catchCause(result, onFailure) : void_;
+        });
+        fiber = fx
+            .run(make(onFailure, onSuccess))
+            .pipe(matchCauseEffect(make(onFailure, () => complete(void_))), runForkWith(services));
+    }).pipe(ensuring(suspend(() => (fiber === undefined ? void_ : interrupt(fiber)))));
+}));
 /**
  * Runs an `Fx` stream to completion, discarding all values.
  * Useful when the side effects of the stream are all that matter.
  *
+ * @remarks
+ * ## Why
+ *
+ * Some producers perform all useful work in acquisition, effects, or finalization and
+ * need execution without retaining their emitted values.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the Effect owns one source subscription until completion, failure, or
+ * interruption. It allocates no collection and adds no per-value effect. Source
+ * failures and services remain visible.
+ *
+ * @example
+ * ```ts
+ * import { drain, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = drain(fromIterable([1, 2, 3]))
+ * ```
+ *
  * @param fx - The `Fx` stream to drain.
  * @returns An `Effect` that completes when the stream ends.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export const drain = (fx) => observe(fx, () => void_);
 /**
  * Runs an `Fx` stream as a Layer.
  * The stream is forked in the background when the layer is acquired.
  *
+ * @remarks
+ * ## Why
+ *
+ * A background producer can share the same acquisition and shutdown boundary as an
+ * application's Effect [Layer](https://effect.website/docs/v4/api/effect/Layer) graph
+ * even when it provides no service itself.
+ *
+ * ## Ownership and lifetime
+ *
+ * Building the Layer starts `drain(fx)` with `forkScoped`. Acquisition succeeds after
+ * the fiber is registered; it does not wait for that fiber. The Layer scope interrupts
+ * the fiber on release. A source failure is stored in the discarded child Fiber exit:
+ * it does not fail Layer acquisition and this API exposes no handle for awaiting it.
+ * Recover, report, or otherwise observe failures inside `fx` before calling
+ * `drainLayer`, or use `fork` when the caller needs the Fiber exit. The annotated `E`
+ * channel remains in the public Layer type even though the background exit is not
+ * propagated by this implementation. `Scope` is supplied by the Layer.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const reported = Fx.fail("offline").pipe(
+ *   Fx.catch((error) => Fx.fromEffect(Effect.logError(error)))
+ * )
+ * const Background = Fx.drainLayer(reported)
+ * const program = Effect.void.pipe(Effect.provide(Background))
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @returns A `Layer` that manages the background execution of the stream.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
-export const drainLayer = (fx) => effectDiscard(forkChild(drain(fx)));
+export const drainLayer = (fx) => effectDiscard(forkScoped(drain(fx)));
 /**
  * Observes the values of an `Fx` stream using a callback function and returns a `Layer`.
  * The callback can return `void` or an `Effect` which will be executed for each value.
  *
+ * @remarks
+ * ## Why
+ *
+ * Observation side effects can be installed as application infrastructure and share
+ * the Layer graph's typed dependencies and shutdown behavior.
+ *
+ * ## Ownership and lifetime
+ *
+ * Building the Layer forks `observe(fx, f)` in its scope and completes acquisition
+ * after registration. Releasing the Layer interrupts the observer and source. Source
+ * and callback failures terminate the discarded child Fiber; they do not fail Layer
+ * acquisition, and this API exposes no Fiber handle from which to await the exit.
+ * Handle or report those failures inside the source/callback, or use `observe`/`fork`
+ * when the caller must observe them. The annotated `E | E2` Layer error remains in the
+ * public type even though this implementation does not propagate the background exit.
+ * `Scope` is supplied internally; delivery behavior remains that of `observe`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { fromIterable, observeLayer } from "@typed/fx/Fx"
+ *
+ * const report = (value: number) =>
+ *   Effect.try({ try: () => JSON.stringify(BigInt(value)), catch: String }).pipe(
+ *     Effect.catch((error) => Effect.logError(error))
+ *   )
+ * const LogValues = observeLayer(fromIterable([1, 2]), report)
+ * const program = Effect.void.pipe(Effect.provide(LogValues))
+ * ```
+ *
  * @param fx - The `Fx` stream to observe.
  * @param f - The function to call for each emitted value.
  * @returns A `Layer` that manages the background execution of the stream.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
-export const observeLayer = dual(2, (fx, f) => effectDiscard(observe(fx, f)));
+export const observeLayer = dual(2, (fx, f) => effectDiscard(forkScoped(observe(fx, f))));

package/dist/Fx/run/runPromise.d.ts

@@ -4,22 +4,65 @@ import type { Fx } from "../Fx.js";
 /**
  * Runs an `Fx` stream to completion and returns a Promise of the Exit.
  *
+ * @remarks
+ * ## Why
+ *
+ * Promise-based hosts can inspect success or the complete typed failure `Cause`
+ * without Promise rejection erasing Effect's `Exit` structure.
+ *
+ * ## Ownership and lifetime
+ *
+ * Calling `runPromiseExit` starts the source immediately on Effect's default runtime,
+ * so all services must already be eliminated. The root fiber owns the source until it
+ * completes; `RunOptions` can supply cancellation. Values are discarded. The Promise
+ * always resolves with an `Exit`, including failure and interruption.
+ *
+ * @example
+ * ```ts
+ * import { Exit } from "effect"
+ * import { fail, runPromiseExit } from "@typed/fx/Fx"
+ *
+ * const outcome = runPromiseExit(fail("offline"))
+ * const failed = outcome.then(Exit.isFailure)
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @param options - `RunOptions` for execution.
  * @returns A Promise resolving to the `Exit` of the execution.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export declare const runPromiseExit: <A, E>(fx: Fx<A, E>, options?: RunOptions) => Promise<Exit.Exit<void, E>>;
 /**
  * Runs an `Fx` stream to completion and returns a Promise.
  * Rejects if the stream fails.
  *
+ * @remarks
+ * ## Why
+ *
+ * `runPromise` is the direct boundary for Promise-oriented hosts that treat stream
+ * completion as resolution and typed failure as rejection.
+ *
+ * ## Ownership and lifetime
+ *
+ * Calling it starts the source immediately on Effect's default runtime, so the `Fx`
+ * cannot require services. The root fiber owns the subscription until completion;
+ * `RunOptions` controls launch and cancellation. Values are discarded. Typed failures,
+ * defects, and interruption reject according to Effect's `runPromise` semantics.
+ *
+ * @example
+ * ```ts
+ * import { fromIterable, runPromise } from "@typed/fx/Fx"
+ *
+ * const completion = runPromise(fromIterable([1, 2, 3]))
+ * const settled = completion.then(() => "done")
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @param options - `RunOptions` for execution.
  * @returns A Promise that resolves when the stream completes.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export declare const runPromise: <A, E>(fx: Fx<A, E>, options?: RunOptions) => Promise<unknown>;
 //# sourceMappingURL=runPromise.d.ts.map

package/dist/Fx/run/runPromise.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runPromise.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/runPromise.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EACjC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EACZ,UAAU,UAAU,KACnB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAA8C,CAAC;AAE5E;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,UAAU,KAAG,OAAO,CAAC,OAAO,CAC9C,CAAC"}
+{"version":3,"file":"runPromise.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/runPromise.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,MAC7B,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,YACF,UAAU,KACnB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAA8C,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,UAAU,KAAG,OAAO,CAAC,OAAO,CAC9C,CAAC"}

package/dist/Fx/run/runPromise.js

@@ -3,21 +3,64 @@ import { drain } from "./observe.js";
 /**
  * Runs an `Fx` stream to completion and returns a Promise of the Exit.
  *
+ * @remarks
+ * ## Why
+ *
+ * Promise-based hosts can inspect success or the complete typed failure `Cause`
+ * without Promise rejection erasing Effect's `Exit` structure.
+ *
+ * ## Ownership and lifetime
+ *
+ * Calling `runPromiseExit` starts the source immediately on Effect's default runtime,
+ * so all services must already be eliminated. The root fiber owns the source until it
+ * completes; `RunOptions` can supply cancellation. Values are discarded. The Promise
+ * always resolves with an `Exit`, including failure and interruption.
+ *
+ * @example
+ * ```ts
+ * import { Exit } from "effect"
+ * import { fail, runPromiseExit } from "@typed/fx/Fx"
+ *
+ * const outcome = runPromiseExit(fail("offline"))
+ * const failed = outcome.then(Exit.isFailure)
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @param options - `RunOptions` for execution.
  * @returns A Promise resolving to the `Exit` of the execution.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export const runPromiseExit = (fx, options) => Effect.runPromiseExit(drain(fx), options);
 /**
  * Runs an `Fx` stream to completion and returns a Promise.
  * Rejects if the stream fails.
  *
+ * @remarks
+ * ## Why
+ *
+ * `runPromise` is the direct boundary for Promise-oriented hosts that treat stream
+ * completion as resolution and typed failure as rejection.
+ *
+ * ## Ownership and lifetime
+ *
+ * Calling it starts the source immediately on Effect's default runtime, so the `Fx`
+ * cannot require services. The root fiber owns the subscription until completion;
+ * `RunOptions` controls launch and cancellation. Values are discarded. Typed failures,
+ * defects, and interruption reject according to Effect's `runPromise` semantics.
+ *
+ * @example
+ * ```ts
+ * import { fromIterable, runPromise } from "@typed/fx/Fx"
+ *
+ * const completion = runPromise(fromIterable([1, 2, 3]))
+ * const settled = completion.then(() => "done")
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @param options - `RunOptions` for execution.
  * @returns A Promise that resolves when the stream completes.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export const runPromise = (fx, options) => Effect.runPromise(drain(fx), options);

package/dist/Fx/stream.d.ts

@@ -1,7 +1,99 @@
 import * as Stream from "effect/Stream";
 import type * as Fx from "./Fx.js";
+/**
+ * Buffering and callback options accepted while adapting an `Fx` to an Effect `Stream`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The adapter exposes Effect Stream's own callback policy instead of inventing a
+ * second buffering vocabulary.
+ *
+ * ## Ownership and lifetime
+ *
+ * This type alias owns no queue or subscription. The selected policy takes effect
+ * only when the resulting Stream is run.
+ *
+ * @since 1.0.0
+ * @category Operator options
+ */
 export type ToStreamOptions = Parameters<typeof Stream.callback<unknown, unknown, unknown>>[1];
+/**
+ * Adapts a push-based `Fx` to an Effect `Stream`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Existing Effect [Stream](https://effect.website/docs/v4/api/effect/Stream) consumers
+ * can use an `Fx` without losing the producer's typed values, failures, or services.
+ * Values and causes cross a queue in emission order; the queue ends when the `Fx` run
+ * completes.
+ *
+ * ## Ownership and lifetime
+ *
+ * Conversion is lazy. Running the Stream allocates the callback queue and runs the
+ * `Fx`; the Stream's scope owns both. Interruption closes the callback subscription
+ * through Effect Stream's lifecycle. Buffering follows `options`.
+ *
+ * @example
+ * ```ts
+ * import { Stream } from "effect"
+ * import { fromIterable, toStream } from "@typed/fx/Fx"
+ *
+ * const values = toStream(fromIterable([1, 2, 3]))
+ * const total = Stream.runFold(values, () => 0, (sum, value) => sum + value)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Stream interop
+ */
 export declare const toStream: <A, E, R>(fx: Fx.Fx<A, E, R>, options?: ToStreamOptions) => Stream.Stream<A, E, R>;
+/**
+ * Effect Stream mapping options used while delivering elements to an `Fx` sink.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Stream-to-sink scheduling and concurrency remain controlled by Effect Stream's
+ * established `mapEffect` options.
+ *
+ * ## Ownership and lifetime
+ *
+ * This type alias performs no acquisition. Options are applied each time the
+ * adapted `Fx` is run.
+ *
+ * @since 1.0.0
+ * @category Operator options
+ */
 export type FromStreamOptions = Parameters<typeof Stream.mapEffect<unknown, unknown, unknown, unknown>>[1];
+/**
+ * Adapts an Effect `Stream` to a push-based `Fx`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Stream producers can participate in `Fx` composition without wrapping their
+ * behavior in a new abstraction. Each Stream element is offered to the sink through
+ * `Stream.mapEffect`; Stream causes are forwarded unchanged to `sink.onFailure`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Conversion starts nothing. Each `Fx.run` starts one Stream run owned by the caller's
+ * fiber and scope. Interruption stops the Stream and its finalizers. Delivery order
+ * and concurrency follow Effect Stream's `mapEffect` semantics and `options`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Stream } from "effect"
+ * import { collectAll, fromStream } from "@typed/fx/Fx"
+ *
+ * const source = fromStream(Stream.make("a", "b"))
+ * const values = collectAll(source)
+ * const program = Effect.map(values, (items) => items.join(""))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Stream interop
+ */
 export declare const fromStream: <A, E, R>(stream: Stream.Stream<A, E, R>, options?: FromStreamOptions) => Fx.Fx<A, E, R>;
 //# sourceMappingURL=stream.d.ts.map

package/dist/Fx/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/Fx/stream.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/F,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9B,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,UAAU,eAAe,KACxB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAUrB,CAAC;AAEJ,MAAM,MAAM,iBAAiB,GAAG,UAAU,CACxC,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAC5D,CAAC,CAAC,CAAC,CAAC;AAEL,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAChC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,UAAU,iBAAiB,KAC1B,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CASb,CAAC"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/Fx/stream.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAC1B,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,YACR,eAAe,KACxB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAarB,CAAC;AAEJ;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CACxC,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAC5D,CAAC,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UACxB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,YACpB,iBAAiB,KAC1B,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CASb,CAAC"}

package/dist/Fx/stream.js

@@ -1,7 +1,66 @@
+import * as Effect from "effect/Effect";
 import { pipe } from "effect/Function";
 import * as Queue from "effect/Queue";
 import * as Stream from "effect/Stream";
 import * as Sink from "../Sink/Sink.js";
 import { make } from "./constructors/make.js";
-export const toStream = (fx, options) => Stream.callback((queue) => fx.run(Sink.make((cause) => Queue.failCause(queue, cause), (value) => Queue.offer(queue, value))), options);
+/**
+ * Adapts a push-based `Fx` to an Effect `Stream`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Existing Effect [Stream](https://effect.website/docs/v4/api/effect/Stream) consumers
+ * can use an `Fx` without losing the producer's typed values, failures, or services.
+ * Values and causes cross a queue in emission order; the queue ends when the `Fx` run
+ * completes.
+ *
+ * ## Ownership and lifetime
+ *
+ * Conversion is lazy. Running the Stream allocates the callback queue and runs the
+ * `Fx`; the Stream's scope owns both. Interruption closes the callback subscription
+ * through Effect Stream's lifecycle. Buffering follows `options`.
+ *
+ * @example
+ * ```ts
+ * import { Stream } from "effect"
+ * import { fromIterable, toStream } from "@typed/fx/Fx"
+ *
+ * const values = toStream(fromIterable([1, 2, 3]))
+ * const total = Stream.runFold(values, () => 0, (sum, value) => sum + value)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Stream interop
+ */
+export const toStream = (fx, options) => Stream.callback((queue) => Effect.flatMap(fx.run(Sink.make((cause) => Queue.failCause(queue, cause), (value) => Queue.offer(queue, value))), () => Queue.end(queue)), options);
+/**
+ * Adapts an Effect `Stream` to a push-based `Fx`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Stream producers can participate in `Fx` composition without wrapping their
+ * behavior in a new abstraction. Each Stream element is offered to the sink through
+ * `Stream.mapEffect`; Stream causes are forwarded unchanged to `sink.onFailure`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Conversion starts nothing. Each `Fx.run` starts one Stream run owned by the caller's
+ * fiber and scope. Interruption stops the Stream and its finalizers. Delivery order
+ * and concurrency follow Effect Stream's `mapEffect` semantics and `options`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Stream } from "effect"
+ * import { collectAll, fromStream } from "@typed/fx/Fx"
+ *
+ * const source = fromStream(Stream.make("a", "b"))
+ * const values = collectAll(source)
+ * const program = Effect.map(values, (items) => items.join(""))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Stream interop
+ */
 export const fromStream = (stream, options) => make((sink) => pipe(stream, Stream.mapEffect(sink.onSuccess, options), Stream.catchCause((cause) => Stream.fromEffect(sink.onFailure(cause))), Stream.runDrain));