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

package/dist/Fx/combinators/catch.js

@@ -15,12 +15,44 @@ const matchesTag = (tag, error) => {
     return tag.some((t) => t === error._tag);
 };
 /**
- * Recovers from a typed failure of an Fx by switching to a fallback Fx.
+ * Recovers from the first typed failure of an Fx by running a fallback Fx.
  *
- * Mirrors `Effect.catch` / `Effect.catchAll` (catches `Cause.Fail` only).
+ * @remarks
+ * ## Why
+ *
+ * Typed failures are part of an Fx's public error channel, so callers often
+ * need to replace a failed producer based on its first typed failure. This is
+ * the push-stream counterpart of Effect's typed recovery.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source runs until it reports a Cause containing a `Fail`. The first typed
+ * failure starts exactly one fallback and the entire original Cause is replaced,
+ * including any defects or interrupts composed beside that Fail. A Cause with
+ * no Fail passes through unchanged. Source values already delivered remain
+ * delivered. The fallback's services become requirements of the returned Fx,
+ * and external interruption stops whichever run is active.
+ *
+ * @example
+ * ```ts
+ * import { catch as recover } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const resilient = recover(fail("offline"), (error) => succeed(error.length))
+ * ```
+ *
+ * @example Recovering a Fail discards its complete composite Cause
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catch as recover } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const composite = Cause.combine(Cause.fail("offline"), Cause.die("socket defect"))
+ * const recovered = recover(failCause(composite), () => succeed("cached"))
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catch_ = dual(2, (self, f) => make((sink) => self.run(makeSink((cause) => {
     const result = Cause.findFail(cause);
@@ -31,29 +63,96 @@ export const catch_ = dual(2, (self, f) => make((sink) => self.run(makeSink((cau
 }, sink.onSuccess))));
 export { catch_ as catch };
 /**
- * An alias for {@link catch}.
+ * Uses the Effect-style `catchAll` name for {@link catch}.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The alias lets Effect users apply the same typed-failure recovery vocabulary
+ * to Fx without introducing different runtime behavior.
+ *
+ * ## Ownership and lifetime
+ *
+ * It has exactly the source/fallback switching, failure, service, and
+ * interruption semantics of {@link catch}; it allocates no wrapper resource
+ * beyond that combinator.
+ *
+ * @example
+ * ```ts
+ * import { catchAll } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchAll(fail("missing"), () => succeed("default"))
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catchAll = catch_;
 /**
- * Recovers from *any* failure cause of an Fx (including defects and interrupts)
- * by switching to a fallback Fx.
+ * Recovers from any failure cause by running a fallback Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A full `Cause` retains typed failures, defects, interruption, and composed
+ * causes. Handling that structure explicitly is necessary at boundaries that
+ * must translate every termination mode rather than only expected errors.
  *
- * Mirrors `Effect.catchCause`.
+ * ## Ownership and lifetime
+ *
+ * The handler runs once after the source reports a cause and its returned Fx
+ * continues in the same subscription. It receives the cause unchanged. Values
+ * emitted before failure are not replayed, and the fallback's errors and
+ * services replace the recovered source error and join its requirements.
+ * Because interruption is catchable here, use this only when intentionally
+ * translating interruption rather than for ordinary typed recovery.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catchCause } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const reported = catchCause(failCause(Cause.die("boom")), (cause) =>
+ *   succeed(Cause.pretty(cause))
+ * )
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catchCause = dual(2, (self, f) => make((sink) => self.run(makeSink((cause) => f(cause).run(sink), sink.onSuccess))));
 /**
- * Recovers from a typed failure by matching on the `_tag` field of the error.
+ * Recovers selected tagged typed failures by running a fallback Fx.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchTag`.
+ * Tagged error unions are idiomatic Effect APIs. Selecting one or more tags
+ * narrows the handler input and removes only those variants from the returned
+ * error channel, preserving the rest for later composition.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source owns the subscription until its Cause contains a Fail whose tag
+ * matches. That first matching Fail starts one handler Fx and replaces the
+ * entire original Cause, including any defects or interrupts composed with it.
+ * A Cause with no Fail, or a first Fail with another tag, passes through intact.
+ * The fallback is lazy and contributes its errors and services to the result.
+ *
+ * @example
+ * ```ts
+ * import { catchTag } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * type Missing = { readonly _tag: "Missing"; readonly id: string }
+ * const source = fail<Missing>({ _tag: "Missing", id: "42" })
+ * const recovered = catchTag(source, "Missing", ({ id }) => succeed(`missing:${id}`))
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catchTag = dual(3, (self, k, f) => make((sink) => self.run(makeSink((cause) => {
     const result = Cause.findFail(cause);
@@ -68,13 +167,33 @@ export const catchTag = dual(3, (self, k, f) => make((sink) => self.run(makeSink
     }
 }, sink.onSuccess))));
 /**
- * Recovers from a typed failure when a predicate holds, by switching to a fallback Fx.
- * Only applies to `Cause.Fail`; defects and interrupts are not caught.
+ * Recovers a typed failure only when a predicate accepts it.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchIf`.
+ * Some typed errors are distinguished by values rather than tags. Predicate
+ * recovery handles that subset while retaining `E` in the result because a
+ * rejected error can still escape.
+ *
+ * ## Ownership and lifetime
+ *
+ * The predicate is evaluated on the first Fail found anywhere in the source
+ * Cause. A match starts one lazy fallback and replaces that entire Cause,
+ * including any defects or interrupts composed with the Fail. A rejection, or
+ * a Cause containing no Fail, forwards the original Cause unchanged. The
+ * fallback contributes its errors and services and shares the subscription.
+ *
+ * @example
+ * ```ts
+ * import { catchIf } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchIf(fail(404), (status) => status === 404, () => succeed("missing"))
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catchIf = dual(3, (self, predicate, f) => make((sink) => self.run(makeSink((cause) => {
     const result = Cause.findFail(cause);
@@ -88,22 +207,73 @@ export const catchIf = dual(3, (self, predicate, f) => make((sink) => self.run(m
     return sink.onFailure(cause);
 }, sink.onSuccess))));
 /**
- * Recovers from a failure cause when a predicate on the cause holds,
- * by switching to a fallback Fx.
+ * Recovers a failure cause only when a predicate accepts the complete cause.
+ *
+ * @remarks
+ * ## Why
  *
- * Mirrors `Effect.catchCauseIf`.
+ * Cause-level predicates can distinguish defects, interruption, sequential or
+ * parallel cause structure that a typed-error predicate cannot observe.
+ *
+ * ## Ownership and lifetime
+ *
+ * The predicate receives the source cause unchanged. A match starts one lazy
+ * fallback in the same subscription; otherwise the original cause propagates.
+ * The fallback's requirements and errors are added, prior source values stay
+ * delivered, and interrupting the returned Fx interrupts its active run.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { catchCauseIf } from "@typed/fx/Fx"
+ * import { failCause, succeed } from "@typed/fx/Fx"
+ *
+ * const recovered = catchCauseIf(
+ *   failCause(Cause.die("bad decoder")),
+ *   Cause.hasDies,
+ *   () => succeed("reported")
+ * )
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catchCauseIf = dual(3, (self, predicate, f) => make((sink) => self.run(makeSink((cause) => (predicate(cause) ? f(cause).run(sink) : sink.onFailure(cause)), sink.onSuccess))));
 /**
- * Recovers from typed failures by matching on the `_tag` field with multiple handlers at once.
+ * Recovers several tagged typed-error variants with one handler table.
+ *
+ * @remarks
+ * ## Why
+ *
+ * A handler table keeps multi-variant recovery exhaustive and preserves the
+ * precise success, error, and service unions produced by each selected case.
+ * Unlisted variants remain visible in the returned error channel.
+ *
+ * ## Ownership and lifetime
+ *
+ * The first Fail found anywhere in the source Cause is inspected. A listed tag
+ * starts exactly one handler Fx and replaces the entire original Cause,
+ * including any defects or interrupts composed with that Fail. An untagged or
+ * unlisted first Fail, or a Cause with no Fail, propagates intact. Handlers are
+ * lazy and contribute their individual errors and service requirements.
+ *
+ * @example
+ * ```ts
+ * import { catchTags } from "@typed/fx/Fx"
+ * import { fail, succeed } from "@typed/fx/Fx"
  *
- * Mirrors `Effect.catchTags`.
+ * type Failure =
+ *   | { readonly _tag: "Missing"; readonly id: string }
+ *   | { readonly _tag: "Forbidden" }
+ * const source = fail<Failure>({ _tag: "Missing", id: "42" })
+ * const recovered = catchTags(source, {
+ *   Missing: ({ id }) => succeed(`missing:${id}`),
+ *   Forbidden: () => succeed("forbidden")
+ * })
+ * ```
  *
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const catchTags = dual(2, (self, cases) => make((sink) => self.run(makeSink((cause) => {
     const result = Cause.findFail(cause);

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

@@ -1,12 +1,35 @@
 import type * as Cause from "effect/Cause";
 import type { Fx } from "../Fx.js";
 /**
- * Emits only the failure causes from an Fx, discarding successful values.
+ * Emits the source's terminal failure cause and discards every successful value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Failure telemetry and supervision often need the complete Effect `Cause`
+ * without treating that cause as another failure. Materializing only the
+ * failure side makes those pipelines ordinary, infallible Fx values.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source is subscribed once. Success values are dropped in arrival order;
+ * a terminal cause is emitted once and the returned Fx completes without a
+ * typed error. Defects and interruption are retained inside the emitted cause.
+ * No resource is acquired beyond the source subscription.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { causes } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const failures = causes(failCause(Cause.fail("offline")))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Cause<E>`.
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export declare const causes: <A, E, R>(fx: Fx<A, E, R>) => Fx<Cause.Cause<E>, never, R>;
 //# sourceMappingURL=causes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"causes.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/causes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAO1E,CAAC"}
+{"version":3,"file":"causes.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/causes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAO1E,CAAC"}

package/dist/Fx/combinators/causes.js

@@ -3,12 +3,35 @@ import * as Option from "effect/Option";
 import { exit } from "./exit.js";
 import { filterMap } from "./filterMap.js";
 /**
- * Emits only the failure causes from an Fx, discarding successful values.
+ * Emits the source's terminal failure cause and discards every successful value.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Failure telemetry and supervision often need the complete Effect `Cause`
+ * without treating that cause as another failure. Materializing only the
+ * failure side makes those pipelines ordinary, infallible Fx values.
+ *
+ * ## Ownership and lifetime
+ *
+ * The source is subscribed once. Success values are dropped in arrival order;
+ * a terminal cause is emitted once and the returned Fx completes without a
+ * typed error. Defects and interruption are retained inside the emitted cause.
+ * No resource is acquired beyond the source subscription.
+ *
+ * @example
+ * ```ts
+ * import { Cause } from "effect"
+ * import { causes } from "@typed/fx/Fx"
+ * import { failCause } from "@typed/fx/Fx"
+ *
+ * const failures = causes(failCause(Cause.fail("offline")))
+ * ```
  *
  * @param fx - The `Fx` stream.
  * @returns An `Fx` emitting `Cause<E>`.
  * @since 1.0.0
- * @category combinators
+ * @category Errors and recovery
  */
 export const causes = (fx) => filterMap(exit(fx), Exit.match({
     onFailure: Option.some,

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

@@ -8,10 +8,30 @@ 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
- * @category combinators
+ * @category Selecting values
  */
 export declare const changesWithEffect: {
     <A, E2, R2>(f: (prev: A, next: A) => Effect.Effect<boolean, E2, R2>): <E, R>(fx: Fx<A, E | E2, R>) => Fx<A, E | E2, R | R2>;

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,10 +12,30 @@ 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
- * @category combinators
+ * @category Selecting values
  */
 export const changesWithEffect = dual(2, (fx, f) => make((sink) => sinkCore.withStateSemaphore(sink, Option.none(), (s) => fx.run(makeSink(s.onFailure, (a2) => Effect.matchCauseEffect(Effect.flatMap(s.get, (state) => Option.match(state, {
     onNone: () => Effect.flatMap(s.onSuccess(a2), () => s.updateEffect(() => Effect.succeed(Option.some(a2)))),

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

@@ -3,10 +3,27 @@ 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
- * @category combinators
+ * @category Selecting values
  */
 export declare const compact: <A, E, R>(self: Fx<Option.Option<A>, E, R>) => Fx<A, E, R>;
 //# sourceMappingURL=compact.d.ts.map

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,9 +3,26 @@ 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
- * @category combinators
+ * @category Selecting values
  */
 export const compact = (self) => make((sink) => self.run(sinkCore.compact(sink)));

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 Concurrent work
+ */
+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 Concurrent work
+ */
+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 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)));