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

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

@@ -1,6 +1,30 @@
 /**
  * Creates an Fx from a collection of failures (errors).
  *
+ * @remarks
+ * ## Why
+ *
+ * Validation and batch operations can preserve every independent typed failure in a
+ * single Effect `Cause` rather than choosing one error or emitting partial values.
+ * Equal reasons are de-duplicated by `Cause.combine`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The iterable is consumed eagerly when `fromFailures` is called. Running the result
+ * forwards the combined cause once, emits no values, and acquires no resources. An
+ * empty iterable produces the empty Cause.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { fromFailures, observe } from "@typed/fx/Fx"
+ *
+ * const failures = fromFailures(["name", "email"])
+ * const program = observe(failures, () => Effect.void).pipe(
+ *   Effect.catch((error) => Effect.succeed(error))
+ * )
+ * ```
+ *
  * @param failures - An iterable of failures.
  * @returns An `Fx` that fails with the combined failures.
  * @since 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"fromFailures.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/fromFailures.ts"],"names":[],"mappings":"AAUA;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAdE,CAAC,kEAcgD,CAAC"}
+{"version":3,"file":"fromFailures.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/fromFailures.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,YAAY,GAtCE,CAAC,kEAsCgD,CAAC"}

package/dist/Fx/constructors/fromFailures.js

@@ -5,6 +5,30 @@ const fromFailuresCause = (failures) => Array.from(failures).reduce((acc, e) =>
 /**
  * Creates an Fx from a collection of failures (errors).
  *
+ * @remarks
+ * ## Why
+ *
+ * Validation and batch operations can preserve every independent typed failure in a
+ * single Effect `Cause` rather than choosing one error or emitting partial values.
+ * Equal reasons are de-duplicated by `Cause.combine`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The iterable is consumed eagerly when `fromFailures` is called. Running the result
+ * forwards the combined cause once, emits no values, and acquires no resources. An
+ * empty iterable produces the empty Cause.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { fromFailures, observe } from "@typed/fx/Fx"
+ *
+ * const failures = fromFailures(["name", "email"])
+ * const program = observe(failures, () => Effect.void).pipe(
+ *   Effect.catch((error) => Effect.succeed(error))
+ * )
+ * ```
+ *
  * @param failures - An iterable of failures.
  * @returns An `Fx` that fails with the combined failures.
  * @since 1.0.0

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

@@ -3,6 +3,28 @@ import type { Fx } from "../Fx.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/fromIterable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fromIterable.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/fromIterable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,UAAU,QAAQ,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,CACa,CAAC"}
+{"version":3,"file":"fromIterable.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/fromIterable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,CACa,CAAC"}

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.
@@ -42,11 +94,10 @@ export const make = (run) => new Make(run);
  * @category constructors
  */
 export const callback = (run) => make((sink) => Effect.acquireUseRelease(Scope.make(), (scope) => withEarlyExit(sink, Effect.fn(function* (sink) {
-    const services = yield* Effect.services();
+    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)),
@@ -56,6 +107,6 @@ export const callback = (run) => make((sink) => Effect.acquireUseRelease(Scope.m
     };
     const effect = run(emit);
     if (effect)
-        yield* Scope.addFinalizer(scope, Effect.provideServices(effect, services));
+        yield* Scope.addFinalizer(scope, Effect.provideContext(effect, services));
     return yield* Effect.never;
 })), Scope.close));

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