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

package/dist/Fx/constructors/fromIterable.js

@@ -4,6 +4,28 @@ import { make } from "./make.js";
  * Creates an Fx from an Iterable.
  * Emits each value from the iterable in order and then completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * Finite synchronous collections can participate in push composition without
+ * changing their iteration order or introducing a separate collection protocol.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction stores the iterable but does not iterate it. Each run obtains a fresh
+ * iterator, offers values sequentially to the sink, and completes after iteration.
+ * Interruption stops further iteration. No child fiber or buffer is created.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { collectAll, fromIterable } from "@typed/fx/Fx"
+ *
+ * const program = collectAll(fromIterable(new Set([1, 2, 3]))).pipe(
+ *   Effect.map((values) => values.join(","))
+ * )
+ * ```
+ *
  * @param iterable - The iterable to emit values from.
  * @returns An `Fx` that emits the values from the iterable.
  * @since 1.0.0

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

@@ -4,6 +4,29 @@ import type { Fx } from "../Fx.js";
  * Creates an Fx that emits values according to a Schedule.
  * The Fx emits `void` each time the schedule fires.
  *
+ * @remarks
+ * ## Why
+ *
+ * Effect [Schedule](https://effect.website/docs/v4/api/effect/Schedule) values already
+ * encode recurrence, delay, and typed schedule failures. `fromSchedule` exposes
+ * those decisions as producer-driven ticks without another timing model.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no clock. Running the `Fx` repeatedly invokes the sink under
+ * the schedule and completes when the schedule completes. Schedule failures are
+ * forwarded as causes; interruption cancels waiting and stops further ticks. The
+ * returned `Fx` retains the schedule's `Error` and `Env` channels.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { collectAll, fromSchedule } from "@typed/fx/Fx"
+ *
+ * const threeTicks = fromSchedule(Schedule.recurs(2))
+ * const program = collectAll(threeTicks)
+ * ```
+ *
  * @param schedule - The schedule to follow.
  * @returns An `Fx` that emits periodically according to the schedule.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"fromSchedule.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/fromSchedule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,EAAE,GAAG,EACrC,UAAU,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAC/C,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CACuE,CAAC"}
+{"version":3,"file":"fromSchedule.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/fromSchedule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,EAAE,GAAG,YAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAC/C,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAGnB,CAAC"}

package/dist/Fx/constructors/fromSchedule.js

@@ -1,13 +1,36 @@
-import { schedule as schedule_Effect } from "effect/Effect";
+import { catchCause, schedule as schedule_Effect } from "effect/Effect";
 import { make } from "./make.js";
 /**
  * Creates an Fx that emits values according to a Schedule.
  * The Fx emits `void` each time the schedule fires.
  *
+ * @remarks
+ * ## Why
+ *
+ * Effect [Schedule](https://effect.website/docs/v4/api/effect/Schedule) values already
+ * encode recurrence, delay, and typed schedule failures. `fromSchedule` exposes
+ * those decisions as producer-driven ticks without another timing model.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no clock. Running the `Fx` repeatedly invokes the sink under
+ * the schedule and completes when the schedule completes. Schedule failures are
+ * forwarded as causes; interruption cancels waiting and stops further ticks. The
+ * returned `Fx` retains the schedule's `Error` and `Env` channels.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { collectAll, fromSchedule } from "@typed/fx/Fx"
+ *
+ * const threeTicks = fromSchedule(Schedule.recurs(2))
+ * const program = collectAll(threeTicks)
+ * ```
+ *
  * @param schedule - The schedule to follow.
  * @returns An `Fx` that emits periodically according to the schedule.
  * @since 1.0.0
  * @category constructors
  */
 export const fromSchedule = (schedule) => 
-/*#__PURE__*/ make((sink) => schedule_Effect(sink.onSuccess(), schedule));
+/*#__PURE__*/ make((sink) => catchCause(schedule_Effect(sink.onSuccess(), schedule), sink.onFailure));

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

@@ -8,9 +8,10 @@ export * from "./fromEffect.js";
 export * from "./fromFailures.js";
 export * from "./fromIterable.js";
 export * from "./fromSchedule.js";
-export * from "./fromYieldable.js";
 export * from "./interrupt.js";
 export * from "./make.js";
 export * from "./periodic.js";
 export * from "./succeed.js";
+export * from "./suspend.js";
+export * from "./sync.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/Fx/constructors/index.js

