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

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 Concurrent work
+ */
+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 Concurrent work
+ */
+export const concatMapEffect = dual(2, (self, f) => concatMap(self, flow(f, fromEffect)));

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

@@ -1,11 +1,49 @@
 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.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare const continueWith: {
     <B, E2, R2>(f: () => Fx<B, E2, R2>): <A, E, R>(fx: Fx<A, E, R>) => Fx<A | B, E | E2, R | R2>;
@@ -14,10 +52,34 @@ 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
- * @category combinators
+ * @category Combining sources
  */
 export declare const append: {
     <B>(value: B): <A, E, R>(fx: Fx<A, E, R>) => Fx<A | B, E, R>;
@@ -26,10 +88,33 @@ 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
- * @category combinators
+ * @category Combining sources
  */
 export declare const prepend: {
     <B>(value: B): <A, E, R>(fx: Fx<A, E, R>) => Fx<B | A, E, R>;
@@ -38,11 +123,34 @@ 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`.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export declare const delimit: {
     <B, C>(before: B, after: C): <A, E, R>(fx: Fx<A, E, R>) => Fx<A | B | C, E, R>;

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,39 +3,147 @@ 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.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export const continueWith = dual(2, (fx, f) => make((sink) => Effect.flatMap(fx.run(sink), () => f().run(sink))));
 /**
  * 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
- * @category combinators
+ * @category Combining sources
  */
 export const append = dual(2, (fx, value) => continueWith(fx, () => succeed(value)));
 /**
  * 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
- * @category combinators
+ * @category Combining sources
  */
 export const prepend = dual(2, (fx, value) => continueWith(succeed(value), () => fx));
 /**
  * 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`.
  * @since 1.0.0
- * @category combinators
+ * @category Combining sources
  */
 export const delimit = dual(3, (fx, before, after) => fx.pipe(prepend(before), append(after)));

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

@@ -0,0 +1,34 @@
+import { Duration, Scope } from "effect";
+import type { 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 Time and rate
+ */
+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,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAKnC;;;;;;;;;;;;;;;;;;;;;;;;;;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 Time and rate
+ */
+export const debounce = dual(2, (fx, duration) => switchMap(fx, (a) => make(Effect.fn(function* (sink) {
+    yield* Effect.sleep(duration);
+    yield* sink.onSuccess(a);
+}))));

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

@@ -0,0 +1,36 @@
+import type { Fx } from "../Fx.js";
+import { Duration } from "effect";
+/**
+ * Sleeps for `duration` before forwarding each successful source delivery.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Per-value delay is useful when pacing downstream work without changing the
+ * stream's error type or replacing the producer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each delivered value runs an Effect sleep before reaching the sink. This uses
+ * `mapEffect` and inherits producer concurrency: a sequential producer waits for
+ * each delayed delivery, while concurrent deliveries can overlap their sleeps.
+ * No queue or ordering guarantee is added. The source run must await its pending
+ * deliveries before normal completion. Source failures propagate; interruption
+ * cancels active sleeps. No external resource is retained.
+ *
+ * @example
+ * ```ts
+ * import { delay } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const paced = delay(fromIterable([1, 2, 3]), "100 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const delay: {
+    (duration: Duration.Input): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E, R>;
+    <A, E, R>(self: Fx<A, E, R>, duration: Duration.Input): Fx<A, E, R>;
+};
+//# sourceMappingURL=delay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/delay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAU,MAAM,QAAQ,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAGrE,CAAC"}

package/dist/Fx/combinators/delay.js

@@ -0,0 +1,33 @@
+import { dual } from "effect/Function";
+import { Effect } from "effect";
+import { mapEffect } from "./mapEffect.js";
+/**
+ * Sleeps for `duration` before forwarding each successful source delivery.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Per-value delay is useful when pacing downstream work without changing the
+ * stream's error type or replacing the producer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each delivered value runs an Effect sleep before reaching the sink. This uses
+ * `mapEffect` and inherits producer concurrency: a sequential producer waits for
+ * each delayed delivery, while concurrent deliveries can overlap their sleeps.
+ * No queue or ordering guarantee is added. The source run must await its pending
+ * deliveries before normal completion. Source failures propagate; interruption
+ * cancels active sleeps. No external resource is retained.
+ *
+ * @example
+ * ```ts
+ * import { delay } from "@typed/fx/Fx"
+ * import { fromIterable } from "@typed/fx/Fx"
+ *
+ * const paced = delay(fromIterable([1, 2, 3]), "100 millis")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export const delay = dual(2, (self, duration) => mapEffect(self, (a) => Effect.as(Effect.sleep(duration), a)));

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

@@ -0,0 +1,71 @@
+import * as Effect from "effect/Effect";
+import type { Fx } from "../Fx.js";
+/**
+ * Drops elements from an Fx until a predicate returns true.
+ * Emits from the first element for which the predicate returns true (including that element) and all following elements.
+ *
+ * @remarks
+ * ## Why
+ * `dropUntil` opens a one-way gate at the first matching value. The match and every later value emit
+ * once in source order; after opening, the predicate is no longer consulted.
+ *
+ * ## Ownership and lifetime
+ * The gate is local to one run and discarded on completion or interruption. No resources are
+ * acquired and the source's errors and services pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const ready = Fx.fromIterable([1, 2, 3]).pipe(Fx.dropUntil((n) => n >= 2))
+ * ```
+ *
+ * @param predicate - The predicate function.
+ * @returns An `Fx` that emits once the predicate first matches.
+ * @since 1.0.0
+ * @category Selecting values
+ */
+export declare const dropUntil: {
+    <A>(predicate: (a: A) => boolean): <E, R>(fx: Fx<A, E, R>) => Fx<A, E, R>;
+    <A, E, R>(fx: Fx<A, E, R>, predicate: (a: A) => boolean): Fx<A, E, R>;
+};
+/**
+ * Drops elements from an Fx until an effectful predicate returns true.
+ * Emits from the first element for which the predicate effect succeeds with true (including that element) and all following elements.
+ *
+ * @remarks
+ * ## Why
+ * `dropUntilEffect` makes the gate decision Effectful. The first `true` opens the gate and is
+ * forwarded, but its `skipWhileEffect` implementation eagerly evaluates the predicate for every
+ * later value as well; those later boolean results no longer affect forwarding.
+ *
+ * ## Ownership and lifetime
+ * The gate is per run. Predicate effects inherit producer ordering and concurrency, are interrupted
+ * with their invoking delivery, and expose `E2`/`R2`. Failures remain observable after the gate opens.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import { Fx } from "@typed/fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const checks = yield* Ref.make(0)
+ *   const values = yield* Fx.collectAll(
+ *     Fx.fromIterable([2, 3]).pipe(
+ *       Fx.dropUntilEffect((n) => Ref.update(checks, (count) => count + 1).pipe(Effect.as(n === 2)))
+ *     )
+ *   )
+ *   return { values, checks: yield* Ref.get(checks) } // { values: [2, 3], checks: 2 }
+ * })
+ * ```
+ *
+ * @param predicate - Effectful predicate function.
+ * @returns An `Fx` that emits once the predicate first matches.
+ * @since 1.0.0
+ * @category Selecting values
+ */
+export declare const dropUntilEffect: {
+    <A, E2, R2>(predicate: (a: A) => Effect.Effect<boolean, E2, R2>): <E, R>(fx: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+    <A, E, R, E2, R2>(fx: Fx<A, E, R>, predicate: (a: A) => Effect.Effect<boolean, E2, R2>): Fx<A, E | E2, R | R2>;
+};
+//# sourceMappingURL=dropUntil.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dropUntil.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/dropUntil.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAGvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAClD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACd,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,GAClD,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAO1B,CAAC"}