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

package/dist/Fx/combinators/changesWithEffect.d.ts

@@ -8,6 +8,26 @@ import type { Fx } from "../Fx.js";
  * `Equivalence<A>`, you supply `(prev, next) => Effect<boolean>` where `true`
  * means "equal" (skip) and `false` means "changed" (emit).
  *
+ * @remarks
+ * ## Why
+ * `changesWithEffect` supports service-backed or failing equivalence checks. The first value always
+ * emits; every later value is compared with the last emitted value and emits only when the effect
+ * returns `false`, preserving source order.
+ *
+ * ## Ownership and lifetime
+ * One previous value and a semaphore are scoped to each run. Comparison effects are serialized,
+ * interrupted with the run, and add their failures and services to the resulting Fx.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const changes = Fx.fromIterable([1, 1, 2]).pipe(
+ *   Fx.changesWithEffect((previous, next) => Effect.succeed(previous === next)),
+ * )
+ * ```
+ *
  * @param f - Effectful function: `(prev, next) => Effect<boolean>`. Return `true` to skip (treat as duplicate), `false` to emit.
  * @returns An `Fx` with consecutive "equal" elements removed.
  * @since 1.0.0

package/dist/Fx/combinators/changesWithEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changesWithEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/changesWithEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAMxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,EAAE;IAC9B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GACtD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEzD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACpB,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GACtD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAoC1B,CAAC"}
+{"version":3,"file":"changesWithEffect.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/changesWithEffect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAMxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,iBAAiB,EAAE;IAC9B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GACtD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEzD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EACpB,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GACtD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAoC1B,CAAC"}

package/dist/Fx/combinators/changesWithEffect.js

@@ -12,6 +12,26 @@ import { make } from "../constructors/make.js";
  * `Equivalence<A>`, you supply `(prev, next) => Effect<boolean>` where `true`
  * means "equal" (skip) and `false` means "changed" (emit).
  *
+ * @remarks
+ * ## Why
+ * `changesWithEffect` supports service-backed or failing equivalence checks. The first value always
+ * emits; every later value is compared with the last emitted value and emits only when the effect
+ * returns `false`, preserving source order.
+ *
+ * ## Ownership and lifetime
+ * One previous value and a semaphore are scoped to each run. Comparison effects are serialized,
+ * interrupted with the run, and add their failures and services to the resulting Fx.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const changes = Fx.fromIterable([1, 1, 2]).pipe(
+ *   Fx.changesWithEffect((previous, next) => Effect.succeed(previous === next)),
+ * )
+ * ```
+ *
  * @param f - Effectful function: `(prev, next) => Effect<boolean>`. Return `true` to skip (treat as duplicate), `false` to emit.
  * @returns An `Fx` with consecutive "equal" elements removed.
  * @since 1.0.0

package/dist/Fx/combinators/compact.d.ts

