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

package/dist/Fx/combinators/onInterrupt.js

@@ -7,10 +7,55 @@ import { make as makeSink } from "../../Sink/Sink.js";
 import { make } from "../constructors/make.js";
 const toFinalizer = (f) => (interruptors) => typeof f === "function" ? f(interruptors) : f;
 /**
- * Adds an `Effect.onInterrupt`-style finalizer to an `Fx`.
+ * Runs a finalizer when the Fx reports or externally receives interruption.
  *
- * The finalizer is run only when the stream is interrupted (either via an
- * interrupt cause or by interrupting the running fiber).
+ * @remarks
+ * ## Why
+ *
+ * Cancellation-specific cleanup should not run for success or ordinary typed
+ * failure. The interruptor IDs retain Effect's information about which fibers
+ * requested cancellation.
+ *
+ * ## Ownership and lifetime
+ *
+ * An interrupt-only Cause reported by the source invokes the finalizer before
+ * that Cause is delivered; finalizer failure is combined with it. External
+ * interruption of the running fiber also invokes the finalizer, suppressing its
+ * failure to preserve cancellation. Those paths are tracked separately: if an
+ * external interruption arrives while reported-Cause handling is still active,
+ * the finalizer can run once for each path. Successful and non-interrupt failures
+ * do not invoke it. A finalizer captured while constructing an Fx is shared by
+ * every run of that Fx; create mutable cleanup state lazily inside `gen` or
+ * `genScoped` when each subscription must own a distinct resource.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { onInterrupt } from "@typed/fx/Fx"
+ * import { interrupt } from "@typed/fx/Fx"
+ *
+ * const observed = onInterrupt(
+ *   interrupt(1),
+ *   (ids) => Effect.log(`interrupted by ${ids.size}`)
+ * )
+ * ```
+ *
+ * @example Keep the finalizer idempotent when both interrupt paths are possible
+ * ```ts
+ * import { Effect } from "effect"
+ * import { gen } from "@typed/fx/Fx"
+ * import { onInterrupt } from "@typed/fx/Fx"
+ * import { interrupt } from "@typed/fx/Fx"
+ *
+ * const observed = gen(function* () {
+ *   // `gen` creates this controller separately for every subscription.
+ *   const controller = yield* Effect.sync(() => new AbortController())
+ *   return onInterrupt(
+ *     interrupt(1),
+ *     Effect.sync(() => controller.abort()) // `abort` is idempotent.
+ *   )
+ * })
+ * ```
  *
  * @since 1.0.0
  * @category combinators

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

@@ -0,0 +1,28 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Emits consecutive pairs `[previous, current]`. The first value is not emitted
+ * until a second value arrives.
+ *
+ * Equivalent to RxJS `pairwise` and Effect `Stream.sliding(2)` for pairs.
+ *
+ * @remarks
+ * ## Why
+ * `pairwise` exposes transitions rather than isolated values. For `n` inputs it emits `max(0,
+ * n - 1)` adjacent pairs in source order, retaining only the immediately preceding value.
+ *
+ * ## Ownership and lifetime
+ * The previous-value cell belongs to one run of the returned Fx and is discarded when that run
+ * completes or is interrupted. Source errors and services are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const changes = Fx.fromIterable([10, 13, 12]).pipe(Fx.pairwise)
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const pairwise: <A, E = never, R = never>(self: Fx<A, E, R>) => Fx<readonly [A, A], E, R>;
+//# sourceMappingURL=pairwise.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pairwise.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/pairwise.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAM3F,CAAC"}

package/dist/Fx/combinators/pairwise.js

@@ -0,0 +1,31 @@
+import * as Option from "effect/Option";
+import { filterMapLoop } from "./filterMapLoop.js";
+/**
+ * Emits consecutive pairs `[previous, current]`. The first value is not emitted
+ * until a second value arrives.
+ *
+ * Equivalent to RxJS `pairwise` and Effect `Stream.sliding(2)` for pairs.
+ *
+ * @remarks
+ * ## Why
+ * `pairwise` exposes transitions rather than isolated values. For `n` inputs it emits `max(0,
+ * n - 1)` adjacent pairs in source order, retaining only the immediately preceding value.
+ *
+ * ## Ownership and lifetime
+ * The previous-value cell belongs to one run of the returned Fx and is discarded when that run
+ * completes or is interrupted. Source errors and services are unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const changes = Fx.fromIterable([10, 13, 12]).pipe(Fx.pairwise)
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const pairwise = (self) => filterMapLoop(self, Option.none(), (prev, a) => Option.match(prev, {
+    onNone: () => [Option.none(), Option.some(a)],
+    onSome: (previous) => [Option.some([previous, a]), Option.some(a)],
+}));

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

@@ -3,10 +3,34 @@ import * as Layer from "effect/Layer";
 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.
@@ -17,15 +41,70 @@ 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>;
 };
+/**
+ * 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 combinators
+ */
 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 a single service to an Fx.
+ * 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"
  *
- * Equivalent to `provideContext(fx, Context.make(tag, service))`. The service
- * is available for the entire Fx stream, scoped to the stream lifetime.
+ * 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.
@@ -38,10 +117,52 @@ export declare const provideService: {
     <A, E, R, Id, S>(fx: Fx<A, E, R>, tag: Context.Service<Id, S>, service: S): Fx<A, E, Exclude<R, Id>>;
 };
 /**
- * Provides a single service to an Fx by running an effect that produces the 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"
  *
- * The effect is run when the Fx is run; the resulting service is provided to the
- * entire stream. Equivalent to `provide(fx, Layer.effect(tag, serviceEffect))`.
+ * 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).

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":"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"}
+{"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

@@ -6,10 +6,34 @@ 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.
@@ -25,12 +49,67 @@ export const provide = dual(2, (fx, layer) => make(Effect.fnUntraced(function* (
     }
     return yield* fx.run(sink).pipe(Effect.provideContext(servicesExit.value), Effect.onExit((exit) => Scope.close(scope, exit)));
 })));
+/**
+ * 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 combinators
+ */
 export const provideContext = dual(2, (fx, services) => provide(fx, Layer.succeedContext(services)));
 /**
- * Provides a single service to an Fx.
+ * 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"
  *
- * Equivalent to `provideContext(fx, Context.make(tag, service))`. The service
- * is available for the entire Fx stream, scoped to the stream lifetime.
+ * 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.
@@ -40,10 +119,52 @@ export const provideContext = dual(2, (fx, services) => provide(fx, Layer.succee
  */
 export const provideService = dual(3, (fx, tag, service) => provideContext(fx, Context.make(tag, service)));
 /**
- * Provides a single service to an Fx by running an effect that produces the 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"
  *
- * The effect is run when the Fx is run; the resulting service is provided to the
- * entire stream. Equivalent to `provide(fx, Layer.effect(tag, serviceEffect))`.
+ * 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).

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 combinators
+ */
+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 combinators
+ */
+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"}