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

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

@@ -1,23 +1,177 @@
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import type * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import type { Fx } from "../Fx.js";
 /**
- * Provides context to an Fx from a Layer.
+ * Builds a Layer for each subscription and provides it to the entire Fx run.
  *
- * The context is provided to the entire Fx stream, including any effects run
- * during its execution. The context is scoped to the lifetime of the stream.
+ * @remarks
+ * ## Why
+ *
+ * Fx preserves Effect service requirements in `R`; providing a Layer closes
+ * those requirements while retaining acquisition failures and dependencies in
+ * the resulting type.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each subscription creates a private Scope and builds the Layer inside it
+ * before the source starts. A build failure is sent to the sink and the source
+ * never runs. Otherwise the built Context is available to every source Effect,
+ * and the Scope closes with the source's success, failure, defect, or
+ * interruption. Provided services are removed from `R`; Layer dependencies and
+ * errors are added.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect, Layer } from "effect"
+ * import { provide } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, ({ url }) => url))
+ * const runnable = provide(request, Layer.succeed(Config, { url: "/api" }))
+ * ```
  *
  * @param layer - The Layer to provide.
  * @returns An `Fx` with the required context provided.
  * @since 1.0.0
- * @category combinators
+ * @category Providing services
  */
 export declare const provide: {
     <R2, E2 = never, R3 = never>(layer: Layer.Layer<R2, E2, R3>): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E | E2, Exclude<R, R2> | R3>;
     <A, E, R, R2, E2 = never, R3 = never>(fx: Fx<A, E, R>, layer: Layer.Layer<R2, E2, R3>): Fx<A, E | E2, Exclude<R, R2> | R3>;
 };