@@ -8,8 +8,9 @@ export * from "./fromEffect.js";
 export * from "./fromFailures.js";
 export * from "./fromIterable.js";
 export * from "./fromSchedule.js";
-export * from "./fromYieldable.js";
 export * from "./interrupt.js";
 export * from "./make.js";
 export * from "./periodic.js";
 export * from "./succeed.js";
+export * from "./suspend.js";
+export * from "./sync.js";

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

@@ -1,7 +1,27 @@
 /**
  * Creates an Fx that immediately interrupts.
  *
- * @param id - The FiberId responsible for the interruption.
+ * @remarks
+ * ## Why
+ *
+ * A known Effect interruption cause can be represented as an `Fx` branch without
+ * disguising it as a typed failure or defect.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction is inert. Each run forwards one interruption cause carrying `id` to
+ * the sink, emits no values, and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { interrupt, observe } from "@typed/fx/Fx"
+ *
+ * const source = interrupt(1)
+ * const program = observe(source, () => Effect.void)
+ * ```
+ *
+ * @param id - Optional numeric fiber identifier responsible for the interruption.
  * @returns An `Fx` that is interrupted.
  * @since 1.0.0
  * @category constructors

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

@@ -1 +1 @@
-{"version":3,"file":"interrupt.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/interrupt.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,8EAAiD,CAAC"}
+{"version":3,"file":"interrupt.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/interrupt.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS,8EAAiD,CAAC"}

package/dist/Fx/constructors/interrupt.js

@@ -4,7 +4,27 @@ import { failCause } from "./failCause.js";
 /**
  * Creates an Fx that immediately interrupts.
  *
- * @param id - The FiberId responsible for the interruption.
+ * @remarks
+ * ## Why
+ *
+ * A known Effect interruption cause can be represented as an `Fx` branch without
+ * disguising it as a typed failure or defect.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction is inert. Each run forwards one interruption cause carrying `id` to
+ * the sink, emits no values, and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { interrupt, observe } from "@typed/fx/Fx"
+ *
+ * const source = interrupt(1)
+ * const program = observe(source, () => Effect.void)
+ * ```
+ *
+ * @param id - Optional numeric fiber identifier responsible for the interruption.
  * @returns An `Fx` that is interrupted.
  * @since 1.0.0
  * @category constructors

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

@@ -9,6 +9,31 @@ import type { Fx } from "../Fx.js";
  * This is the lowest-level constructor for Fx, giving you full control over
  * the stream's behavior.
  *
+ * @remarks
+ * ## Why
+ *
+ * `make` is the protocol boundary for custom producers. It exposes the real `Sink`
+ * operation so libraries can define cardinality, ordering, concurrency, causes, and
+ * services without an opinionated source wrapper.
+ *
+ * ## Ownership and lifetime
+ *
+ * `make` only stores `run`; it starts no work. Every call to `Fx.run` executes that
+ * function in the caller's fiber. The function must keep all acquisition and cleanup
+ * inside its returned Effect or a required `Scope`; its error channel is `never`
+ * because producer failures must be sent to `sink.onFailure`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { collectAll, make } from "@typed/fx/Fx"
+ *
+ * const pair = make<number>((sink) =>
+ *   Effect.andThen(sink.onSuccess(1), sink.onSuccess(2))
+ * )
+ * const program = collectAll(pair)
+ * ```
+ *
  * @param run - A function that takes a `Sink` and returns an `Effect` that drives the stream.
  * @returns An `Fx` instance.
  * @since 1.0.0
@@ -16,20 +41,140 @@ import type { Fx } from "../Fx.js";
  */
 export declare const make: <A, E = never, R = never>(run: <RSink = never>(sink: Sink<A, E, RSink>) => Effect.Effect<unknown, never, R | RSink>) => Fx<A, E, R>;
 /**
- * Interface for emitting values, errors, or completion signals in a callback-based Fx.
+ * Operations supplied to a callback producer for emitting values or ending its run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Callback sources need an explicit bridge into Sink operations while retaining the
+ * distinction between typed failures, defects, interruption causes, and completion.
+ *
+ * ## Ownership and lifetime
+ *
+ * An `Emit` is valid only for the active callback run. Every operation forks the
+ * corresponding sink Effect in that run's scope and returns its `Fiber`; callers may
+ * inspect or interrupt that delivery. Retaining it after cleanup is unsupported.
+ *
  * @since 1.0.0
  * @category models
  */
 export type Emit<A, E = never> = {
+    /**
+     * Starts delivery of one value and returns the delivery fiber.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Callback producers push values when they arrive instead of waiting to be pulled.
+     *
+     * ## Ownership and lifetime
+     *
+     * The active callback scope owns the returned fiber; deliveries can overlap when
+     * `succeed` is called again before an earlier sink Effect completes.
+     *
+     * @since 1.0.0
+     * @category emitters
+     */
     succeed: (value: A) => Fiber<unknown, never>;
+    /**
+     * Starts delivery of a complete Effect `Cause` and returns the delivery fiber.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Typed failures, defects, and interruption remain structurally distinct.
+     *
+     * ## Ownership and lifetime
+     *
+     * The active callback scope owns the returned fiber. This operation does not
+     * automatically call `done`; terminal behavior is determined by the sink.
+     *
+     * @since 1.0.0
+     * @category emitters
+     */
     failCause: (cause: Cause.Cause<E>) => Fiber<unknown, never>;
+    /**
+     * Starts delivery of one typed failure and returns the delivery fiber.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Expected callback errors enter `E` without being converted to defects.
+     *
+     * ## Ownership and lifetime
+     *
+     * The active callback scope owns the returned fiber. The error is wrapped with
+     * `Cause.fail` and forwarded to the sink.
+     *
+     * @since 1.0.0
+     * @category emitters
+     */
     fail: (error: E) => Fiber<unknown, never>;
+    /**
+     * Starts delivery of one unexpected defect and returns the delivery fiber.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Programming defects remain outside the typed `E` channel.
+     *
+     * ## Ownership and lifetime
+     *
+     * The active callback scope owns the returned fiber. The value is wrapped with
+     * `Cause.die` and forwarded to the sink.
+     *
+     * @since 1.0.0
+     * @category emitters
+     */
     die: (error: unknown) => Fiber<unknown, never>;
+    /**
+     * Requests early completion and returns the sink's early-exit fiber.
+     *
+     * @remarks
+     * ## Why
+     *
+     * Finite callback APIs need an explicit completion signal distinct from failure.
+     *
+     * ## Ownership and lifetime
+     *
+     * The active callback scope owns the returned fiber. Early exit ends the run and
+     * causes callback cleanup registered by `callback` to execute.
+     *
+     * @since 1.0.0
+     * @category emitters
+     */
     done: () => Fiber<unknown, never>;
 };
 /**
  * Creates an Fx from a callback-based source.
  *
+ * @remarks
+ * ## Why
+ *
+ * DOM events, sockets, observers, and foreign libraries decide when values exist.
+ * `callback` turns that push boundary into `Fx` while keeping failure and cleanup
+ * inside Effect's structured lifetime.
+ *
+ * ## Ownership and lifetime
+ *
+ * Registration is lazy: `run` is called once for each `Fx` run. The run creates a
+ * child scope and stays active until `emit.done()`, sink early exit, or interruption.
+ * If `run` returns an Effect, it is registered as the scope finalizer. Each emit
+ * operation starts its sink handler in a fiber, so handler completion can overlap;
+ * use the returned fibers or a serialized source when ordering of effects matters.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { callback, collectUpTo } from "@typed/fx/Fx"
+ *
+ * const messages = callback<string>((emit) => {
+ *   const timer = setInterval(() => emit.succeed("tick"), 10)
+ *   return Effect.sync(() => clearInterval(timer))
+ * })
+ * const program = collectUpTo(messages, 2)
+ * ```
+ *
  * @param run - A function that receives an `Emit` object to push values/errors.
  *              It can return a cleanup effect.
  * @returns An `Fx` adapted from the callback.

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

@@ -1 +1 @@
-{"version":3,"file":"make.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/make.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAK1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAsBnC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAC1C,KAAK,CAAC,KAAK,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KACxF,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAA2B,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7C,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5D,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1C,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;CACnC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAC9C,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KACjE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAiCV,CAAC"}
+{"version":3,"file":"make.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/make.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAK1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAsBnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,OACrC,CAAC,KAAK,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KACxF,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAA2B,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7C;;;;;;;;;;;;;;;OAeG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5D;;;;;;;;;;;;;;;OAeG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C;;;;;;;;;;;;;;;OAeG;IACH,IAAI,EAAE,MAAM,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,OACzC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KACjE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CA6BV,CAAC"}

package/dist/Fx/constructors/make.js

@@ -26,6 +26,31 @@ class Make {
  * This is the lowest-level constructor for Fx, giving you full control over
  * the stream's behavior.
  *
+ * @remarks
+ * ## Why
+ *
+ * `make` is the protocol boundary for custom producers. It exposes the real `Sink`
+ * operation so libraries can define cardinality, ordering, concurrency, causes, and
+ * services without an opinionated source wrapper.
+ *
+ * ## Ownership and lifetime
+ *
+ * `make` only stores `run`; it starts no work. Every call to `Fx.run` executes that
+ * function in the caller's fiber. The function must keep all acquisition and cleanup
+ * inside its returned Effect or a required `Scope`; its error channel is `never`
+ * because producer failures must be sent to `sink.onFailure`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { collectAll, make } from "@typed/fx/Fx"
+ *
+ * const pair = make<number>((sink) =>
+ *   Effect.andThen(sink.onSuccess(1), sink.onSuccess(2))
+ * )
+ * const program = collectAll(pair)
+ * ```
+ *
  * @param run - A function that takes a `Sink` and returns an `Effect` that drives the stream.
  * @returns An `Fx` instance.
  * @since 1.0.0
@@ -35,6 +60,33 @@ export const make = (run) => new Make(run);
 /**
  * Creates an Fx from a callback-based source.
  *
+ * @remarks
+ * ## Why
+ *
+ * DOM events, sockets, observers, and foreign libraries decide when values exist.
+ * `callback` turns that push boundary into `Fx` while keeping failure and cleanup
+ * inside Effect's structured lifetime.
+ *
+ * ## Ownership and lifetime
+ *
+ * Registration is lazy: `run` is called once for each `Fx` run. The run creates a
+ * child scope and stays active until `emit.done()`, sink early exit, or interruption.
+ * If `run` returns an Effect, it is registered as the scope finalizer. Each emit
+ * operation starts its sink handler in a fiber, so handler completion can overlap;
+ * use the returned fibers or a serialized source when ordering of effects matters.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { callback, collectUpTo } from "@typed/fx/Fx"
+ *
+ * const messages = callback<string>((emit) => {
+ *   const timer = setInterval(() => emit.succeed("tick"), 10)
+ *   return Effect.sync(() => clearInterval(timer))
+ * })
+ * const program = collectUpTo(messages, 2)
+ * ```
+ *
  * @param run - A function that receives an `Emit` object to push values/errors.
  *              It can return a cleanup effect.
  * @returns An `Fx` adapted from the callback.
@@ -44,9 +96,8 @@ export const make = (run) => new Make(run);
 export const callback = (run) => make((sink) => Effect.acquireUseRelease(Scope.make(), (scope) => withEarlyExit(sink, Effect.fn(function* (sink) {
     const services = yield* Effect.context();
     const runFork = Effect.runForkWith(services);
-    const controller = new AbortController();
-    yield* Scope.addFinalizer(scope, Effect.sync(() => controller.abort()));
-    const runEffect = (effect) => runFork(effect, { signal: controller.signal });
+    const signal = yield* Scope.provide(Effect.abortSignal, scope);
+    const runEffect = (effect) => runFork(effect, { signal });
     const emit = {
         succeed: (value) => runEffect(sink.onSuccess(value)),
         failCause: (cause) => runEffect(sink.onFailure(cause)),

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

@@ -3,6 +3,35 @@ import type { Fx } from "../Fx.js";
 /**
  * Creates an Fx that emits a `void` value periodically.
  *
+ * @remarks
+ * ## Why
+ *
+ * Common interval work can use Effect's
+ * [Schedule](https://effect.website/docs/v4/api/effect/Schedule) clock and
+ * interruption semantics rather than an unmanaged platform timer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no clock. A run waits `period` before the first emission and
+ * again between every subsequent emission. The run fiber owns the schedule; no ticks
+ * continue after interruption.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import * as TestClock from "effect/testing/TestClock"
+ * import { collectUpTo, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* Effect.forkChild(collectUpTo(periodic("1 second"), 1))
+ *   yield* TestClock.adjust("999 millis")
+ *   const beforeFirstPeriod = fiber.pollUnsafe()
+ *   yield* TestClock.adjust("1 millis")
+ *   const firstTick = yield* Fiber.join(fiber)
+ *   return { beforeFirstPeriod, firstTick }
+ * })
+ * ```
+ *
  * @param period - The duration between emissions.
  * @returns An `Fx` that emits repeatedly.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"periodic.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/periodic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,QAAQ,CAAC,KAAK,KAAG,EAAE,CAAC,IAAI,CACb,CAAC"}
+{"version":3,"file":"periodic.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/periodic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,QAAQ,WAAY,QAAQ,CAAC,KAAK,KAAG,EAAE,CAAC,IAAI,CACb,CAAC"}

package/dist/Fx/constructors/periodic.js

@@ -3,6 +3,35 @@ import { fromSchedule } from "./fromSchedule.js";
 /**
  * Creates an Fx that emits a `void` value periodically.
  *
+ * @remarks
+ * ## Why
+ *
+ * Common interval work can use Effect's
+ * [Schedule](https://effect.website/docs/v4/api/effect/Schedule) clock and
+ * interruption semantics rather than an unmanaged platform timer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no clock. A run waits `period` before the first emission and
+ * again between every subsequent emission. The run fiber owns the schedule; no ticks
+ * continue after interruption.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import * as TestClock from "effect/testing/TestClock"
+ * import { collectUpTo, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* Effect.forkChild(collectUpTo(periodic("1 second"), 1))
+ *   yield* TestClock.adjust("999 millis")
+ *   const beforeFirstPeriod = fiber.pollUnsafe()
+ *   yield* TestClock.adjust("1 millis")
+ *   const firstTick = yield* Fiber.join(fiber)
+ *   return { beforeFirstPeriod, firstTick }
+ * })
+ * ```
+ *
  * @param period - The duration between emissions.
  * @returns An `Fx` that emits repeatedly.
  * @since 1.0.0

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

@@ -2,6 +2,24 @@ import type { Fx } from "../Fx.js";
 /**
  * Creates an Fx that emits a single value and then completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * A known value can enter `Fx` composition without adding failure or service
+ * requirements.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction stores the value. Each run offers it exactly once, waits for the sink
+ * handler, and completes without acquiring resources.
+ *
+ * @example
+ * ```ts
+ * import { collectAll, succeed } from "@typed/fx/Fx"
+ *
+ * const program = collectAll(succeed({ status: "ready" }))
+ * ```
+ *
  * @param value - The value to emit.
  * @returns An `Fx` that emits the value.
  * @since 1.0.0
@@ -9,21 +27,75 @@ import type { Fx } from "../Fx.js";
  */
 export declare const succeed: <A>(value: A) => Fx<A>;
 /**
- * An Fx that emits `null` and then completes.
+ * An Fx that emits `null` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant avoids repeatedly spelling `succeed(null)` in optional-value
+ * compositions. It is also exported as `null`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { first, succeedNull } from "@typed/fx/Fx"
+ *
+ * const program = first(succeedNull)
+ * ```
+ *
  * @since 1.0.0
  * @category constructors
  */
 export declare const succeedNull: Fx<null, never, never>;
 export { succeedNull as null };
 /**
- * An Fx that emits `undefined` and then completes.
+ * An Fx that emits `undefined` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant avoids repeatedly spelling `succeed(undefined)` in optional
+ * compositions. It is also exported as `undefined`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { first, succeedUndefined } from "@typed/fx/Fx"
+ *
+ * const program = first(succeedUndefined)
+ * ```
+ *
  * @since 1.0.0
  * @category constructors
  */
 export declare const succeedUndefined: Fx<undefined, never, never>;
 export { succeedUndefined as undefined };
 /**
- * An Fx that emits `void` and then completes.
+ * An Fx that emits `void` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant is a completion pulse for operations whose payload is
+ * irrelevant. It is also exported as `void`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { drain, succeedVoid } from "@typed/fx/Fx"
+ *
+ * const program = drain(succeedVoid)
+ * ```
+ *
  * @since 1.0.0
  * @category constructors
  */

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

@@ -1 +1 @@
-{"version":3,"file":"succeed.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/succeed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,EAAE,CAAC,CAAC,CACc,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,WAAW,wBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAAgC,CAAC;AAC9D,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC"}
+{"version":3,"file":"succeed.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/succeed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,CAAC,KAAG,EAAE,CAAC,CAAC,CACc,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,wBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB,6BAAgC,CAAC;AAC9D,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC"}