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

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

@@ -4,29 +4,95 @@ import type { Fx } from "../Fx.js";
 /**
  * Collects all values emitted by an `Fx` into an array.
  *
+ * @remarks
+ * ## Why
+ *
+ * Finite producers sometimes need to cross from push processing back to one Effect
+ * value. `collectAll` makes that buffering explicit rather than hiding it in `Fx`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The array is allocated separately for each Effect run. Subscription starts when the
+ * Effect runs and ends on source completion, failure, or interruption. Every emitted
+ * value is retained until completion, so an infinite source never completes and can
+ * grow memory without bound. Failures and services remain in `E` and `R`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { collectAll, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = collectAll(fromIterable([1, 2, 3])).pipe(
+ *   Effect.map((values) => values.reduce((sum, value) => sum + value, 0))
+ * )
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @returns An `Effect` that produces an array of all values when the `Fx` completes.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export declare const collectAll: <A, E = never, R = never>(fx: Fx<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
 /**
  * Forks the collection of all values from an `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Collection can proceed concurrently while the caller retains a typed `Fiber` for
+ * awaiting, polling, or interruption.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the returned Effect starts a child fiber immediately. The parent fiber's
+ * scope supervises it, so parent termination interrupts collection. The child retains
+ * every value until completion and exposes source failure as its `E` channel.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { collectAllFork, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* collectAllFork(fromIterable([1, 2, 3]))
+ *   return yield* Fiber.join(fiber)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @returns An `Effect` that produces a `Fiber` which computes the array of values.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export declare const collectAllFork: <A, E = never, R = never>(fx: Fx<A, E, R>) => Effect.Effect<Fiber.Fiber<ReadonlyArray<A>, E>, never, R>;
 /**
  * Collects the first `n` values emitted by an `Fx` into an array.
  *
+ * @remarks
+ * ## Why
+ *
+ * `collectUpTo` creates a bounded pull result from a push source and stops upstream as
+ * soon as the requested cardinality has arrived.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each Effect run owns a fresh array and source subscription. At most `upTo` values
+ * are retained in producer order; reaching the bound requests early exit and cleans
+ * up upstream. If the source completes first, the shorter array is returned. Source
+ * failures before completion remain typed.
+ *
+ * @example
+ * ```ts
+ * import { collectUpTo, fromIterable } from "@typed/fx/Fx"
+ *
+ * const firstTwo = collectUpTo(fromIterable([1, 2, 3]), 2)
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @param upTo - The maximum number of values to collect.
  * @returns An `Effect` that produces an array of up to `n` values.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export declare const collectUpTo: {
     (upTo: number): <A, E, R>(fx: Fx<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -35,11 +101,34 @@ export declare const collectUpTo: {
 /**
  * Forks the collection of up to `n` values from an `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * A bounded collection can run concurrently while the caller keeps control through
+ * the returned fiber.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the Effect starts a supervised child immediately. It retains at most
+ * `upTo` values, stops upstream at the bound, and is interrupted when its parent
+ * terminates. Source failures are reported by the child fiber.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { collectUpToFork, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* collectUpToFork(periodic("10 millis"), 2)
+ *   return yield* Fiber.join(fiber)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @param upTo - The maximum number of values to collect.
  * @returns An `Effect` that produces a `Fiber` which computes the array of values.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export declare const collectUpToFork: <A, E = never, R = never>(fx: Fx<A, E, R>, upTo: number) => Effect.Effect<Fiber.Fiber<ReadonlyArray<A>, E>, never, R>;
 //# sourceMappingURL=collect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/collect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAChD,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAQnC,CAAC;AAEL;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EACpD,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAIvD,CAAC;AAEL;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE;IACxB,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAKjF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EACrD,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAIvD,CAAC"}
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/collect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,MAC5C,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAQnC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,MAChD,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACd,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAIvD,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,WAAW,EAAE;IACxB,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAKjF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,MACjD,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,QACT,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAIvD,CAAC"}

package/dist/Fx/run/collect.js

@@ -5,22 +5,68 @@ import { observe } from "./observe.js";
 /**
  * Collects all values emitted by an `Fx` into an array.
  *
+ * @remarks
+ * ## Why
+ *
+ * Finite producers sometimes need to cross from push processing back to one Effect
+ * value. `collectAll` makes that buffering explicit rather than hiding it in `Fx`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The array is allocated separately for each Effect run. Subscription starts when the
+ * Effect runs and ends on source completion, failure, or interruption. Every emitted
+ * value is retained until completion, so an infinite source never completes and can
+ * grow memory without bound. Failures and services remain in `E` and `R`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { collectAll, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = collectAll(fromIterable([1, 2, 3])).pipe(
+ *   Effect.map((values) => values.reduce((sum, value) => sum + value, 0))
+ * )
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @returns An `Effect` that produces an array of all values when the `Fx` completes.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export const collectAll = (fx) => Effect.suspend(() => {
     const values = [];
-    return fx.pipe(observe((value) => Effect.sync(() => values.push(value))), (_) => Effect.map(_.asEffect(), () => values));
+    return fx.pipe(observe((value) => Effect.sync(() => values.push(value))), Effect.map(() => values));
 });
 /**
  * Forks the collection of all values from an `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Collection can proceed concurrently while the caller retains a typed `Fiber` for
+ * awaiting, polling, or interruption.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the returned Effect starts a child fiber immediately. The parent fiber's
+ * scope supervises it, so parent termination interrupts collection. The child retains
+ * every value until completion and exposes source failure as its `E` channel.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { collectAllFork, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* collectAllFork(fromIterable([1, 2, 3]))
+ *   return yield* Fiber.join(fiber)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @returns An `Effect` that produces a `Fiber` which computes the array of values.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export const collectAllFork = (fx) => Effect.forkChild(collectAll(fx), {
     startImmediately: true,
@@ -29,21 +75,64 @@ export const collectAllFork = (fx) => Effect.forkChild(collectAll(fx), {
 /**
  * Collects the first `n` values emitted by an `Fx` into an array.
  *
+ * @remarks
+ * ## Why
+ *
+ * `collectUpTo` creates a bounded pull result from a push source and stops upstream as
+ * soon as the requested cardinality has arrived.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each Effect run owns a fresh array and source subscription. At most `upTo` values
+ * are retained in producer order; reaching the bound requests early exit and cleans
+ * up upstream. If the source completes first, the shorter array is returned. Source
+ * failures before completion remain typed.
+ *
+ * @example
+ * ```ts
+ * import { collectUpTo, fromIterable } from "@typed/fx/Fx"
+ *
+ * const firstTwo = collectUpTo(fromIterable([1, 2, 3]), 2)
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @param upTo - The maximum number of values to collect.
  * @returns An `Effect` that produces an array of up to `n` values.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export const collectUpTo = dual(2, (fx, upTo) => fx.pipe(take(upTo), collectAll));
 /**
  * Forks the collection of up to `n` values from an `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * A bounded collection can run concurrently while the caller keeps control through
+ * the returned fiber.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the Effect starts a supervised child immediately. It retains at most
+ * `upTo` values, stops upstream at the bound, and is interrupted when its parent
+ * terminates. Source failures are reported by the child fiber.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { collectUpToFork, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* collectUpToFork(periodic("10 millis"), 2)
+ *   return yield* Fiber.join(fiber)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` to collect values from.
  * @param upTo - The maximum number of values to collect.
  * @returns An `Effect` that produces a `Fiber` which computes the array of values.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export const collectUpToFork = (fx, upTo) => Effect.forkChild(collectUpTo(fx, upTo), {
     startImmediately: true,

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

@@ -5,10 +5,32 @@ import type { Fx } from "../Fx.js";
  * Returns the first value emitted by the `Fx` wrapped in an `Option`.
  * If the `Fx` is empty, returns `None`.
  *
+ * @remarks
+ * ## Why
+ *
+ * `first` safely crosses from a possibly empty push source to one Effect value without
+ * inventing an error for the zero-emission case.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the Effect subscribes once and stops upstream after the first value. It
+ * returns `None` only when the source completes first; a source failure is still `E`.
+ * Interruption cleans up the active source.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { first, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = first(fromIterable([10, 20])).pipe(
+ *   Effect.map(Option.getOrElse(() => 0))
+ * )
+ * ```
+ *
  * @param fx - The `Fx` stream.
  * @returns An `Effect` that produces `Some(firstValue)` or `None`.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export declare function first<A, E, R>(fx: Fx<A, E, R>): Effect<Option<A>, E, R>;
 //# sourceMappingURL=first.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"first.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/first.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEvE"}
+{"version":3,"file":"first.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/first.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEvE"}

package/dist/Fx/run/first.js

@@ -6,10 +6,32 @@ import { collectUpTo } from "./collect.js";
  * Returns the first value emitted by the `Fx` wrapped in an `Option`.
  * If the `Fx` is empty, returns `None`.
  *
+ * @remarks
+ * ## Why
+ *
+ * `first` safely crosses from a possibly empty push source to one Effect value without
+ * inventing an error for the zero-emission case.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running the Effect subscribes once and stops upstream after the first value. It
+ * returns `None` only when the source completes first; a source failure is still `E`.
+ * Interruption cleans up the active source.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import { first, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = first(fromIterable([10, 20])).pipe(
+ *   Effect.map(Option.getOrElse(() => 0))
+ * )
+ * ```
+ *
  * @param fx - The `Fx` stream.
  * @returns An `Effect` that produces `Some(firstValue)` or `None`.
  * @since 1.0.0
- * @category runners
+ * @category Collecting values
  */
 export function first(fx) {
     return pipe(fx, collectUpTo(1), map(head));

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

@@ -5,11 +5,36 @@ import type { Fx } from "../Fx.js";
  * Forks the execution of an `Fx` into a background fiber.
  * The stream will run until it completes or the fiber is interrupted.
  *
+ * @remarks
+ * ## Why
+ *
+ * `fork` keeps background execution inside Effect's supervised fiber tree while
+ * returning an explicit handle for coordination.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect acquires the source services and creates a child attached to
+ * the calling fiber's scope. Parent termination interrupts the child. By default the
+ * child starts immediately and remains interruptible; `options` can change those two
+ * Effect fiber policies. Values are discarded and source failure is reported by the
+ * child fiber.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { fork, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* fork(periodic("1 second"))
+ *   return yield* Fiber.interrupt(fiber)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` stream to fork.
  * @param options - Configuration for the forked fiber.
  * @returns An `Effect` that produces a `Fiber`.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export declare const fork: <A, E, R>(fx: Fx<A, E, R>, options?: {
     readonly startImmediately?: boolean;
@@ -19,11 +44,36 @@ export declare const fork: <A, E, R>(fx: Fx<A, E, R>, options?: {
  * Runs an `Fx` in a new fiber, using the standard `Effect.runFork`.
  * This is useful for integrating with the top-level Effect runtime.
  *
+ * @remarks
+ * ## Why
+ *
+ * Application and foreign-runtime boundaries sometimes need to start an `Fx` without
+ * already being inside an Effect program.
+ *
+ * ## Ownership and lifetime
+ *
+ * `runFork` starts immediately on Effect's default runtime, so it only accepts an `Fx`
+ * with no unsupplied services. The returned root fiber owns the subscription and must
+ * be interrupted by the caller when the source should stop. Values are discarded;
+ * failures appear on the fiber and `RunOptions` controls the runtime launch.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { periodic, runFork } from "@typed/fx/Fx"
+ *
+ * const fiber = runFork(periodic("1 second"))
+ *
+ * // `runFork` is already a host-runtime boundary. Execute the returned
+ * // interruption Effect when this host no longer needs the subscription.
+ * await Effect.runPromise(Fiber.interrupt(fiber))
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @param options - `RunOptions` for the execution.
  * @returns The created `Fiber`.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export declare const runFork: <A, E>(fx: Fx<A, E>, options?: RunOptions) => Fiber<void, E>;
 //# sourceMappingURL=fork.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/fork.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAC1B,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,UAAU;IACR,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC,KACA,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAIjC,CAAC;AAEL;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,UAAU,KAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAC7C,CAAC"}
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../../src/Fx/run/fork.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MACtB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,YACL;IACR,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC,KACA,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAIjC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,UAAU,KAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAC7C,CAAC"}

package/dist/Fx/run/fork.js

@@ -4,11 +4,36 @@ import { drain } from "./observe.js";
  * Forks the execution of an `Fx` into a background fiber.
  * The stream will run until it completes or the fiber is interrupted.
  *
+ * @remarks
+ * ## Why
+ *
+ * `fork` keeps background execution inside Effect's supervised fiber tree while
+ * returning an explicit handle for coordination.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect acquires the source services and creates a child attached to
+ * the calling fiber's scope. Parent termination interrupts the child. By default the
+ * child starts immediately and remains interruptible; `options` can change those two
+ * Effect fiber policies. Values are discarded and source failure is reported by the
+ * child fiber.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { fork, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* fork(periodic("1 second"))
+ *   return yield* Fiber.interrupt(fiber)
+ * })
+ * ```
+ *
  * @param fx - The `Fx` stream to fork.
  * @param options - Configuration for the forked fiber.
  * @returns An `Effect` that produces a `Fiber`.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export const fork = (fx, options) => effectFork(drain(fx), {
     startImmediately: options?.startImmediately ?? true,
@@ -18,10 +43,35 @@ export const fork = (fx, options) => effectFork(drain(fx), {
  * Runs an `Fx` in a new fiber, using the standard `Effect.runFork`.
  * This is useful for integrating with the top-level Effect runtime.
  *
+ * @remarks
+ * ## Why
+ *
+ * Application and foreign-runtime boundaries sometimes need to start an `Fx` without
+ * already being inside an Effect program.
+ *
+ * ## Ownership and lifetime
+ *
+ * `runFork` starts immediately on Effect's default runtime, so it only accepts an `Fx`
+ * with no unsupplied services. The returned root fiber owns the subscription and must
+ * be interrupted by the caller when the source should stop. Values are discarded;
+ * failures appear on the fiber and `RunOptions` controls the runtime launch.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import { periodic, runFork } from "@typed/fx/Fx"
+ *
+ * const fiber = runFork(periodic("1 second"))
+ *
+ * // `runFork` is already a host-runtime boundary. Execute the returned
+ * // interruption Effect when this host no longer needs the subscription.
+ * await Effect.runPromise(Fiber.interrupt(fiber))
+ * ```
+ *
  * @param fx - The `Fx` stream to run.
  * @param options - `RunOptions` for the execution.
  * @returns The created `Fiber`.
  * @since 1.0.0
- * @category runners
+ * @category Running effects
  */
 export const runFork = (fx, options) => effectRunFork(drain(fx), options);

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

@@ -6,11 +6,40 @@ import type { Fx } from "../Fx.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 declare const observe: {
     <A, E2 = never, R2 = never>(f: (value: A) => void | Effect<unknown, E2, R2>): <E, R>(fx: Fx<A, E, R>) => Effect<unknown, E | E2, R | R2>;
@@ -20,31 +49,110 @@ export declare const observe: {
  * 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 declare const drain: <A, E, R>(fx: Fx<A, E, R>) => Effect<void, E, R>;
 /**
  * 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 declare const drainLayer: <A, E, R>(fx: Fx<A, E, R>) => Layer<never, E, Exclude<R, Scope>>;
 /**
  * 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 declare const observeLayer: {
     <A, E2 = never, R2 = never>(f: (value: A) => void | Effect<unknown, E2, R2>): <E, R>(fx: Fx<A, E, R>) => Layer<never, E | E2, Exclude<R | R2, Scope>>;