@@ -3,6 +3,23 @@ import type { Fx } from "../Fx.js";
 /**
  * Compacts an Fx of Options, discarding `None` values and unwrapping `Some` values.
  *
+ * @remarks
+ * ## Why
+ * `compact` turns optional pushed values into ordinary pushed values without inventing a sentinel.
+ * It emits once for each `Some`, never for `None`, and preserves the order of retained values.
+ *
+ * ## Ownership and lifetime
+ * This is a stateless sink transformation. It acquires no resources and forwards source failures,
+ * services, completion, and interruption unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const present = Fx.fromIterable([Option.some(1), Option.none(), Option.some(2)]).pipe(Fx.compact)
+ * ```
+ *
  * @param self - An `Fx` emitting `Option<A>`.
  * @returns An `Fx` emitting `A`.
  * @since 1.0.0

package/dist/Fx/combinators/compact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACnB,CAAC"}
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACnB,CAAC"}

package/dist/Fx/combinators/compact.js

@@ -3,6 +3,23 @@ import { make } from "../constructors/make.js";
 /**
  * Compacts an Fx of Options, discarding `None` values and unwrapping `Some` values.
  *
+ * @remarks
+ * ## Why
+ * `compact` turns optional pushed values into ordinary pushed values without inventing a sentinel.
+ * It emits once for each `Some`, never for `None`, and preserves the order of retained values.
+ *
+ * ## Ownership and lifetime
+ * This is a stateless sink transformation. It acquires no resources and forwards source failures,
+ * services, completion, and interruption unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const present = Fx.fromIterable([Option.some(1), Option.none(), Option.some(2)]).pipe(Fx.compact)
+ * ```
+ *
  * @param self - An `Fx` emitting `Option<A>`.
  * @returns An `Fx` emitting `A`.
  * @since 1.0.0

package/dist/Fx/combinators/concatMap.d.ts

@@ -0,0 +1,86 @@
+import type { FlatMapLike } from "./flatMap.js";
+import type { FlatMapEffectLike } from "./flatMapEffect.js";
+/**
+ * Maps each element to an inner Fx and concatenates the results sequentially.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `concatMap` is the flattening policy for work that must not overlap: the next
+ * source value is admitted only after the current inner Fx completes. It is the
+ * bounded-concurrency form of {@link flatMapConcurrently} with a limit of one.
+ *
+ * ## Ordering and cardinality
+ *
+ * Every source value creates exactly one inner Fx. Inner values retain both
+ * source order and their order within each inner Fx; no inner value is buffered
+ * behind a later inner because later inners have not started yet.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and inner failures are forwarded to the output Sink, and both service
+ * requirements remain in the returned type. The required `Scope` owns the
+ * admitted inner fiber; interruption closes it and prevents queued source work
+ * from starting. No values are dropped, switched, or replayed.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const ordered = Fx.concatMap(Fx.fromIterable([
+ *   { id: "first", wait: "20 millis" as const },
+ *   { id: "second", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Fx.at(id, wait))
+ *
+ * const program = Effect.scoped(Fx.collectAll(ordered))
+ * Effect.runPromise(program).then(console.log)
+ * // ["first", "second"]: the one-millisecond inner is not started early
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const concatMap: FlatMapLike;
+/**
+ * Maps each element to an Effect and concatenates the results sequentially.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the Effect-producing form of {@link concatMap}. It makes serialized
+ * commands explicit without requiring callers to wrap each Effect with
+ * `Fx.fromEffect`.
+ *
+ * ## Ordering and cardinality
+ *
+ * Each source value starts one Effect only after the previous Effect has
+ * completed. Each successful Effect emits exactly one value, so output order is
+ * source order and there is no overlap or buffering of successful results.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source failures and Effect failures remain typed; callback services are added
+ * to the output requirements. The returned Fx requires `Scope`, which owns the
+ * active callback Effect and interrupts it when observation ends.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const saved = Fx.concatMapEffect(Fx.fromIterable([
+ *   { id: "first", wait: "20 millis" as const },
+ *   { id: "second", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Effect.as(Effect.sleep(wait), id))
+ *
+ * const program = Effect.scoped(Fx.collectAll(saved))
+ * Effect.runPromise(program).then(console.log)
+ * // ["first", "second"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const concatMapEffect: FlatMapEffectLike;
+//# sourceMappingURL=concatMap.d.ts.map

package/dist/Fx/combinators/concatMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concatMap.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/concatMap.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,SAAS,EAAE,WAOvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,eAAe,EAAE,iBAM7B,CAAC"}

package/dist/Fx/combinators/concatMap.js

@@ -0,0 +1,86 @@
+import { dual, flow } from "effect/Function";
+import { fromEffect } from "../constructors/fromEffect.js";
+import { flatMapConcurrently } from "./flatMapConcurrently.js";
+/**
+ * Maps each element to an inner Fx and concatenates the results sequentially.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `concatMap` is the flattening policy for work that must not overlap: the next
+ * source value is admitted only after the current inner Fx completes. It is the
+ * bounded-concurrency form of {@link flatMapConcurrently} with a limit of one.
+ *
+ * ## Ordering and cardinality
+ *
+ * Every source value creates exactly one inner Fx. Inner values retain both
+ * source order and their order within each inner Fx; no inner value is buffered
+ * behind a later inner because later inners have not started yet.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source and inner failures are forwarded to the output Sink, and both service
+ * requirements remain in the returned type. The required `Scope` owns the
+ * admitted inner fiber; interruption closes it and prevents queued source work
+ * from starting. No values are dropped, switched, or replayed.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const ordered = Fx.concatMap(Fx.fromIterable([
+ *   { id: "first", wait: "20 millis" as const },
+ *   { id: "second", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Fx.at(id, wait))
+ *
+ * const program = Effect.scoped(Fx.collectAll(ordered))
+ * Effect.runPromise(program).then(console.log)
+ * // ["first", "second"]: the one-millisecond inner is not started early
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const concatMap = dual(2, (self, f) => flatMapConcurrently(self, f, 1));
+/**
+ * Maps each element to an Effect and concatenates the results sequentially.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the Effect-producing form of {@link concatMap}. It makes serialized
+ * commands explicit without requiring callers to wrap each Effect with
+ * `Fx.fromEffect`.
+ *
+ * ## Ordering and cardinality
+ *
+ * Each source value starts one Effect only after the previous Effect has
+ * completed. Each successful Effect emits exactly one value, so output order is
+ * source order and there is no overlap or buffering of successful results.
+ *
+ * ## Ownership and lifetime
+ *
+ * Source failures and Effect failures remain typed; callback services are added
+ * to the output requirements. The returned Fx requires `Scope`, which owns the
+ * active callback Effect and interrupts it when observation ends.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const saved = Fx.concatMapEffect(Fx.fromIterable([
+ *   { id: "first", wait: "20 millis" as const },
+ *   { id: "second", wait: "1 millis" as const }
+ * ]), ({ id, wait }) => Effect.as(Effect.sleep(wait), id))
+ *
+ * const program = Effect.scoped(Fx.collectAll(saved))
+ * Effect.runPromise(program).then(console.log)
+ * // ["first", "second"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const concatMapEffect = dual(2, (self, f) => concatMap(self, flow(f, fromEffect)));

package/dist/Fx/combinators/continueWith.d.ts

@@ -1,6 +1,44 @@
 import type { Fx } from "../Fx.js";
 /**
- * continues an Fx with another Fx after the first one completes.
+ * Continues an Fx with a lazily created Fx after the first run returns.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This sequences two producer runs without converting either to a pull
+ * collection. The thunk is lazy, so the continuation is not constructed until
+ * the first `Fx.run` Effect returns.
+ *
+ * ## Ordering and cardinality
+ *
+ * All successes from `fx` are delivered before successes from `f()`. A source
+ * failure is also delivered to the shared Sink, but delivery does not fail
+ * `Fx.run`: `Sink.onFailure` returns an Effect whose error channel is `never`.
+ * After that handler returns, the continuation still runs. The two producers
+ * never run concurrently.
+ *
+ * ## Ownership and lifetime
+ *
+ * Failures and service requirements from both producers remain on the public
+ * type and both failures are delivered to the same Sink. The returned Fx owns
+ * neither input. Interruption or a defect that prevents the first run Effect
+ * from returning also prevents the continuation from starting.
+ *
+ * @example
+ * ```ts
+ * import { Fx, Sink } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const events: Array<string> = []
+ * const phases = Fx.continueWith(Fx.fail("offline"), () => Fx.succeed("fallback"))
+ * const program = phases.run(Sink.make(
+ *   () => Effect.sync(() => events.push("failure delivered")),
+ *   (value) => Effect.sync(() => events.push(value))
+ * ))
+ *
+ * Effect.runPromise(program).then(() => console.log(events))
+ * // ["failure delivered", "fallback"]
+ * ```
  *
  * @param f - A function that returns the next Fx to run.
  * @returns An `Fx` that emits values from the first Fx, then from the second Fx.
@@ -14,6 +52,30 @@ export declare const continueWith: {
 /**
  * Appends a value to the end of an Fx.
  *
+ * @remarks
+ * ## Why
+ *
+ * `append` is the constant-value specialization of {@link continueWith}. It
+ * emits a terminal marker after the source run returns, including after a source
+ * failure has been delivered to the Sink.
+ *
+ * ## Ownership and lifetime
+ *
+ * The value is emitted exactly once after every source success and any delivered
+ * source failure. Interruption or a defect that prevents the source run from
+ * returning suppresses it. No resource is acquired; the source error, services,
+ * and observation lifetime are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const framed = Fx.append(Fx.fromIterable([1, 2]), "done")
+ * Effect.runPromise(Fx.collectAll(framed)).then(console.log)
+ * // [1, 2, "done"]
+ * ```
+ *
  * @param value - The value to append.
  * @returns An `Fx` that emits values from the input Fx, then the appended value.
  * @since 1.0.0
@@ -26,6 +88,29 @@ export declare const append: {
 /**
  * Prepends a value to the beginning of an Fx.
  *
+ * @remarks
+ * ## Why
+ *
+ * `prepend` emits an initial marker through the same Sink before the source is
+ * observed, without allocating a separate collection or state holder.
+ *
+ * ## Ownership and lifetime
+ *
+ * The value is emitted exactly once before the source run starts, then every
+ * source success or failure is delivered. Interruption or a defect in the Sink's
+ * prepended-value handler prevents the source from starting. The operation
+ * acquires no resource and retains source failure, services, and lifetime.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const framed = Fx.prepend(Fx.fromIterable([1, 2]), "start")
+ * Effect.runPromise(Fx.collectAll(framed)).then(console.log)
+ * // ["start", 1, 2]
+ * ```
+ *
  * @param value - The value to prepend.
  * @returns An `Fx` that emits the prepended value, then values from the input Fx.
  * @since 1.0.0
@@ -38,6 +123,29 @@ export declare const prepend: {
 /**
  * Wraps an Fx with a start and end value.
  *
+ * @remarks
+ * ## Why
+ *
+ * `delimit` composes {@link prepend} and {@link append} for protocols whose
+ * normal run must be bracketed by values rather than resource finalizers.
+ *
+ * ## Ownership and lifetime
+ *
+ * `before` is emitted once, followed by every source success or delivered source
+ * failure, then `after` once when the source run Effect returns. Interruption or
+ * a defect suppresses `after`; this is Sink sequencing, not `Effect.ensuring`.
+ * No resource is acquired and source requirements are kept.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const framed = Fx.delimit(Fx.fromIterable([1, 2]), "[", "]")
+ * Effect.runPromise(Fx.collectAll(framed)).then(console.log)
+ * // ["[", 1, 2, "]"]
+ * ```
+ *
  * @param before - The value to emit before the Fx starts.
  * @param after - The value to emit after the Fx completes.
  * @returns An `Fx` that emits `before`, then values from the input Fx, then `after`.

package/dist/Fx/combinators/continueWith.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"continueWith.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/continueWith.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE;IACzB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAE7F,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAK1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAK1D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7D,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAK1D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/E,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAK5E,CAAC"}
+{"version":3,"file":"continueWith.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/continueWith.ts"],"names":[],"mappings":"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"}

package/dist/Fx/combinators/continueWith.js

@@ -3,7 +3,45 @@ import { dual } from "effect/Function";
 import { make } from "../constructors/make.js";
 import { succeed } from "../constructors/succeed.js";
 /**
- * continues an Fx with another Fx after the first one completes.
+ * Continues an Fx with a lazily created Fx after the first run returns.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This sequences two producer runs without converting either to a pull
+ * collection. The thunk is lazy, so the continuation is not constructed until
+ * the first `Fx.run` Effect returns.
+ *
+ * ## Ordering and cardinality
+ *
+ * All successes from `fx` are delivered before successes from `f()`. A source
+ * failure is also delivered to the shared Sink, but delivery does not fail
+ * `Fx.run`: `Sink.onFailure` returns an Effect whose error channel is `never`.
+ * After that handler returns, the continuation still runs. The two producers
+ * never run concurrently.
+ *
+ * ## Ownership and lifetime
+ *
+ * Failures and service requirements from both producers remain on the public
+ * type and both failures are delivered to the same Sink. The returned Fx owns
+ * neither input. Interruption or a defect that prevents the first run Effect
+ * from returning also prevents the continuation from starting.
+ *
+ * @example
+ * ```ts
+ * import { Fx, Sink } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const events: Array<string> = []
+ * const phases = Fx.continueWith(Fx.fail("offline"), () => Fx.succeed("fallback"))
+ * const program = phases.run(Sink.make(
+ *   () => Effect.sync(() => events.push("failure delivered")),
+ *   (value) => Effect.sync(() => events.push(value))
+ * ))
+ *
+ * Effect.runPromise(program).then(() => console.log(events))
+ * // ["failure delivered", "fallback"]
+ * ```
  *
  * @param f - A function that returns the next Fx to run.
  * @returns An `Fx` that emits values from the first Fx, then from the second Fx.
@@ -14,6 +52,30 @@ export const continueWith = dual(2, (fx, f) => make((sink) => Effect.flatMap(fx.
 /**
  * Appends a value to the end of an Fx.
  *
+ * @remarks
+ * ## Why
+ *
+ * `append` is the constant-value specialization of {@link continueWith}. It
+ * emits a terminal marker after the source run returns, including after a source
+ * failure has been delivered to the Sink.
+ *
+ * ## Ownership and lifetime
+ *
+ * The value is emitted exactly once after every source success and any delivered
+ * source failure. Interruption or a defect that prevents the source run from
+ * returning suppresses it. No resource is acquired; the source error, services,
+ * and observation lifetime are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const framed = Fx.append(Fx.fromIterable([1, 2]), "done")
+ * Effect.runPromise(Fx.collectAll(framed)).then(console.log)
+ * // [1, 2, "done"]
+ * ```
+ *
  * @param value - The value to append.
  * @returns An `Fx` that emits values from the input Fx, then the appended value.
  * @since 1.0.0
@@ -23,6 +85,29 @@ export const append = dual(2, (fx, value) => continueWith(fx, () => succeed(valu
 /**
  * Prepends a value to the beginning of an Fx.
  *
+ * @remarks
+ * ## Why
+ *
+ * `prepend` emits an initial marker through the same Sink before the source is
+ * observed, without allocating a separate collection or state holder.
+ *
+ * ## Ownership and lifetime
+ *
+ * The value is emitted exactly once before the source run starts, then every
+ * source success or failure is delivered. Interruption or a defect in the Sink's
+ * prepended-value handler prevents the source from starting. The operation
+ * acquires no resource and retains source failure, services, and lifetime.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const framed = Fx.prepend(Fx.fromIterable([1, 2]), "start")
+ * Effect.runPromise(Fx.collectAll(framed)).then(console.log)
+ * // ["start", 1, 2]
+ * ```
+ *
  * @param value - The value to prepend.
  * @returns An `Fx` that emits the prepended value, then values from the input Fx.
  * @since 1.0.0
@@ -32,6 +117,29 @@ export const prepend = dual(2, (fx, value) => continueWith(succeed(value), () =>
 /**
  * Wraps an Fx with a start and end value.
  *
+ * @remarks
+ * ## Why
+ *
+ * `delimit` composes {@link prepend} and {@link append} for protocols whose
+ * normal run must be bracketed by values rather than resource finalizers.
+ *
+ * ## Ownership and lifetime
+ *
+ * `before` is emitted once, followed by every source success or delivered source
+ * failure, then `after` once when the source run Effect returns. Interruption or
+ * a defect suppresses `after`; this is Sink sequencing, not `Effect.ensuring`.
+ * No resource is acquired and source requirements are kept.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const framed = Fx.delimit(Fx.fromIterable([1, 2]), "[", "]")
+ * Effect.runPromise(Fx.collectAll(framed)).then(console.log)
+ * // ["[", 1, 2, "]"]
+ * ```
+ *
  * @param before - The value to emit before the Fx starts.
  * @param after - The value to emit after the Fx completes.
  * @returns An `Fx` that emits `before`, then values from the input Fx, then `after`.

package/dist/Fx/combinators/debounce.d.ts

@@ -0,0 +1,34 @@
+import { Duration, Scope } from "effect";
+import { Fx } from "../Fx.js";
+/**
+ * Emits a value only after no newer source value arrives for `duration`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Bursty producers such as text input should often trigger work only after
+ * they settle. Debouncing represents that quiet-period rule in the Fx graph.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each value starts a scoped sleep. A newer value interrupts the previous
+ * sleep and replaces its pending value, so at most the latest value is emitted
+ * after a quiet period. Source errors terminate the result. Interruption stops
+ * both source and pending timer; `Scope` owns those switching lifetimes.
+ *
+ * @example
+ * ```ts
+ * import { debounce } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const settled = debounce(fromIterable(["t", "ty", "typed"]), "250 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const debounce: {
+    (duration: Duration.Input): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, R | Scope.Scope>;
+    <A, E, R>(fx: Fx<A, E, R>, duration: Duration.Input): Fx<A, E, R | Scope.Scope>;
+};
+//# sourceMappingURL=debounce.d.ts.map

package/dist/Fx/combinators/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAK9B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACpF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CAUjF,CAAC"}

package/dist/Fx/combinators/debounce.js

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import { switchMap } from "./switchMap.js";
+import { make } from "../constructors/make.js";
+import { dual } from "effect/Function";
+/**
+ * Emits a value only after no newer source value arrives for `duration`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Bursty producers such as text input should often trigger work only after
+ * they settle. Debouncing represents that quiet-period rule in the Fx graph.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each value starts a scoped sleep. A newer value interrupts the previous
+ * sleep and replaces its pending value, so at most the latest value is emitted
+ * after a quiet period. Source errors terminate the result. Interruption stops
+ * both source and pending timer; `Scope` owns those switching lifetimes.
+ *
+ * @example
+ * ```ts
+ * import { debounce } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const settled = debounce(fromIterable(["t", "ty", "typed"]), "250 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const debounce = dual(2, (fx, duration) => switchMap(fx, (a) => make(Effect.fn(function* (sink) {
+    yield* Effect.sleep(duration);
+    yield* sink.onSuccess(a);
+}))));