@typed/fx 2.0.0-beta.4 → 2.0.0-beta.5

package/dist/Fx/run/observe.js

@@ -7,6 +7,33 @@ 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`.
+ *
+ * @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.
@@ -26,6 +53,25 @@ export const observe = dual(2, (fx, f) => contextWith((services) => callback((re
  * 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
@@ -36,6 +82,36 @@ 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
@@ -46,6 +122,36 @@ 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.

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

@@ -4,6 +4,28 @@ 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.
@@ -15,6 +37,27 @@ export declare const runPromiseExit: <A, E>(fx: Fx<A, E>, options?: RunOptions)
  * 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.

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,6 +3,28 @@ 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.
@@ -14,6 +36,27 @@ export const runPromiseExit = (fx, options) => Effect.runPromiseExit(drain(fx),
  * 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.

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 models
+ */
 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 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 models
+ */
 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 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 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 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));