-export declare const provideServices: {
-    <R2>(services: ServiceMap.ServiceMap<R2>): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, Exclude<R, R2>>;
-    <A, E, R, R2>(fx: Fx<A, E, R>, services: ServiceMap.ServiceMap<R2>): Fx<A, E, Exclude<R, R2>>;
+/**
+ * Provides an already-built Effect Context to the entire Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Callers that already own service instances should not rebuild them through a
+ * resourceful Layer merely to satisfy an Fx's environment.
+ *
+ * ## Ownership and lifetime
+ *
+ * The Context is captured when this combinator is created and reused for each
+ * subscription. Its services are available to all source Effects and removed
+ * from `R`. This function does not acquire or release those service values;
+ * their owner must keep them valid for every subscription that uses the result.
+ * Source completion, failure, and interruption are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideContext } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const context = Context.make(Config, { url: "/api" })
+ * const runnable = provideContext(fromEffect(Effect.map(Config, (x) => x.url)), context)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Providing services
+ */
+export declare const provideContext: {
+    <R2>(services: Context.Context<R2>): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, Exclude<R, R2>>;
+    <A, E, R, R2>(fx: Fx<A, E, R>, services: Context.Context<R2>): Fx<A, E, Exclude<R, R2>>;
+};
+/**
+ * Provides one existing service value to the entire Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the precise single-service form of {@link provideContext}, useful for
+ * tests and application edges where the instance is already owned.
+ *
+ * ## Ownership and lifetime
+ *
+ * The service value is captured and reused for every subscription. It is not
+ * acquired or finalized here; its caller owns its lifetime. The matching
+ * service identifier is removed from `R`, while values, errors, ordering, and
+ * interruption remain those of the source.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideService } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const runnable = provideService(
+ *   fromEffect(Effect.map(Config, (x) => x.url)),
+ *   Config,
+ *   { url: "/api" }
+ * )
+ * ```
+ *
+ * @param tag - The service tag (identifier).
+ * @param service - The service implementation.
+ * @returns An `Fx` with the required service provided.
+ * @since 1.0.0
+ * @category Providing services
+ */
+export declare const provideService: {
+    <Id, S>(tag: Context.Service<Id, S>, service: S): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E, Exclude<R, Id>>;
+    <A, E, R, Id, S>(fx: Fx<A, E, R>, tag: Context.Service<Id, S>, service: S): Fx<A, E, Exclude<R, Id>>;
+};
+/**
+ * Acquires one service with an Effect before running the Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Some service instances require effectful configuration but do not warrant a
+ * separately named Layer. This keeps acquisition failure and dependencies
+ * explicit in the returned Fx type.
+ *
+ * ## Ownership and lifetime
+ *
+ * The service Effect runs once per subscription while {@link provide} builds
+ * its Layer. A failure prevents the source from starting. On success, the
+ * service is available for the whole source run and its identifier is removed
+ * from `R`; acquisition errors and every requirement in `R2` are added. In
+ * particular, an `Effect.acquireRelease` service Effect still leaves
+ * `Scope.Scope` in the returned Fx requirements—the private Layer Scope does
+ * not erase that public requirement. The caller must provide that Scope.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideServiceEffect } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, (x) => x.url))
+ * const runnable = provideServiceEffect(request, Config, Effect.succeed({ url: "/api" }))
+ * ```
+ *
+ * @example Scoped acquisition keeps `Scope` in the returned Fx requirements
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideServiceEffect } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ * import { collectAll } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, (x) => x.url))
+ * const acquired = Effect.acquireRelease(
+ *   Effect.succeed({ url: "/api" }),
+ *   () => Effect.void
+ * )
+ * const scopedFx = provideServiceEffect(request, Config, acquired)
+ * const program = Effect.scoped(collectAll(scopedFx))
+ * ```
+ *
+ * @param tag - The service tag (identifier).
+ * @param serviceEffect - Effect that produces the service (may have its own requirements).
+ * @returns An `Fx` with the required service provided.
+ * @since 1.0.0
+ * @category Providing services
+ */
+export declare const provideServiceEffect: {
+    <Id, S, E2, R2>(tag: Context.Service<Id, S>, serviceEffect: Effect.Effect<S, E2, R2>): <A, E, R>(fx: Fx<A, E, R>) => Fx<A, E | E2, Exclude<R, Id> | R2>;
+    <A, E, R, Id, S, E2, R2>(fx: Fx<A, E, R>, tag: Context.Service<Id, S>, serviceEffect: Effect.Effect<S, E2, R2>): Fx<A, E | E2, Exclude<R, Id> | R2>;
 };
 //# sourceMappingURL=provide.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"provide.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/provide.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACzB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAC7B,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAEpE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EAClC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACf,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAC7B,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAuBvC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE;IAC5B,CAAC,EAAE,EAAE,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,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,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAElG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;CAK/F,CAAC"}
+{"version":3,"file":"provide.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/provide.ts"],"names":[],"mappings":"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"}

package/dist/Fx/combinators/provide.js

@@ -3,17 +3,42 @@ import * as Exit from "effect/Exit";
 import { dual } from "effect/Function";
 import * as Layer from "effect/Layer";
 import * as Scope from "effect/Scope";
