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

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

@@ -1,10 +1,30 @@
 /**
  * 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
+ * @category Failure sources
  */
 export declare const interrupt: (fiberId?: number | undefined) => import("../Fx.js").Fx<never, never, never>;
 //# sourceMappingURL=interrupt.d.ts.map

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,9 +4,29 @@ 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
+ * @category Failure sources
  */
 export const interrupt = /*#__PURE__*/ flow(Cause.interrupt, failCause);

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

@@ -9,32 +9,179 @@ 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` stores the callback without invoking it. Calling `fx.run(sink)` asks the
+ * callback to construct its Effect; executing that Effect performs the subscription.
+ * Keep acquisition, publication, and cleanup inside the returned Effect or a required
+ * `Scope`, rather than performing side effects while constructing it. The returned
+ * Effect has no typed failure channel because producer failures are delivered through
+ * `sink.onFailure`; defects and interruption can still affect the run.
+ *
+ * @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
- * @category constructors
+ * @category Callback sources
  */
 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
+ * @category Callback protocol
  */
 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.
  * @since 1.0.0
- * @category constructors
+ * @category Callback sources
  */
 export declare const callback: <A, E = never, R = never>(run: (emit: Emit<A, E>) => void | Effect.Effect<unknown, never, R>) => Fx<A, E, R>;
 //# sourceMappingURL=make.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,27 +26,80 @@ 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` stores the callback without invoking it. Calling `fx.run(sink)` asks the
+ * callback to construct its Effect; executing that Effect performs the subscription.
+ * Keep acquisition, publication, and cleanup inside the returned Effect or a required
+ * `Scope`, rather than performing side effects while constructing it. The returned
+ * Effect has no typed failure channel because producer failures are delivered through
+ * `sink.onFailure`; defects and interruption can still affect the run.
+ *
+ * @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
- * @category constructors
+ * @category Callback sources
  */
 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.
  * @since 1.0.0
- * @category constructors
+ * @category Callback sources
  */
 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 +109,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,10 +3,39 @@ 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
- * @category constructors
+ * @category Time and rate
  */
-export declare const periodic: (period: Duration.DurationInput) => Fx<void>;
+export declare const periodic: (period: Duration.Input) => Fx<void>;
 //# sourceMappingURL=periodic.d.ts.map

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,aAAa,KAAG,EAAE,CAAC,IAAI,CACrB,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,10 +3,39 @@ 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
- * @category constructors
+ * @category Time and rate
  */
 export const periodic = (period) => 
 /*#__PURE__*/ fromSchedule(spaced(period));

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

@@ -2,30 +2,102 @@ 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
- * @category constructors
+ * @category Value sources
  */
 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
+ * @category Value sources
  */
 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
+ * @category Value sources
  */
 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
+ * @category Value sources
  */
 export declare const succeedVoid: Fx<void, never, never>;
 export { succeedVoid as void };

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"}

package/dist/Fx/constructors/succeed.js

@@ -2,31 +2,103 @@ import { make } from "./make.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
- * @category constructors
+ * @category Value sources
  */
 export const succeed = (value) => 
 /*#__PURE__*/ make((sink) => sink.onSuccess(value));
 /**
- * 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
+ * @category Value sources
  */
 export const succeedNull = succeed(null);
 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
+ * @category Value sources
  */
 export const succeedUndefined = succeed(undefined);
 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
+ * @category Value sources
  */
 export const succeedVoid = succeed(void 0);
 export { succeedVoid as void };