+import * as Context from "effect/Context";
 import { make } from "../constructors/make.js";
 /**
- * Provides context to an Fx from a Layer.
+ * Builds a Layer for each subscription and provides it to the entire Fx run.
  *
- * The context is provided to the entire Fx stream, including any effects run
- * during its execution. The context is scoped to the lifetime of the stream.
+ * @remarks
+ * ## Why
+ *
+ * Fx preserves Effect service requirements in `R`; providing a Layer closes
+ * those requirements while retaining acquisition failures and dependencies in
+ * the resulting type.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each subscription creates a private Scope and builds the Layer inside it
+ * before the source starts. A build failure is sent to the sink and the source
+ * never runs. Otherwise the built Context is available to every source Effect,
+ * and the Scope closes with the source's success, failure, defect, or
+ * interruption. Provided services are removed from `R`; Layer dependencies and
+ * errors are added.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect, Layer } from "effect"
+ * import { provide } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, ({ url }) => url))
+ * const runnable = provide(request, Layer.succeed(Config, { url: "/api" }))
+ * ```
  *
  * @param layer - The Layer to provide.
  * @returns An `Fx` with the required context provided.
  * @since 1.0.0
- * @category combinators
+ * @category Providing services
  */
 export const provide = dual(2, (fx, layer) => make(Effect.fnUntraced(function* (sink) {
     const scope = yield* Scope.make();
@@ -22,6 +47,129 @@ export const provide = dual(2, (fx, layer) => make(Effect.fnUntraced(function* (
         yield* Scope.close(scope, servicesExit);
         return yield* sink.onFailure(servicesExit.cause);
     }
-    return yield* fx.run(sink).pipe(Effect.provideServices(servicesExit.value), Effect.onExit((exit) => Scope.close(scope, exit)));
+    return yield* fx.run(sink).pipe(Effect.provideContext(servicesExit.value), Effect.onExit((exit) => Scope.close(scope, exit)));
 })));
-export const provideServices = dual(2, (fx, services) => provide(fx, Layer.succeedServices(services)));
+/**
+ * Provides an already-built Effect Context to the entire Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Callers that already own service instances should not rebuild them through a
+ * resourceful Layer merely to satisfy an Fx's environment.
+ *
+ * ## Ownership and lifetime
+ *
+ * The Context is captured when this combinator is created and reused for each
+ * subscription. Its services are available to all source Effects and removed
+ * from `R`. This function does not acquire or release those service values;
+ * their owner must keep them valid for every subscription that uses the result.
+ * Source completion, failure, and interruption are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideContext } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const context = Context.make(Config, { url: "/api" })
+ * const runnable = provideContext(fromEffect(Effect.map(Config, (x) => x.url)), context)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Providing services
+ */
+export const provideContext = dual(2, (fx, services) => provide(fx, Layer.succeedContext(services)));
+/**
+ * Provides one existing service value to the entire Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * This is the precise single-service form of {@link provideContext}, useful for
+ * tests and application edges where the instance is already owned.
+ *
+ * ## Ownership and lifetime
+ *
+ * The service value is captured and reused for every subscription. It is not
+ * acquired or finalized here; its caller owns its lifetime. The matching
+ * service identifier is removed from `R`, while values, errors, ordering, and
+ * interruption remain those of the source.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideService } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const runnable = provideService(
+ *   fromEffect(Effect.map(Config, (x) => x.url)),
+ *   Config,
+ *   { url: "/api" }
+ * )
+ * ```
+ *
+ * @param tag - The service tag (identifier).
+ * @param service - The service implementation.
+ * @returns An `Fx` with the required service provided.
+ * @since 1.0.0
+ * @category Providing services
+ */
+export const provideService = dual(3, (fx, tag, service) => provideContext(fx, Context.make(tag, service)));
+/**
+ * Acquires one service with an Effect before running the Fx.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Some service instances require effectful configuration but do not warrant a
+ * separately named Layer. This keeps acquisition failure and dependencies
+ * explicit in the returned Fx type.
+ *
+ * ## Ownership and lifetime
+ *
+ * The service Effect runs once per subscription while {@link provide} builds
+ * its Layer. A failure prevents the source from starting. On success, the
+ * service is available for the whole source run and its identifier is removed
+ * from `R`; acquisition errors and every requirement in `R2` are added. In
+ * particular, an `Effect.acquireRelease` service Effect still leaves
+ * `Scope.Scope` in the returned Fx requirements—the private Layer Scope does
+ * not erase that public requirement. The caller must provide that Scope.
+ *
+ * @example
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideServiceEffect } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, (x) => x.url))
+ * const runnable = provideServiceEffect(request, Config, Effect.succeed({ url: "/api" }))
+ * ```
+ *
+ * @example Scoped acquisition keeps `Scope` in the returned Fx requirements
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { provideServiceEffect } from "@typed/fx/Fx"
+ * import { fromEffect } from "@typed/fx/Fx"
+ * import { collectAll } from "@typed/fx/Fx"
+ *
+ * class Config extends Context.Service<Config, { readonly url: string }>()("Config") {}
+ * const request = fromEffect(Effect.map(Config, (x) => x.url))
+ * const acquired = Effect.acquireRelease(
+ *   Effect.succeed({ url: "/api" }),
+ *   () => Effect.void
+ * )
+ * const scopedFx = provideServiceEffect(request, Config, acquired)
+ * const program = Effect.scoped(collectAll(scopedFx))
+ * ```
+ *
+ * @param tag - The service tag (identifier).
+ * @param serviceEffect - Effect that produces the service (may have its own requirements).
+ * @returns An `Fx` with the required service provided.
+ * @since 1.0.0
+ * @category Providing services
+ */
+export const provideServiceEffect = dual(3, (fx, tag, serviceEffect) => provide(fx, Layer.effect(tag, serviceEffect)));

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

@@ -0,0 +1,92 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Runs two streams concurrently until one emits, then mirrors the winner and
+ * interrupts the other.
+ *
+ * A failure or completion from one side before the other emits does **not**
+ * win unless every side ends without emitting. After a winner is chosen, that
+ * stream's later failures are propagated.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `race` selects a live producer by its first useful value rather than by setup,
+ * completion, or a fast failure. This is suitable for redundant sources where a
+ * producer that ends silently should not prevent another from becoming useful.
+ *
+ * ## Selection, ordering, and cardinality
+ *
+ * Both inputs start concurrently. The first emitted value atomically selects its
+ * producer; that value and all later values from the winner are forwarded in
+ * order. The loser emits nothing after selection and is interrupted. There is no
+ * buffering or replay.
+ *
+ * ## Ownership and lifetime
+ *
+ * Before a winner, a non-interruption failure is remembered but does not win; it
+ * is reported only if both inputs end without a value. After selection, winner
+ * failures are forwarded. Both environments remain required. The observing
+ * fiber owns both child fibers and interruption cancels the race and finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const response = Fx.race(
+ *   Fx.ensuring(Fx.at("slow", "50 millis"), Effect.log("slow closed")),
+ *   Fx.ensuring(Fx.at("fast", "5 millis"), Effect.log("fast closed"))
+ * )
+ * Effect.runPromise(Fx.collectAll(response)).then(console.log)
+ * // "slow closed" proves loser cleanup; the winning finalizer also runs
+ * // resolves ["fast"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Concurrent work
+ */
+export declare const race: {
+    <AR, ER, RR>(that: Fx<AR, ER, RR>): <AL, EL, RL>(self: Fx<AL, EL, RL>) => Fx<AL | AR, EL | ER, RL | RR>;
+    <AL, EL, RL, AR, ER, RR>(self: Fx<AL, EL, RL>, that: Fx<AR, ER, RR>): Fx<AL | AR, EL | ER, RL | RR>;
+};
+/**
+ * Races many streams: the first to emit wins and the rest are interrupted.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `raceAll` extends {@link race} to a runtime-sized set while preserving the
+ * first-value selection rule.
+ *
+ * ## Selection, ordering, and cardinality
+ *
+ * All inputs start concurrently. The first emitted value selects one input and
+ * only that input's values are forwarded afterward. Zero inputs produce the
+ * empty Fx; one input is returned unchanged. No result buffer is retained.
+ *
+ * ## Ownership and lifetime
+ *
+ * Before selection, the first non-interruption failure is retained and reported
+ * only if every input ends without emitting. After selection, winner failures
+ * are forwarded. All environments are required. Losers are interrupted and the
+ * observing fiber owns cleanup for every child.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const response = Fx.raceAll(
+ *   Fx.at("cache", "30 millis"),
+ *   Fx.at("primary", "5 millis"),
+ *   Fx.at("replica", "20 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(response)).then(console.log)
+ * // ["primary"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Concurrent work
+ */
+export declare const raceAll: <FX extends ReadonlyArray<Fx<any, any, any>>>(...fxs: FX) => Fx<Fx.Success<FX[number]>, Fx.Error<FX[number]>, Fx.Services<FX[number]>>;
+//# sourceMappingURL=race.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"race.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/race.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,IAAI,EAAE;IACjB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACxG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EACrB,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EACpB,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GACnB,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;CAOlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,OAAO,GAAI,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,UACzD,EAAE,KACT,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAwF1E,CAAC"}

package/dist/Fx/combinators/race.js

@@ -0,0 +1,149 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import { dual } from "effect/Function";
+import * as Ref from "effect/Ref";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { empty } from "../constructors/empty.js";
+import { make } from "../constructors/make.js";
+/**
+ * Runs two streams concurrently until one emits, then mirrors the winner and
+ * interrupts the other.
+ *
+ * A failure or completion from one side before the other emits does **not**
+ * win unless every side ends without emitting. After a winner is chosen, that
+ * stream's later failures are propagated.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `race` selects a live producer by its first useful value rather than by setup,
+ * completion, or a fast failure. This is suitable for redundant sources where a
+ * producer that ends silently should not prevent another from becoming useful.
+ *
+ * ## Selection, ordering, and cardinality
+ *
+ * Both inputs start concurrently. The first emitted value atomically selects its
+ * producer; that value and all later values from the winner are forwarded in
+ * order. The loser emits nothing after selection and is interrupted. There is no
+ * buffering or replay.
+ *
+ * ## Ownership and lifetime
+ *
+ * Before a winner, a non-interruption failure is remembered but does not win; it
+ * is reported only if both inputs end without a value. After selection, winner
+ * failures are forwarded. Both environments remain required. The observing
+ * fiber owns both child fibers and interruption cancels the race and finalizers.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const response = Fx.race(
+ *   Fx.ensuring(Fx.at("slow", "50 millis"), Effect.log("slow closed")),
+ *   Fx.ensuring(Fx.at("fast", "5 millis"), Effect.log("fast closed"))
+ * )
+ * Effect.runPromise(Fx.collectAll(response)).then(console.log)
+ * // "slow closed" proves loser cleanup; the winning finalizer also runs
+ * // resolves ["fast"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Concurrent work
+ */
+export const race = dual(2, (self, that) => raceAll(self, that));
+/**
+ * Races many streams: the first to emit wins and the rest are interrupted.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `raceAll` extends {@link race} to a runtime-sized set while preserving the
+ * first-value selection rule.
+ *
+ * ## Selection, ordering, and cardinality
+ *
+ * All inputs start concurrently. The first emitted value selects one input and
+ * only that input's values are forwarded afterward. Zero inputs produce the
+ * empty Fx; one input is returned unchanged. No result buffer is retained.
+ *
+ * ## Ownership and lifetime
+ *
+ * Before selection, the first non-interruption failure is retained and reported
+ * only if every input ends without emitting. After selection, winner failures
+ * are forwarded. All environments are required. Losers are interrupted and the
+ * observing fiber owns cleanup for every child.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { Effect } from "effect"
+ *
+ * const response = Fx.raceAll(
+ *   Fx.at("cache", "30 millis"),
+ *   Fx.at("primary", "5 millis"),
+ *   Fx.at("replica", "20 millis")
+ * )
+ * Effect.runPromise(Fx.collectAll(response)).then(console.log)
+ * // ["primary"]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Concurrent work
+ */
+export const raceAll = (...fxs) => {
+    if (fxs.length === 0) {
+        return empty;
+    }
+    if (fxs.length === 1) {
+        return fxs[0];
+    }
+    return make((sink) => Effect.gen(function* () {
+        const winner = yield* SynchronizedRef.make(null);
+        const ended = yield* Ref.make(0);
+        const firstFail = yield* Ref.make(null);
+        const fibersRef = yield* Ref.make([]);
+        const interruptOthers = (except) => Effect.flatMap(Ref.get(fibersRef), (fibers) => Effect.forEach(fibers, (fiber, i) => (i === except ? Effect.void : Fiber.interrupt(fiber)), { discard: true }));
+        const markEnded = Effect.gen(function* () {
+            const current = yield* SynchronizedRef.get(winner);
+            if (current !== null)
+                return;
+            const n = yield* Ref.updateAndGet(ended, (count) => count + 1);
+            if (n === fxs.length) {
+                const cause = yield* Ref.get(firstFail);
+                if (cause !== null) {
+                    yield* sink.onFailure(cause);
+                }
+            }
+        });
+        const fibers = [];
+        for (let i = 0; i < fxs.length; i++) {
+            const fx = fxs[i];
+            const fiber = yield* Effect.forkChild(Effect.flatMap(SynchronizedRef.get(winner), (already) => already !== null
+                ? Effect.void
+                : fx
+                    .run(makeSink((cause) => Effect.flatMap(SynchronizedRef.get(winner), (w) => {
+                    if (w === i)
+                        return sink.onFailure(cause);
+                    if (w === null && !Cause.hasInterruptsOnly(cause)) {
+                        return Ref.update(firstFail, (prev) => prev ?? cause);
+                    }
+                    return Effect.void;
+                }), (a) => SynchronizedRef.updateEffect(winner, (w) => {
+                    if (w === null) {
+                        return interruptOthers(i).pipe(Effect.andThen(sink.onSuccess(a)), Effect.as(i));
+                    }
+                    if (w === i) {
+                        return sink.onSuccess(a).pipe(Effect.as(w));
+                    }
+                    return Effect.succeed(w);
+                })))
+                    .pipe(Effect.ensuring(markEnded))), { startImmediately: true, uninterruptible: false });
+            fibers.push(fiber);
+        }
+        yield* Ref.set(fibersRef, fibers);
+        yield* Effect.forEach(fibers, (fiber) => Fiber.join(fiber).pipe(Effect.catchCause(() => Effect.void)), { concurrency: "unbounded", discard: true });
+    }));
+};

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

@@ -0,0 +1,41 @@
+import * as Schedule from "effect/Schedule";
+import type { Fx } from "../Fx.js";
+/**
+ * Repeats the entire stream according to `schedule` after each successful
+ * completion. Failures are not repeated.
+ *
+ * `Schedule.recurs(n)` runs the stream `n + 1` times (the original plus `n`
+ * repeats), matching Effect `Stream.repeat`.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Repetition is a subscription-level decision: after one producer completes,
+ * a Schedule decides whether and when a fresh run should begin. Keeping that
+ * decision in Effect's Schedule preserves typed timing services and failures.
+ *
+ * ## Ownership and lifetime
+ *
+ * Runs are strictly sequential. Every source value is forwarded before the
+ * Schedule is stepped with `void`; a successful step sleeps as configured and
+ * starts a new source run. A source failure stops immediately and is never
+ * repeated. Schedule failure is forwarded; Schedule completion ends normally.
+ * Interruption cancels the active source or schedule sleep. No runs overlap.
+ *
+ * @example
+ * ```ts
+ * import { Schedule } from "effect"
+ * import { repeat } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const threeTicks = repeat(succeed("tick"), Schedule.recurs(2))
+ * ```
+ *
+ * @since 1.0.0
+ * @category Time and rate
+ */
+export declare const repeat: {
+    <X, E2, R2>(schedule: Schedule.Schedule<X, void, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+    <A, E, R, X, E2, R2>(self: Fx<A, E, R>, schedule: Schedule.Schedule<X, void, E2, R2>): Fx<A, E | E2, R | R2>;
+};
+//# sourceMappingURL=repeat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repeat.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/repeat.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAG5C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EACR,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAC3C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EACjB,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,GAC3C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;CAoC1B,CAAC"}